sdk

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

type Action interface {
	// contains filtered or unexported methods
}

type AlbumMetadata struct {
	Title              *string
	AlbumArtist        *string
	Artist             *string
	Year               *int
	ReleaseDate        *string
	Genre              *string
	TotalTracks        *int
	TotalDiscs         *int
	RecordLabel        *string
	ReleaseType        *string
	Compilation        *bool
	MusicbrainzAlbumID *string
	SortTitle          *string
}

type ArtistMetadata struct {
	Name                *string
	SortName            *string
	MusicbrainzArtistID *string
	Bio                 *string
	Country             *string
	FormedYear          *int
	Genre               *string
}

type AudioTrack struct {
	Codec         string // "aac", "ac3", "eac3", "truehd", "dts", "dts-hd", "flac"
	Channels      int    // Number of channels (2, 6, 8, etc.)
	ChannelLayout string // "stereo", "5.1", "7.1", "Atmos"
	Language      string // ISO 639-1/2 code, e.g., "en", "eng"
	IsDefault     bool
	IsCommentary  bool
}

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

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

type Capability struct {
	Name      string           // Capability name (e.g., "embedding")
	Providers []PluginProvider // Plugins providing this capability
}

type CapabilityDescription struct {
	Capability        string
	APIVersion        string
	SupportedVersions []string
	Methods           []CapabilityMethod
	Providers         []PluginProvider
}

type CapabilityError struct {
	Code      pluginv1.CapabilityErrorCode
	Message   string
	Details   string
	Retryable bool
}

type CapabilityMethod struct {
	Name         string
	Description  string
	IsStreaming  bool
	RequestType  string
	ResponseType string
}

type CastMember struct {
	Name  string
	Role  string
	Thumb string
	Order int
}

type ChatChunk struct {
	// Content is the text in this chunk
	Content string

	// Done indicates if this is the final chunk
	Done bool

	// FinishReason is set on the final chunk
	FinishReason string
}

type ChatMessage struct {
	// Role is "system", "user", or "assistant"
	Role string

	// Content is the message text
	Content string
}

type ChatRequest struct {
	// Messages is the conversation history
	Messages []ChatMessage

	// Model is the model to use (uses provider default if empty)
	Model string

	// Temperature controls randomness (0.0-2.0)
	Temperature float32

	// MaxTokens limits the response length
	MaxTokens int
}

type ChatResponse struct {
	// Content is the generated text
	Content string

	// FinishReason indicates why generation stopped: "stop", "length", "content_filter"
	FinishReason string

	// PromptTokens is the number of tokens in the prompt
	PromptTokens int

	// CompletionTokens is the number of tokens in the response
	CompletionTokens int
}

type ConfigurableEnricher interface {
	// GetSettingsSchema returns a JSON Schema describing the plugin's configurable settings.
	// Use Schema.Build() to generate this from your schema definition.
	GetSettingsSchema() ([]byte, error)

	// Configure applies new settings to the plugin.
	Configure(settings []byte) error

	// IsConfigured returns whether the plugin is properly configured.
	// Plugins requiring API keys should return false until the key is set.
	// The host uses this to exclude unconfigured plugins from capability resolution.
	IsConfigured() bool
}

type ConfigurableProvider interface {
	// GetSettingsSchema returns the JSON Schema for provider settings.
	// Use Schema.Build() to generate this from your schema definition.
	GetSettingsSchema() ([]byte, error)

	// Configure applies new settings to the provider.
	Configure(settings []byte) error

	// IsConfigured returns whether the provider is properly configured.
	// Providers requiring API keys should return false until the key is set.
	// The host uses this to exclude unconfigured providers from capability resolution.
	IsConfigured() bool
}

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

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

type DependsOnConfig struct {
	// Field is the property name this depends on
	Field string `json:"field"`
	// Value is the value the field must have for this to be visible
	Value any `json:"value"`
}

type Embedding struct {
	// EntityType identifies the type of entity (e.g., "movie", "tv_show", "track")
	EntityType string

	// EntityID is the unique identifier within the entity type
	EntityID int64

	// Vector is the embedding vector (float32)
	Vector []float32

	// Text is the original text that was embedded (optional, for debugging)
	Text string

	// Model is the model used to generate the embedding (optional, for tracking)
	Model string
}

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

type EnrichRequest struct {
	MediaID     int64
	MediaType   string
	FilePath    string
	Title       string
	Year        int
	ExistingIDs map[string]string

	// TV-specific
	ShowTitle     string
	SeasonNumber  int
	EpisodeNumber int

	// Music-specific
	Artist      string
	Album       string
	TrackNumber int
}

type EnrichResponse struct {
	Matched         bool
	Metadata        *EnrichedMetadata
	DiscoveredIDs   map[string]string
	Images          []EnrichedImage
	Skipped         bool
	SkipReason      string
	ConfidenceScore float32 // 0.0 to 1.0
}

type EnrichedImage struct {
	Type     string // "poster", "fanart", "banner", etc.
	Path     string // Local path or remote URL
	IsRemote bool
	Language string
	Width    int
	Height   int
	Rating   float32
}

type EnrichedMetadata struct {
	Title          *string
	OriginalTitle  *string
	SortTitle      *string
	Year           *int
	Plot           *string
	Tagline        *string
	Genres         []string
	Keywords       []Keyword
	ContentRating  *string
	RuntimeMinutes *int
	Rating         *float32
	RatingVotes    *int
	Directors      []string
	Writers        []string
	Cast           []CastMember
	Studios        []string
	SimilarTitles  []string // Titles of similar/recommended content (from TMDb recommendations)

	// Music-specific fields (for tracks)
	Artist      *string
	Album       *string
	ReleaseDate *string

	// Music album metadata
	AlbumMetadata *AlbumMetadata

	// Music artist metadata
	ArtistMetadata *ArtistMetadata
}

type EnricherCapabilities struct {
	MediaTypes []string // "movie", "tv", "music"
	Provides   []string // "metadata", "artwork", "external_ids"
	IsLocal    bool     // Local enrichers get high concurrency
	RateLimit  int      // Requests per minute (0 = unlimited)
	Requires   []string // External IDs required (e.g., ["imdb"])
	Priority   int      // Execution priority (lower = earlier)
}

type EnricherCoreGRPCPlugin struct {
	plugin.Plugin
	Impl EnricherPlugin
	// contains filtered or unexported fields
}

type EnricherGRPCPlugin struct {
	plugin.Plugin
	Impl EnricherPlugin
	// contains filtered or unexported fields
}

type EnricherPlugin interface {

	// GetCapabilities returns what this enricher provides and requires.
	GetCapabilities() EnricherCapabilities

	// Initialize is called when the plugin is loaded.
	// Config is the contents of config.yml passed by the host.
	// Services provides access to host services (storage, LLM, etc.) - may have nil fields.
	Initialize(ctx context.Context, dataDir string, config []byte, services *HostServices) error

	// Shutdown is called before the plugin is unloaded.
	// Use this to clean up any resources.
	Shutdown(ctx context.Context) error

	// Enrich processes a single media item.
	Enrich(ctx context.Context, req *EnrichRequest) (*EnrichResponse, error)
	// contains filtered or unexported methods
}

type EntityTypeStats struct {
	EntityType string // "movie", "tv_show", etc.
	Indexed    int64  // Number of indexed items
	Total      int64  // Total items in database
}

type Event struct {
	// Type is the event type, e.g., "media.added"
	Type string

	// Source identifies who emitted the event
	Source string

	// Timestamp is when the event occurred
	Timestamp time.Time

	// Payload is the JSON-encoded event data
	Payload []byte

	// CorrelationID links related events
	CorrelationID string
}

type EventHandler interface {
	// GetSubscriptions returns event types this plugin wants to receive.
	GetSubscriptions() []string

	// OnEvent handles an incoming event.
	// Returns true if the event was handled.
	OnEvent(event Event) bool
}

type FindSimilarRequest struct {
	EntityType string // Type of the source entity
	EntityID   int64  // ID of the source entity
	Limit      int    // Maximum number of similar items to return
}

type HTTPEnricher interface {
	// GetRoutes returns HTTP routes this enricher exposes.
	GetRoutes() []Route

	// HandleHTTP handles a non-streaming HTTP request.
	HandleHTTP(ctx context.Context, req *HTTPRequest) (*HTTPResponse, error)
}

type HTTPProvider interface {
	// GetRoutes returns HTTP routes this provider exposes.
	GetRoutes() []Route

	// HandleHTTP handles a non-streaming HTTP request.
	HandleHTTP(ctx context.Context, req *HTTPRequest) (*HTTPResponse, error)

	// HandleHTTPStream handles a streaming HTTP request (e.g., model download).
	// Return nil if not implemented.
	HandleHTTPStream(ctx context.Context, req *HTTPRequest, stream HTTPStreamWriter) error
}

type HTTPRequest struct {
	// Path is the request path relative to the plugin, e.g., "/search"
	Path string

	// Method is the HTTP method: GET, POST, etc.
	Method string

	// Headers contains HTTP headers (lowercase keys)
	Headers map[string]string

	// Query contains query string parameters
	Query map[string]string

	// PathParams contains parameters extracted from :param patterns
	PathParams map[string]string

	// Body is the request body (for POST, PUT, PATCH)
	Body []byte

	// UserID is the authenticated user ID (empty if not authenticated)
	UserID string

	// IsAdmin indicates whether the user has admin role
	IsAdmin bool
}

type HTTPResponse struct {
	// StatusCode is the HTTP status code
	StatusCode int

	// Headers contains response headers
	Headers map[string]string

	// Body is the response body
	Body []byte

	// ContentType is the Content-Type header (convenience, also in Headers)
	ContentType string
}

type HTTPStreamWriter interface {
	// WriteHeader sends the response status and headers.
	// Must be called before WriteChunk.
	WriteHeader(statusCode int, contentType string, headers map[string]string) error

	// WriteChunk sends a chunk of response data.
	WriteChunk(data []byte) error
}

type HostDataGRPCPlugin struct{ plugin.Plugin }

type HostPluginsGRPCPlugin struct{ plugin.Plugin }

type HostServices struct {
	// Storage provides key-value, SQL, and vector storage for plugins
	Storage *StorageClient

	// Data provides access to media database
	Data *DataClient

	// Weather provides weather/location data
	Weather *WeatherClient

	// Plugins provides capability-based access to other plugins
	Plugins *PluginsClient

	// Ratings provides read-only access to user ratings (favorites, likes, dislikes)
	Ratings *RatingsClient

	// Progress provides read-only access to user watch history
	Progress *ProgressClient
}

type HostStorageGRPCPlugin struct{ plugin.Plugin }

type HostWeatherGRPCPlugin struct{ plugin.Plugin }

type IndexLibraryRequest struct {
	LibraryID   int64  // Library database ID
	LibraryType string // "movie", "tv", "music"
}

type IndexLibraryResponse struct {
	Started bool   // Whether indexing was started
	Message string // Status message
}

type IndexingProgress struct {
	EntityType  string // Entity type being indexed
	Total       int64  // Total items to process
	Processed   int64  // Items processed so far
	Failed      int64  // Items that failed
	LastError   string // Most recent error message
	StartedAt   int64  // Unix timestamp when started
	LastUpdated int64  // Unix timestamp of last update
}

type InvokeMetadata struct {
	ProviderPlugin string            // Which plugin handled the request
	LatencyMs      int64             // How long the provider took
	Metadata       map[string]string // Response metadata from provider
}

type InvokeOption func(*invokeOptions)

type ItemAction interface {
	// contains filtered or unexported methods
}

type Keyword struct {
	ID         int
	Name       string
	IsLocation bool
}

type Library struct {
	ID        int64
	Name      string
	Path      string
	MediaType string // "movie", "tv", "music"
}

type LibraryScanCompletedPayload struct {
	LibraryID   int64 `json:"library_id"`
	ItemsAdded  int   `json:"items_added"`
	ItemsUpdate int   `json:"items_updated"`
	ItemsRemove int   `json:"items_removed"`
	DurationMs  int64 `json:"duration_ms"`
}

type LibraryScanStartedPayload struct {
	LibraryID int64  `json:"library_id"`
	ScanType  string `json:"scan_type"` // "full" or "incremental"
}

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

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

type Media struct {
	ID          int64
	MediaType   string
	Title       string
	Year        int
	FilePath    string
	LibraryID   int64
	ExternalIDs map[string]string
}

type MediaAddedPayload struct {
	MediaID   int64  `json:"media_id"`
	MediaType string `json:"media_type"`
	Title     string `json:"title"`
	Year      int    `json:"year"`
	LibraryID int64  `json:"library_id"`
}

type MediaDeletedPayload struct {
	MediaID   int64  `json:"media_id"`
	MediaType string `json:"media_type"`
}

type MediaDetails struct {
	ID          int64
	MediaType   string
	Title       string
	Year        int
	LibraryID   int64
	ExternalIDs map[string]string

	// Rich metadata
	Plot             string
	Tagline          string
	Genres           []string
	Directors        []string
	Writers          []string
	Cast             []CastMember
	Studios          []string
	ContentRating    string
	RuntimeMinutes   int
	OriginalLanguage string
	CountryOfOrigin  string
	Producers        []string
	LocationKeywords []string
	ThemeKeywords    []string
	Composers        []string // Music composers
	Cinematographers []string // Directors of Photography
	SimilarTitles    []string // Similar/recommended titles from TMDb

	// Playback information for filtering by technical specs
	PlaybackInfo *PlaybackInfo

	// TV-specific
	ShowTitle     string
	SeasonNumber  int
	EpisodeNumber int

	// Music-specific
	ArtistName  string
	AlbumTitle  string
	Biography   string
	Country     string
	ReleaseType string
}

type MediaItem struct {
	// EntityType is the media type: "movie", "tv_show", "tv_episode", etc.
	EntityType string `json:"entity_type"`

	// EntityID is the database ID of the media item.
	EntityID int64 `json:"entity_id"`

	// Title is the display title.
	Title string `json:"title"`

	// Year is the release/air year.
	Year int `json:"year,omitempty"`

	// Poster is the URL to the poster image.
	Poster string `json:"poster,omitempty"`

	// Backdrop is the URL to the backdrop image.
	Backdrop string `json:"backdrop,omitempty"`

	// Reason is an optional recommendation reason.
	// Example: "Similar to Breaking Bad"
	Reason string `json:"reason,omitempty"`

	// Progress is optional playback progress (for continue watching).
	Progress *MediaProgress `json:"progress,omitempty"`

	// Rating is the user's rating for this item (if any).
	// Values: "up", "down", "favorite", or nil if not rated.
	Rating *string `json:"rating,omitempty"`
}

type MediaList struct {
	Items   []*MediaDetails
	Total   int
	HasMore bool
}

type MediaProgress struct {
	// Percent is the progress percentage (0-100).
	Percent int `json:"percent"`

	// PositionSeconds is the playback position in seconds.
	PositionSeconds int `json:"position_seconds"`

	// DurationSeconds is the total duration in seconds.
	DurationSeconds int `json:"duration_seconds"`
}

type MediaUpdatedPayload struct {
	MediaID      int64    `json:"media_id"`
	MediaType    string   `json:"media_type"`
	UpdatedField []string `json:"updated_fields"`
}

type Migration struct {
	// Version is the migration version number. Must be unique and positive.
	// Migrations are applied in version order.
	Version int

	// SQL is the DDL statement(s) to execute for this migration.
	// Multiple statements can be separated by semicolons.
	SQL string
}

type MoodTag struct {
	Tag        string
	Confidence float32
}

type PlaybackInfo struct {
	// Video specs
	Width           int    // Video width in pixels
	Height          int    // Video height in pixels
	ResolutionLabel string // "SD", "720p", "1080p", "4K", "8K"
	HDRFormat       string // "SDR", "HDR10", "HDR10+", "Dolby Vision", "HLG"
	VideoCodec      string // "h264", "hevc", "av1", etc.
	Bitrate         int64  // Video bitrate in bits/second

	// Audio and subtitle tracks
	AudioTracks    []AudioTrack
	SubtitleTracks []SubtitleTrack
}

type PlaybackStartedPayload struct {
	SessionID string `json:"session_id"`
	UserID    string `json:"user_id"`
	MediaID   int64  `json:"media_id"`
	MediaType string `json:"media_type"`
}

type PlaybackStoppedPayload struct {
	SessionID    string  `json:"session_id"`
	UserID       string  `json:"user_id"`
	MediaID      int64   `json:"media_id"`
	PositionSecs float64 `json:"position_secs"`
	DurationSecs float64 `json:"duration_secs"`
}

type PluginMeta struct {
	// DisplayName is the human-readable name shown in the UI.
	// Example: "OpenAI", "Ollama", "TMDB"
	DisplayName string `json:"displayName"`

	// ProviderName is the name shown in provider selection dropdowns.
	// If not set, DisplayName is used. Use this when the plugin name
	// differs from how it should appear as a provider option.
	// Example: DisplayName="AI Features", ProviderName="Ollama"
	ProviderName string `json:"providerName,omitempty"`

	// Description is a short description of what the plugin does.
	// Example: "OpenAI API for embeddings and chat"
	Description string `json:"description"`

	// Tip is optional help text shown as a tooltip.
	// Example: "Requires API key. Usage is billed per token."
	Tip string `json:"tip,omitempty"`

	// IsLocal indicates if this runs locally (no external API calls).
	// Local plugins show a "Local" badge in the UI.
	IsLocal bool `json:"isLocal,omitempty"`

	// Icon is the icon name to display. Common options:
	// "cloud", "hard-drive", "brain", "compass", "star", "settings"
	Icon string `json:"icon,omitempty"`
}

type PluginMetrics struct {
	// RequestsTotal is the total number of requests handled.
	RequestsTotal int64

	// ErrorsTotal is the total number of errors encountered.
	ErrorsTotal int64

	// AvgLatency is the average request latency.
	AvgLatency time.Duration
}

type PluginProvider struct {
	ID          string // Plugin ID (e.g., "provider-ollama")
	Name        string // Human-readable name (e.g., "Ollama Provider")
	Enabled     bool   // Whether the plugin is enabled
	Configured  bool   // Whether the plugin is properly configured
	IsPreferred bool   // Whether this is the preferred provider
}

type PluginRefConfig struct {
	// Capability is the capability to filter plugins by (e.g., "embedding", "chat").
	// Only plugins providing this capability appear in the dropdown.
	Capability string

	// SettingsKey is the key where the referenced plugin's settings are stored.
	// If empty, defaults to "{capability}_provider_settings".
	SettingsKey string
}

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

type PluginsClientAware interface {
	// SetPluginsClient receives the PluginsClient for capability broker access.
	// Called after Initialize() if the host provides the HostPlugins service.
	SetPluginsClient(client *PluginsClient)
}

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

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

type PropertyType string

type ProviderCapabilities struct {
	// ProviderID is a unique identifier, e.g., "ollama", "openai", "anthropic"
	ProviderID string

	// DisplayName is the human-readable name, e.g., "Ollama (Local)"
	DisplayName string

	// Description describes the provider
	Description string

	// SupportsChat indicates if this provider supports chat completions
	SupportsChat bool

	// SupportsEmbedding indicates if this provider supports embedding generation
	SupportsEmbedding bool

	// SupportsStreaming indicates if this provider supports streaming responses
	SupportsStreaming bool

	// RequiresAPIKey indicates if this provider requires an API key
	RequiresAPIKey bool

	// RequiresURL indicates if this provider requires a custom URL (e.g., Ollama)
	RequiresURL bool

	// IsLocal indicates if this provider runs locally (affects UI display)
	IsLocal bool

	// DefaultChatModel is the default model ID for chat
	DefaultChatModel string

	// DefaultEmbeddingModel is the default model ID for embeddings
	DefaultEmbeddingModel string
}

type ProviderCoreGRPCPlugin struct {
	plugin.Plugin
	Impl ProviderPlugin
	// contains filtered or unexported fields
}

type ProviderHealth struct {
	// Healthy indicates if the provider is ready to serve requests
	Healthy bool

	// Message is a human-readable status message
	Message string

	// Latency is the health check latency
	Latency time.Duration

	// Error is the error message if unhealthy
	Error string
}

type ProviderModel struct {
	// ID is the model identifier, e.g., "llama3.2", "gpt-4o-mini"
	ID string

	// Name is the human-readable name
	Name string

	// Description describes the model
	Description string

	// IsChat indicates if this is a chat/completion model
	IsChat bool

	// IsEmbedding indicates if this is an embedding model
	IsEmbedding bool

	// ContextLength is the context window size (for chat models)
	ContextLength int

	// EmbeddingDimensions is the embedding vector size (for embedding models)
	EmbeddingDimensions int

	// Size is the model size for display, e.g., "7B", "3.8GB"
	Size string

	// Recommended indicates if this model is recommended
	Recommended bool
}

type ProviderPlugin interface {

	// GetProviderCapabilities returns what this provider supports.
	GetProviderCapabilities() ProviderCapabilities

	// Initialize is called when the plugin is loaded.
	// Config contains the contents of config.yml passed by the host.
	Initialize(ctx context.Context, dataDir string, config []byte, systemInfo *SystemInfo) error

	// Shutdown is called before the plugin is unloaded.
	Shutdown(ctx context.Context) error

	// HealthCheck verifies the provider is working (API key valid, service reachable).
	HealthCheck(ctx context.Context) (*ProviderHealth, error)

	// ListModels returns available models from this provider.
	ListModels(ctx context.Context) ([]ProviderModel, error)

	// GenerateEmbedding generates an embedding for a single text.
	GenerateEmbedding(ctx context.Context, text, model string) ([]float32, error)

	// GenerateEmbeddingBatch generates embeddings for multiple texts.
	GenerateEmbeddingBatch(ctx context.Context, texts []string, model string) ([][]float32, error)

	// Chat sends a chat completion request.
	Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

	// ChatStream sends a streaming chat completion request.
	// Implementations should send chunks to the provided channel and close it when done.
	ChatStream(ctx context.Context, req *ChatRequest, chunks chan<- ChatChunk) error
	// contains filtered or unexported methods
}

type ProviderServiceGRPCPlugin struct {
	plugin.Plugin
	Impl ProviderPlugin
	// contains filtered or unexported fields
}

type RateLimit struct {
	// RequestsPerMinute is the maximum requests per minute (0 = no limit)
	RequestsPerMinute int

	// PerUser limits per-user if true, otherwise global for this route
	PerUser bool
}

type Rating struct {
	ID         int64
	UserID     string
	EntityType string // "movie", "tv_show", "tv_episode"
	EntityID   int64
	Rating     string // "favorite", "up", "down"
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

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

type Route struct {
	// Path is relative to the plugin namespace, e.g., "/search" or "/items/:id"
	// Supports :param syntax for path parameters
	Path string

	// Methods lists HTTP methods this route handles: GET, POST, PUT, DELETE, PATCH
	Methods []string

	// AdminOnly restricts this route to admin users
	AdminOnly bool

	// Description is human-readable text for API docs
	Description string

	// Capability is the capability name this route provides (e.g., "search", "chat")
	// Other plugins can invoke this capability via the host plugins service.
	Capability string

	// AliasPath is a stable URL alias for this route (e.g., "/api/search")
	// If set, the host will create an alias at this path that proxies to this route.
	// This allows plugins to claim well-known API paths.
	AliasPath string

	// Streaming indicates this route uses HandleHTTPStream instead of HandleHTTP
	Streaming bool

	// RateLimit optionally limits requests to this route
	RateLimit *RateLimit
}

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

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

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

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

type SearchProvider interface {

	// Search performs a search with the given request.
	// This is called when users search via the search hero or global search.
	Search(ctx context.Context, req *SearchProviderRequest) (*SearchProviderResponse, error)

	// GetSuggestions returns contextual suggestions for the search hero.
	// Suggestions can be personalized based on user, time, weather, etc.
	GetSuggestions(ctx context.Context, req *SuggestionRequest) (*SuggestionResponse, error)

	// GetSearchProviderInfo returns metadata about this search provider.
	// Used for provider selection UI and priority ordering.
	GetSearchProviderInfo(ctx context.Context) (*SearchProviderInfo, error)
	// contains filtered or unexported methods
}

type SearchProviderInfo struct {
	// ID is a unique identifier for this provider.
	// Example: "semantic-search", "basic-search"
	ID string

	// Name is the human-readable name.
	// Example: "AI-Powered Search", "Basic Search"
	Name string

	// Description describes what this provider does.
	// Example: "Semantic search using AI embeddings"
	Description string

	// Icon is the icon name to display.
	// Common icons: "sparkles", "search", "brain"
	Icon string

	// Priority determines which provider is used by default.
	// Higher values = higher priority. Suggested ranges:
	//   100+ = AI-powered providers (semantic search)
	//   50   = Enhanced providers (fuzzy matching)
	//   10   = Basic providers (text search)
	Priority int

	// Capabilities lists what this provider supports.
	// Values:
	//   "natural_language" - Understands natural language queries
	//   "suggestions"      - Provides contextual suggestions
	//   "context_aware"    - Uses user context (time, weather, etc.)
	//   "fuzzy_matching"   - Handles typos and variations
	Capabilities []string
}

type SearchProviderRequest struct {
	// Query is the search query text.
	Query string

	// EntityTypes filters results by media types.
	// Empty means all types. Example: ["movie", "tv_show"]
	EntityTypes []string

	// Limit is the maximum number of results to return.
	Limit int

	// UserID is the requesting user (for context enrichment).
	UserID string
}

type SearchProviderResponse struct {
	// Results is the list of search results.
	Results []SearchResult

	// Total is the total number of results (may be more than len(Results)).
	Total int

	// Provider is the ID of the provider that served this result.
	Provider string

	// Fallback indicates if this is a fallback result (basic text search).
	Fallback bool
}

type SearchResult struct {
	// EntityType is the media type: "movie", "tv_show", "tv_episode", etc.
	EntityType string

	// EntityID is the database ID of the media item.
	EntityID int64

	// Title is the display title.
	Title string

	// Year is the release/air year.
	Year int

	// Poster is the URL to the poster image.
	Poster string

	// Score is the relevance score (0.0-1.0).
	Score float32

	// Reason is an optional explanation for why this result matched.
	// Example: "Matches your search for 'sci-fi adventure'"
	Reason string
}

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

type SemanticSearchRequest struct {
	Query       string   // Natural language search query
	EntityTypes []string // Filter by entity types: "movie", "tv_show", "tv_episode", etc.
	Limit       int      // Maximum number of results
	UserID      string   // Optional user ID for context enrichment (location, time)
}

type SemanticSearchResponse struct {
	Results []SemanticSearchResult
	Total   int
}

type SemanticSearchResult struct {
	EntityType string  // "movie", "tv_show", etc.
	EntityID   int64   // Database ID of the entity
	Similarity float32 // Cosine similarity score (0.0 to 1.0)
	Text       string  // The indexed text that matched
}

type ShowWhen struct {
	Field string
	Value any
}

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

type StreamChunk struct {
	Payload        []byte            // Serialized response proto
	ProviderPlugin string            // Which plugin is streaming
	Metadata       map[string]string // Chunk metadata
	Error          error             // Error if chunk failed
}

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

type SubtitleTrack struct {
	Language   string // ISO 639-1/2 code
	Codec      string // "srt", "ass", "pgs", "vobsub"
	IsForced   bool
	IsSDH      bool // Subtitles for Deaf/Hard of Hearing
	IsExternal bool // External file vs embedded
}

type Suggestion struct {
	// ID is a unique identifier for this suggestion.
	ID string `json:"id"`

	// Label is the display text.
	Label string `json:"label"`

	// Icon is the icon name to display.
	// Common icons: "fire", "cloud-rain", "sun", "moon", "snowflake", "heart"
	Icon string `json:"icon,omitempty"`

	// Description is an optional subtitle.
	Description string `json:"description,omitempty"`

	// Style affects rendering: "primary", "secondary", "accent".
	Style string `json:"style,omitempty"`

	// Action defines what happens when the suggestion is clicked.
	Action SuggestionAction `json:"action"`
}

type SuggestionAction struct {
	// Type is the action type: "search", "filter", "navigate".
	Type string `json:"type"`

	// Query is the search query for Type="search".
	Query string `json:"query,omitempty"`

	// Filter is filter parameters for Type="filter".
	Filter map[string]string `json:"filter,omitempty"`

	// URL is the navigation URL for Type="navigate".
	URL string `json:"url,omitempty"`
}

type SuggestionRequest struct {
	// UserID is the requesting user (for personalization).
	UserID string

	// Context describes where suggestions will be shown.
	// Values: "homepage" (search hero), "search_focus" (focused search input)
	Context string

	// Limit is the maximum number of suggestions to return.
	Limit int
}

type SuggestionResponse struct {
	// Suggestions is the list of suggestions to display.
	Suggestions []Suggestion
}

type SystemInfo struct {
	// RAM in bytes
	RAMBytes uint64

	// Available RAM in bytes
	RAMAvailableBytes uint64

	// Whether the system has a GPU
	HasGPU bool

	// VRAM in bytes
	VRAMBytes uint64

	// GPU name
	GPUName string

	// CPU core count
	CPUCores int

	// CPU model name
	CPUModel string

	// Operating system: "linux", "darwin", "windows"
	OS string

	// Architecture: "amd64", "arm64"
	Arch string
}

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

type TrendingItem struct {
	// ExternalID is the external identifier in format "source:id".
	// Example: "tmdb:12345", "imdb:tt1234567"
	ExternalID string `json:"external_id"`

	// MediaType is "movie" or "tv".
	MediaType string `json:"media_type"`

	// Title is the display title.
	Title string `json:"title"`

	// Year is the release/air year.
	Year int `json:"year"`

	// Popularity is the provider-specific popularity score.
	// Higher is more popular. Scale varies by provider.
	Popularity float32 `json:"popularity"`

	// PosterPath is the external URL to the poster image.
	// Example: "https://image.tmdb.org/t/p/w500/abc123.jpg"
	PosterPath string `json:"poster_path,omitempty"`

	// Overview is a brief description/plot summary.
	Overview string `json:"overview,omitempty"`

	// LocalID is the matched local library ID (filled in by the core service).
	// Nil if not matched to local library.
	LocalID *int64 `json:"local_id,omitempty"`

	// LocalMatched indicates whether this item was matched to the local library.
	LocalMatched bool `json:"local_matched"`
}

type TrendingProvider interface {

	// GetTrending returns currently trending items from this provider.
	// The response contains external IDs that the core service matches
	// against the user's local library.
	GetTrending(ctx context.Context, req *TrendingRequest) (*TrendingResponse, error)

	// GetTrendingProviderInfo returns metadata about this trending source.
	// Used for provider selection and capability discovery.
	GetTrendingProviderInfo(ctx context.Context) (*TrendingProviderInfo, error)
	// contains filtered or unexported methods
}

type TrendingProviderGRPCPlugin struct {
	plugin.Plugin
	Impl TrendingProvider
}

type TrendingProviderInfo struct {
	// ID is a unique identifier for this provider.
	// Example: "tmdb", "trakt"
	ID string

	// Name is the human-readable name.
	// Example: "TMDb Trending", "Trakt Popular"
	Name string

	// Description describes what this provider offers.
	// Example: "Trending movies and TV shows from The Movie Database"
	Description string

	// Windows lists supported time windows.
	// Example: ["day", "week"]
	Windows []string

	// MediaTypes lists supported media types.
	// Example: ["movie", "tv", "all"]
	MediaTypes []string

	// UpdateFreq describes how often data is updated.
	// Values: "hourly", "daily", "weekly"
	UpdateFreq string
}

type TrendingRequest struct {
	// MediaType filters by media type.
	// Values: "movie", "tv", "all" (default: "all")
	MediaType string

	// Window is the time window for trending.
	// Values: "day", "week" (default: "week")
	Window string

	// Limit is the maximum number of items to return.
	// Default: 20
	Limit int

	// Region is an optional ISO 3166-1 country code for regional trending.
	// Example: "US", "GB", "DE"
	Region string
}

type TrendingResponse struct {
	// Items is the list of trending items.
	Items []TrendingItem

	// Window is the time window used.
	Window string

	// Source is the provider that served this data.
	// Example: "tmdb", "trakt"
	Source string

	// CachedAt is the Unix timestamp when this data was fetched.
	// Used for cache management.
	CachedAt int64
}

type TrendingResult struct {
	// Items contains trending items matched to the local library.
	Items []TrendingItem

	// Source is the provider that served the original data.
	Source string

	// Window is the time window used.
	Window string

	// TotalMatched is the number of items matched to local library.
	TotalMatched int

	// TotalTrending is the total trending items from the provider.
	TotalTrending int
}

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

type VectorSearchEnricherPlugin interface {
	EnricherPlugin
	VectorSearchPlugin
}

type VectorSearchGRPCPlugin struct {
	plugin.Plugin
	Impl VectorSearchPlugin
}

type VectorSearchPlugin interface {

	// Search performs semantic search across indexed media.
	// The query is converted to an embedding and matched against stored embeddings.
	Search(ctx context.Context, req *SemanticSearchRequest) (*SemanticSearchResponse, error)

	// FindSimilar finds items similar to a given entity.
	// Uses the entity's stored embedding to find similar items.
	FindSimilar(ctx context.Context, req *FindSimilarRequest) (*SemanticSearchResponse, error)

	// GetStatus returns the current indexing status and statistics.
	GetStatus(ctx context.Context) (*VectorSearchStatus, error)

	// IndexLibrary triggers indexing for all media in a library.
	// Indexing runs in the background; use GetStatus to monitor progress.
	IndexLibrary(ctx context.Context, req *IndexLibraryRequest) (*IndexLibraryResponse, error)

	// CancelIndexing cancels any running indexing operation.
	CancelIndexing(ctx context.Context) error
	// contains filtered or unexported methods
}

type VectorSearchRequest struct {
	// QueryVector is the embedding to search for similar items
	QueryVector []float32

	// EntityTypes filters results by type (empty = all types)
	EntityTypes []string

	// Limit is the maximum number of results (default: 20)
	Limit int

	// Offset for pagination
	Offset int

	// MinSimilarity filters results below this threshold (0.0-1.0)
	MinSimilarity float32
}

type VectorSearchResponse struct {
	// Results ordered by similarity (highest first)
	Results []VectorSearchResult

	// TotalCount is the total number of matching embeddings
	TotalCount int
}

type VectorSearchResult struct {
	// EntityType of the matched embedding
	EntityType string

	// EntityID of the matched embedding
	EntityID int64

	// Similarity score (0.0-1.0, higher is more similar)
	Similarity float32

	// Text that was embedded
	Text string
}

type VectorSearchStatus struct {
	IsIndexing   bool              // Whether indexing is currently running
	Progress     *IndexingProgress // Current operation progress (if indexing)
	Stats        []EntityTypeStats // Per-entity-type statistics
	TotalIndexed int64             // Total embeddings stored
}

type WatchProgress struct {
	MediaID         int64
	MediaType       string  // "movie", "tv_episode"
	ProgressSeconds float64 // Current playback position
	DurationSeconds float64 // Total duration
	ProgressPercent float64 // Progress as percentage (0-100)
	IsWatched       bool    // True if marked as watched
	LastWatchedAt   time.Time
}

type Weather struct {
	Temperature   float32 // Celsius
	Humidity      int     // Percentage
	IsDay         bool
	Precipitation float32 // mm
	CloudCover    int     // Percentage
	WeatherCode   int     // WMO code
	Condition     string  // sunny, cloudy, rainy, snowy, stormy, foggy
	TimeOfDay     string  // morning, afternoon, evening, night
	Season        string  // spring, summer, fall, winter
}

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

type Widget struct {
	// ID is a unique identifier for this widget within the plugin.
	// Example: "rec-for-you", "search-hero"
	ID string `json:"id"`

	// Type determines how the widget is rendered.
	// Use WidgetTypeSearchHero, WidgetTypeMediaRow, etc.
	Type string `json:"type"`

	// Location specifies where on the home screen this widget appears.
	// Use LocationHomepageTop or LocationHomepageSections.
	Location string `json:"location"`

	// ClientTypes specifies which clients should render this widget.
	// Use ["all"] for all clients, or specific types like ["web", "ios"].
	// Clients filter widgets by their type and only render matching ones.
	ClientTypes []string `json:"client_types"`

	// Priority determines order within a location (higher = rendered first).
	// Use 100 for critical widgets, 50 for normal, 0 for fallback.
	Priority int `json:"priority"`

	// CacheTTLSeconds is how long clients should cache this widget's data.
	// Use 60 for frequently changing data, 3600 for stable data.
	CacheTTLSeconds int `json:"cache_ttl_seconds,omitempty"`

	// Config contains widget-specific configuration passed to the client.
	// Common fields:
	//   - endpoint: HTTP endpoint to fetch widget data (e.g., "/recommendations")
	//   - title: Default title for the widget
	//   - show_suggestions: For search-hero, whether to show suggestion chips
	Config map[string]any `json:"config,omitempty"`

	// RequiredCapability makes this widget only appear when a capability is available.
	// Example: "search_provider" - only show if semantic search is enabled.
	RequiredCapability string `json:"required_capability,omitempty"`

	// SettingsKey references a boolean setting that controls widget visibility.
	// When the setting is false, the widget is hidden.
	// Example: "enabled", "show_recommendations"
	SettingsKey string `json:"settings_key,omitempty"`
}

type WidgetCoreGRPCPlugin struct {
	plugin.Plugin
	Impl WidgetPlugin
	// contains filtered or unexported fields
}

type WidgetDataRequest struct {
	// WidgetID is the widget being requested.
	WidgetID string

	// UserID is the requesting user (for personalization).
	UserID string

	// ClientType is the type of client making the request.
	ClientType string

	// ImageSize is the preferred image size ("small", "medium", "large").
	ImageSize string
}

type WidgetDataResponse struct {
	// Data is the widget-specific data to render.
	// Shape depends on widget type (see WidgetType* constants).
	Data map[string]any `json:"data"`

	// CacheTTLSeconds overrides the widget's default cache TTL.
	CacheTTLSeconds int `json:"cache_ttl_seconds,omitempty"`
}

type WidgetError struct {
	// WidgetID is the widget that failed.
	WidgetID string

	// PluginID is the plugin that provides the widget.
	PluginID string

	// Error is the error message.
	Error string

	// Timestamp is when the error occurred.
	Timestamp int64
}

type WidgetPlugin interface {

	// Initialize is called when the plugin is loaded.
	// Config is the contents of config.yml passed by the host.
	// Services provides access to host services (storage, data, etc.) - may have nil fields.
	Initialize(ctx context.Context, dataDir string, config []byte, services *HostServices) error

	// Shutdown is called before the plugin is unloaded.
	// Use this to clean up any resources.
	Shutdown(ctx context.Context) error

	// GetSettingsSchema returns a JSON Schema describing the plugin's configurable settings.
	// Use Schema.Build() to generate this from your schema definition.
	// Include Widgets() to register home screen widgets.
	GetSettingsSchema() ([]byte, error)

	// Configure applies new settings to the plugin.
	Configure(settings []byte) error

	// IsConfigured returns whether the plugin is properly configured.
	// Plugins requiring API keys should return false until the key is set.
	// The host uses this to exclude unconfigured plugins from capability resolution.
	IsConfigured() bool

	// GetRoutes returns HTTP routes this plugin exposes.
	GetRoutes() []Route

	// HandleHTTP handles a non-streaming HTTP request.
	HandleHTTP(ctx context.Context, req *HTTPRequest) (*HTTPResponse, error)
	// contains filtered or unexported methods
}