provider

type Capabilities struct {
	// Chat indicates the provider supports basic conversational messages.
	// All providers must support this — it is included for completeness.
	Chat bool

	// Streaming indicates the provider can stream token-by-token responses.
	// If false, Chat() will emit a single EventToken followed by EventDone.
	Streaming bool

	// Models indicates the provider can list available models via Models().
	Models bool

	// ToolCalling indicates the provider supports structured tool/function calls
	// from the AI model (e.g. OpenAI function calling style).
	ToolCalling bool

	// Memory indicates the provider has server-side memory / long-term context.
	Memory bool

	// AgentExecution indicates the provider can autonomously execute multi-step
	// tasks (e.g. OpenClaw or Hermes with tool chains and planning).
	AgentExecution bool

	// FilesystemAccess indicates the provider's agent can read/write files on
	// the backend server.
	FilesystemAccess bool

	// CommandExecution indicates the provider's agent can run shell commands
	// on the backend server.
	CommandExecution bool
}

type ConstructorFn func(name string, cfg config.ProviderConfig) (Provider, error)

type Event struct {
	Type    EventType
	Content string // text token or status message
	Error   error  // non-nil only when Type == EventError
	// Meta is optional provider-specific metadata (tool name, model, etc.).
	Meta map[string]any
}

type EventType string

type Message struct {
	Role    Role
	Content string
}

type Model struct {
	ID          string
	Name        string
	Description string
	Size        int64 // bytes, if known (e.g. Ollama local models)
}

type Provider interface {
	// Connect establishes a connection to the backend and validates credentials.
	// It must be called before any other method.
	Connect(ctx context.Context) error

	// Close releases all resources held by the provider.
	Close() error

	// Chat sends a message and returns a channel of streaming events.
	// The caller is responsible for draining the channel until it is closed.
	// Cancelling ctx will cause the provider to close the channel and stop
	// generation.
	//
	// history is the conversation history to send for context.
	// message is the new user message.
	Chat(ctx context.Context, history []Message, message string) (<-chan Event, error)

	// Models returns the list of models available on this provider.
	// Returns an error if the provider does not support model listing.
	Models(ctx context.Context) ([]Model, error)

	// Status returns the current health status of this provider.
	Status(ctx context.Context) (ProviderStatus, error)

	// Capabilities returns the set of features this provider supports.
	// Callers must check Capabilities before calling optional features.
	Capabilities() Capabilities

	// Name returns the human-readable name of this provider implementation.
	Name() string
}

type ProviderStatus struct {
	Connected bool
	Latency   time.Duration
	Message   string   // human-readable status
	Details   []string // extra lines (e.g. loaded models, auth info)
	Endpoint  string   // the URL being checked
}

type Registry struct {
	// contains filtered or unexported fields
}

type Role string

type Router struct {
	// contains filtered or unexported fields
}