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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
// 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
}