// Package plugin defines the core interfaces and types for Cyrene's plugin system.
// Plugins extend Cyrene with IoT device control, LLM tools, and RAG capabilities.
// Each plugin type implements one or more of the Provider interfaces.
package plugin

import "context"

// Plugin is the base interface that all plugins must implement.
type Plugin interface {
	// Name returns the unique plugin identifier (e.g., "iot-mock", "calculator").
	Name() string

	// Version returns the semantic version string (e.g., "1.0.0").
	Version() string

	// Description returns a human-readable description of the plugin.
	Description() string

	// Init initializes the plugin. Called once at startup.
	// Return an error to skip this plugin (other plugins are unaffected).
	Init(ctx context.Context, cfg PluginConfig) error

	// Close cleans up plugin resources. Called on shutdown.
	Close() error

	// Enabled returns whether the plugin is currently available.
	// Used for conditional plugins (e.g., web-search disabled when SearXNG is down).
	Enabled() bool
}

// PluginConfig provides shared configuration to all plugins during Init.
type PluginConfig struct {
	// DataDir is the base directory for plugin data storage.
	DataDir string

	// NATSURL is the NATS connection address.
	NATSURL string

	// DatabaseURL is the PostgreSQL connection string.
	DatabaseURL string

	// LogLevel is the current log level string.
	LogLevel string

	// Extra holds plugin-specific config from environment variables
	// (keys prefixed with PLUGIN_{NAME}_).
	Extra map[string]string
}

// --- Device types shared across IoT plugins ---

// DeviceType categorizes an IoT device.
type DeviceType string

const (
	DeviceLight      DeviceType = "light"
	DeviceAC         DeviceType = "ac"
	DeviceCurtain    DeviceType = "curtain"
	DeviceSensor     DeviceType = "sensor"
	DeviceLock       DeviceType = "lock"
	DeviceSwitch     DeviceType = "switch"
	DeviceHumidifier DeviceType = "humidifier"
	DeviceTV         DeviceType = "tv"
)

// Device represents an IoT device.
type Device struct {
	ID      string         `json:"id"`
	Name    string         `json:"name"`
	Type    DeviceType     `json:"type"`
	State   map[string]any `json:"state"`   // Dynamic state fields
	Online  bool           `json:"online"`
	History []DeviceEvent  `json:"history"` // Recent events
}

// DeviceEvent represents a single state change on a device.
type DeviceEvent struct {
	DeviceID  string `json:"device_id"`
	Field     string `json:"field"`
	OldValue  any    `json:"old_value"`
	NewValue  any    `json:"new_value"`
	Timestamp int64  `json:"timestamp"` // Unix timestamp
}

// --- Tool types ---

// ToolDefinition describes an LLM-callable tool.
type ToolDefinition struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	// Parameters is a JSON Schema object describing the tool's input parameters.
	Parameters map[string]any `json:"parameters"`
}

// RAGDocument represents a document in the RAG knowledge base.
type RAGDocument struct {
	ID       string            `json:"id"`
	Title    string            `json:"title"`
	Content  string            `json:"content"`
	Metadata map[string]string `json:"metadata"`
	Source   string            `json:"source"`
}

// RAGSearchResult represents a single search result from RAG.
type RAGSearchResult struct {
	Document RAGDocument `json:"document"`
	Score    float64     `json:"score"`
	Chunk    string      `json:"chunk"` // The relevant chunk from the document
}