feat(plugin): add plugin interface system and iot-mock implementation

- internal/plugin: Plugin/IoTProvider/ToolProvider/RAGProvider interfaces
- internal/plugin: Registry with type-safe auto-detection, 11 tests
- plugins/iot-mock: 8 simulated smart home devices, 11 tests
- 63 total tests, build + vet clean

backend/internal/plugin/plugin.go

@@ -0,0 +1,109 @@
+// 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
+}