provider

package
v4.0.19 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package provider defines the complete model-provider boundary consumed by Floret's runtime. Gateways own transport; the runtime owns the Agent loop.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrContextOverflow reports that a provider rejected a request because its
	// rendered context exceeded the model limit.
	ErrContextOverflow = errors.New("provider context overflow")
)

Functions

This section is empty.

Types

type AnthropicOptions 

type AnthropicOptions struct {
	Provider              string
	Model                 string
	BaseURL               string
	APIKey                string
	StateCompatibilityKey string
	HTTPClient            *http.Client
	Capabilities          Capabilities
}

AnthropicOptions configures an explicit Anthropic messages transport. BaseURL is the API root; the gateway sends requests to BaseURL/messages.

type Attachment 

type Attachment struct {
	ResourceRef string               `json:"resource_ref"`
	Name        string               `json:"name"`
	MIMEType    string               `json:"mime_type"`
	SizeBytes   int64                `json:"size_bytes,omitempty"`
	TextStats   *AttachmentTextStats `json:"text_stats,omitempty"`
}

Attachment is an opaque host resource descriptor visible to a gateway.

type AttachmentPayloadMode 

type AttachmentPayloadMode string

AttachmentPayloadMode declares whether Request attachments stay as opaque descriptors or are expanded by a prepared request. 

const (
	// AttachmentDescriptors keeps attachment resource references opaque.
	AttachmentDescriptors AttachmentPayloadMode = "descriptors"
	// AttachmentExpanded requires Gateway to implement RequestPreparer.
	AttachmentExpanded AttachmentPayloadMode = "expanded"
)

type AttachmentTextStats 

type AttachmentTextStats struct {
	UnicodeCodePointCount int64 `json:"unicode_code_points"`
	LogicalLineCount      int64 `json:"logical_lines"`
}

AttachmentTextStats is a stable display snapshot for textual attachments.

type Capabilities 

type Capabilities struct {
	Reasoning           ReasoningSupport           `json:"reasoning"`
	ReasoningCapability config.ReasoningCapability `json:"reasoning_capability,omitempty"`
	AttachmentPayload   AttachmentPayloadMode      `json:"attachment_payload"`
}

Capabilities describes provider behavior that affects request validation.

func (Capabilities) Validate 

func (capabilities Capabilities) Validate() error

Validate verifies an explicit capability declaration.

type Event 

type Event struct {
	Type           EventType         `json:"type"`
	Text           string            `json:"text,omitempty"`
	ToolCallStream *ToolCallStream   `json:"tool_call_stream,omitempty"`
	ToolCalls      []ToolCall        `json:"tool_calls,omitempty"`
	HostedToolCall *ToolCall         `json:"hosted_tool_call,omitempty"`
	HostedResult   *HostedToolResult `json:"hosted_result,omitempty"`
	Sources        []Source          `json:"sources,omitempty"`
	Reason         string            `json:"reason,omitempty"`
	Usage          Usage             `json:"usage,omitempty"`
	ResponseID     string            `json:"response_id,omitempty"`
	ResponseState  *State            `json:"response_state,omitempty"`
	Err            error             `json:"-"`
}

Event carries one streamed provider output.

type EventType 

type EventType string

EventType is one streamed provider event kind. 

const (
	// EventDelta appends assistant text.
	EventDelta EventType = "delta"
	// EventReasoning appends assistant reasoning.
	EventReasoning EventType = "reasoning"
	// EventToolCallStart begins one streamed tool call.
	EventToolCallStart EventType = "tool_call_start"
	// EventToolCallDelta appends streamed tool-call arguments.
	EventToolCallDelta EventType = "tool_call_delta"
	// EventToolCallEnd ends one streamed tool call.
	EventToolCallEnd EventType = "tool_call_end"
	// EventToolCalls delivers executable local tool calls.
	EventToolCalls EventType = "tool_calls"
	// EventUsage reports normalized provider usage.
	EventUsage EventType = "usage"
	// EventSources reports provider citations.
	EventSources EventType = "sources"
	// EventHostedToolCall reports a provider-native tool invocation.
	EventHostedToolCall EventType = "hosted_tool_call"
	// EventHostedToolResult reports the structured result of a provider-native
	// tool invocation.
	EventHostedToolResult EventType = "hosted_tool_result"
	// EventDone terminates a successful provider step.
	EventDone EventType = "done"
	// EventEmpty terminates an empty provider step.
	EventEmpty EventType = "empty"
	// EventTruncated terminates a length-limited provider step.
	EventTruncated EventType = "truncated"
	// EventError terminates a failed provider step.
	EventError EventType = "error"
)

type Gateway 

type Gateway interface {
	Identity() Identity
	Capabilities() Capabilities
	Stream(context.Context, Request) (<-chan Event, error)
}

Gateway is the single model-execution path used by every Agent.

func NewAnthropic 

func NewAnthropic(options AnthropicOptions) (Gateway, error)

NewAnthropic constructs an explicit Anthropic messages Gateway.

func NewOpenAICompatible 

func NewOpenAICompatible(options OpenAICompatibleOptions) (Gateway, error)

NewOpenAICompatible constructs an explicit OpenAI-compatible Gateway.

type HostedToolDefinition 

type HostedToolDefinition struct {
	Name        string         `json:"name"`
	Type        string         `json:"type"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
	Options     map[string]any `json:"options,omitempty"`
}

HostedToolDefinition is one provider-native capability that the local tool runtime must not dispatch.

type HostedToolResult 

type HostedToolResult struct {
	Text     string                 `json:"text,omitempty"`
	Results  []HostedToolResultItem `json:"results,omitempty"`
	Error    *HostedToolResultError `json:"error,omitempty"`
	Metadata map[string]any         `json:"metadata,omitempty"`
}

HostedToolResult is a provider-neutral projection of provider-native tool output.

type HostedToolResultError 

type HostedToolResultError struct {
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}

HostedToolResultError describes a provider-native tool failure.

type HostedToolResultItem 

type HostedToolResultItem struct {
	Title    string         `json:"title,omitempty"`
	URL      string         `json:"url,omitempty"`
	Snippet  string         `json:"snippet,omitempty"`
	Source   string         `json:"source,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

HostedToolResultItem is one structured provider-native result item.

type Identity 

type Identity struct {
	Provider              string `json:"provider"`
	Model                 string `json:"model"`
	StateCompatibilityKey string `json:"state_compatibility_key"`
}

Identity describes one provider/model transport and its opaque-state compatibility boundary.

func (Identity) Validate 

func (identity Identity) Validate() error

Validate verifies a complete provider identity.

type Labels 

type Labels struct {
	Correlation map[string]string `json:"correlation,omitempty"`
	Host        map[string]string `json:"host,omitempty"`
}

Labels carries opaque correlation and host labels.

type Message 

type Message struct {
	Role        MessageRole  `json:"role"`
	Text        string       `json:"text,omitempty"`
	Attachments []Attachment `json:"attachments,omitempty"`
	Reasoning   string       `json:"reasoning,omitempty"`
	ToolCalls   []ToolCall   `json:"tool_calls,omitempty"`
	ToolResult  *ToolResult  `json:"tool_result,omitempty"`
}

Message is one typed provider-visible context item.

func (Message) Validate 

func (message Message) Validate() error

Validate verifies the role-specific message shape.

type MessageRole 

type MessageRole string

MessageRole is a provider-visible message role. 

const (
	// RoleSystem identifies a system instruction.
	RoleSystem MessageRole = "system"
	// RoleUser identifies admitted user input.
	RoleUser MessageRole = "user"
	// RoleAssistant identifies assistant output or tool calls.
	RoleAssistant MessageRole = "assistant"
	// RoleTool identifies one local tool result.
	RoleTool MessageRole = "tool"
)

type OpenAICompatibleOptions 

type OpenAICompatibleOptions struct {
	Provider              string
	Model                 string
	BaseURL               string
	APIKey                string
	StateCompatibilityKey string
	HTTPClient            *http.Client
	Capabilities          Capabilities
}

OpenAICompatibleOptions configures an explicit OpenAI chat-completions transport. BaseURL is the API root; the gateway sends requests to BaseURL/chat/completions.

type PreparedRequest 

type PreparedRequest interface {
	Stream(context.Context) (<-chan Event, error)
	TokenEstimate() TokenEstimate
	RenderedPayloadFingerprint() string
	Close() error
}

PreparedRequest is one immutable, single-use rendered provider request.

type ReasoningSupport 

type ReasoningSupport string

ReasoningSupport declares whether a gateway accepts reasoning policy. 

const (
	// ReasoningUnsupported declares that the model has no reasoning controls.
	ReasoningUnsupported ReasoningSupport = "unsupported"
	// ReasoningSupported declares that ReasoningCapability is authoritative.
	ReasoningSupported ReasoningSupport = "supported"
)

type Request 

type Request struct {
	RunID            identity.RunID            `json:"run_id"`
	ThreadID         identity.ThreadID         `json:"thread_id,omitempty"`
	TurnID           identity.TurnID           `json:"turn_id,omitempty"`
	TraceID          identity.TraceID          `json:"trace_id,omitempty"`
	PromptScopeID    identity.PromptScopeID    `json:"prompt_scope_id"`
	LogicalRequestID identity.LogicalRequestID `json:"logical_request_id,omitempty"`
	AttemptID        string                    `json:"attempt_id,omitempty"`
	AttemptEpoch     int                       `json:"attempt_epoch,omitempty"`
	Step             int                       `json:"step"`
	Messages         []Message                 `json:"messages"`
	Tools            []tools.ToolDefinition    `json:"tools,omitempty"`
	HostedTools      []HostedToolDefinition    `json:"hosted_tools,omitempty"`
	MaxOutputTokens  int64                     `json:"max_output_tokens,omitempty"`
	Reasoning        config.ReasoningSelection `json:"reasoning,omitempty"`
	PreviousState    *State                    `json:"previous_state,omitempty"`
	Labels           Labels                    `json:"labels,omitempty"`
}

Request is one complete provider-visible model request.

func (Request) MarshalJSON 

func (request Request) MarshalJSON() ([]byte, error)

MarshalJSON omits the optional logical request identity when a low-level provider request is constructed before runtime admission has assigned one. Non-empty identities still use identity.LogicalRequestID's validation.

func (Request) Validate 

func (request Request) Validate() error

Validate verifies identities and provider-visible message structure.

type RequestPreparer 

type RequestPreparer interface {
	Prepare(context.Context, Request) (PreparedRequest, error)
}

RequestPreparer renders a complete provider request before context limits are applied.

type Source 

type Source struct {
	Title string `json:"title,omitempty"`
	URL   string `json:"url,omitempty"`
}

Source is one provider citation.

type State 

type State struct {
	Kind       string            `json:"kind,omitempty"`
	ID         string            `json:"id,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

State is opaque provider continuation state persisted by Floret.

type TokenEstimate 

type TokenEstimate struct {
	PrefixTokens         int64  `json:"prefix_tokens,omitempty"`
	MessageTokens        int64  `json:"message_tokens,omitempty"`
	ToolDefinitionTokens int64  `json:"tool_definition_tokens,omitempty"`
	EstimatedInputTokens int64  `json:"estimated_input_tokens,omitempty"`
	Source               string `json:"source,omitempty"`
	Method               string `json:"method,omitempty"`
	Confidence           string `json:"confidence,omitempty"`
	Coverage             string `json:"coverage,omitempty"`
}

TokenEstimate describes the size of a complete rendered request.

type ToolCall 

type ToolCall struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Args string `json:"args"`
}

ToolCall is one provider-requested local invocation.

type ToolCallStream 

type ToolCallStream struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

ToolCallStream identifies one tool call while its arguments stream.

type ToolResult 

type ToolResult struct {
	CallID   string `json:"call_id"`
	ToolName string `json:"tool_name"`
	Text     string `json:"text,omitempty"`
}

ToolResult is one provider-visible local tool outcome.

type Usage 

type Usage struct {
	InputTokens       int64   `json:"input_tokens,omitempty"`
	OutputTokens      int64   `json:"output_tokens,omitempty"`
	ReasoningTokens   int64   `json:"reasoning_tokens,omitempty"`
	CacheReadTokens   int64   `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens  int64   `json:"cache_write_tokens,omitempty"`
	TotalTokens       int64   `json:"total_tokens,omitempty"`
	CostUSD           float64 `json:"cost_usd,omitempty"`
	Source            string  `json:"source,omitempty"`
	Available         bool    `json:"available,omitempty"`
	WindowInputTokens int64   `json:"window_input_tokens,omitempty"`
}

Usage is normalized provider token and cost usage.

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.