llm

Documentation

Overview

Package llm provides provider-neutral primitives for LLM-backed workflows.

Index

• Variables
• func EnforceResultLimits(payload []byte, limits ResultLimits) error
• func RedactText(input string, policy RedactionPolicy) string
• func ValidateMutationSafety(policy MutationPolicy, mutations []MutationRequest) error
• type AuthSpec
• type AuthType
• type Capability
• type Client
  • func NewInstrumentedClient(next Client, provider string, scope *observability.Scope, logger *slog.Logger) Client
• type ClientConfig
• type InstrumentedClient
  • func (c *InstrumentedClient) Complete(ctx context.Context, req Request) (Response, error)
  • func (c *InstrumentedClient) HealthCheck(ctx context.Context) error
• type Message
• type ModelOption
• type MutationPolicy
• type MutationRequest
• type PromptCatalog
  • func LoadPromptCatalog(fsys fs.FS, dir string) (*PromptCatalog, error)
  • func (c *PromptCatalog) Get(workflow, purpose string) (PromptDefinition, bool)
  • func (c *PromptCatalog) Len() int
  • func (c *PromptCatalog) List() []PromptDefinition
• type PromptDefinition
• type PromptVariable
• type Provider
  • func (p Provider) RequireCapabilities(required ...Capability) error
• type ProviderMetadata
• type RedactionPolicy
  • func DefaultRedactionPolicy() RedactionPolicy
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) GetProvider(name string) (Provider, error)
  • func (r *Registry) ListProviders() []Provider
  • func (r *Registry) RegisterProvider(provider Provider) error
• type Request
• type Response
• type ResponseFormat
• type ResponseFormatType
• type ResultLimits
• type Role
• type Router
  • func NewRouter(cfg RouterConfig) *Router
  • func (r *Router) Complete(ctx context.Context, tenant store.Tenant, req Request) (Response, error)
  • func (r *Router) PromptCatalog() *PromptCatalog
• type RouterConfig
• type RuntimeStore
• type Tool
• type ToolCall
• type Usage

Variables

var (
	KindNoProviderConfigured  = errors.Kind{Code: "llm_no_provider_configured", Status: http.StatusConflict}
	KindCapabilityUnsupported = errors.Kind{Code: "llm_capability_unsupported", Status: http.StatusConflict}
)

Functions

func EnforceResultLimits

func EnforceResultLimits(payload []byte, limits ResultLimits) error

EnforceResultLimits validates a raw provider result size.

func RedactText

func RedactText(input string, policy RedactionPolicy) string

RedactText masks common high-risk values before a prompt is assembled.

func ValidateMutationSafety

func ValidateMutationSafety(policy MutationPolicy, mutations []MutationRequest) error

ValidateMutationSafety validates proposed mutations before persistence.

Types

type AuthSpec

type AuthSpec struct {
	Type           AuthType `json:"type"`
	Required       bool     `json:"required"`
	RequiredScopes []string `json:"required_scopes,omitempty"`
}

AuthSpec describes provider authentication requirements.

type AuthType

type AuthType string

AuthType describes how an LLM provider authenticates.

const (
	AuthTypeNone   AuthType = "none"
	AuthTypeAPIKey AuthType = "api_key"
	AuthTypeOAuth  AuthType = "oauth"
)

type Capability

type Capability string

Capability describes a provider feature that workflows may require.

const (
	CapabilityTextGeneration Capability = "text_generation"
	CapabilityTools          Capability = "tools"
	CapabilityJSONSchema     Capability = "json_schema"
	CapabilityStreaming      Capability = "streaming"
)

type Client

type Client interface {
	Complete(ctx context.Context, req Request) (Response, error)
	HealthCheck(ctx context.Context) error
}

Client is implemented by concrete LLM providers.

func NewInstrumentedClient

func NewInstrumentedClient(next Client, provider string, scope *observability.Scope, logger *slog.Logger) Client

type ClientConfig

type ClientConfig struct {
	Config      json.RawMessage
	Credentials json.RawMessage
}

ClientConfig contains tenant runtime state needed to construct a provider client.

type InstrumentedClient

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

InstrumentedClient records provider-neutral telemetry around an LLM client.

func (*InstrumentedClient) Complete

func (c *InstrumentedClient) Complete(ctx context.Context, req Request) (Response, error)

func (*InstrumentedClient) HealthCheck

func (c *InstrumentedClient) HealthCheck(ctx context.Context) error

type Message

type Message struct {
	Role       Role   `json:"role" yaml:"role"`
	Content    string `json:"content" yaml:"content"`
	Name       string `json:"name,omitempty" yaml:"name,omitempty"`
	ToolCallID string `json:"tool_call_id,omitempty" yaml:"tool_call_id,omitempty"`
}

Message is a provider-neutral chat/message input or output.

type ModelOption

type ModelOption struct {
	ID          string `json:"id"`
	DisplayName string `json:"display_name"`
	Quality     string `json:"quality"`
	Cost        string `json:"cost"`
	Description string `json:"description,omitempty"`
	Recommended bool   `json:"recommended,omitempty"`
}

ModelOption describes one provider model preset exposed to setup UIs.

type MutationPolicy

type MutationPolicy struct {
	AllowMutations    bool
	AllowedResources  []string
	AllowedOperations []string
}

MutationPolicy controls whether a workflow may propose or execute mutations.

type MutationRequest

type MutationRequest struct {
	Resource  string
	Operation string
}

MutationRequest describes a proposed write from an LLM-enabled workflow.

type PromptCatalog

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

PromptCatalog stores prompt definitions keyed by workflow and purpose.

func LoadPromptCatalog

func LoadPromptCatalog(fsys fs.FS, dir string) (*PromptCatalog, error)

LoadPromptCatalog loads YAML prompt definitions from dir. Non-YAML files are ignored.

func (*PromptCatalog) Get

func (c *PromptCatalog) Get(workflow, purpose string) (PromptDefinition, bool)

Get returns the prompt for a workflow and purpose.

func (*PromptCatalog) Len

func (c *PromptCatalog) Len() int

Len returns the number of prompt definitions.

func (*PromptCatalog) List

func (c *PromptCatalog) List() []PromptDefinition

List returns all prompts sorted by workflow and purpose.

type PromptDefinition

type PromptDefinition struct {
	ID                   string           `json:"id" yaml:"id"`
	Version              int              `json:"version" yaml:"version"`
	Workflow             string           `json:"workflow" yaml:"workflow"`
	Purpose              string           `json:"purpose" yaml:"purpose"`
	Description          string           `json:"description,omitempty" yaml:"description,omitempty"`
	RequiredCapabilities []Capability     `json:"required_capabilities,omitempty" yaml:"required_capabilities,omitempty"`
	Variables            []PromptVariable `json:"variables,omitempty" yaml:"variables,omitempty"`
	Messages             []Message        `json:"messages" yaml:"messages"`
	ResultLimits         ResultLimits     `json:"result_limits,omitempty" yaml:"result_limits,omitempty"`
}

PromptDefinition is a centrally managed prompt file.

type PromptVariable

type PromptVariable struct {
	Name        string `json:"name" yaml:"name"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Required    bool   `json:"required" yaml:"required"`
}

PromptVariable describes a template variable accepted by a prompt.

type Provider

type Provider struct {
	Metadata  ProviderMetadata
	NewClient func(ClientConfig) (Client, error)
}

Provider defines an LLM provider and the client it can construct.

func (Provider) RequireCapabilities

func (p Provider) RequireCapabilities(required ...Capability) error

RequireCapabilities returns an error if the provider lacks a required capability.

type ProviderMetadata

type ProviderMetadata struct {
	Name         string          `json:"name"`
	DisplayName  string          `json:"display_name,omitempty"`
	Description  string          `json:"description,omitempty"`
	Auth         AuthSpec        `json:"auth"`
	ConfigSchema json.RawMessage `json:"config_schema,omitempty"`
	Capabilities []Capability    `json:"capabilities"`
	ModelOptions []ModelOption   `json:"model_options,omitempty"`
}

ProviderMetadata describes an LLM provider for catalog display and routing.

type RedactionPolicy

type RedactionPolicy struct {
	Replacement string
}

RedactionPolicy controls deterministic prompt redaction.

func DefaultRedactionPolicy

func DefaultRedactionPolicy() RedactionPolicy

DefaultRedactionPolicy returns the baseline privacy policy shared by workflows.

type Registry

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

Registry manages available LLM providers.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty LLM provider registry.

func (*Registry) GetProvider

func (r *Registry) GetProvider(name string) (Provider, error)

GetProvider returns a provider by name.

func (*Registry) ListProviders

func (r *Registry) ListProviders() []Provider

ListProviders returns all registered providers sorted by name.

func (*Registry) RegisterProvider

func (r *Registry) RegisterProvider(provider Provider) error

RegisterProvider registers an LLM provider.

type Request

type Request struct {
	Workflow             string          `json:"workflow,omitempty"`
	Purpose              string          `json:"purpose,omitempty"`
	Messages             []Message       `json:"messages"`
	Tools                []Tool          `json:"tools,omitempty"`
	ResponseFormat       ResponseFormat  `json:"response_format,omitempty"`
	RequiredCapabilities []Capability    `json:"required_capabilities,omitempty"`
	MaxOutputTokens      int             `json:"max_output_tokens,omitempty"`
	Temperature          *float64        `json:"temperature,omitempty"`
	Metadata             json.RawMessage `json:"metadata,omitempty"`
}

Request is the provider-neutral input for a model completion.

type Response

type Response struct {
	Messages     []Message  `json:"messages,omitempty"`
	Text         string     `json:"text,omitempty"`
	ToolCalls    []ToolCall `json:"tool_calls,omitempty"`
	Usage        Usage      `json:"usage,omitempty"`
	FinishReason string     `json:"finish_reason,omitempty"`
}

Response is the provider-neutral output from a model completion.

type ResponseFormat

type ResponseFormat struct {
	Type   ResponseFormatType `json:"type"`
	Name   string             `json:"name,omitempty"`
	Strict bool               `json:"strict,omitempty"`
	Schema json.RawMessage    `json:"schema,omitempty"`
}

ResponseFormat describes expected model output shape.

type ResponseFormatType

type ResponseFormatType string

ResponseFormatType identifies structured output requirements.

const (
	ResponseFormatText       ResponseFormatType = "text"
	ResponseFormatJSONObject ResponseFormatType = "json_object"
	ResponseFormatJSONSchema ResponseFormatType = "json_schema"
)

type ResultLimits

type ResultLimits struct {
	MaxBytes int `json:"max_bytes,omitempty" yaml:"max_bytes,omitempty"`
	MaxItems int `json:"max_items,omitempty" yaml:"max_items,omitempty"`
}

ResultLimits constrains the amount of model output a workflow may accept.

type Role

type Role string

Role identifies the speaker for a model message.

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

type Router

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

Router resolves the active tenant provider and enforces capability requirements.

func NewRouter

func NewRouter(cfg RouterConfig) *Router

NewRouter creates an LLM router.

func (*Router) Complete

func (r *Router) Complete(ctx context.Context, tenant store.Tenant, req Request) (Response, error)

Complete resolves the active provider and delegates the request.

func (*Router) PromptCatalog

func (r *Router) PromptCatalog() *PromptCatalog

PromptCatalog returns the router prompt catalog.

type RouterConfig

type RouterConfig struct {
	Registry *Registry
	Runtime  RuntimeStore
	Prompts  *PromptCatalog
	Scope    *observability.Scope
	Logger   *slog.Logger
}

RouterConfig holds router dependencies.

type RuntimeStore

type RuntimeStore interface {
	GetActiveLLMProviderRuntime(ctx context.Context, tenant store.Tenant) (store.LLMProviderRuntime, bool, error)
}

RuntimeStore is the tenant-scoped LLM runtime state needed by the router.

type Tool

type Tool struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`
}

Tool declares a callable tool exposed to an LLM provider.

type ToolCall

type ToolCall struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
}

ToolCall is a provider-neutral model tool invocation.

type Usage

type Usage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	TotalTokens  int `json:"total_tokens"`
}

Usage records provider token accounting in provider-neutral fields.