Aska
750d594055
- 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
110 lines
3.4 KiB
Go
110 lines
3.4 KiB
Go
// 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
|
|
}
|