Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

11.6 KB
Raw Blame
// Package providers contains AI provider client implementations
package providers

import (
	"context"
	"time"

	"github.com/rcourtman/pulse-go-rewrite/internal/agentcapabilities"
)

// Message represents a chat message
type Message struct {
	Role             string      `json:"role"`                        // "user", "assistant", "system"
	Content          string      `json:"content"`                     // Text content (simple case)
	ReasoningContent string      `json:"reasoning_content,omitempty"` // DeepSeek thinking mode
	ToolCalls        []ToolCall  `json:"tool_calls"`                  // For assistant messages with tool calls
	ToolResult       *ToolResult `json:"tool_result,omitempty"`       // For user messages with tool results
}

func EmptyMessage() Message {
	return Message{}.NormalizeCollections()
}

func (m Message) NormalizeCollections() Message {
	if m.ToolCalls == nil {
		m.ToolCalls = []ToolCall{}
	}
	for i := range m.ToolCalls {
		m.ToolCalls[i] = m.ToolCalls[i].NormalizeCollections()
	}
	return m
}

// ToolCall represents a tool invocation from the AI. It aliases the shared
// Pulse Intelligence provider-call shape so Assistant execution projects
// model-selected calls through the same boundary as external agent adapters.
type ToolCall = agentcapabilities.ProviderToolCall

func EmptyToolCall() ToolCall {
	return agentcapabilities.EmptyProviderToolCall()
}

// ToolResult represents the result of a tool execution.
type ToolResult = agentcapabilities.ProviderToolResult

// Tool represents an AI tool definition. It aliases the shared Pulse
// Intelligence provider tool shape so Assistant provider clients project tools
// through the same schema boundary.
type Tool = agentcapabilities.ProviderTool

func EmptyTool() Tool {
	return agentcapabilities.EmptyProviderTool()
}

// ToolChoiceType represents how the model should choose tools
type ToolChoiceType string

const (
	// ToolChoiceNone prevents the model from using any tools
	ToolChoiceNone ToolChoiceType = "none"
	// ToolChoiceRequired asks providers with a native forcing mechanism to
	// require at least one tool call.
	ToolChoiceRequired ToolChoiceType = "required"
)

// ToolChoice controls how the model selects tools
type ToolChoice struct {
	Type ToolChoiceType `json:"type"`
}

// ReasoningEffort is a provider-neutral hint for transports that expose a
// reasoning-depth control separately from their output-token allowance.
// Providers without an equivalent control may ignore it; MaxTokens remains
// the canonical hard output allowance where the provider supports one.
type ReasoningEffort string

const (
	ReasoningEffortLow    ReasoningEffort = "low"
	ReasoningEffortMedium ReasoningEffort = "medium"
	ReasoningEffortHigh   ReasoningEffort = "high"
)

func (e ReasoningEffort) Valid() bool {
	switch e {
	case "", ReasoningEffortLow, ReasoningEffortMedium, ReasoningEffortHigh:
		return true
	default:
		return false
	}
}

// ChatRequest represents a request to the AI provider
type ChatRequest struct {
	Messages        []Message       `json:"messages"`
	Model           string          `json:"model"`
	ExecutionID     string          `json:"execution_id,omitempty"` // Stable higher-level run ID shared across related provider turns
	MaxTokens       int             `json:"max_tokens,omitempty"`
	ReasoningEffort ReasoningEffort `json:"reasoning_effort,omitempty"`
	Temperature     float64         `json:"temperature,omitempty"`
	// TemperatureSet marks Temperature as an explicit request value. Adapters
	// treat a zero Temperature without this flag as "unset" and let the
	// provider default apply; probes that pin temperature 0 for deterministic
	// output (#1624) need the zero forwarded rather than dropped.
	TemperatureSet bool `json:"-"`
	// MinContextTokens asks providers with a runtime context-size control
	// (Ollama num_ctx) to serve the request with at least this many context
	// tokens. Ollama otherwise loads models at its server default (typically
	// 4096) regardless of the model's trained window and silently truncates
	// large prompts (#1624). Providers without such a control ignore it.
	MinContextTokens int    `json:"-"`
	System           string `json:"system,omitempty"` // System prompt (Anthropic style)
	// SystemCacheablePrefix marks the stable leading portion of System. When
	// set and it is an exact prefix of System, providers with prompt-caching
	// support (Anthropic) place a cache breakpoint after this prefix so the
	// frozen base plus mode text is reused across turns while per-turn content
	// appended after it stays outside the cached block. Providers without that
	// control ignore it and send System unchanged.
	SystemCacheablePrefix string        `json:"-"`
	Tools                 []Tool        `json:"tools,omitempty"`       // Available tools
	ToolChoice            *ToolChoice   `json:"tool_choice,omitempty"` // nil = model-owned automatic selection; none = text-only safety brake; required = provider-native forced tool use where supported
	StreamIdleTimeout     time.Duration `json:"-"`                     // Optional use-case-specific inter-chunk stall allowance; provider request payloads must not serialize it.
}

func (r ChatRequest) NormalizeCollections() ChatRequest {
	if r.Messages == nil {
		r.Messages = []Message{}
	}
	for i := range r.Messages {
		r.Messages[i] = r.Messages[i].NormalizeCollections()
	}
	if r.Tools == nil {
		r.Tools = []Tool{}
	}
	for i := range r.Tools {
		r.Tools[i] = r.Tools[i].NormalizeCollections()
	}
	return r
}

// ChatResponse represents a response from the AI provider
type ChatResponse struct {
	Content          string     `json:"content"`
	ReasoningContent string     `json:"reasoning_content,omitempty"` // DeepSeek thinking mode
	Model            string     `json:"model"`
	StopReason       string     `json:"stop_reason,omitempty"` // "end_turn", "tool_use"
	ToolCalls        []ToolCall `json:"tool_calls"`            // Tool invocations
	InputTokens      int        `json:"input_tokens,omitempty"`
	OutputTokens     int        `json:"output_tokens,omitempty"`
	// CacheCreationInputTokens and CacheReadInputTokens are the prompt-cache
	// buckets a provider reports beside InputTokens (Anthropic). InputTokens
	// stays the provider's ordinary, uncached input count, so the three never
	// overlap; the cost ledger prices each bucket at its own rate.
	CacheCreationInputTokens int `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens     int `json:"cache_read_input_tokens,omitempty"`
}

func (r ChatResponse) NormalizeCollections() ChatResponse {
	if r.ToolCalls == nil {
		r.ToolCalls = []ToolCall{}
	}
	for i := range r.ToolCalls {
		r.ToolCalls[i] = r.ToolCalls[i].NormalizeCollections()
	}
	return r
}

// ModelInfo represents information about an available model
type ModelInfo struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	CreatedAt   int64  `json:"created_at,omitempty"`
	Notable     bool   `json:"notable"` // Whether this is a "latest and greatest" model
	Provider    string `json:"provider,omitempty"`
}

// ModelDiagnostics captures optional runtime-owned metadata for a concrete
// model. Providers that can inspect a locally installed model (currently
// Ollama) expose this in addition to the ordinary model catalogue so Patrol
// readiness can bind evidence to the model build that was actually tested.
// Capability metadata is advisory; callers must still exercise the real chat
// and tool-call transport before declaring the model ready.
type ModelDiagnostics struct {
	Fingerprint       string   `json:"fingerprint,omitempty"`
	Family            string   `json:"family,omitempty"`
	ParameterSize     string   `json:"parameter_size,omitempty"`
	QuantizationLevel string   `json:"quantization_level,omitempty"`
	ContextWindow     int      `json:"context_window,omitempty"`
	Capabilities      []string `json:"capabilities,omitempty"`
}

// ModelDiagnosticsProvider is implemented by providers that can inspect the
// exact installed model build without sending a chat completion.
type ModelDiagnosticsProvider interface {
	InspectModel(ctx context.Context, model string) (*ModelDiagnostics, error)
}

// Provider defines the interface for AI providers
type Provider interface {
	// Chat sends a chat request and returns the response
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)

	// TestConnection validates the API key and connectivity
	TestConnection(ctx context.Context) error

	// Name returns the provider name
	Name() string

	// ListModels returns available models from the provider's API
	// Returns nil if the provider doesn't support listing models
	ListModels(ctx context.Context) ([]ModelInfo, error)
}

// StreamEvent represents a streaming event from the AI provider
type StreamEvent struct {
	Type string      // "content", "thinking", "tool_start", "tool_progress", "tool_end", "done", "error"
	Data interface{} // Type-specific data
}

// ContentEvent is the data for "content" stream events
type ContentEvent struct {
	Text string `json:"text"`
}

// ThinkingEvent is the data for "thinking" stream events (extended thinking/reasoning)
type ThinkingEvent struct {
	Text string `json:"text"`
}

// ToolStartEvent is the data for "tool_start" stream events
type ToolStartEvent struct {
	ID    string                 `json:"id"`
	Name  string                 `json:"name"`
	Input map[string]interface{} `json:"input"`
}

func (e ToolStartEvent) NormalizeCollections() ToolStartEvent {
	if e.Input == nil {
		e.Input = map[string]interface{}{}
	}
	return e
}

// ToolProgressEvent is the data for "tool_progress" stream events.
// Providers use this to mutate an already visible pending tool row while the
// model is still streaming tool arguments or while execution advances.
type ToolProgressEvent struct {
	ID       string                 `json:"id"`
	Name     string                 `json:"name"`
	Input    map[string]interface{} `json:"input,omitempty"`
	RawInput string                 `json:"raw_input,omitempty"`
	Phase    string                 `json:"phase,omitempty"`
	Message  string                 `json:"message,omitempty"`
}

func (e ToolProgressEvent) NormalizeCollections() ToolProgressEvent {
	if e.Input == nil {
		e.Input = map[string]interface{}{}
	}
	return e
}

// ToolEndEvent is the data for "tool_end" stream events
type ToolEndEvent struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Result  string `json:"result,omitempty"`
	IsError bool   `json:"is_error,omitempty"`
}

// ErrorEvent is the data for "error" stream events
type ErrorEvent struct {
	Message string `json:"message"`
}

// DoneEvent is the data for "done" stream events
type DoneEvent struct {
	StopReason   string     `json:"stop_reason,omitempty"`
	ToolCalls    []ToolCall `json:"tool_calls"`
	InputTokens  int        `json:"input_tokens,omitempty"`
	OutputTokens int        `json:"output_tokens,omitempty"`
	// Prompt-cache buckets, disjoint from InputTokens; see ChatResponse.
	CacheCreationInputTokens int `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens     int `json:"cache_read_input_tokens,omitempty"`
}

func (e DoneEvent) NormalizeCollections() DoneEvent {
	if e.ToolCalls == nil {
		e.ToolCalls = []ToolCall{}
	}
	for i := range e.ToolCalls {
		e.ToolCalls[i] = e.ToolCalls[i].NormalizeCollections()
	}
	return e
}

// StreamCallback is called for each streaming event
type StreamCallback func(event StreamEvent)

// StreamingProvider extends Provider with streaming support
type StreamingProvider interface {
	Provider
	// ChatStream sends a chat request and streams the response via callback
	ChatStream(ctx context.Context, req ChatRequest, callback StreamCallback) error
	// SupportsThinking returns true if the model supports extended thinking/reasoning
	SupportsThinking(model string) bool
}