Cyrene-Plugins/sdk/plugin.go

package sdk

import (
	"context"
	"net/http"
)

// Plugin is the main interface every plugin must implement.
type Plugin interface {
	Metadata() PluginMetadata
	Init(ctx context.Context, config PluginConfig) error
	Start(ctx context.Context, host HostAPI) error
	Stop(ctx context.Context) error
	Health(ctx context.Context) error
	Tools() []Tool
}

// Tool is the interface every tool must implement.
type Tool interface {
	Definition() ToolDefinition
	Execute(ctx context.Context, args map[string]interface{}) (*ToolResult, error)
	Validate(args map[string]interface{}) error
	Complexity() ToolComplexity
}

// ComplexTool extends Tool for async multi-round execution.
type ComplexTool interface {
	Tool
	ExecuteAsync(ctx context.Context, args map[string]interface{}) (<-chan ToolProgress, error)
	Cancel(ctx context.Context, executionID string) error
}

// HostAPI gives plugins access to Cyrene core capabilities.
type HostAPI interface {
	CallLLM(ctx context.Context, messages []LLMMessage) (*LLMResponse, error)
	SearchMemory(ctx context.Context, userID, query string, limit int) ([]MemoryEntry, error)
	StoreMemory(ctx context.Context, entry MemoryEntry) error
	Logger() Logger
	GetConfig(key string) (string, error)
	SetConfig(key, value string) error
	PublishEvent(ctx context.Context, event map[string]interface{}) error
	HTTPClient() *http.Client
}

// Logger is a minimal logging interface for plugins.
type Logger interface {
	Printf(format string, args ...interface{})
	Println(args ...interface{})
}