api

package
v0.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 10, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package api implements the Ollama-compatible HTTP API endpoints. This allows Thane to be used as a drop-in replacement for Ollama in Home Assistant's native Ollama integration.

The Ollama-compatible API can be served either: - On a dedicated port via OllamaServer (recommended for HA integration) - Embedded in the main server via RegisterOllamaRoutes (for single-port setups)

Package api implements the Ollama-compatible HTTP API as a separate server. This allows Thane to expose an Ollama-compatible API on port 11434 for Home Assistant integration, while keeping the native API on port 8080.

Package api implements the OpenAI-compatible HTTP API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ChatCompletionRequest 

type ChatCompletionRequest struct {
	Model    string          `json:"model"`
	Messages []agent.Message `json:"messages"`
	Stream   bool            `json:"stream,omitempty"`
}

ChatCompletionRequest is the OpenAI-compatible request format.

type ChatCompletionResponse 

type ChatCompletionResponse struct {
	ID      string   `json:"id"`
	Object  string   `json:"object"`
	Created int64    `json:"created"`
	Model   string   `json:"model"`
	Choices []Choice `json:"choices"`
	Usage   Usage    `json:"usage"`
}

ChatCompletionResponse is the OpenAI-compatible response format.

type Choice 

type Choice struct {
	Index        int           `json:"index"`
	Message      agent.Message `json:"message"`
	FinishReason string        `json:"finish_reason"`
}

Choice represents a completion choice.

type DependencyStatus 

type DependencyStatus struct {
	Name      string `json:"name"`
	Ready     bool   `json:"ready"`
	LastCheck string `json:"last_check,omitempty"`
	LastError string `json:"last_error,omitempty"`
}

DependencyStatus describes the health of a single watched dependency.

type HealthStatusFunc 

type HealthStatusFunc func() map[string]DependencyStatus

HealthStatusFunc returns dependency health information for the /health endpoint.

type OllamaChatMessage 

type OllamaChatMessage struct {
	Role    string   `json:"role"`
	Content string   `json:"content"`
	Images  []string `json:"images,omitempty"`
}

OllamaChatMessage is the Ollama message format.

type OllamaChatRequest 

type OllamaChatRequest struct {
	Model     string              `json:"model"`
	Messages  []OllamaChatMessage `json:"messages"`
	Stream    *bool               `json:"stream,omitempty"`
	Options   map[string]any      `json:"options,omitempty"`
	Format    string              `json:"format,omitempty"`
	Tools     []map[string]any    `json:"tools,omitempty"`
	Think     bool                `json:"think,omitempty"`
	KeepAlive string              `json:"keep_alive,omitempty"`
}

OllamaChatRequest is the Ollama /api/chat request format.

type OllamaChatResponse 

type OllamaChatResponse struct {
	Model              string            `json:"model"`
	CreatedAt          string            `json:"created_at"`
	Message            OllamaChatMessage `json:"message"`
	Done               bool              `json:"done"`
	DoneReason         string            `json:"done_reason,omitempty"`
	TotalDuration      int64             `json:"total_duration,omitempty"`
	LoadDuration       int64             `json:"load_duration,omitempty"`
	PromptEvalCount    int               `json:"prompt_eval_count,omitempty"`
	PromptEvalDuration int64             `json:"prompt_eval_duration,omitempty"`
	EvalCount          int               `json:"eval_count,omitempty"`
	EvalDuration       int64             `json:"eval_duration,omitempty"`
}

OllamaChatResponse is the Ollama /api/chat response format.

type OllamaModel 

type OllamaModel struct {
	Name       string            `json:"name"`
	Model      string            `json:"model"`
	ModifiedAt string            `json:"modified_at"`
	Size       int64             `json:"size"`
	Digest     string            `json:"digest"`
	Details    OllamaModelDetail `json:"details"`
}

OllamaModel represents a model in the tags response.

type OllamaModelDetail 

type OllamaModelDetail struct {
	ParentModel       string   `json:"parent_model"`
	Format            string   `json:"format"`
	Family            string   `json:"family"`
	Families          []string `json:"families"`
	ParameterSize     string   `json:"parameter_size"`
	QuantizationLevel string   `json:"quantization_level"`
}

OllamaModelDetail contains model details.

type OllamaServer 

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

OllamaServer is a dedicated server for Ollama-compatible API endpoints. It runs on a separate port (default 11434) to avoid conflicts with the native API.

Use this for dual-port setups where you want Ollama compatibility on a dedicated port (e.g., for Home Assistant integration). For single-port setups, use Server.RegisterOllamaRoutes instead.

func NewOllamaServer 

func NewOllamaServer(address string, port int, loop *agent.Loop, logger *slog.Logger) *OllamaServer

NewOllamaServer creates a new Ollama-compatible API server.

Parameters:

  • address: IP address to bind to (empty string binds to all interfaces)
  • port: Port to listen on (typically 11434 for Ollama compatibility)
  • loop: The agent loop that processes requests
  • logger: Logger for request and error logging

The server is created but not started. Call Start to begin serving requests.

func (*OllamaServer) Shutdown 

func (s *OllamaServer) Shutdown(ctx context.Context) error

Shutdown gracefully stops the server.

This method should be called to cleanly shut down the server, allowing it to finish processing active requests. The provided context can be used to set a deadline for the shutdown process.

If the server was never started or has already been shut down, this method returns nil.

func (*OllamaServer) Start 

func (s *OllamaServer) Start(ctx context.Context) error

Start begins serving Ollama-compatible HTTP requests. This method blocks until the server is shut down or encounters an error.

The server listens on the address and port specified during creation. It implements the following Ollama API endpoints:

  • POST /api/chat - Main conversation endpoint
  • POST /api/generate - Simple completion endpoint
  • GET /api/tags - List available models
  • GET /api/version - Get server version
  • GET / and HEAD / - Health check endpoints

Use Shutdown to gracefully stop the server.

type OllamaTagsResponse 

type OllamaTagsResponse struct {
	Models []OllamaModel `json:"models"`
}

OllamaTagsResponse is the Ollama /api/tags response format.

type OllamaVersionResponse 

type OllamaVersionResponse struct {
	Version string `json:"version"`
}

OllamaVersionResponse is the Ollama /api/version response.

type Server 

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

Server is the HTTP API server.

func NewServer 

func NewServer(address string, port int, loop *agent.Loop, rtr *router.Router, pricing map[string]config.PricingEntry, logger *slog.Logger) *Server

NewServer creates a new API server. The pricing map drives cost estimation in session stats; pass nil for zero-cost defaults.

func (*Server) DashboardSnapshot 

func (s *Server) DashboardSnapshot() SessionStatsSnapshot

DashboardSnapshot returns a copy of the current session stats enriched with context window, message count, and build information. This is used by the web dashboard to display runtime overview data.

func (*Server) LastRequest 

func (s *Server) LastRequest() time.Time

LastRequest returns when the most recent LLM request completed. Returns the zero value if no requests have been recorded. This method is safe for concurrent use.

func (*Server) RegisterOllamaRoutes 

func (s *Server) RegisterOllamaRoutes(mux *http.ServeMux)

RegisterOllamaRoutes adds Ollama-compatible API endpoints to the mux. Use this for single-port setups. For dual-port, use OllamaServer instead.

func (*Server) SetArchiveStore 

func (s *Server) SetArchiveStore(as *memory.ArchiveStore)

SetArchiveStore configures the archive store for archive API endpoints.

func (*Server) SetCheckpointer 

func (s *Server) SetCheckpointer(cp *checkpoint.Checkpointer)

SetCheckpointer configures the checkpointer for checkpoint API endpoints.

func (*Server) SetConnManager 

func (s *Server) SetConnManager(fn HealthStatusFunc)

SetConnManager sets the dependency health provider for the /health endpoint.

func (*Server) SetEventBus 

func (s *Server) SetEventBus(bus *events.Bus)

SetEventBus configures the event bus for the WebSocket event stream.

func (*Server) SetMemoryStore 

func (s *Server) SetMemoryStore(ms *memory.SQLiteStore)

SetMemoryStore configures the memory store for history API endpoints.

func (*Server) SetTokenObserver 

func (s *Server) SetTokenObserver(obs TokenObserver)

SetTokenObserver registers an observer that is notified after each LLM completion with the token counts from that request. This is used by the MQTT publisher's daily token accumulator.

func (*Server) SetWebServer 

func (s *Server) SetWebServer(ws WebServerRegistrar)

SetWebServer configures the web dashboard. When set, the dashboard serves HTML at "/" and the old JSON root handler becomes a fallback.

func (*Server) Shutdown 

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully stops the server.

func (*Server) Start 

func (s *Server) Start(ctx context.Context) error

Start begins serving HTTP requests.

type SessionStats 

type SessionStats struct {
	TotalInputTokens  int64     `json:"total_input_tokens"`
	TotalOutputTokens int64     `json:"total_output_tokens"`
	TotalRequests     int64     `json:"total_requests"`
	EstimatedCostUSD  float64   `json:"estimated_cost_usd"`
	ReportedBalance   float64   `json:"reported_balance_usd,omitempty"`
	BalanceSetAt      string    `json:"balance_set_at,omitempty"`
	LastRequestAt     time.Time `json:"-"` // Used by MQTT publisher, not exposed in JSON.
	// contains filtered or unexported fields
}

SessionStats tracks token usage and cost for the current session.

func (*SessionStats) LastRequest 

func (s *SessionStats) LastRequest() time.Time

LastRequest returns when the most recent LLM request completed. Returns the zero value if no requests have been recorded.

func (*SessionStats) Record 

func (s *SessionStats) Record(model string, inputTokens, outputTokens int)

Record accumulates token usage and cost for a model. Cost is computed from the config-driven pricing table.

func (*SessionStats) SetBalance 

func (s *SessionStats) SetBalance(balance float64)

func (*SessionStats) Snapshot 

func (s *SessionStats) Snapshot() SessionStatsSnapshot

type SessionStatsSnapshot 

type SessionStatsSnapshot struct {
	TotalInputTokens  int64             `json:"total_input_tokens"`
	TotalOutputTokens int64             `json:"total_output_tokens"`
	TotalRequests     int64             `json:"total_requests"`
	EstimatedCostUSD  float64           `json:"estimated_cost_usd"`
	ReportedBalance   float64           `json:"reported_balance_usd,omitempty"`
	BalanceSetAt      string            `json:"balance_set_at,omitempty"`
	ContextTokens     int               `json:"context_tokens"`
	ContextWindow     int               `json:"context_window"`
	MessageCount      int               `json:"message_count"`
	Build             map[string]string `json:"build,omitempty"`
}

SessionStatsSnapshot is a copy-safe snapshot of session stats.

type SimpleChatRequest 

type SimpleChatRequest struct {
	Message        string `json:"message"`
	ConversationID string `json:"conversation_id,omitempty"`
}

SimpleChatRequest is a minimal chat request for easy testing.

type SimpleChatResponse 

type SimpleChatResponse struct {
	Response       string   `json:"response"`
	Model          string   `json:"model"`
	ConversationID string   `json:"conversation_id"`
	ToolCalls      []string `json:"tool_calls,omitempty"` // Tool names used
}

SimpleChatResponse is a minimal chat response.

type StreamChoice 

type StreamChoice struct {
	Index        int         `json:"index"`
	Delta        StreamDelta `json:"delta"`
	FinishReason *string     `json:"finish_reason"`
}

StreamChoice represents a streaming choice with delta content.

type StreamChunk 

type StreamChunk struct {
	ID      string         `json:"id"`
	Object  string         `json:"object"`
	Created int64          `json:"created"`
	Model   string         `json:"model"`
	Choices []StreamChoice `json:"choices"`
}

StreamChunk is the SSE format for streaming responses.

type StreamDelta 

type StreamDelta struct {
	Role    string `json:"role,omitempty"`
	Content string `json:"content,omitempty"`
}

StreamDelta represents incremental content.

type TokenObserver 

type TokenObserver interface {
	OnTokens(inputTokens, outputTokens int)
}

TokenObserver is notified after each LLM completion with the token counts from that request. Implementations must be safe for concurrent use.

type Usage 

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

Usage represents token usage.

type WebServerRegistrar 

type WebServerRegistrar interface {
	RegisterRoutes(mux *http.ServeMux)
}

WebServerRegistrar is implemented by types that can register HTTP routes on a ServeMux. It decouples the API server from the concrete web.WebServer type so that the web package can be wired in without a circular import.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.