llm

type ChatRequest struct {
	// SystemPrompt is the system message that sets the assistant's behavior.
	SystemPrompt string

	// UserPrompt is the user's message/question.
	UserPrompt string

	// MaxTokens limits the response length (default: 256).
	MaxTokens int

	// Temperature controls randomness (0.0-2.0, default: 0.7).
	// Use nil for default, or pointer to 0.0 for deterministic output.
	Temperature *float64
}

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

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

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

	// TotalTokens is the total tokens used.
	TotalTokens int

	// Model is the model that generated the response.
	Model string

	// FinishReason indicates why generation stopped ("stop", "length", etc.).
	FinishReason string
}

type Client interface {
	// ChatCompletion sends a chat completion request and returns the response.
	ChatCompletion(ctx context.Context, req ChatRequest) (*ChatResponse, error)

	// Model returns the model identifier being used.
	Model() string

	// Close releases any resources held by the client.
	Close() error
}

type CommunitySummaryData struct {
	EntityCount    int
	Domains        []DomainGroup // Grouped by domain from entity ID part[2]
	DominantDomain string        // Most common domain, or "mixed"
	OrgPlatform    string        // Common org.platform if uniform
	Keywords       string
	SampleEntities []EntityParts // Parsed entity samples
}

type CommunitySummaryInfo struct {
	Summary     string
	EntityCount int
	Keywords    string
}

type Config struct {
	// Provider specifies which LLM backend to use.
	// Values: "openai" (any OpenAI-compatible API), "none" (disabled)
	Provider string `json:"provider"`

	// BaseURL is the base URL of the LLM service.
	// Examples:
	//   - "http://shimmy:8080/v1" (local shimmy)
	//   - "https://api.openai.com/v1" (OpenAI cloud)
	BaseURL string `json:"base_url"`

	// Model is the model identifier to use.
	// Examples:
	//   - "mistral-7b-instruct" (shimmy)
	//   - "gpt-4" (OpenAI)
	Model string `json:"model"`

	// APIKey for authentication (optional for local services).
	APIKey string `json:"api_key,omitempty"`

	// TimeoutSeconds for HTTP requests (default: 60).
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`

	// MaxRetries for transient failures (default: 3).
	MaxRetries int `json:"max_retries,omitempty"`

	// PromptsFile is the path to a JSON file with custom prompts.
	// If not specified, uses embedded default prompts.
	PromptsFile string `json:"prompts_file,omitempty"`

	// Domain specifies which prompt domain to use (e.g., "iot", "default").
	// Allows domain-specific prompts registered by processors.
	Domain string `json:"domain,omitempty"`
}

type ContentFetcher interface {
	// FetchEntityContent retrieves title/abstract for entities with StorageRefs.
	// Returns map[entityID]*EntityContent for successful fetches.
	// Missing content is not an error - returns partial results gracefully.
	// Entities without StorageRef are skipped silently.
	FetchEntityContent(ctx context.Context, entities []*gtypes.EntityState) (map[string]*EntityContent, error)
}

type ContentFetcherOption func(*NATSContentFetcher) error

type DomainGroup struct {
	Domain      string       // e.g., "environmental", "content"
	Count       int          // Total entities in domain
	SystemTypes []SystemType // system.type breakdown
}

type EntityContent struct {
	Title    string // From ContentRole "title"
	Abstract string // From ContentRole "abstract" or description
}

type EntityDescriptionData struct {
	ID            string
	Type          string
	Properties    []PropertyInfo
	Relationships []RelationshipInfo
}

type EntityParts struct {
	Full     string // Complete entity ID
	Org      string // Part 0: Organization
	Platform string // Part 1: Platform
	Domain   string // Part 2: Business domain
	System   string // Part 3: System/subsystem
	Type     string // Part 4: Entity type
	Instance string // Part 5: Instance ID
	Title    string // Entity title from content store (optional)
	Abstract string // Entity abstract from content store (optional)
}

type EntitySample struct {
	ID          string
	Type        string
	Name        string
	Description string // From content store abstract (optional)
}

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

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

type OpenAIConfig struct {
	// BaseURL is the base URL of the LLM service.
	// Examples:
	//   - "http://shimmy:8080/v1" (shimmy local inference)
	//   - "http://localhost:8080/v1" (local development)
	//   - "https://api.openai.com/v1" (OpenAI cloud)
	BaseURL string

	// Model is the model to use for chat completions.
	// Examples:
	//   - "mistral-7b-instruct" (shimmy with Mistral)
	//   - "gpt-4" (OpenAI)
	//   - "llama2" (Ollama)
	Model string

	// APIKey for authentication (optional for local services).
	// Required for OpenAI, optional for shimmy/Ollama.
	APIKey string

	// Timeout for HTTP requests (default: 60s for LLM inference).
	Timeout time.Duration

	// MaxRetries for transient failures (default: 3).
	MaxRetries int

	// Logger for error logging (optional, defaults to slog.Default()).
	Logger *slog.Logger
}

type PromptTemplate struct {
	// System is the system message that sets assistant behavior.
	System string `json:"system"`

	// UserFormat is a Go text/template for the user message.
	UserFormat string `json:"user_format"`
}

type PropertyInfo struct {
	Predicate string
	Value     string
}

type RelationshipInfo struct {
	Predicate string
	Target    string
}

type RenderedPrompt struct {
	System string
	User   string
}

type SearchAnswerData struct {
	Query       string
	Communities []CommunitySummaryInfo
	Entities    []EntitySample
}

type SystemType struct {
	Name  string // e.g., "sensor.temperature"
	Count int
}