gillmprovider

package
v0.82.2 Latest Latest
Warning

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

Go to latest
Published: Jul 27, 2026 License: MIT Imports: 50 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CloudflareWorkersAIBaseURL          = "https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1"
	CloudflareAIGatewayCompatBaseURL    = "https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat"
	CloudflareAIGatewayOpenAIBaseURL    = "https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai"
	CloudflareAIGatewayAnthropicBaseURL = "https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic"
)
View Source
const (
	// AnthropicAuthTokenEnv is reported as configured authentication but is
	// resolved into an Authorization bearer header, never an SDK API key.
	AnthropicAuthTokenEnv = envkeys.AnthropicAuthTokenEnv
	// AnthropicOAuthTokenEnv contains Claude subscription OAuth tokens.
	AnthropicOAuthTokenEnv = envkeys.AnthropicOAuthTokenEnv
	// AnthropicAPIKeyEnv contains conventional Anthropic API keys.
	AnthropicAPIKeyEnv = envkeys.AnthropicAPIKeyEnv
)
View Source
const (
	GCPVertexCredentialsMarker = "gcp-vertex-credentials"
	// GoogleCloudPlatformScope is the OAuth scope required by Vertex AI.
	GoogleCloudPlatformScope = "https://www.googleapis.com/auth/cloud-platform"
)
View Source
const (
	ImagesStopReasonStop    = "stop"
	ImagesStopReasonError   = "error"
	ImagesStopReasonAborted = "aborted"
)
View Source
const (
	NonVisionUserImagePlaceholder = "(image omitted: model does not support images)"
	NonVisionToolImagePlaceholder = "(tool image omitted: model does not support images)"
)
View Source
const (
	AnthropicOAuthTokenURL = "https://platform.claude.com/v1/oauth/token"
	AnthropicOAuthClientID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
)
View Source
const (
	// DefaultRemoteCatalogBaseURL is the release catalog service used by Pi.
	DefaultRemoteCatalogBaseURL = "https://pi.dev"

	// RemoteCatalogRefreshInterval is the minimum interval between successful
	// or explicitly unavailable remote catalog checks.
	RemoteCatalogRefreshInterval = 4 * time.Hour
)
View Source
const (
	RoleUser       = "user"
	RoleAssistant  = "assistant"
	RoleToolResult = "toolResult"

	ContentText     = "text"
	ContentThinking = "thinking"
	ContentImage    = "image"
	ContentToolCall = "toolCall"

	StopReasonStop    = "stop"
	StopReasonLength  = "length"
	StopReasonError   = "error"
	StopReasonAborted = "aborted"
)
View Source
const BuiltInAPIProviderSourceID = "builtin"
View Source
const DefaultAzureOpenAIAPIVersion = "v1"
View Source
const DefaultMaxProviderRetryDelay = 60 * time.Second
View Source
const (
	// DefaultRadiusGateway is Pi's hosted Radius endpoint.
	DefaultRadiusGateway = "https://radius.pi.dev"
)
View Source
const MaxProviderErrorBodyChars = 4000

MaxProviderErrorBodyChars bounds provider response bodies exposed to callers.

View Source
const OpenAIPromptCacheKeyMaxLength = 64

OpenAIPromptCacheKeyMaxLength is OpenAI's cache-key limit in Unicode characters.

View Source
const StopReasonToolUse = "toolUse"
View Source
const UnsupportedProxyProtocolMessage = httpproxy.UnsupportedProxyProtocolMessage

Variables

This section is empty.

Functions

func AppendAssistantMessageDiagnostic

func AppendAssistantMessageDiagnostic(message *Message, diagnostic AssistantMessageDiagnostic)

func AppendGrammarToolInputJSONDelta added in v0.82.0

func AppendGrammarToolInputJSONDelta(
	buffer *GrammarToolInputJSONBuffer,
	inputProperty string,
	nextInput string,
	closeInput bool,
) (string, bool, error)

AppendGrammarToolInputJSONDelta turns a monotonically growing raw grammar input into an append-only JSON object stream. The bool result distinguishes a deliberate no-op from an emitted empty string.

func ApplyOpenAIAnthropicCacheControl

func ApplyOpenAIAnthropicCacheControl(messages []OpenAIChatMessage, tools []OpenAIChatTool, cacheControl *OpenAICompatCacheControl)

func ApplyOpenAICodexServiceTierPricing

func ApplyOpenAICodexServiceTierPricing(usage *Usage, serviceTier string, model Model)

func ApplyOpenAIResponsesServiceTierPricing

func ApplyOpenAIResponsesServiceTierPricing(usage *Usage, serviceTier string, model Model)

func BedrockInferenceProfileRegion added in v0.82.0

func BedrockInferenceProfileRegion(modelID string) string

func BuildAnthropicHeaders

func BuildAnthropicHeaders(model Model, context Context, options AnthropicPayloadOptions) map[string]string

func BuildAnthropicRequestHeaders

func BuildAnthropicRequestHeaders(model Model, context Context, options AnthropicPayloadOptions) map[string]string

func BuildBedrockAdditionalModelRequestFields

func BuildBedrockAdditionalModelRequestFields(model Model, options BedrockPayloadOptions) map[string]any

func BuildCopilotDynamicHeaders

func BuildCopilotDynamicHeaders(messages []Message) map[string]string

func BuildDefaultAzureOpenAIBaseURL

func BuildDefaultAzureOpenAIBaseURL(resourceName string) string

func BuildOpenAICodexSSEHeaders

func BuildOpenAICodexSSEHeaders(modelHeaders, optionHeaders map[string]string, token, sessionID string) (map[string]string, error)

func BuildOpenAICodexWebSocketHeaders

func BuildOpenAICodexWebSocketHeaders(modelHeaders, optionHeaders map[string]string, token, requestID string) (map[string]string, error)

func BuildOpenAICompletionsHeaders

func BuildOpenAICompletionsHeaders(model Model, options OpenAICompletionsPayloadOptions) map[string]string

func BuildOpenAIResponsesHeaders

func BuildOpenAIResponsesHeaders(model Model, options OpenAIResponsesPayloadOptions) map[string]string

func CalculateContextTokens added in v0.82.0

func CalculateContextTokens(usage Usage) int

CalculateContextTokens returns the provider total when present and otherwise reconstructs it from the four input/output/cache buckets.

func ClampMaxTokensToContext added in v0.82.0

func ClampMaxTokensToContext(model Model, context Context, maxTokens int) int

ClampMaxTokensToContext caps an output-token budget at the estimated remaining context while retaining at least one output token.

func ClampOpenAIPromptCacheKey added in v0.82.0

func ClampOpenAIPromptCacheKey(key string) string

ClampOpenAIPromptCacheKey applies OpenAI's 64-character cache-key limit. Runes are used instead of bytes so truncation never splits UTF-8 input.

func ClampThinkingLevel

func ClampThinkingLevel(model Model, level string) string

func CleanupSessionResources

func CleanupSessionResources(sessionID string) error

func ClearAPIProviders

func ClearAPIProviders()

func CloseOpenAICodexWebSocketSessions

func CloseOpenAICodexWebSocketSessions(sessionIDs ...string)

func CreateGrammarToolInputProperties added in v0.82.0

func CreateGrammarToolInputProperties(
	tools []Tool,
	supportsOpenAIGrammarTools bool,
) (map[string]string, error)

func DetectOpenAIResponsesSessionAffinityFormat added in v0.82.0

func DetectOpenAIResponsesSessionAffinityFormat(model Model) string

func EstimateMessageTokens added in v0.82.0

func EstimateMessageTokens(message Message) int

EstimateMessageTokens estimates one canonical LLM message. Unknown roles are intentionally ignored because they belong to higher-level transcript types.

func EstimateTextAndImageContentChars added in v0.82.0

func EstimateTextAndImageContentChars(content []ContentPart) int

EstimateTextAndImageContentChars estimates the UTF-16 content size and assigns the same fixed 4,800-character budget Pi uses for each image.

func EstimateTextAndImageContentTokens added in v0.82.0

func EstimateTextAndImageContentTokens(content []ContentPart) int

EstimateTextAndImageContentTokens estimates text blocks and assigns the same fixed 1,200-token budget Pi uses for each image.

func EstimateTextTokens added in v0.82.0

func EstimateTextTokens(text string) int

EstimateTextTokens applies Pi's deliberately cheap four UTF-16-code-units per token heuristic.

func ExtractOpenAICodexAccountID

func ExtractOpenAICodexAccountID(token string) (string, error)

func ExtractTextContent added in v0.82.0

func ExtractTextContent(content []ContentPart) string

ExtractTextContent is the common newline-joined form.

func FindEnvKeys

func FindEnvKeys(provider string) []string

func FindEnvKeysWithOverrides added in v0.82.0

func FindEnvKeysWithOverrides(provider string, env ProviderEnv) []string

FindEnvKeysWithOverrides reports provider API-key variables available from request-scoped overrides or the ambient process environment.

func FormatProviderError added in v0.82.0

func FormatProviderError(normalized NormalizedProviderError, prefix ...string) string

FormatProviderError composes a provider error without dropping a response body that was retained separately from the Go error message.

func FormatThrownValue

func FormatThrownValue(value any) string

func FromClaudeCodeToolName

func FromClaudeCodeToolName(name string, tools []Tool) string

func GetBuiltinModelDataGeneratedAt added in v0.82.0

func GetBuiltinModelDataGeneratedAt() time.Time

GetBuiltinModelDataGeneratedAt returns the release catalog generation time.

func GetBuiltinProviderIDs added in v0.82.0

func GetBuiltinProviderIDs() []string

GetBuiltinProviderIDs returns static catalog provider IDs in generated order.

func GetConfiguredBedrockProfile added in v0.82.0

func GetConfiguredBedrockProfile(options BedrockClientOptions) string

func GetConfiguredBedrockRegion

func GetConfiguredBedrockRegion(options BedrockClientOptions) string

func GetEnvAPIKey

func GetEnvAPIKey(provider string) string

func GetEnvAPIKeyWithOverrides added in v0.82.0

func GetEnvAPIKeyWithOverrides(provider string, env ProviderEnv) string

GetEnvAPIKeyWithOverrides resolves provider authentication from request overrides before consulting the ambient process environment.

func GetGrammarToolInput added in v0.82.0

func GetGrammarToolInput(toolName string, arguments map[string]any, inputProperty string) (string, error)

func GetImageProviders

func GetImageProviders() []string

func GetOverflowPatterns

func GetOverflowPatterns() []*regexp.Regexp

func GetProviderEnvValue added in v0.82.0

func GetProviderEnvValue(name string, env ProviderEnv) string

GetProviderEnvValue resolves a request-scoped provider override before the ambient process environment. Empty overrides intentionally fall through.

func GetProviders

func GetProviders() []string

func GetSupportedThinkingLevels

func GetSupportedThinkingLevels(model Model) []string

func GitHubCopilotBaseURL

func GitHubCopilotBaseURL(token, enterpriseDomain string) string

func GitHubCopilotPollSchedule

func GitHubCopilotPollSchedule(startMillis int64, intervalSeconds, expiresSeconds int, responses []GitHubCopilotDevicePollResponse) ([]int64, error)

func GoogleThinkingBudget

func GoogleThinkingBudget(model Model, effort string, custom map[string]int) int

func GoogleThinkingLevel

func GoogleThinkingLevel(effort string, model Model) string

func GoogleVertexBaseURLIncludesAPIVersion

func GoogleVertexBaseURLIncludesAPIVersion(baseURL string) bool

func GoogleVertexStreamEndpoint added in v0.82.0

func GoogleVertexStreamEndpoint(model Model, config GoogleVertexClientConfig) (string, error)

GoogleVertexStreamEndpoint builds the REST endpoint selected by the Google Gen AI SDK: Express mode uses the global collection, while ADC requests use a project/location resource path unless a collection-scoped custom base URL is configured.

func HasAPI added in v0.82.0

func HasAPI(model Model, api string) bool

HasAPI reports whether a dynamically selected model uses the requested API.

func HasConfiguredBedrockProfile

func HasConfiguredBedrockProfile(options BedrockClientOptions) bool

func HasCopilotVisionInput

func HasCopilotVisionInput(messages []Message) bool

func InferCopilotInitiator

func InferCopilotInitiator(messages []Message) string

func IsAnthropicClaudeBedrockModel

func IsAnthropicClaudeBedrockModel(model Model) bool

func IsCloudflareProvider

func IsCloudflareProvider(provider string) bool

func IsContextOverflow

func IsContextOverflow(message Message, contextWindow int) bool

func IsGoogleThinkingPart

func IsGoogleThinkingPart(part GooglePart) bool

func IsGovCloudBedrockTarget

func IsGovCloudBedrockTarget(model Model, options BedrockPayloadOptions) bool

func IsMalformedJSONError

func IsMalformedJSONError(err error) bool

func IsOpenAICodexRetryable

func IsOpenAICodexRetryable(status int, body string) bool

func IsOpenAICodexTerminalRateLimitError added in v0.82.0

func IsOpenAICodexTerminalRateLimitError(body string) bool

IsOpenAICodexTerminalRateLimitError identifies quota and billing failures that must not be retried even when the HTTP status is 429.

func IsPlaceholderAPIKey

func IsPlaceholderAPIKey(apiKey string) bool

func IsReservedBedrockHeader added in v0.82.0

func IsReservedBedrockHeader(key string) bool

IsReservedBedrockHeader reports headers owned by HTTP routing or AWS authentication. Caller values for these fields are never installed.

func IsRetryableAssistantError added in v0.82.0

func IsRetryableAssistantError(message Message) bool

IsRetryableAssistantError classifies a terminal assistant error using the shared Pi-compatible provider and transport patterns. Policy and retry state remain owned by the calling runtime.

func IsRetryableProviderError added in v0.82.0

func IsRetryableProviderError(err error) bool

IsRetryableProviderError mirrors the OpenAI and Anthropic SDK status/header policy while using Go's typed error chain.

func IsSessionResourceCleanupError

func IsSessionResourceCleanupError(err error) bool

func JoinTextContent added in v0.82.0

func JoinTextContent(content []ContentPart, separator string) string

JoinTextContent extracts text blocks in transcript order and joins them with separator. Thinking, image, and tool-call blocks are deliberately ignored.

func MapAnthropicThinkingEffort

func MapAnthropicThinkingEffort(model Model, level string) string

func MapBedrockThinkingEffort

func MapBedrockThinkingEffort(model Model, level string) string

func MapGoogleFinishReason

func MapGoogleFinishReason(reason string) string

func MapMistralReasoningEffort

func MapMistralReasoningEffort(model Model, level string) string

func MapOpenAIChatFinishReason

func MapOpenAIChatFinishReason(reason string) (string, string)

func ModelsAreEqual

func ModelsAreEqual(a, b *Model) bool

func NewHTTPClient added in v0.82.0

func NewHTTPClient(config HTTPRuntimeConfig) (*http.Client, error)

NewHTTPClient constructs an independently owned provider client. It avoids mutating http.DefaultTransport, disables HTTP/2 to keep per-connection idle deadlines isolated, and uses an explicit proxy when configured.

func NormalizeAzureOpenAIBaseURL

func NormalizeAzureOpenAIBaseURL(baseURL string) (string, error)

func NormalizeRadiusGatewayURL added in v0.82.0

func NormalizeRadiusGatewayURL(value string) string

NormalizeRadiusGatewayURL adds HTTPS when no URI scheme is present and removes trailing slashes. Unsupported explicit schemes remain intact so the endpoint validator can reject them instead of silently rewriting them.

func NormalizeToolCallIDForAnthropic

func NormalizeToolCallIDForAnthropic(id string) string

func NormalizeToolCallIDForOpenAICompletions

func NormalizeToolCallIDForOpenAICompletions(id string, model Model) string

func NormalizeToolCallIDForOpenAIResponses

func NormalizeToolCallIDForOpenAIResponses(id string, target Model, source Message, allowedToolCallProviders map[string]bool) string

func NowMillis

func NowMillis() int64

func OAuthErrorHTML

func OAuthErrorHTML(message, details string) string

func OAuthPageHTML

func OAuthPageHTML(options OAuthPageOptions) string

func OAuthSuccessHTML

func OAuthSuccessHTML(message string) string

func OpenAICodexRefreshError

func OpenAICodexRefreshError(status int, statusText, body string) error

func OpenAICodexRetryDelay

func OpenAICodexRetryDelay(
	_ int,
	headers map[string]string,
	attempt int,
	now time.Time,
) time.Duration

func OpenAICodexServiceTierCostMultiplier

func OpenAICodexServiceTierCostMultiplier(model Model, serviceTier string) float64

func OpenAIResponsesServiceTierCostMultiplier

func OpenAIResponsesServiceTierCostMultiplier(model Model, serviceTier string) float64

func PollOAuthDeviceCodeFlow added in v0.82.0

func PollOAuthDeviceCodeFlow[T any](
	ctx context.Context,
	options OAuthDeviceCodePollOptions[T],
) (T, error)

PollOAuthDeviceCodeFlow polls immediately by default, observes RFC 8628 slow_down responses, and stops promptly when ctx is cancelled.

func RegisterAPIProvider

func RegisterAPIProvider(api string, provider APIProvider)

func RegisterAPIProviderWithSource

func RegisterAPIProviderWithSource(api string, provider APIProvider, sourceID string)

func RegisterBuiltInAPIProvider

func RegisterBuiltInAPIProvider(api string, provider APIProvider)

func RegisterBuiltInAPIProviders

func RegisterBuiltInAPIProviders()

func RegisterBundledOAuthFlowLoaders added in v0.82.0

func RegisterBundledOAuthFlowLoaders(loaders map[string]OAuthAuthLoader)

RegisterBundledOAuthFlowLoaders atomically installs a set of statically linked OAuth implementations. A nil loader removes that provider, matching RegisterOAuthAuthLoader while avoiding a partially visible batch.

func RegisterImageModel

func RegisterImageModel(model ImagesModel)

func RegisterImagesAPIProvider

func RegisterImagesAPIProvider(api string, provider ImagesAPIProvider)

func RegisterModel

func RegisterModel(model Model)

func RegisterOAuthAuthLoader added in v0.82.0

func RegisterOAuthAuthLoader(providerID string, loader OAuthAuthLoader)

RegisterOAuthAuthLoader installs or replaces one provider's lazy OAuth implementation. Passing nil unregisters the provider.

func RegisterSessionResourceCleanup

func RegisterSessionResourceCleanup(cleanup SessionResourceCleanup) func()

func RepairJSON

func RepairJSON(data string) string

func RequiresGoogleToolCallID

func RequiresGoogleToolCallID(modelID string) bool

func ResetAPIProviders

func ResetAPIProviders()

func ResetOpenAICodexWebSocketDebugStats

func ResetOpenAICodexWebSocketDebugStats(sessionIDs ...string)

func ResetUUIDv7ForTest added in v0.82.0

func ResetUUIDv7ForTest()

ResetUUIDv7ForTest resets only the package default generator.

func ResolveAzureDeploymentName

func ResolveAzureDeploymentName(model Model, explicit string) string

func ResolveCloudflareBaseURL

func ResolveCloudflareBaseURL(model Model) (string, error)

func ResolveGoogleVertexAPIKey

func ResolveGoogleVertexAPIKey(options GoogleVertexOptions) string

func ResolveGoogleVertexCustomBaseURL

func ResolveGoogleVertexCustomBaseURL(baseURL string) string

func ResolveHTTPProxyURLForTarget

func ResolveHTTPProxyURLForTarget(targetURL string) (*url.URL, error)

func ResolveHTTPProxyURLForTargetWithEnv added in v0.82.0

func ResolveHTTPProxyURLForTargetWithEnv(
	targetURL string,
	env ProviderEnv,
) (*url.URL, error)

ResolveHTTPProxyURLForTargetWithEnv resolves request-scoped proxy variables before falling back to the ambient process environment.

func ResolveJSONSchemaStrictSampling added in v0.82.0

func ResolveJSONSchemaStrictSampling(tool Tool, supportsStrictMode bool) (*bool, error)

func ResolveOpenAICodexServiceTier

func ResolveOpenAICodexServiceTier(responseServiceTier, requestServiceTier string) string

func ResolveOpenAICodexURL

func ResolveOpenAICodexURL(baseURL string) string

func ResolveOpenAICodexWebSocketURL

func ResolveOpenAICodexWebSocketURL(baseURL string) string

func RetainGoogleThoughtSignature

func RetainGoogleThoughtSignature(existing, incoming string) string

func RetryProviderRequest added in v0.82.0

func RetryProviderRequest[T any](ctx context.Context, options ProviderRetryOptions, request func(context.Context) (T, error)) (T, error)

RetryProviderRequest retries only typed ProviderError values. Transport code should wrap network failures with newProviderTransportError so ordinary application errors fail fast.

func SanitizeSchemaForOpenAPI

func SanitizeSchemaForOpenAPI(schema any) any

func SanitizeSurrogates

func SanitizeSurrogates(text string) string

func SchemaToMap

func SchemaToMap(schema Schema) map[string]any

func ShouldSendOpenAICompletionsTools

func ShouldSendOpenAICompletionsTools(context Context) bool

func ShouldUseExplicitBedrockEndpoint

func ShouldUseExplicitBedrockEndpoint(baseURL, configuredRegion string, hasConfiguredProfile bool) bool

func StandardBedrockEndpointRegion

func StandardBedrockEndpointRegion(baseURL string) string

func SupportsAnthropicAdaptiveThinking

func SupportsAnthropicAdaptiveThinking(model Model) bool

func SupportsBedrockAdaptiveThinking

func SupportsBedrockAdaptiveThinking(model Model) bool

func SupportsBedrockPromptCaching

func SupportsBedrockPromptCaching(model Model, force bool) bool

func SupportsGoogleMultimodalFunctionResponse

func SupportsGoogleMultimodalFunctionResponse(modelID string) bool

func SupportsGoogleStrictToolSampling added in v0.82.0

func SupportsGoogleStrictToolSampling(modelID string) bool

SupportsGoogleStrictToolSampling reports whether Google validates required function parameters for the model's tool calls.

func ToClaudeCodeToolName

func ToClaudeCodeToolName(name string) string

func TruncateProviderErrorText added in v0.82.0

func TruncateProviderErrorText(text string, maxChars int) string

TruncateProviderErrorText uses UTF-16 code units because Pi's JavaScript String.length and String.slice do. utf16.Decode replaces a split surrogate with U+FFFD, keeping the Go result valid UTF-8 at the only boundary where the two string models cannot represent exactly the same intermediate value.

func UUIDLikeID

func UUIDLikeID() string

func UUIDv7 added in v0.82.0

func UUIDv7() string

UUIDv7 generates an RFC 9562 time-ordered identifier.

func UUIDv7With added in v0.82.0

func UUIDv7With(randomBytes RandomBytesFunc, nowMillis NowMillisFunc) string

UUIDv7With preserves Gi's injectable compatibility surface while sharing the same monotonic stream as UUIDv7.

func UnmarshalJSONWithRepair

func UnmarshalJSONWithRepair(data []byte, target any) error

func UnregisterAPIProvider

func UnregisterAPIProvider(api string)

func UnregisterAPIProviders

func UnregisterAPIProviders(sourceID string)

func UnregisterImagesAPIProvider

func UnregisterImagesAPIProvider(api string)

func UnregisterOAuthAuthLoader added in v0.82.0

func UnregisterOAuthAuthLoader(providerID string)

UnregisterOAuthAuthLoader removes one provider's lazy OAuth implementation.

func UsesMistralReasoningEffort

func UsesMistralReasoningEffort(model Model) bool

func ValidateGoogleVertexClientConfig added in v0.82.0

func ValidateGoogleVertexClientConfig(config GoogleVertexClientConfig) error

ValidateGoogleVertexClientConfig checks the mutually exclusive Express and ADC configuration requirements without performing authentication or I/O.

func ValidateOpenRouterImagesPayload

func ValidateOpenRouterImagesPayload(payload OpenRouterImagesPayload) error

func ValidateThinkingLevelSupported

func ValidateThinkingLevelSupported(model Model, level string) error

func ValidateToolArguments

func ValidateToolArguments(tool Tool, toolCall ContentPart) (map[string]any, error)

func ValidateToolCall

func ValidateToolCall(tools []Tool, toolCall ContentPart) (map[string]any, error)

Types

type APIKeyAuth added in v0.82.0

type APIKeyAuth struct {
	Name    string
	Login   func(ctx context.Context, interaction AuthInteraction) (Credential, error)
	Check   func(ctx context.Context, input APIKeyCheckInput) (*AuthCheck, error)
	Resolve func(ctx context.Context, input APIKeyResolveInput) (*AuthResult, error)
}

APIKeyAuth defines provider-specific API-key login and resolution.

func EnvAPIKeyAuth added in v0.82.0

func EnvAPIKeyAuth(name string, envVars ...string) *APIKeyAuth

EnvAPIKeyAuth builds the standard provider auth contract: a stored key wins, otherwise environment variables are checked in declaration order.

type APIKeyCheckInput added in v0.82.0

type APIKeyCheckInput struct {
	Context    AuthContext
	Credential *Credential
}

APIKeyCheckInput supplies deterministic context for a side-effect-free auth availability check.

type APIKeyResolveInput added in v0.82.0

type APIKeyResolveInput struct {
	Context    AuthContext
	Credential *Credential
}

APIKeyResolveInput supplies deterministic context and an optional stored credential to an API-key resolver.

type APIProvider

type APIProvider interface {
	Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)
	StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)
}

func GetAPIProvider

func GetAPIProvider(api string) APIProvider

type APIProviderFuncs

type APIProviderFuncs struct {
	StreamFunc       func(Model, Context, StreamOptions) (*AssistantMessageEventStream, error)
	StreamSimpleFunc func(Model, Context, SimpleStreamOptions) (*AssistantMessageEventStream, error)
}

func (APIProviderFuncs) Stream

func (p APIProviderFuncs) Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)

func (APIProviderFuncs) StreamSimple

func (p APIProviderFuncs) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type APIProviderRegistration

type APIProviderRegistration struct {
	API      string
	Provider APIProvider
	SourceID string
}

func GetAPIProviders

func GetAPIProviders() []APIProviderRegistration

type AbortUsageExpectation

type AbortUsageExpectation string
const (
	AbortUsageFinalOnly   AbortUsageExpectation = "final-only"
	AbortUsageInputOnly   AbortUsageExpectation = "input-only"
	AbortUsageIncremental AbortUsageExpectation = "incremental"
)

func ExpectedAbortUsage

func ExpectedAbortUsage(model Model) AbortUsageExpectation

type AnthropicCacheCreationUsage added in v0.82.0

type AnthropicCacheCreationUsage struct {
	Ephemeral5mInputTokens int `json:"ephemeral_5m_input_tokens"`
	Ephemeral1hInputTokens int `json:"ephemeral_1h_input_tokens"`
}

type AnthropicCompat

type AnthropicCompat struct {
	SupportsEagerToolInputStreaming bool
	SupportsCacheControlOnTools     bool
	SupportsLongCacheRetention      bool
	SupportsStrictTools             bool
	SupportsToolReferences          bool
	SupportsTemperature             bool
	SendSessionAffinityHeaders      bool
	AllowEmptySignature             bool
}

func ResolveAnthropicCompat

func ResolveAnthropicCompat(model Model) AnthropicCompat

type AnthropicContentBlock

type AnthropicContentBlock struct {
	Type         string                    `json:"type"`
	Text         string                    `json:"text,omitempty"`
	Source       *AnthropicImageSource     `json:"source,omitempty"`
	ID           string                    `json:"id,omitempty"`
	Name         string                    `json:"name,omitempty"`
	Input        map[string]any            `json:"input,omitempty"`
	ToolUseID    string                    `json:"tool_use_id,omitempty"`
	ToolName     string                    `json:"tool_name,omitempty"`
	Content      any                       `json:"content,omitempty"`
	IsError      bool                      `json:"is_error,omitempty"`
	Thinking     string                    `json:"thinking,omitempty"`
	Signature    *string                   `json:"signature,omitempty"`
	Data         string                    `json:"data,omitempty"`
	CacheControl *OpenAICompatCacheControl `json:"cache_control,omitempty"`
}

type AnthropicImageSource

type AnthropicImageSource struct {
	Type      string `json:"type"`
	MediaType string `json:"media_type"`
	Data      string `json:"data"`
}

type AnthropicMessage

type AnthropicMessage struct {
	Role    string `json:"role"`
	Content any    `json:"content"`
}

func ConvertAnthropicMessages

func ConvertAnthropicMessages(model Model, context Context, isOAuthToken bool, cacheControl *OpenAICompatCacheControl) []AnthropicMessage

type AnthropicMessagesProvider

type AnthropicMessagesProvider struct {
	Client HTTPDoer
}

func NewAnthropicMessagesProvider

func NewAnthropicMessagesProvider(client HTTPDoer) AnthropicMessagesProvider

func (AnthropicMessagesProvider) Stream

func (p AnthropicMessagesProvider) Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)

func (AnthropicMessagesProvider) StreamSimple

func (p AnthropicMessagesProvider) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type AnthropicOAuthOptions added in v0.82.0

type AnthropicOAuthOptions struct {
	Client         HTTPDoer
	AuthContext    AuthContext
	CallbackHost   string
	RequestTimeout time.Duration
}

AnthropicOAuthOptions configures the provider-owned Claude Pro/Max OAuth flow. The zero value uses the Pi-compatible endpoints, callback address, and request timeout.

type AnthropicOutputTokensDetails added in v0.82.0

type AnthropicOutputTokensDetails struct {
	ThinkingTokens *int `json:"thinking_tokens"`
}

type AnthropicPayload

type AnthropicPayload struct {
	Model        string                  `json:"model"`
	Messages     []AnthropicMessage      `json:"messages"`
	System       []AnthropicContentBlock `json:"system,omitempty"`
	MaxTokens    int                     `json:"max_tokens"`
	Stream       bool                    `json:"stream"`
	Temperature  *float64                `json:"temperature,omitempty"`
	Tools        []AnthropicTool         `json:"tools,omitempty"`
	Thinking     map[string]any          `json:"thinking,omitempty"`
	OutputConfig map[string]any          `json:"output_config,omitempty"`
	Metadata     map[string]any          `json:"metadata,omitempty"`
}

func BuildAnthropicPayload

func BuildAnthropicPayload(model Model, context Context, options AnthropicPayloadOptions) AnthropicPayload

func BuildAnthropicPayloadChecked added in v0.82.0

func BuildAnthropicPayloadChecked(model Model, context Context, options AnthropicPayloadOptions) (AnthropicPayload, error)

type AnthropicPayloadOptions

type AnthropicPayloadOptions struct {
	MaxTokens        int
	Temperature      *float64
	CacheRetention   string
	SessionID        string
	Reasoning        string
	ThinkingBudgets  map[string]int
	ThinkingDisplay  string
	Metadata         map[string]any
	Headers          map[string]string
	IsOAuthToken     bool
	InterleavedThink *bool
	// contains filtered or unexported fields
}

type AnthropicRawUsage

type AnthropicRawUsage struct {
	InputTokens              int                          `json:"input_tokens"`
	OutputTokens             int                          `json:"output_tokens"`
	CacheReadInputTokens     int                          `json:"cache_read_input_tokens"`
	CacheCreationInputTokens int                          `json:"cache_creation_input_tokens"`
	CacheCreation            AnthropicCacheCreationUsage  `json:"cache_creation"`
	OutputTokensDetails      AnthropicOutputTokensDetails `json:"output_tokens_details"`
}

type AnthropicRequestState added in v0.82.0

type AnthropicRequestState struct {
	Compat            AnthropicCompat
	ToolPlacement     DeferredToolSet
	DeferredToolNames map[string]struct{}
	NormalizeToolName ToolNameNormalizer
}

AnthropicRequestState is resolved once per request so message references and the advertised tool list cannot disagree about deferred placement.

func ResolveAnthropicRequestState added in v0.82.0

func ResolveAnthropicRequestState(model Model, context Context, isOAuthToken bool) AnthropicRequestState

type AnthropicSSEEvent

type AnthropicSSEEvent struct {
	Event string
	Data  string
}

type AnthropicStreamProcessor added in v0.82.2

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

AnthropicStreamProcessor owns the single mutable partial-message state used for both incremental events and the terminal result.

func NewAnthropicStreamProcessor added in v0.82.2

func NewAnthropicStreamProcessor(model Model) *AnthropicStreamProcessor

func (*AnthropicStreamProcessor) Fail added in v0.82.2

func (p *AnthropicStreamProcessor) Fail(err error, aborted bool) Message

func (*AnthropicStreamProcessor) Finish added in v0.82.2

func (p *AnthropicStreamProcessor) Finish() (Message, error)

func (*AnthropicStreamProcessor) Message added in v0.82.2

func (p *AnthropicStreamProcessor) Message() Message

func (*AnthropicStreamProcessor) Process added in v0.82.2

type AnthropicTool

type AnthropicTool struct {
	Name                string                    `json:"name"`
	Description         string                    `json:"description,omitempty"`
	EagerInputStreaming *bool                     `json:"eager_input_streaming,omitempty"`
	Strict              *bool                     `json:"strict,omitempty"`
	InputSchema         map[string]any            `json:"input_schema"`
	DeferLoading        bool                      `json:"defer_loading,omitempty"`
	CacheControl        *OpenAICompatCacheControl `json:"cache_control,omitempty"`
}

func ConvertAnthropicTools

func ConvertAnthropicTools(tools []Tool, isOAuthToken bool, supportsEagerToolInputStreaming bool, cacheControl *OpenAICompatCacheControl) []AnthropicTool

func ConvertAnthropicToolsChecked added in v0.82.0

func ConvertAnthropicToolsChecked(tools []Tool, options AnthropicToolOptions) ([]AnthropicTool, error)

type AnthropicToolOptions added in v0.82.0

type AnthropicToolOptions struct {
	IsOAuthToken                    bool
	SupportsEagerToolInputStreaming bool
	SupportsStrictTools             bool
	CacheControl                    *OpenAICompatCacheControl
	DeferLoading                    bool
}

type AssistantImages

type AssistantImages struct {
	API          string
	Provider     string
	Model        string
	Output       []ImagesContent
	ResponseID   string
	Usage        Usage
	StopReason   string
	ErrorMessage string
	Timestamp    int64
}

func AbortedImages

func AbortedImages(model ImagesModel, err error) AssistantImages

func ErrorImages

func ErrorImages(model ImagesModel, err error) AssistantImages

func GenerateImages

func GenerateImages(model ImagesModel, imagesContext ImagesContext, options ImagesOptions) (AssistantImages, error)

func ParseOpenRouterImagesResponse

func ParseOpenRouterImagesResponse(model ImagesModel, response OpenRouterImagesResponse) AssistantImages

type AssistantMessageDiagnostic

type AssistantMessageDiagnostic struct {
	Type      string               `json:"type"`
	Timestamp int64                `json:"timestamp"`
	Error     *DiagnosticErrorInfo `json:"error,omitempty"`
	Details   map[string]any       `json:"details,omitempty"`
}

func NewAssistantMessageDiagnostic

func NewAssistantMessageDiagnostic(diagnosticType string, err error, details map[string]any) AssistantMessageDiagnostic

type AssistantMessageEvent

type AssistantMessageEvent struct {
	Type             string      `json:"type"`
	Partial          Message     `json:"partial,omitempty"`
	Message          Message     `json:"message,omitempty"`
	Error            Message     `json:"error,omitempty"`
	Reason           string      `json:"reason,omitempty"`
	ContentIndex     int         `json:"contentIndex,omitempty"`
	Delta            string      `json:"delta,omitempty"`
	Content          string      `json:"content,omitempty"`
	ContentSignature string      `json:"contentSignature,omitempty"`
	Redacted         *bool       `json:"redacted,omitempty"`
	ID               string      `json:"id,omitempty"`
	ToolName         string      `json:"toolName,omitempty"`
	ToolCall         ContentPart `json:"toolCall,omitempty"`
}

func ProcessBedrockConverseStreamEvents

func ProcessBedrockConverseStreamEvents(model Model, output *Message, events []BedrockConverseStreamEvent) []AssistantMessageEvent

func ProcessOpenAICodexStreamEvents

func ProcessOpenAICodexStreamEvents(model Model, output *Message, events []OpenAIResponsesStreamEvent, options OpenAICodexProcessOptions) []AssistantMessageEvent

func ProcessOpenAIResponsesStreamEvents

func ProcessOpenAIResponsesStreamEvents(model Model, output *Message, events []OpenAIResponsesStreamEvent) []AssistantMessageEvent

func (AssistantMessageEvent) MarshalJSON added in v0.82.2

func (e AssistantMessageEvent) MarshalJSON() ([]byte, error)

MarshalJSON projects the unified Go event state onto Pi's discriminated event union. In particular, contentIndex must remain present when it is zero, while inactive message fields must not leak onto another event variant.

type AssistantMessageEventStream

type AssistantMessageEventStream = EventStream[AssistantMessageEvent, Message]

func CompletedAssistantStream

func CompletedAssistantStream(message Message) *AssistantMessageEventStream

func ErrorAssistantStream

func ErrorAssistantStream(message Message) *AssistantMessageEventStream

func NewAssistantMessageEventStream

func NewAssistantMessageEventStream() *AssistantMessageEventStream

func Stream

func Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)

func StreamSimple

func StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type AuthCheck added in v0.82.0

type AuthCheck struct {
	Source string
	Type   CredentialType
}

AuthCheck describes auth availability without resolving request secrets.

type AuthContext added in v0.82.0

type AuthContext interface {
	Env(ctx context.Context, name string) (value string, ok bool, err error)
	FileExists(ctx context.Context, path string) (bool, error)
}

AuthContext isolates ambient process state so auth resolution remains deterministic in tests and reusable by non-CLI applications.

func DefaultProviderAuthContext added in v0.82.0

func DefaultProviderAuthContext() AuthContext

DefaultProviderAuthContext returns the process-backed auth context.

type AuthContextFuncs added in v0.82.0

type AuthContextFuncs struct {
	EnvFunc        func(ctx context.Context, name string) (value string, ok bool, err error)
	FileExistsFunc func(ctx context.Context, path string) (bool, error)
}

AuthContextFuncs adapts functions to AuthContext. Missing functions use the same behavior as ProcessAuthContext.

func (AuthContextFuncs) Env added in v0.82.0

func (f AuthContextFuncs) Env(ctx context.Context, name string) (string, bool, error)

func (AuthContextFuncs) FileExists added in v0.82.0

func (f AuthContextFuncs) FileExists(ctx context.Context, path string) (bool, error)

type AuthEvent added in v0.82.0

type AuthEvent struct {
	Type             AuthEventType
	Message          string
	Links            []AuthInfoLink
	URL              string
	Instructions     string
	UserCode         string
	VerificationURI  string
	IntervalSeconds  int
	ExpiresInSeconds int
}

AuthEvent describes an out-of-band login notification.

type AuthEventType added in v0.82.0

type AuthEventType string

AuthEventType identifies an out-of-band login notification.

const (
	// AuthEventInfo reports general login information.
	AuthEventInfo AuthEventType = "info"
	// AuthEventURL asks the user to open an authorization URL.
	AuthEventURL AuthEventType = "auth_url"
	// AuthEventDeviceCode reports a device authorization challenge.
	AuthEventDeviceCode AuthEventType = "device_code"
	// AuthEventProgress reports non-terminal login progress.
	AuthEventProgress AuthEventType = "progress"
)
type AuthInfoLink struct {
	URL   string
	Label string
}

AuthInfoLink is a user-facing link attached to an auth event.

type AuthInteraction added in v0.82.0

type AuthInteraction interface {
	Prompt(ctx context.Context, prompt AuthPrompt) (string, error)
	Notify(event AuthEvent)
}

AuthInteraction is implemented by the application so provider login flows remain independent of any terminal or UI package.

type AuthPrompt added in v0.82.0

type AuthPrompt struct {
	Type        AuthPromptType
	Message     string
	Placeholder string
	Options     []AuthPromptOption
}

AuthPrompt describes one interactive login request.

type AuthPromptOption added in v0.82.0

type AuthPromptOption struct {
	ID          string
	Label       string
	Description string
}

AuthPromptOption is one selectable login response.

type AuthPromptType added in v0.82.0

type AuthPromptType string

AuthPromptType identifies an interactive login input shape.

const (
	// AuthPromptText requests visible free-form text.
	AuthPromptText AuthPromptType = "text"
	// AuthPromptSecret requests a secret value.
	AuthPromptSecret AuthPromptType = "secret"
	// AuthPromptSelect requests one option identifier.
	AuthPromptSelect AuthPromptType = "select"
	// AuthPromptManualCode requests an OAuth callback code.
	AuthPromptManualCode AuthPromptType = "manual_code"
)

type AuthResolutionOverrides added in v0.82.0

type AuthResolutionOverrides struct {
	// APIKey is a pointer so callers can distinguish no override from an
	// explicit empty key.
	APIKey *string
	Env    ProviderEnv
}

AuthResolutionOverrides contains request-scoped key and environment values.

type AuthResult added in v0.82.0

type AuthResult struct {
	Auth   ModelAuth
	Env    ProviderEnv
	Source string
}

AuthResult contains resolved request auth plus status-facing provenance.

func ResolveProviderAuth added in v0.82.0

func ResolveProviderAuth(
	ctx context.Context,
	providerID string,
	auth ProviderAuth,
	credentials CredentialStore,
	authContext AuthContext,
	overrides AuthResolutionOverrides,
) (*AuthResult, error)

ResolveProviderAuth resolves the effective authentication for a provider. A stored credential owns the provider: ambient sources are consulted only when no credential exists.

type AzureOpenAIConfig

type AzureOpenAIConfig struct {
	BaseURL    string
	APIVersion string
}

func ResolveAzureOpenAIConfig

func ResolveAzureOpenAIConfig(model Model, options AzureOpenAIResponsesOptions) (AzureOpenAIConfig, error)

type AzureOpenAIResponsesOptions

type AzureOpenAIResponsesOptions struct {
	AzureAPIVersion     string
	AzureResourceName   string
	AzureBaseURL        string
	AzureDeploymentName string
	Env                 ProviderEnv
}

type AzureOpenAIResponsesPayload

type AzureOpenAIResponsesPayload struct {
	Model           string                     `json:"model"`
	Input           []OpenAIResponsesInputItem `json:"input"`
	Stream          bool                       `json:"stream"`
	Store           bool                       `json:"store"`
	PromptCacheKey  string                     `json:"prompt_cache_key,omitempty"`
	MaxOutputTokens int                        `json:"max_output_tokens,omitempty"`
	Temperature     *float64                   `json:"temperature,omitempty"`
	Tools           []OpenAIResponsesTool      `json:"tools,omitempty"`
	Reasoning       map[string]string          `json:"reasoning,omitempty"`
	Include         []string                   `json:"include,omitempty"`
}

func BuildAzureOpenAIResponsesPayload

func BuildAzureOpenAIResponsesPayload(model Model, context Context, options AzureOpenAIResponsesPayloadOptions) AzureOpenAIResponsesPayload

func BuildAzureOpenAIResponsesPayloadChecked added in v0.82.0

func BuildAzureOpenAIResponsesPayloadChecked(
	model Model,
	context Context,
	options AzureOpenAIResponsesPayloadOptions,
) (AzureOpenAIResponsesPayload, error)

type AzureOpenAIResponsesPayloadOptions

type AzureOpenAIResponsesPayloadOptions struct {
	DeploymentName   string
	MaxTokens        int
	Temperature      *float64
	SessionID        string
	ReasoningEffort  string
	ReasoningSummary string
}

type AzureOpenAIResponsesProvider

type AzureOpenAIResponsesProvider struct {
	Client HTTPDoer
}

func NewAzureOpenAIResponsesProvider

func NewAzureOpenAIResponsesProvider(client HTTPDoer) AzureOpenAIResponsesProvider

func (AzureOpenAIResponsesProvider) Stream

func (AzureOpenAIResponsesProvider) StreamSimple

func (p AzureOpenAIResponsesProvider) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type BedrockCachePoint

type BedrockCachePoint struct {
	Type string
	TTL  string
}

type BedrockClientConfig

type BedrockClientConfig struct {
	Endpoint    string
	Region      string
	Profile     string
	Credentials *BedrockCredentials
	BearerToken string
	SkipAuth    bool
	ProxyURL    string
	ForceHTTP1  bool
}

func ResolveBedrockClientConfig

func ResolveBedrockClientConfig(model Model, options BedrockClientOptions) BedrockClientConfig

func ResolveBedrockClientConfigChecked added in v0.82.0

func ResolveBedrockClientConfigChecked(
	model Model,
	options BedrockClientOptions,
) (BedrockClientConfig, error)

ResolveBedrockClientConfigChecked resolves the complete live-client configuration and surfaces proxy validation errors before the AWS SDK loads ambient credentials or profiles.

type BedrockClientOptions

type BedrockClientOptions struct {
	Region      string
	Profile     string
	APIKey      string
	BearerToken string
	Env         ProviderEnv
}

type BedrockContentBlock

type BedrockContentBlock struct {
	Text             string
	Image            *BedrockImageBlock
	ToolUse          *BedrockToolUseBlock
	ToolResult       *BedrockToolResultBlock
	ReasoningContent *BedrockReasoningContent
	CachePoint       *BedrockCachePoint
}

type BedrockContentBlockDeltaEvent

type BedrockContentBlockDeltaEvent struct {
	ContentBlockIndex int
	Text              string
	ToolUseInput      string
	ReasoningContent  *BedrockReasoningContent
}

type BedrockContentBlockStartEvent

type BedrockContentBlockStartEvent struct {
	ContentBlockIndex int
	ToolUse           *BedrockToolUseBlock
}

type BedrockContentBlockStopEvent

type BedrockContentBlockStopEvent struct {
	ContentBlockIndex int
}

type BedrockConverseStreamEvent

type BedrockConverseStreamEvent struct {
	MessageStart      *BedrockMessageStartEvent
	ContentBlockStart *BedrockContentBlockStartEvent
	ContentBlockDelta *BedrockContentBlockDeltaEvent
	ContentBlockStop  *BedrockContentBlockStopEvent
	MessageStop       *BedrockMessageStopEvent
	Metadata          *BedrockMetadataEvent
	Error             error
}

type BedrockConverseStreamProcessor

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

func NewBedrockConverseStreamProcessor

func NewBedrockConverseStreamProcessor(model Model, output *Message) *BedrockConverseStreamProcessor

func (*BedrockConverseStreamProcessor) Process

type BedrockConverseStreamProvider

type BedrockConverseStreamProvider struct {
	Transport BedrockConverseStreamTransport
}

func (BedrockConverseStreamProvider) Stream

func (BedrockConverseStreamProvider) StreamSimple

type BedrockConverseStreamRequest

type BedrockConverseStreamRequest struct {
	Model           Model
	Payload         BedrockPayload
	ClientConfig    BedrockClientConfig
	MaxTokens       int
	Temperature     *float64
	CacheRetention  string
	RequestMetadata map[string]string
	Headers         map[string]string
	OnResponse      func(status int, headers map[string]string) error
}

type BedrockConverseStreamTransport

type BedrockConverseStreamTransport func(context.Context, BedrockConverseStreamRequest) (<-chan BedrockConverseStreamEvent, error)

func NewAWSBedrockConverseStreamTransport added in v0.82.0

func NewAWSBedrockConverseStreamTransport() BedrockConverseStreamTransport

NewAWSBedrockConverseStreamTransport returns the package's live AWS SDK v2 transport. The provider still accepts an injected transport for deterministic tests and applications that own a custom Bedrock boundary.

type BedrockCredentials added in v0.82.0

type BedrockCredentials struct {
	AccessKeyID     string
	SecretAccessKey string
	SessionToken    string
}

func GetConfiguredBedrockCredentials added in v0.82.0

func GetConfiguredBedrockCredentials(env ProviderEnv) *BedrockCredentials

type BedrockImageBlock

type BedrockImageBlock struct {
	Format string
	Data   string
}

type BedrockMessage

type BedrockMessage struct {
	Role    string
	Content []BedrockContentBlock
}

func ConvertBedrockMessages

func ConvertBedrockMessages(model Model, context Context, cacheRetention string, forcePromptCache bool) []BedrockMessage

type BedrockMessageStartEvent

type BedrockMessageStartEvent struct {
	Role string
}

type BedrockMessageStopEvent

type BedrockMessageStopEvent struct {
	StopReason string
}

type BedrockMetadataEvent

type BedrockMetadataEvent struct {
	Usage BedrockUsage
}

type BedrockNamedToolChoice

type BedrockNamedToolChoice struct {
	Type string
	Name string
}

type BedrockPayload

type BedrockPayload struct {
	System                       []BedrockContentBlock
	Messages                     []BedrockMessage
	ToolConfig                   *BedrockToolConfig
	AdditionalModelRequestFields map[string]any
}

func BuildBedrockPayload

func BuildBedrockPayload(model Model, context Context, options BedrockPayloadOptions) BedrockPayload

func BuildBedrockPayloadChecked added in v0.82.0

func BuildBedrockPayloadChecked(
	model Model,
	context Context,
	options BedrockPayloadOptions,
) (BedrockPayload, error)

BuildBedrockPayloadChecked validates constrained-sampling requirements while converting the provider-neutral context into the canonical Bedrock payload.

type BedrockPayloadOptions

type BedrockPayloadOptions struct {
	Reasoning           string
	Region              string
	ThinkingBudgets     map[string]int
	ThinkingDisplay     string
	InterleavedThinking *bool
	CacheRetention      string
	ForcePromptCache    bool
	ToolChoice          any
}

type BedrockReasoningContent

type BedrockReasoningContent struct {
	Text      string
	Signature string
}

type BedrockTool

type BedrockTool struct {
	ToolSpec BedrockToolSpec
}

type BedrockToolConfig

type BedrockToolConfig struct {
	Tools      []BedrockTool
	ToolChoice any
}

func ConvertBedrockToolConfig

func ConvertBedrockToolConfig(tools []Tool, toolChoice any) *BedrockToolConfig

type BedrockToolInputSchema

type BedrockToolInputSchema struct {
	JSON map[string]any
}

type BedrockToolResultBlock

type BedrockToolResultBlock struct {
	ToolUseID string
	Content   []BedrockContentBlock
	Status    string
}

type BedrockToolSpec

type BedrockToolSpec struct {
	Name        string
	Description string
	InputSchema BedrockToolInputSchema
	Strict      *bool
}

type BedrockToolUseBlock

type BedrockToolUseBlock struct {
	ToolUseID string
	Name      string
	Input     map[string]any
}

type BedrockUsage

type BedrockUsage struct {
	InputTokens          int
	OutputTokens         int
	CacheReadInputTokens int
	CacheWriteTokens     int
	TotalTokens          int
}

type ConstrainedSamplingConfig added in v0.82.0

type ConstrainedSamplingConfig struct {
	Type     ConstrainedSamplingType       `json:"type"`
	Strict   ConstrainedSamplingStrictness `json:"strict,omitempty"`
	Variants GrammarVariants               `json:"variants,omitempty"`
}

ConstrainedSamplingConfig is the Go representation of Pi's discriminated constrained-sampling union. A nil Tool.ConstrainedSampling is equivalent to Pi's absent/false value.

type ConstrainedSamplingStrictness added in v0.82.0

type ConstrainedSamplingStrictness string
const (
	ConstrainedSamplingPrefer  ConstrainedSamplingStrictness = "prefer"
	ConstrainedSamplingRequire ConstrainedSamplingStrictness = "require"
)

type ConstrainedSamplingType added in v0.82.0

type ConstrainedSamplingType string
const (
	ConstrainedSamplingJSONSchema ConstrainedSamplingType = "json_schema"
	ConstrainedSamplingGrammar    ConstrainedSamplingType = "grammar"
)

type ContentPart

type ContentPart struct {
	Type              string         `json:"type"`
	Text              string         `json:"text,omitempty"`
	TextSignature     string         `json:"textSignature,omitempty"`
	Thinking          string         `json:"thinking,omitempty"`
	ThinkingSignature string         `json:"thinkingSignature,omitempty"`
	Redacted          bool           `json:"redacted,omitempty"`
	Data              string         `json:"data,omitempty"`
	MIMEType          string         `json:"mimeType,omitempty"`
	ID                string         `json:"id,omitempty"`
	Name              string         `json:"name,omitempty"`
	Arguments         map[string]any `json:"arguments,omitempty"`
	ThoughtSignature  string         `json:"thoughtSignature,omitempty"`
}

func FauxText

func FauxText(text string) ContentPart

func FauxThinking

func FauxThinking(thinking string) ContentPart

func FauxToolCall

func FauxToolCall(name string, arguments map[string]any, id string) ContentPart

func Image

func Image(data, mimeType string) ContentPart

func Text

func Text(text string) ContentPart

func Thinking

func Thinking(thinking string) ContentPart

func ToolCall

func ToolCall(id, name string, args map[string]any) ContentPart

func (ContentPart) MarshalJSON added in v0.82.2

func (p ContentPart) MarshalJSON() ([]byte, error)

MarshalJSON projects the unified content state onto Pi's discriminated content union, retaining required empty values at stream-start boundaries.

type Context

type Context struct {
	SystemPrompt string    `json:"systemPrompt,omitempty"`
	Messages     []Message `json:"messages,omitempty"`
	Tools        []Tool    `json:"tools,omitempty"`
}

type ContextUsageEstimate added in v0.82.0

type ContextUsageEstimate struct {
	Tokens         int  `json:"tokens"`
	UsageTokens    int  `json:"usageTokens"`
	TrailingTokens int  `json:"trailingTokens"`
	LastUsageIndex *int `json:"lastUsageIndex"`
}

ContextUsageEstimate separates a provider-reported prefix checkpoint from locally estimated content appended after that checkpoint.

func EstimateContextTokens added in v0.82.0

func EstimateContextTokens(context Context) ContextUsageEstimate

EstimateContextTokens estimates the full provider context. A valid assistant usage checkpoint already includes the prior system prompt and tool schemas, so only transcript-loaded tools introduced after that checkpoint are added.

func EstimateMessagesTokens added in v0.82.0

func EstimateMessagesTokens(messages []Message) ContextUsageEstimate

EstimateMessagesTokens estimates a message-only context.

type ConvertOpenAIResponsesOptions

type ConvertOpenAIResponsesOptions struct {
	AllowedToolCallProviders   map[string]bool
	IncludeSystemPrompt        *bool
	SupportsDeveloperRole      *bool
	GrammarToolInputProperties map[string]string
	DeferredTools              map[string]Tool
	ToolOptions                OpenAIResponsesToolOptions
}

type CreateImagesProviderOptions added in v0.82.0

type CreateImagesProviderOptions struct {
	ID     string
	Name   string
	Auth   ProviderAuth
	Models []ImagesModel

	FetchModels func(ctx context.Context) ([]ImagesModel, error)
	API         ImagesAPIProvider
}

CreateImagesProviderOptions describes an image provider with a static model snapshot, optional dynamic refresh, and one transport implementation.

type CreateProviderOptions added in v0.82.0

type CreateProviderOptions struct {
	ID      string
	Name    string
	BaseURL string
	Headers map[string]string
	Auth    ProviderAuth
	Models  []Model

	FetchModels  func(ctx context.Context, input RefreshModelsContext) ([]Model, error)
	FilterModels func(models []Model, credential *Credential) []Model
	API          APIProvider
	APIs         map[string]APIProvider
}

CreateProviderOptions describes a static catalog with an optional dynamic overlay and either one stream implementation or API-specific transports.

type Credential added in v0.82.0

type Credential struct {
	Type          CredentialType `json:"type"`
	Key           string         `json:"key,omitempty"`
	Access        string         `json:"access,omitempty"`
	Refresh       string         `json:"refresh,omitempty"`
	Expires       int64          `json:"expires,omitempty"`
	Env           ProviderEnv    `json:"env,omitempty"`
	EnterpriseURL string         `json:"enterpriseUrl,omitempty"`
	Metadata      map[string]any `json:"-"`
}

Credential is the canonical persisted auth record. Metadata preserves provider-specific OAuth fields without weakening the typed common fields.

func (Credential) Clone added in v0.82.0

func (c Credential) Clone() Credential

func (Credential) MarshalJSON added in v0.82.0

func (c Credential) MarshalJSON() ([]byte, error)

func (*Credential) UnmarshalJSON added in v0.82.0

func (c *Credential) UnmarshalJSON(data []byte) error

type CredentialInfo added in v0.82.0

type CredentialInfo struct {
	ProviderID string         `json:"providerId"`
	Type       CredentialType `json:"type"`
}

CredentialInfo is the non-secret projection returned by credential enumeration.

type CredentialModifier added in v0.82.0

type CredentialModifier func(ctx context.Context, current Credential, exists bool) (next Credential, write bool, err error)

CredentialModifier returns write=false to preserve the current credential. A successful write always replaces the provider's complete credential. Once a modifier returns write=true without an error, the store commits the value even if ctx was canceled during the modifier; this prevents losing a successfully rotated OAuth refresh token.

type CredentialStore added in v0.82.0

type CredentialStore interface {
	ReadCredential(ctx context.Context, providerID string) (Credential, bool, error)
	ListCredentials(ctx context.Context) ([]CredentialInfo, error)
	ModifyCredential(ctx context.Context, providerID string, modify CredentialModifier) (Credential, bool, error)
	DeleteCredential(ctx context.Context, providerID string) error
}

CredentialStore is the app-owned persistence boundary. ModifyCredential is the only write path so OAuth refresh and login cannot overwrite each other.

type CredentialType added in v0.82.0

type CredentialType string

CredentialType identifies the persisted credential variant.

const (
	// CredentialTypeAPIKey stores an API key or a resolvable key expression.
	CredentialTypeAPIKey CredentialType = "api_key"
	// CredentialTypeOAuth stores a renewable OAuth token set.
	CredentialTypeOAuth CredentialType = "oauth"
)

type DeferredToolSet added in v0.82.0

type DeferredToolSet struct {
	Immediate     []Tool
	Deferred      map[string]Tool
	DeferredTools []Tool
}

DeferredToolSet is the request-time split between tools sent in the request prefix and tools loaded at transcript markers. Callers treat it as read-only after resolution.

func SplitDeferredTools added in v0.82.0

func SplitDeferredTools(context Context, enabled bool, normalizeName ToolNameNormalizer) DeferredToolSet

SplitDeferredTools classifies the current tool registry against transcript load markers. The last definition for a normalized name wins while the first occurrence owns deterministic output order, matching JavaScript Map order.

type DiagnosticErrorInfo

type DiagnosticErrorInfo struct {
	Name    string `json:"name,omitempty"`
	Message string `json:"message"`
	Stack   string `json:"stack,omitempty"`
	Code    any    `json:"code,omitempty"`
}

func ExtractDiagnosticError

func ExtractDiagnosticError(value any) DiagnosticErrorInfo

type EventStream

type EventStream[T any, R any] struct {
	*eventstream.EventStream[T, R]
}

func NewEventStream

func NewEventStream[T any, R any](isComplete func(T) bool, extract func(T) R) *EventStream[T, R]

type FauxModelDefinition

type FauxModelDefinition struct {
	ID            string
	Name          string
	Reasoning     bool
	Input         []string
	Cost          ModelCost
	ContextWindow int
	MaxTokens     int
}

type FauxOption

type FauxOption func(*FauxOptions)

func WithFauxAPI

func WithFauxAPI(api string) FauxOption

func WithFauxModels

func WithFauxModels(models ...FauxModelDefinition) FauxOption

func WithFauxProvider

func WithFauxProvider(provider string) FauxOption

func WithFauxTokenSize

func WithFauxTokenSize(min, max int) FauxOption

func WithFauxTokensPerSecond

func WithFauxTokensPerSecond(tokensPerSecond float64) FauxOption

type FauxOptions

type FauxOptions struct {
	API             string
	Provider        string
	Models          []FauxModelDefinition
	TokensPerSecond float64
	TokenSize       FauxTokenSize
}

type FauxProviderHandle added in v0.82.0

type FauxProviderHandle struct {
	Provider *Provider
	// contains filtered or unexported fields
}

FauxProviderHandle owns an isolated provider and its deterministic response queue. It avoids the process-wide API registry and is safe to use alongside other Models collections.

func NewFauxProvider added in v0.82.0

func NewFauxProvider(options ...FauxOption) (*FauxProviderHandle, error)

NewFauxProvider constructs an instance-scoped faux provider for integration tests and embedding applications.

func (*FauxProviderHandle) AppendResponses added in v0.82.0

func (f *FauxProviderHandle) AppendResponses(responses []FauxResponseStep)

AppendResponses appends responses to the faux queue.

func (*FauxProviderHandle) GetModel added in v0.82.0

func (f *FauxProviderHandle) GetModel(modelID ...string) (Model, bool)

GetModel returns a detached model from the faux provider catalog.

func (*FauxProviderHandle) PendingResponseCount added in v0.82.0

func (f *FauxProviderHandle) PendingResponseCount() int

PendingResponseCount returns the number of responses not yet consumed.

func (*FauxProviderHandle) SetResponses added in v0.82.0

func (f *FauxProviderHandle) SetResponses(responses []FauxResponseStep)

SetResponses replaces the queued faux responses.

func (*FauxProviderHandle) State added in v0.82.0

func (f *FauxProviderHandle) State() FauxState

State returns a consistent snapshot of the faux provider state.

type FauxProviderRegistration

type FauxProviderRegistration struct {
	API      string
	Provider string
	Models   []Model
	State    FauxState
	// contains filtered or unexported fields
}

func RegisterFauxProvider

func RegisterFauxProvider(options ...FauxOption) *FauxProviderRegistration

func (*FauxProviderRegistration) AppendResponses

func (r *FauxProviderRegistration) AppendResponses(responses []FauxResponseStep)

func (*FauxProviderRegistration) GetModel

func (r *FauxProviderRegistration) GetModel(modelID ...string) (Model, bool)

func (*FauxProviderRegistration) MustModel

func (r *FauxProviderRegistration) MustModel(modelID ...string) Model

func (*FauxProviderRegistration) PendingResponseCount

func (r *FauxProviderRegistration) PendingResponseCount() int

func (*FauxProviderRegistration) SetResponses

func (r *FauxProviderRegistration) SetResponses(responses []FauxResponseStep)

func (*FauxProviderRegistration) Stream

func (r *FauxProviderRegistration) Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)

func (*FauxProviderRegistration) StreamSimple

func (r *FauxProviderRegistration) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

func (*FauxProviderRegistration) Unregister

func (r *FauxProviderRegistration) Unregister()

type FauxResponseFactory

type FauxResponseFactory func(context Context, options StreamOptions, state FauxState, model Model) (Message, error)

type FauxResponseStep

type FauxResponseStep struct {
	Message Message
	Factory FauxResponseFactory
}

type FauxState

type FauxState struct {
	CallCount int
}

type FauxTokenSize

type FauxTokenSize struct {
	Min int
	Max int
}

type GitHubCopilotDevicePollResponse

type GitHubCopilotDevicePollResponse struct {
	AccessToken string
	Error       string
	Interval    int
}

type GitHubCopilotOAuthOptions added in v0.82.0

type GitHubCopilotOAuthOptions struct {
	Client              HTTPDoer
	RequestTimeout      time.Duration
	ModelCatalogTimeout time.Duration
}

GitHubCopilotOAuthOptions configures provider-owned GitHub Copilot OAuth transport. RequestTimeout covers login, token, and policy requests, while ModelCatalogTimeout bounds the account-specific model picker lookup.

type GoogleAuthOptions added in v0.82.0

type GoogleAuthOptions struct {
	KeyFilename string
}

GoogleAuthOptions captures the request-scoped ADC configuration that Pi passes to the Google client. Keeping it separate from the client config avoids mutating process-wide environment variables.

func BuildGoogleAuthOptions added in v0.82.0

func BuildGoogleAuthOptions(env ProviderEnv) *GoogleAuthOptions

BuildGoogleAuthOptions projects request-scoped provider environment into the explicit credential-file option used by an ADC token provider.

type GoogleCandidate

type GoogleCandidate struct {
	Content      GoogleContent `json:"content"`
	FinishReason string        `json:"finishReason"`
}

type GoogleContent

type GoogleContent struct {
	Role  string       `json:"role"`
	Parts []GooglePart `json:"parts"`
}

func ConvertGoogleMessages

func ConvertGoogleMessages(model Model, context Context) []GoogleContent

type GoogleFunctionCall

type GoogleFunctionCall struct {
	Name string         `json:"name"`
	Args map[string]any `json:"args"`
	ID   string         `json:"id,omitempty"`
}

type GoogleFunctionCallingConfig added in v0.82.0

type GoogleFunctionCallingConfig struct {
	Mode GoogleFunctionCallingMode `json:"mode"`
}

type GoogleFunctionCallingMode added in v0.82.0

type GoogleFunctionCallingMode string
const (
	GoogleFunctionCallingAuto      GoogleFunctionCallingMode = "AUTO"
	GoogleFunctionCallingNone      GoogleFunctionCallingMode = "NONE"
	GoogleFunctionCallingAny       GoogleFunctionCallingMode = "ANY"
	GoogleFunctionCallingValidated GoogleFunctionCallingMode = "VALIDATED"
)

func ResolveGoogleFunctionCallingMode added in v0.82.0

func ResolveGoogleFunctionCallingMode(
	tools []Tool,
	toolChoice any,
	supportsStrictMode bool,
) (GoogleFunctionCallingMode, error)

ResolveGoogleFunctionCallingMode combines caller tool choice with each tool's constrained-sampling contract. Sampling requirements are validated before applying the explicit Google mode.

type GoogleFunctionDeclaration

type GoogleFunctionDeclaration struct {
	Name                 string `json:"name"`
	Description          string `json:"description,omitempty"`
	Parameters           any    `json:"parameters,omitempty"`
	ParametersJSONSchema any    `json:"parametersJsonSchema,omitempty"`
}

type GoogleFunctionResponse

type GoogleFunctionResponse struct {
	Name     string         `json:"name"`
	Response map[string]any `json:"response"`
	Parts    []GooglePart   `json:"parts,omitempty"`
	ID       string         `json:"id,omitempty"`
}

type GoogleGenerateConfig

type GoogleGenerateConfig struct {
	Temperature     *float64              `json:"temperature,omitempty"`
	MaxOutputTokens int                   `json:"maxOutputTokens,omitempty"`
	ThinkingConfig  *GoogleThinkingConfig `json:"thinkingConfig,omitempty"`
}

type GoogleInlineData

type GoogleInlineData struct {
	MIMEType string `json:"mimeType"`
	Data     string `json:"data"`
}

type GooglePart

type GooglePart struct {
	Text             string                  `json:"text,omitempty"`
	Thought          bool                    `json:"thought,omitempty"`
	ThoughtSignature string                  `json:"thoughtSignature,omitempty"`
	InlineData       *GoogleInlineData       `json:"inlineData,omitempty"`
	FunctionCall     *GoogleFunctionCall     `json:"functionCall,omitempty"`
	FunctionResponse *GoogleFunctionResponse `json:"functionResponse,omitempty"`
}

type GooglePayload

type GooglePayload struct {
	Model             string               `json:"-"`
	Contents          []GoogleContent      `json:"contents"`
	Tools             []GoogleToolGroup    `json:"tools,omitempty"`
	ToolConfig        *GoogleToolConfig    `json:"toolConfig,omitempty"`
	SystemInstruction *GoogleSystemContent `json:"systemInstruction,omitempty"`
	Config            GoogleGenerateConfig `json:"generationConfig,omitempty"`
}

func BuildGooglePayload

func BuildGooglePayload(model Model, llmContext Context, options GooglePayloadOptions) GooglePayload

func BuildGooglePayloadChecked added in v0.82.0

func BuildGooglePayloadChecked(
	model Model,
	llmContext Context,
	options GooglePayloadOptions,
) (GooglePayload, error)

BuildGooglePayloadChecked resolves request-wide compatibility state before serializing the payload. Providers should use this form so invalid strict sampling requirements fail before any network request is attempted.

type GooglePayloadOptions

type GooglePayloadOptions struct {
	MaxTokens       int
	Temperature     *float64
	Reasoning       string
	ThinkingBudgets map[string]int
	ToolChoice      any
}

type GoogleProvider

type GoogleProvider struct {
	Client HTTPDoer
}

func NewGoogleProvider

func NewGoogleProvider(client HTTPDoer) GoogleProvider

func (GoogleProvider) Stream

func (p GoogleProvider) Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)

func (GoogleProvider) StreamSimple

func (p GoogleProvider) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type GoogleStreamChunk

type GoogleStreamChunk struct {
	ResponseID    string               `json:"responseId"`
	Candidates    []GoogleCandidate    `json:"candidates"`
	UsageMetadata *GoogleUsageMetadata `json:"usageMetadata,omitempty"`
}

func DecodeGoogleStreamChunk

func DecodeGoogleStreamChunk(data []byte) (GoogleStreamChunk, error)

type GoogleSystemContent

type GoogleSystemContent struct {
	Parts []GooglePart `json:"parts"`
}

type GoogleThinkingConfig

type GoogleThinkingConfig struct {
	IncludeThoughts *bool  `json:"includeThoughts,omitempty"`
	ThinkingLevel   string `json:"thinkingLevel,omitempty"`
	ThinkingBudget  *int   `json:"thinkingBudget,omitempty"`
}

func BuildGoogleThinkingConfig

func BuildGoogleThinkingConfig(model Model, options GoogleThinkingOptions) *GoogleThinkingConfig

func DisabledGoogleThinkingConfig

func DisabledGoogleThinkingConfig(model Model) *GoogleThinkingConfig

type GoogleThinkingOptions

type GoogleThinkingOptions struct {
	Enabled       *bool
	Level         string
	BudgetTokens  *int
	Reasoning     string
	CustomBudgets map[string]int
}

type GoogleToolConfig added in v0.82.0

type GoogleToolConfig struct {
	FunctionCallingConfig GoogleFunctionCallingConfig `json:"functionCallingConfig"`
}

type GoogleToolGroup

type GoogleToolGroup struct {
	FunctionDeclarations []GoogleFunctionDeclaration `json:"functionDeclarations"`
}

func ConvertGoogleTools

func ConvertGoogleTools(tools []Tool, useParameters bool) []GoogleToolGroup

type GoogleUsageMetadata

type GoogleUsageMetadata struct {
	PromptTokenCount        int `json:"promptTokenCount"`
	CandidatesTokenCount    int `json:"candidatesTokenCount"`
	ThoughtsTokenCount      int `json:"thoughtsTokenCount"`
	CachedContentTokenCount int `json:"cachedContentTokenCount"`
	TotalTokenCount         int `json:"totalTokenCount"`
}

type GoogleVertexAPIProvider added in v0.82.0

type GoogleVertexAPIProvider struct {
	Client        HTTPDoer
	TokenProvider GoogleVertexTokenProvider
}

GoogleVertexAPIProvider owns only stable dependencies. Authentication, endpoint selection, headers, and payload are resolved into request-local values before the HTTP call begins.

func NewGoogleVertexAPIProvider added in v0.82.0

func NewGoogleVertexAPIProvider(
	client HTTPDoer,
	tokenProvider GoogleVertexTokenProvider,
) GoogleVertexAPIProvider

NewGoogleVertexAPIProvider creates a Vertex API provider with injectable HTTP and ADC token boundaries. Nil dependencies select the package defaults.

func (GoogleVertexAPIProvider) Stream added in v0.82.0

func (p GoogleVertexAPIProvider) Stream(
	model Model,
	llmContext Context,
	options StreamOptions,
) (*AssistantMessageEventStream, error)

Stream starts a Vertex AI stream using fully specified options.

func (GoogleVertexAPIProvider) StreamSimple added in v0.82.0

func (p GoogleVertexAPIProvider) StreamSimple(
	model Model,
	llmContext Context,
	options SimpleStreamOptions,
) (*AssistantMessageEventStream, error)

StreamSimple applies the shared simple-option policy before starting Vertex.

type GoogleVertexClientConfig

type GoogleVertexClientConfig struct {
	VertexAI          bool
	APIKey            string
	Project           string
	Location          string
	APIVersion        string
	GoogleAuthOptions *GoogleAuthOptions
	HTTPOptions       *GoogleVertexHTTPOptions
}

func ResolveGoogleVertexClientConfig

func ResolveGoogleVertexClientConfig(model Model, options GoogleVertexOptions) GoogleVertexClientConfig

type GoogleVertexHTTPOptions

type GoogleVertexHTTPOptions struct {
	BaseURL              string
	BaseURLResourceScope string
	APIVersion           string
}

type GoogleVertexOptions

type GoogleVertexOptions struct {
	APIKey   string
	Project  string
	Location string
	Env      ProviderEnv
}

type GoogleVertexTokenProvider added in v0.82.0

type GoogleVertexTokenProvider interface {
	AccessToken(context.Context, GoogleVertexTokenRequest) (string, error)
}

GoogleVertexTokenProvider resolves an ADC access token for one request. Implementations must be safe for concurrent use.

type GoogleVertexTokenProviderFunc added in v0.82.0

type GoogleVertexTokenProviderFunc func(context.Context, GoogleVertexTokenRequest) (string, error)

GoogleVertexTokenProviderFunc adapts a function to GoogleVertexTokenProvider.

func (GoogleVertexTokenProviderFunc) AccessToken added in v0.82.0

type GoogleVertexTokenRequest added in v0.82.0

type GoogleVertexTokenRequest struct {
	Project     string
	Location    string
	AuthOptions *GoogleAuthOptions
}

GoogleVertexTokenRequest is the immutable authentication projection of one resolved Vertex request.

type GrammarConstrainedSampling added in v0.82.0

type GrammarConstrainedSampling struct {
	Format        GrammarFormat
	Definition    string
	InputProperty string
}

func ResolveGrammarConstrainedSampling added in v0.82.0

func ResolveGrammarConstrainedSampling(
	tool Tool,
	supportsOpenAIGrammarTools bool,
) (GrammarConstrainedSampling, bool, error)

type GrammarFormat added in v0.82.0

type GrammarFormat string
const (
	GrammarFormatLark  GrammarFormat = "lark"
	GrammarFormatRegex GrammarFormat = "regex"
)

type GrammarToolInputJSONBuffer added in v0.82.0

type GrammarToolInputJSONBuffer struct {
	Input   string
	Started bool
	Closed  bool
}

GrammarToolInputJSONBuffer tracks the append-only JSON projection exposed to generic tool-call stream consumers while a provider streams raw grammar text.

type GrammarVariants added in v0.82.0

type GrammarVariants struct {
	OpenAILark  string `json:"openai_lark,omitempty"`
	OpenAIRegex string `json:"openai_regex,omitempty"`
}

GrammarVariants carries provider-specific encodings of the same intended grammar. A provider selects only variants it explicitly supports.

type HTTPDoer

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

type HTTPRuntimeConfig added in v0.82.0

type HTTPRuntimeConfig struct {
	IdleTimeout time.Duration
	ProxyURL    string
}

HTTPRuntimeConfig describes the stable HTTP transport dependencies for a group of provider requests. IdleTimeout applies to each socket read, including response headers and streaming body chunks. Zero disables the timeout.

type ImagesAPIProvider

type ImagesAPIProvider interface {
	GenerateImages(model ImagesModel, imagesContext ImagesContext, options ImagesOptions) (AssistantImages, error)
}

func GetImagesAPIProvider

func GetImagesAPIProvider(api string) ImagesAPIProvider

type ImagesAPIProviderFuncs

type ImagesAPIProviderFuncs struct {
	GenerateImagesFunc func(ImagesModel, ImagesContext, ImagesOptions) (AssistantImages, error)
}

func (ImagesAPIProviderFuncs) GenerateImages

func (p ImagesAPIProviderFuncs) GenerateImages(model ImagesModel, imagesContext ImagesContext, options ImagesOptions) (AssistantImages, error)

type ImagesContent

type ImagesContent struct {
	Type     string
	Text     string
	Data     string
	MIMEType string
}

func ImageData

func ImageData(data, mimeType string) ImagesContent

func ImageText

func ImageText(text string) ImagesContent

type ImagesContext

type ImagesContext struct {
	Input []ImagesContent
}

type ImagesModel

type ImagesModel struct {
	ID       string
	Name     string
	API      string
	Provider string
	BaseURL  string
	Input    []string
	Output   []string
	Cost     ModelCost
	Headers  map[string]string
}

func GetImageModel

func GetImageModel(provider, id string) (ImagesModel, bool)

func GetImageModels

func GetImageModels(provider string) []ImagesModel

func MustGetImageModel

func MustGetImageModel(provider, id string) ImagesModel

type ImagesModels added in v0.82.0

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

ImagesModels is an instance-scoped image-provider collection. It owns registration and request assembly while transports remain stateless.

func BuiltinImagesModels added in v0.82.0

func BuiltinImagesModels(options ...ImagesModelsOptions) (*ImagesModels, error)

BuiltinImagesModels creates an isolated ImagesModels collection with every built-in image provider registered.

func NewImagesModels added in v0.82.0

func NewImagesModels(options ...ImagesModelsOptions) *ImagesModels

NewImagesModels creates an isolated image-provider collection.

func (*ImagesModels) ClearProviders added in v0.82.0

func (m *ImagesModels) ClearProviders()

ClearProviders removes every provider without affecting credentials.

func (*ImagesModels) DeleteProvider added in v0.82.0

func (m *ImagesModels) DeleteProvider(providerID string)

DeleteProvider removes one provider without affecting credentials.

func (*ImagesModels) GenerateImages added in v0.82.0

func (m *ImagesModels) GenerateImages(
	ctx context.Context,
	model ImagesModel,
	imagesContext ImagesContext,
	options ImagesOptions,
) AssistantImages

GenerateImages resolves provider auth, assembles a detached request, and returns failures as terminal image results rather than Go errors.

func (*ImagesModels) GetAuth added in v0.82.0

func (m *ImagesModels) GetAuth(
	ctx context.Context,
	providerID string,
	overrides AuthResolutionOverrides,
) (*AuthResult, error)

GetAuth resolves request authentication for one image provider.

func (*ImagesModels) GetModel added in v0.82.0

func (m *ImagesModels) GetModel(providerID, modelID string) (ImagesModel, bool)

GetModel finds one model in a provider's last-known catalog.

func (*ImagesModels) GetModelAuth added in v0.82.0

func (m *ImagesModels) GetModelAuth(
	ctx context.Context,
	model ImagesModel,
	overrides AuthResolutionOverrides,
) (*AuthResult, error)

GetModelAuth resolves request authentication for an image model.

func (*ImagesModels) GetModels added in v0.82.0

func (m *ImagesModels) GetModels(providerID ...string) []ImagesModel

GetModels returns last-known models for one provider or all providers. Provider source failures are isolated and yield no models.

func (*ImagesModels) GetProvider added in v0.82.0

func (m *ImagesModels) GetProvider(providerID string) (*ImagesProvider, bool)

GetProvider finds one registered provider.

func (*ImagesModels) GetProviders added in v0.82.0

func (m *ImagesModels) GetProviders() []*ImagesProvider

GetProviders returns providers in registration order.

func (*ImagesModels) Refresh added in v0.82.0

func (m *ImagesModels) Refresh(ctx context.Context, providerID ...string) error

Refresh updates one dynamic provider or all dynamic providers. A targeted failure is typed; an all-provider refresh is concurrent and best-effort.

func (*ImagesModels) SetProvider added in v0.82.0

func (m *ImagesModels) SetProvider(provider *ImagesProvider) error

SetProvider inserts or replaces a provider by ID without changing its existing registration position.

type ImagesModelsOptions added in v0.82.0

type ImagesModelsOptions = ModelsOptions

ImagesModelsOptions is shared with Models so text and image collections can use the same application-owned credential and authentication state.

type ImagesOptions

type ImagesOptions struct {
	Context context.Context
	APIKey  string
	// APIKeyOverride distinguishes an explicit empty key from no override.
	APIKeyOverride  *string
	Headers         map[string]string
	HeaderRemovals  []string
	Env             ProviderEnv
	TimeoutMillis   int
	MaxRetries      int
	MaxRetryDelayMs int
	Metadata        map[string]any
	OnPayload       func(payload any, model ImagesModel) (any, bool, error)
	OnResponse      func(status int, headers map[string]string, model ImagesModel) error
}

type ImagesProvider added in v0.82.0

type ImagesProvider struct {
	ID   string
	Name string
	Auth ProviderAuth

	ModelSource        func() ([]ImagesModel, error)
	RefreshModelsFunc  func(ctx context.Context) error
	GenerateImagesFunc func(
		model ImagesModel,
		imagesContext ImagesContext,
		options ImagesOptions,
	) (AssistantImages, error)
	// contains filtered or unexported fields
}

ImagesProvider is the image-generation counterpart of Provider. Its callbacks are immutable after registration; refreshed model state is owned by the callback implementation or a provider built with CreateImagesProvider.

func BuiltinImagesProviders added in v0.82.0

func BuiltinImagesProviders() ([]*ImagesProvider, error)

BuiltinImagesProviders constructs every built-in image provider in Pi declaration order.

func CreateImagesProvider added in v0.82.0

func CreateImagesProvider(options CreateImagesProviderOptions) (*ImagesProvider, error)

CreateImagesProvider constructs an image provider with clone-on-read model state and coalesced dynamic refreshes.

func NewOpenRouterImagesRuntimeProvider added in v0.82.0

func NewOpenRouterImagesRuntimeProvider() (*ImagesProvider, error)

NewOpenRouterImagesRuntimeProvider constructs the built-in OpenRouter image provider with the same API-key and OAuth contracts as the text provider.

func (*ImagesProvider) GenerateImages added in v0.82.0

func (p *ImagesProvider) GenerateImages(
	model ImagesModel,
	imagesContext ImagesContext,
	options ImagesOptions,
) (AssistantImages, error)

GenerateImages dispatches one request to the provider's image transport.

func (*ImagesProvider) GetModels added in v0.82.0

func (p *ImagesProvider) GetModels() ([]ImagesModel, error)

GetModels returns a detached snapshot of the provider's current catalog.

func (*ImagesProvider) RefreshModels added in v0.82.0

func (p *ImagesProvider) RefreshModels(ctx context.Context) error

RefreshModels updates a dynamic provider's catalog. Concurrent calls share one in-flight refresh.

type InMemoryCredentialStore added in v0.82.0

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

InMemoryCredentialStore is deterministic and safe for concurrent use. Mutations serialize per provider while unrelated providers can progress.

func NewInMemoryCredentialStore added in v0.82.0

func NewInMemoryCredentialStore(initial ...map[string]Credential) *InMemoryCredentialStore

NewInMemoryCredentialStore builds a store from an optional initial snapshot.

func (*InMemoryCredentialStore) DeleteCredential added in v0.82.0

func (s *InMemoryCredentialStore) DeleteCredential(ctx context.Context, providerID string) error

func (*InMemoryCredentialStore) ListCredentials added in v0.82.0

func (s *InMemoryCredentialStore) ListCredentials(ctx context.Context) ([]CredentialInfo, error)

func (*InMemoryCredentialStore) ModifyCredential added in v0.82.0

func (s *InMemoryCredentialStore) ModifyCredential(
	ctx context.Context,
	providerID string,
	modify CredentialModifier,
) (Credential, bool, error)

func (*InMemoryCredentialStore) ReadCredential added in v0.82.0

func (s *InMemoryCredentialStore) ReadCredential(ctx context.Context, providerID string) (Credential, bool, error)

type InMemoryModelsStore added in v0.82.0

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

InMemoryModelsStore is a concurrent, clone-on-read/write ModelsStore.

func NewInMemoryModelsStore added in v0.82.0

func NewInMemoryModelsStore(initial ...map[string]ModelsStoreEntry) *InMemoryModelsStore

NewInMemoryModelsStore builds a model store from an optional snapshot.

func (*InMemoryModelsStore) DeleteModels added in v0.82.0

func (s *InMemoryModelsStore) DeleteModels(ctx context.Context, providerID string) error

func (*InMemoryModelsStore) ReadModels added in v0.82.0

func (s *InMemoryModelsStore) ReadModels(
	ctx context.Context,
	providerID string,
) (ModelsStoreEntry, bool, error)

func (*InMemoryModelsStore) WriteModels added in v0.82.0

func (s *InMemoryModelsStore) WriteModels(
	ctx context.Context,
	providerID string,
	entry ModelsStoreEntry,
) error

type KimiCodingOAuthOptions added in v0.82.0

type KimiCodingOAuthOptions struct {
	Client         HTTPDoer
	AuthContext    AuthContext
	OAuthHost      string
	RequestTimeout time.Duration
}

KimiCodingOAuthOptions configures Kimi Code OAuth dependencies. OAuthHost takes precedence over KIMI_CODE_OAUTH_HOST and the legacy KIMI_OAUTH_HOST.

type Message

type Message struct {
	Role           string                       `json:"role"`
	Content        []ContentPart                `json:"content,omitempty"`
	Timestamp      int64                        `json:"timestamp,omitempty"`
	API            string                       `json:"api,omitempty"`
	Provider       string                       `json:"provider,omitempty"`
	Model          string                       `json:"model,omitempty"`
	ResponseModel  string                       `json:"responseModel,omitempty"`
	Diagnostics    []AssistantMessageDiagnostic `json:"diagnostics,omitempty"`
	Usage          Usage                        `json:"usage,omitempty"`
	StopReason     string                       `json:"stopReason,omitempty"`
	ErrorMessage   string                       `json:"errorMessage,omitempty"`
	ResponseID     string                       `json:"responseId,omitempty"`
	ToolCallID     string                       `json:"toolCallId,omitempty"`
	ToolName       string                       `json:"toolName,omitempty"`
	CustomType     string                       `json:"customType,omitempty"`
	Display        *bool                        `json:"display,omitempty"`
	Details        any                          `json:"details,omitempty"`
	IsError        bool                         `json:"isError,omitempty"`
	AddedToolNames []string                     `json:"addedToolNames,omitempty"`
}

func AssistantErrorMessage

func AssistantErrorMessage(message string, model Model, aborted bool) Message

func AssistantMessage

func AssistantMessage(content []ContentPart, stopReason string, model Model) Message

func Complete

func Complete(ctx context.Context, model Model, llmContext Context, options StreamOptions) (Message, error)

func CompleteSimple

func CompleteSimple(ctx context.Context, model Model, llmContext Context, options SimpleStreamOptions) (Message, error)

func FauxAssistantMessage

func FauxAssistantMessage(content []ContentPart, stopReason string) Message

func FauxAssistantText

func FauxAssistantText(text string) Message

func ProcessAnthropicSSEEvents

func ProcessAnthropicSSEEvents(model Model, events []AnthropicSSEEvent) (Message, error)

func ProcessOpenAICompletionsChunks

func ProcessOpenAICompletionsChunks(model Model, chunks []*OpenAIChatCompletionChunk) Message

func ProcessOpenAICompletionsChunksWithOptions added in v0.82.0

func ProcessOpenAICompletionsChunksWithOptions(
	model Model,
	chunks []*OpenAIChatCompletionChunk,
	options OpenAICompletionsStreamProcessorOptions,
) Message

func RetryAssistantCall added in v0.82.0

func RetryAssistantCall(
	ctx context.Context,
	policy RetryPolicy,
	callbacks RetryCallbacks,
	produce func(context.Context) (Message, error),
) (Message, error)

RetryAssistantCall applies bounded exponential backoff to assistant error messages. Go errors from produce remain Go errors and are never reclassified; provider adapters should first convert terminal provider failures to Message.

func TransformMessages

func TransformMessages(messages []Message, model Model, normalizeToolCallID NormalizeToolCallIDFunc) []Message

func UserMessageText

func UserMessageText(text string) Message

func (Message) MarshalJSON added in v0.82.2

func (m Message) MarshalJSON() ([]byte, error)

MarshalJSON preserves Pi's role-discriminated message wire shape while retaining one Go value type for state management. Assistant usage is required even when empty; user messages never carry usage; tool results carry it only when present.

type MistralCompletionChoice

type MistralCompletionChoice struct {
	Delta        MistralDelta `json:"delta"`
	FinishReason string       `json:"finish_reason"`
}

type MistralCompletionChunk

type MistralCompletionChunk struct {
	ID      string                    `json:"id"`
	Choices []MistralCompletionChoice `json:"choices"`
	Usage   *MistralUsage             `json:"usage,omitempty"`
}

func DecodeMistralCompletionChunk

func DecodeMistralCompletionChunk(data []byte) (MistralCompletionChunk, error)

type MistralContentPart

type MistralContentPart struct {
	Type     string        `json:"type"`
	Text     string        `json:"text,omitempty"`
	ImageURL string        `json:"image_url,omitempty"`
	Thinking []MistralText `json:"thinking,omitempty"`
}

type MistralDelta

type MistralDelta struct {
	Content   json.RawMessage         `json:"content,omitempty"`
	ToolCalls []MistralStreamToolCall `json:"tool_calls,omitempty"`
}

type MistralMessage

type MistralMessage struct {
	Role       string            `json:"role"`
	Content    any               `json:"content,omitempty"`
	ToolCalls  []MistralToolCall `json:"tool_calls,omitempty"`
	ToolCallID string            `json:"tool_call_id,omitempty"`
	Name       string            `json:"name,omitempty"`
}

func ConvertMistralMessages

func ConvertMistralMessages(model Model, context Context) []MistralMessage

type MistralPayload

type MistralPayload struct {
	Model           string           `json:"model"`
	Messages        []MistralMessage `json:"messages"`
	Tools           []MistralTool    `json:"tools,omitempty"`
	Stream          bool             `json:"stream"`
	MaxTokens       int              `json:"max_tokens,omitempty"`
	Temperature     *float64         `json:"temperature,omitempty"`
	ToolChoice      any              `json:"tool_choice,omitempty"`
	PromptMode      string           `json:"prompt_mode,omitempty"`
	ReasoningEffort string           `json:"reasoning_effort,omitempty"`
	PromptCacheKey  string           `json:"prompt_cache_key,omitempty"`
}

func BuildMistralPayload

func BuildMistralPayload(model Model, context Context, options MistralPayloadOptions) MistralPayload

type MistralPayloadOptions

type MistralPayloadOptions struct {
	MaxTokens      int
	Temperature    *float64
	Reasoning      string
	ToolChoice     any
	SessionID      string
	CacheRetention string
}

type MistralProvider

type MistralProvider struct {
	Client HTTPDoer
}

func NewMistralProvider

func NewMistralProvider(client HTTPDoer) MistralProvider

func (MistralProvider) Stream

func (p MistralProvider) Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)

func (MistralProvider) StreamSimple

func (p MistralProvider) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type MistralStreamEvent

type MistralStreamEvent struct {
	Data MistralCompletionChunk `json:"data"`
}

type MistralStreamToolCall

type MistralStreamToolCall struct {
	Index    *int                    `json:"index,omitempty"`
	ID       string                  `json:"id,omitempty"`
	Type     string                  `json:"type,omitempty"`
	Function MistralToolCallFunction `json:"function"`
}

type MistralText

type MistralText struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

type MistralTool

type MistralTool struct {
	Type     string              `json:"type"`
	Function MistralToolFunction `json:"function"`
}

func ConvertMistralTools

func ConvertMistralTools(tools []Tool) []MistralTool

type MistralToolCall

type MistralToolCall struct {
	ID       string                  `json:"id"`
	Type     string                  `json:"type"`
	Function MistralToolCallFunction `json:"function"`
}

type MistralToolCallFunction

type MistralToolCallFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type MistralToolFunction

type MistralToolFunction struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Parameters  any    `json:"parameters,omitempty"`
	Strict      bool   `json:"strict"`
}

type MistralUsage

type MistralUsage struct {
	PromptTokens       int `json:"prompt_tokens"`
	CompletionTokens   int `json:"completion_tokens"`
	TotalTokens        int `json:"total_tokens"`
	CachedPromptTokens int `json:"-"`
}

func (*MistralUsage) UnmarshalJSON added in v0.82.0

func (u *MistralUsage) UnmarshalJSON(data []byte) error

type Model

type Model struct {
	ID               string             `json:"id"`
	Name             string             `json:"name"`
	API              string             `json:"api"`
	Provider         string             `json:"provider"`
	BaseURL          string             `json:"baseUrl,omitempty"`
	Headers          map[string]string  `json:"headers,omitempty"`
	Compat           ModelCompat        `json:"compat,omitempty"`
	Reasoning        bool               `json:"reasoning"`
	Input            []string           `json:"input,omitempty"`
	Cost             ModelCost          `json:"cost"`
	ContextWindow    int                `json:"contextWindow"`
	MaxTokens        int                `json:"maxTokens"`
	ThinkingLevelMap map[string]*string `json:"thinkingLevelMap,omitempty"`
}

func GetBuiltinModel added in v0.82.0

func GetBuiltinModel(providerID, modelID string) (Model, bool)

GetBuiltinModel returns a detached model from the compiled release catalog.

func GetBuiltinModels added in v0.82.0

func GetBuiltinModels(providerID string) []Model

GetBuiltinModels returns one provider's detached compiled catalog.

func GetModel

func GetModel(provider, modelID string) (Model, bool)

func GetModels

func GetModels(provider string) []Model

func GetRadiusModels added in v0.82.0

func GetRadiusModels(providerID string, credential *Credential) []Model

GetRadiusModels returns models embedded in a legacy OAuth credential.

func GetRadiusModelsFromConfig added in v0.82.0

func GetRadiusModelsFromConfig(
	providerID string,
	config RadiusGatewayConfig,
) []Model

GetRadiusModelsFromConfig converts gateway rows into detached Gi models.

func MustGetModel

func MustGetModel(provider, modelID string) Model

func ResolveCloudflareModel added in v0.82.0

func ResolveCloudflareModel(model Model, env ProviderEnv) Model

ResolveCloudflareModel materializes account-scoped endpoint placeholders from the request-scoped provider environment without mutating the catalog model or process environment.

func (Model) Clone added in v0.82.1

func (m Model) Clone() Model

Clone returns a detached copy of the model and all mutable nested values.

type ModelAuth added in v0.82.0

type ModelAuth struct {
	APIKey         string
	Headers        map[string]string
	HeaderRemovals []string
	BaseURL        string
}

ModelAuth is the complete provider-scoped authentication result for one request. Provider-specific configuration that cannot be expressed here belongs on the provider itself.

type ModelCompat

type ModelCompat struct {
	SupportsStore                               *bool          `json:"supportsStore,omitempty"`
	SupportsDeveloperRole                       *bool          `json:"supportsDeveloperRole,omitempty"`
	SupportsReasoningEffort                     *bool          `json:"supportsReasoningEffort,omitempty"`
	SupportsUsageInStreaming                    *bool          `json:"supportsUsageInStreaming,omitempty"`
	SupportsStrictMode                          *bool          `json:"supportsStrictMode,omitempty"`
	SupportsOpenAIGrammarTools                  *bool          `json:"supportsOpenAIGrammarTools,omitempty"`
	SupportsLongCacheRetention                  *bool          `json:"supportsLongCacheRetention,omitempty"`
	SupportsEagerToolInputStreaming             *bool          `json:"supportsEagerToolInputStreaming,omitempty"`
	SupportsCacheControlOnTools                 *bool          `json:"supportsCacheControlOnTools,omitempty"`
	SupportsExplicitPromptCacheMode             *bool          `json:"supportsExplicitPromptCacheMode,omitempty"`
	SupportsTemperature                         *bool          `json:"supportsTemperature,omitempty"`
	SupportsStrictTools                         *bool          `json:"supportsStrictTools,omitempty"`
	SupportsToolReferences                      *bool          `json:"supportsToolReferences,omitempty"`
	SupportsToolSearch                          *bool          `json:"supportsToolSearch,omitempty"`
	ForceAdaptiveThinking                       *bool          `json:"forceAdaptiveThinking,omitempty"`
	AllowEmptySignature                         *bool          `json:"allowEmptySignature,omitempty"`
	SendSessionAffinityHeaders                  *bool          `json:"sendSessionAffinityHeaders,omitempty"`
	SendSessionIDHeader                         *bool          `json:"sendSessionIdHeader,omitempty"`
	RequiresToolResultName                      *bool          `json:"requiresToolResultName,omitempty"`
	RequiresAssistantAfterToolResult            *bool          `json:"requiresAssistantAfterToolResult,omitempty"`
	RequiresThinkingAsText                      *bool          `json:"requiresThinkingAsText,omitempty"`
	RequiresReasoningContentOnAssistantMessages *bool          `json:"requiresReasoningContentOnAssistantMessages,omitempty"`
	RequiresReasoningContentOnAssistantTurns    *bool          `json:"requiresReasoningContentOnAssistantTurns,omitempty"`
	RequiresReasoningContentOnAssistantEvents   *bool          `json:"requiresReasoningContentOnAssistantEvents,omitempty"`
	ZAIToolStream                               *bool          `json:"zaiToolStream,omitempty"`
	OpenRouterRouting                           map[string]any `json:"openRouterRouting,omitempty"`
	VercelGatewayRouting                        map[string]any `json:"vercelGatewayRouting,omitempty"`
	ChatTemplateKwargs                          map[string]any `json:"chatTemplateKwargs,omitempty"`
	MaxTokensField                              string         `json:"maxTokensField,omitempty"`
	ThinkingFormat                              string         `json:"thinkingFormat,omitempty"`
	CacheControlFormat                          string         `json:"cacheControlFormat,omitempty"`
	DeferredToolsMode                           string         `json:"deferredToolsMode,omitempty"`
	SessionAffinityFormat                       string         `json:"sessionAffinityFormat,omitempty"`
}

type ModelCost

type ModelCost struct {
	Input      float64         `json:"input"`
	Output     float64         `json:"output"`
	CacheRead  float64         `json:"cacheRead"`
	CacheWrite float64         `json:"cacheWrite"`
	Tiers      []ModelCostTier `json:"tiers,omitempty"`
}

type ModelCostTier added in v0.82.0

type ModelCostTier struct {
	InputTokensAbove int     `json:"inputTokensAbove"`
	Input            float64 `json:"input"`
	Output           float64 `json:"output"`
	CacheRead        float64 `json:"cacheRead"`
	CacheWrite       float64 `json:"cacheWrite"`
}

ModelCostTier replaces the base rates when total request input exceeds the configured threshold.

type Models added in v0.82.0

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

Models is an instance-scoped provider collection. It owns provider registration and orchestrates credentials, model catalogs, and request assembly while APIProvider implementations remain transport-only.

func BuiltinModels added in v0.82.0

func BuiltinModels(options ...ModelsOptions) (*Models, error)

BuiltinModels creates an isolated Models collection with every built-in provider registered.

func NewModels added in v0.82.0

func NewModels(options ...ModelsOptions) *Models

NewModels creates an isolated provider collection.

func (*Models) CheckAuth added in v0.82.0

func (m *Models) CheckAuth(ctx context.Context, providerID string) (AuthCheck, bool, error)

CheckAuth reports provider auth availability without refreshing OAuth.

func (*Models) ClearProviders added in v0.82.0

func (m *Models) ClearProviders()

ClearProviders removes every provider without changing credentials or persisted dynamic catalogs.

func (*Models) Complete added in v0.82.0

func (m *Models) Complete(
	ctx context.Context,
	model Model,
	llmContext Context,
	options ModelsStreamOptions,
) (Message, error)

Complete collects Stream's terminal assistant message.

func (*Models) CompleteSimple added in v0.82.0

func (m *Models) CompleteSimple(
	ctx context.Context,
	model Model,
	llmContext Context,
	options ModelsStreamOptions,
) (Message, error)

CompleteSimple collects StreamSimple's terminal assistant message.

func (*Models) DeleteProvider added in v0.82.0

func (m *Models) DeleteProvider(providerID string)

DeleteProvider removes a provider from this collection.

func (*Models) GetAuth added in v0.82.0

func (m *Models) GetAuth(
	ctx context.Context,
	providerID string,
	overrides AuthResolutionOverrides,
) (*AuthResult, error)

GetAuth resolves request auth for one provider.

func (*Models) GetAvailable added in v0.82.0

func (m *Models) GetAvailable(ctx context.Context, providerID ...string) ([]Model, error)

GetAvailable returns models whose providers have complete auth. Provider checks run concurrently while output remains in provider registration order.

func (*Models) GetModel added in v0.82.0

func (m *Models) GetModel(providerID, modelID string) (Model, bool)

GetModel finds a model within one provider's last-known catalog.

func (*Models) GetModelAuth added in v0.82.0

func (m *Models) GetModelAuth(
	ctx context.Context,
	model Model,
	overrides AuthResolutionOverrides,
) (*AuthResult, error)

GetModelAuth resolves provider auth and overlays static model headers.

func (*Models) GetModels added in v0.82.0

func (m *Models) GetModels(providerID ...string) []Model

GetModels returns the last-known models for one provider or every provider. Provider source errors are isolated and yield no models.

func (*Models) GetProvider added in v0.82.0

func (m *Models) GetProvider(providerID string) (*Provider, bool)

GetProvider finds one registered provider.

func (*Models) GetProviders added in v0.82.0

func (m *Models) GetProviders() []*Provider

GetProviders returns providers in registration order.

func (*Models) Login added in v0.82.0

func (m *Models) Login(
	ctx context.Context,
	providerID string,
	credentialType CredentialType,
	interaction AuthInteraction,
) (Credential, error)

Login runs a provider-owned login flow and persists its credential through the canonical serialized mutation path.

func (*Models) Logout added in v0.82.0

func (m *Models) Logout(ctx context.Context, providerID string) error

Logout removes one provider's stored credential.

func (*Models) Refresh added in v0.82.0

Refresh concurrently refreshes configured dynamic providers. Failures are returned per provider and do not discard another provider's successful result.

func (*Models) SetProvider added in v0.82.0

func (m *Models) SetProvider(provider *Provider) error

SetProvider inserts or replaces a provider by ID without changing its existing position.

func (*Models) Stream added in v0.82.0

func (m *Models) Stream(
	ctx context.Context,
	model Model,
	llmContext Context,
	options ModelsStreamOptions,
) *AssistantMessageEventStream

Stream resolves auth asynchronously and forwards the provider's native event stream. Setup failures become terminal stream errors.

func (*Models) StreamSimple added in v0.82.0

func (m *Models) StreamSimple(
	ctx context.Context,
	model Model,
	llmContext Context,
	options ModelsStreamOptions,
) *AssistantMessageEventStream

StreamSimple is the simple-options form of Stream.

type ModelsError added in v0.82.0

type ModelsError struct {
	Code ModelsErrorCode
	Msg  string
	Err  error
}

ModelsError preserves a stable machine-readable category while retaining the underlying cause for errors.Is and errors.As.

func (*ModelsError) Error added in v0.82.0

func (e *ModelsError) Error() string

func (*ModelsError) Unwrap added in v0.82.0

func (e *ModelsError) Unwrap() error

type ModelsErrorCode added in v0.82.0

type ModelsErrorCode string

ModelsErrorCode is a stable machine-readable models subsystem error class.

const (
	// ModelsErrorModelSource reports model source loading failures.
	ModelsErrorModelSource ModelsErrorCode = "model_source"
	// ModelsErrorModelValidation reports invalid model definitions.
	ModelsErrorModelValidation ModelsErrorCode = "model_validation"
	// ModelsErrorProvider reports provider registration or lookup failures.
	ModelsErrorProvider ModelsErrorCode = "provider"
	// ModelsErrorStream reports request streaming failures.
	ModelsErrorStream ModelsErrorCode = "stream"
	// ModelsErrorAuth reports API-key or credential-store failures.
	ModelsErrorAuth ModelsErrorCode = "auth"
	// ModelsErrorOAuth reports OAuth refresh or derivation failures.
	ModelsErrorOAuth ModelsErrorCode = "oauth"
)

type ModelsOptions added in v0.82.0

type ModelsOptions struct {
	Credentials CredentialStore
	ModelsStore ModelsStore
	AuthContext AuthContext
}

ModelsOptions supplies app-owned state boundaries to a Models collection.

type ModelsRefreshOptions added in v0.82.0

type ModelsRefreshOptions struct {
	Offline bool
	Force   bool
}

ModelsRefreshOptions controls dynamic catalog refresh. Offline is false by default so the zero value permits network access.

type ModelsRefreshResult added in v0.82.0

type ModelsRefreshResult struct {
	Aborted bool
	Errors  map[string]error
}

ModelsRefreshResult reports cancellation and provider-specific failures without failing the entire concurrent refresh.

type ModelsStore added in v0.82.0

type ModelsStore interface {
	ReadModels(ctx context.Context, providerID string) (ModelsStoreEntry, bool, error)
	WriteModels(ctx context.Context, providerID string, entry ModelsStoreEntry) error
	DeleteModels(ctx context.Context, providerID string) error
}

ModelsStore persists dynamic model catalogs by provider ID.

type ModelsStoreEntry added in v0.82.0

type ModelsStoreEntry struct {
	Models       []Model `json:"models"`
	LastModified *int64  `json:"lastModified,omitempty"`
	CheckedAt    int64   `json:"checkedAt,omitempty"`
	// ETag is the opaque remote validator, including any quotes, echoed back
	// verbatim as If-None-Match when Models contains the cached response body.
	ETag string `json:"etag,omitempty"`
}

ModelsStoreEntry is one provider's persisted dynamic model catalog.

type ModelsStreamOptions added in v0.82.0

type ModelsStreamOptions struct {
	StreamOptions
	APIKey           *string
	TransformHeaders TransformHeadersFunc
}

ModelsStreamOptions wraps provider options with Models-only request assembly controls. APIKey shadows StreamOptions.APIKey so an explicit empty override remains distinguishable from no override.

type NormalizeToolCallIDFunc

type NormalizeToolCallIDFunc func(id string, model Model, source Message) string

type NormalizedProviderError added in v0.82.0

type NormalizedProviderError struct {
	StatusCode         int
	Body               string
	Message            string
	MessageCarriesBody bool
}

NormalizedProviderError is the stable representation used by provider adapters when rendering failures.

func NormalizeProviderError added in v0.82.0

func NormalizeProviderError(err error) NormalizedProviderError

NormalizeProviderError extracts the typed provider metadata while preserving ordinary Go error wrapping.

type NowMillisFunc added in v0.82.0

type NowMillisFunc func() int64

type OAuthAuth added in v0.82.0

type OAuthAuth struct {
	Name       string
	LoginLabel string
	Login      func(ctx context.Context, interaction AuthInteraction) (Credential, error)
	Refresh    func(ctx context.Context, credential Credential) (Credential, error)
	ToAuth     func(ctx context.Context, credential Credential) (ModelAuth, error)
}

OAuthAuth separates token refresh from side-effect-free request auth derivation so refresh can run within a credential-store transaction.

func LazyOAuthAuth added in v0.82.0

func LazyOAuthAuth(name, loginLabel string, loader OAuthAuthLoader) *OAuthAuth

LazyOAuthAuth exposes stable OAuth metadata while deferring implementation loading until login, refresh, or request-auth derivation is actually used.

func NewAnthropicOAuth added in v0.82.0

func NewAnthropicOAuth(options AnthropicOAuthOptions) *OAuthAuth

NewAnthropicOAuth creates the reusable Claude Pro/Max authorization-code flow. Applications may replace it with RegisterOAuthAuthLoader.

func NewGitHubCopilotOAuth added in v0.82.0

func NewGitHubCopilotOAuth(options GitHubCopilotOAuthOptions) *OAuthAuth

NewGitHubCopilotOAuth creates the reusable GitHub Copilot device-flow contract. Applications may still replace it with RegisterOAuthAuthLoader.

func NewKimiCodingOAuth added in v0.82.0

func NewKimiCodingOAuth(options KimiCodingOAuthOptions) *OAuthAuth

NewKimiCodingOAuth creates the Kimi Code subscription device-flow implementation.

func NewOpenAICodexOAuth added in v0.82.0

func NewOpenAICodexOAuth(options OpenAICodexOAuthOptions) *OAuthAuth

NewOpenAICodexOAuth creates the reusable ChatGPT Plus/Pro browser and headless device-code login contract.

func NewOpenRouterOAuth added in v0.82.0

func NewOpenRouterOAuth(options OpenRouterOAuthOptions) *OAuthAuth

NewOpenRouterOAuth creates the OpenRouter one-shot loopback PKCE flow.

func NewRadiusOAuth added in v0.82.0

func NewRadiusOAuth(options RadiusOAuthOptions) (*OAuthAuth, error)

NewRadiusOAuth creates the complete Radius browser/device-code login, refresh, and request-auth contract. Network access remains deferred until a login or refresh operation is invoked.

func NewXAIOAuth added in v0.82.0

func NewXAIOAuth(options XAIOAuthOptions) *OAuthAuth

NewXAIOAuth creates the xAI subscription device-code login contract.

type OAuthAuthLoader added in v0.82.0

type OAuthAuthLoader func(ctx context.Context) (*OAuthAuth, error)

OAuthAuthLoader resolves one provider's OAuth implementation on demand. Applications register interactive implementations without introducing a dependency from the reusable provider package back to a CLI or TUI package.

type OAuthCredentials

type OAuthCredentials = Credential

OAuthCredentials remains as a compatibility alias for the canonical credential shape. New code should persist Credential with Type set to CredentialTypeOAuth.

type OAuthDeviceCodePollOptions added in v0.82.0

type OAuthDeviceCodePollOptions[T any] struct {
	IntervalSeconds     int
	ExpiresInSeconds    int
	WaitBeforeFirstPoll bool
	Poll                func(context.Context) (OAuthDeviceCodePollResult[T], error)
}

OAuthDeviceCodePollOptions configures an RFC 8628 polling loop.

type OAuthDeviceCodePollResult added in v0.82.0

type OAuthDeviceCodePollResult[T any] struct {
	Status          OAuthDeviceCodePollStatus
	Value           T
	Message         string
	IntervalSeconds int
}

OAuthDeviceCodePollResult is the tagged result returned by one token poll. IntervalSeconds is meaningful only for OAuthDeviceCodeSlowDown.

type OAuthDeviceCodePollStatus added in v0.82.0

type OAuthDeviceCodePollStatus string

OAuthDeviceCodePollStatus identifies the outcome of one device-token poll.

const (
	OAuthDeviceCodePending  OAuthDeviceCodePollStatus = "pending"
	OAuthDeviceCodeSlowDown OAuthDeviceCodePollStatus = "slow_down"
	OAuthDeviceCodeFailed   OAuthDeviceCodePollStatus = "failed"
	OAuthDeviceCodeComplete OAuthDeviceCodePollStatus = "complete"
)

type OAuthPageOptions

type OAuthPageOptions = oauthpage.OAuthPageOptions

type OAuthResponseError added in v0.82.0

type OAuthResponseError struct {
	StatusCode  int
	Code        string
	Description string
	Operation   string
}

OAuthResponseError preserves the HTTP status and OAuth error code so device flows can distinguish transient protocol states from terminal failures.

func (*OAuthResponseError) Error added in v0.82.0

func (e *OAuthResponseError) Error() string

type OAuthTokenRequest

type OAuthTokenRequest struct {
	URL  string
	Body map[string]string
}

func BuildAnthropicAuthorizationCodeTokenRequest

func BuildAnthropicAuthorizationCodeTokenRequest(code, redirectURI string) OAuthTokenRequest

func BuildAnthropicRefreshTokenRequest

func BuildAnthropicRefreshTokenRequest(refreshToken string) OAuthTokenRequest

type OpenAIChatCompletionChoice

type OpenAIChatCompletionChoice struct {
	Delta        OpenAIChatDelta  `json:"delta"`
	FinishReason *string          `json:"finish_reason"`
	Usage        *OpenAIChatUsage `json:"usage,omitempty"`
}

type OpenAIChatCompletionChunk

type OpenAIChatCompletionChunk struct {
	ID      string                       `json:"id"`
	Model   string                       `json:"model,omitempty"`
	Choices []OpenAIChatCompletionChoice `json:"choices"`
	Usage   *OpenAIChatUsage             `json:"usage,omitempty"`
}

func DecodeOpenAIChatCompletionChunk

func DecodeOpenAIChatCompletionChunk(data []byte) (OpenAIChatCompletionChunk, error)

type OpenAIChatCompletionTokenDetails

type OpenAIChatCompletionTokenDetails struct {
	ReasoningTokens int `json:"reasoning_tokens"`
}

type OpenAIChatContentPart

type OpenAIChatContentPart struct {
	Type         string                    `json:"type"`
	Text         string                    `json:"text,omitempty"`
	ImageURL     *OpenAIChatImageURL       `json:"image_url,omitempty"`
	CacheControl *OpenAICompatCacheControl `json:"cache_control,omitempty"`
}

type OpenAIChatCustomTool added in v0.82.0

type OpenAIChatCustomTool struct {
	Name        string                     `json:"name"`
	Description string                     `json:"description,omitempty"`
	Format      OpenAIChatCustomToolFormat `json:"format"`
}

type OpenAIChatCustomToolCall added in v0.82.0

type OpenAIChatCustomToolCall struct {
	Name  string `json:"name"`
	Input string `json:"input"`
}

type OpenAIChatCustomToolCallDelta added in v0.82.0

type OpenAIChatCustomToolCallDelta struct {
	Name  string `json:"name,omitempty"`
	Input string `json:"input,omitempty"`
}

type OpenAIChatCustomToolFormat added in v0.82.0

type OpenAIChatCustomToolFormat struct {
	Type    string                      `json:"type"`
	Grammar OpenAIChatCustomToolGrammar `json:"grammar"`
}

type OpenAIChatCustomToolGrammar added in v0.82.0

type OpenAIChatCustomToolGrammar struct {
	Syntax     GrammarFormat `json:"syntax"`
	Definition string        `json:"definition"`
}

type OpenAIChatDelta

type OpenAIChatDelta struct {
	Content          string                    `json:"content,omitempty"`
	ReasoningContent string                    `json:"reasoning_content,omitempty"`
	Reasoning        string                    `json:"reasoning,omitempty"`
	ReasoningText    string                    `json:"reasoning_text,omitempty"`
	ReasoningDetails []json.RawMessage         `json:"reasoning_details,omitempty"`
	ToolCalls        []OpenAIChatToolCallDelta `json:"tool_calls,omitempty"`
}

type OpenAIChatImageURL

type OpenAIChatImageURL struct {
	URL string `json:"url"`
}

type OpenAIChatMessage

type OpenAIChatMessage struct {
	Role             string               `json:"role"`
	Content          any                  `json:"content,omitempty"`
	ToolCalls        []OpenAIChatToolCall `json:"tool_calls,omitempty"`
	ToolCallID       string               `json:"tool_call_id,omitempty"`
	Name             string               `json:"name,omitempty"`
	ReasoningContent string               `json:"reasoning_content,omitempty"`
	Reasoning        string               `json:"reasoning,omitempty"`
	ReasoningText    string               `json:"reasoning_text,omitempty"`
	ReasoningDetails []map[string]any     `json:"reasoning_details,omitempty"`
	Tools            []OpenAIChatTool     `json:"tools,omitempty"`
	Extra            map[string]any       `json:"-"`
	// contains filtered or unexported fields
}

func ConvertOpenAICompletionsMessages

func ConvertOpenAICompletionsMessages(model Model, context Context, compat OpenAICompletionsCompat) []OpenAIChatMessage

func ConvertOpenAICompletionsMessagesChecked added in v0.82.0

func ConvertOpenAICompletionsMessagesChecked(
	model Model,
	context Context,
	compat OpenAICompletionsCompat,
) ([]OpenAIChatMessage, error)

func (OpenAIChatMessage) MarshalJSON

func (m OpenAIChatMessage) MarshalJSON() ([]byte, error)

type OpenAIChatPromptTokenDetails

type OpenAIChatPromptTokenDetails struct {
	CachedTokens     int `json:"cached_tokens"`
	CacheWriteTokens int `json:"cache_write_tokens"`
}

type OpenAIChatTool

type OpenAIChatTool struct {
	Type         string                    `json:"type"`
	Function     OpenAIChatToolFunction    `json:"function"`
	Custom       *OpenAIChatCustomTool     `json:"custom,omitempty"`
	CacheControl *OpenAICompatCacheControl `json:"cache_control,omitempty"`
}

func ConvertOpenAICompletionsTools

func ConvertOpenAICompletionsTools(tools []Tool, compat OpenAICompletionsCompat) []OpenAIChatTool

func ConvertOpenAICompletionsToolsChecked added in v0.82.0

func ConvertOpenAICompletionsToolsChecked(
	tools []Tool,
	compat OpenAICompletionsCompat,
) ([]OpenAIChatTool, error)

func (OpenAIChatTool) MarshalJSON added in v0.82.0

func (tool OpenAIChatTool) MarshalJSON() ([]byte, error)

type OpenAIChatToolCall

type OpenAIChatToolCall struct {
	ID       string                     `json:"id"`
	Type     string                     `json:"type"`
	Function OpenAIChatToolCallFunction `json:"function"`
	Custom   *OpenAIChatCustomToolCall  `json:"custom,omitempty"`
}

func (OpenAIChatToolCall) MarshalJSON added in v0.82.0

func (call OpenAIChatToolCall) MarshalJSON() ([]byte, error)

type OpenAIChatToolCallDelta

type OpenAIChatToolCallDelta struct {
	Index    *int                            `json:"index,omitempty"`
	ID       string                          `json:"id,omitempty"`
	Type     string                          `json:"type,omitempty"`
	Function OpenAIChatToolCallFunctionDelta `json:"function"`
	Custom   *OpenAIChatCustomToolCallDelta  `json:"custom,omitempty"`
}

type OpenAIChatToolCallFunction

type OpenAIChatToolCallFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type OpenAIChatToolCallFunctionDelta

type OpenAIChatToolCallFunctionDelta struct {
	Name      string `json:"name,omitempty"`
	Arguments string `json:"arguments,omitempty"`
}

type OpenAIChatToolFunction

type OpenAIChatToolFunction struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Parameters  any    `json:"parameters,omitempty"`
	Strict      *bool  `json:"strict,omitempty"`
}

type OpenAIChatUsage

type OpenAIChatUsage struct {
	PromptTokens           int                              `json:"prompt_tokens"`
	CompletionTokens       int                              `json:"completion_tokens"`
	PromptCacheHitTokens   int                              `json:"prompt_cache_hit_tokens"`
	PromptTokensDetails    OpenAIChatPromptTokenDetails     `json:"prompt_tokens_details"`
	CompletionTokenDetails OpenAIChatCompletionTokenDetails `json:"completion_tokens_details"`
}

type OpenAICodexOAuthOptions added in v0.82.0

type OpenAICodexOAuthOptions struct {
	Client         HTTPDoer
	AuthContext    AuthContext
	CallbackHost   string
	Originator     string
	RequestTimeout time.Duration
}

OpenAICodexOAuthOptions configures the provider-owned ChatGPT authorization-code and device-code flows.

type OpenAICodexProcessOptions

type OpenAICodexProcessOptions struct {
	ServiceTier                string
	GrammarToolInputProperties map[string]string
}

type OpenAICodexResponsesPayload

type OpenAICodexResponsesPayload struct {
	Model              string                     `json:"model"`
	Store              bool                       `json:"store"`
	Stream             bool                       `json:"stream"`
	Instructions       string                     `json:"instructions"`
	PreviousResponseID string                     `json:"previous_response_id,omitempty"`
	Input              []OpenAIResponsesInputItem `json:"input,omitempty"`
	Tools              []OpenAIResponsesTool      `json:"tools,omitempty"`
	Temperature        *float64                   `json:"temperature,omitempty"`
	Reasoning          map[string]string          `json:"reasoning,omitempty"`
	ServiceTier        string                     `json:"service_tier,omitempty"`
	Text               map[string]string          `json:"text,omitempty"`
	Include            []string                   `json:"include,omitempty"`
	PromptCacheKey     string                     `json:"prompt_cache_key,omitempty"`
	ToolChoice         string                     `json:"tool_choice,omitempty"`
	ParallelToolCalls  bool                       `json:"parallel_tool_calls"`
}

func BuildOpenAICodexResponsesPayload

func BuildOpenAICodexResponsesPayload(model Model, context Context, options OpenAICodexResponsesPayloadOptions) OpenAICodexResponsesPayload

func BuildOpenAICodexResponsesPayloadChecked added in v0.82.0

func BuildOpenAICodexResponsesPayloadChecked(
	model Model,
	context Context,
	options OpenAICodexResponsesPayloadOptions,
) (OpenAICodexResponsesPayload, error)

type OpenAICodexResponsesPayloadOptions

type OpenAICodexResponsesPayloadOptions struct {
	Temperature      *float64
	SessionID        string
	ReasoningEffort  string
	ReasoningSummary string
	ServiceTier      string
	TextVerbosity    string
}

type OpenAICodexResponsesProvider

type OpenAICodexResponsesProvider struct {
	Client          HTTPDoer
	WebSocketDialer OpenAICodexWebSocketDialer
	Now             func() time.Time
	Sleep           func(context.Context, time.Duration) error
}

func NewOpenAICodexResponsesProvider

func NewOpenAICodexResponsesProvider(client HTTPDoer) OpenAICodexResponsesProvider

func (OpenAICodexResponsesProvider) Stream

func (OpenAICodexResponsesProvider) StreamSimple

func (p OpenAICodexResponsesProvider) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type OpenAICodexRetryDelayExceededError added in v0.82.0

type OpenAICodexRetryDelayExceededError struct {
	Requested time.Duration
	Maximum   time.Duration
}

OpenAICodexRetryDelayExceededError reports a server-requested retry delay above the configured safety limit.

func (*OpenAICodexRetryDelayExceededError) Error added in v0.82.0

type OpenAICodexWebSocket added in v0.82.0

type OpenAICodexWebSocket interface {
	Write(context.Context, []byte) error
	Read(context.Context, time.Duration) ([]byte, error)
	Close(code int, reason string) error
	Reusable() bool
}

OpenAICodexWebSocket is the request-scoped view of a Codex WebSocket connection. Implementations must support one active reader and one active writer; the session pool guarantees that a cached connection has only one borrower at a time.

type OpenAICodexWebSocketDebugStats

type OpenAICodexWebSocketDebugStats struct {
	Requests                int    `json:"requests"`
	ConnectionsCreated      int    `json:"connectionsCreated"`
	ConnectionsReused       int    `json:"connectionsReused"`
	CachedContextRequests   int    `json:"cachedContextRequests"`
	StoreTrueRequests       int    `json:"storeTrueRequests"`
	FullContextRequests     int    `json:"fullContextRequests"`
	DeltaRequests           int    `json:"deltaRequests"`
	LastInputItems          int    `json:"lastInputItems"`
	LastDeltaInputItems     *int   `json:"lastDeltaInputItems,omitempty"`
	LastPreviousResponseID  string `json:"lastPreviousResponseId,omitempty"`
	WebSocketFailures       int    `json:"websocketFailures"`
	SSEFallbacks            int    `json:"sseFallbacks"`
	WebSocketFallbackActive bool   `json:"websocketFallbackActive,omitempty"`
	LastWebSocketError      string `json:"lastWebSocketError,omitempty"`
}

func GetOpenAICodexWebSocketDebugStats

func GetOpenAICodexWebSocketDebugStats(sessionID string) (OpenAICodexWebSocketDebugStats, bool)

type OpenAICodexWebSocketDialer added in v0.82.0

type OpenAICodexWebSocketDialer interface {
	Dial(
		context.Context,
		string,
		map[string]string,
		time.Duration,
	) (OpenAICodexWebSocket, error)
}

OpenAICodexWebSocketDialer separates connection establishment from provider orchestration so lifecycle and fallback behavior can be tested without a network listener.

type OpenAICompatCacheControl

type OpenAICompatCacheControl struct {
	Type string `json:"type"`
	TTL  string `json:"ttl,omitempty"`
}

type OpenAICompletionsCompat

type OpenAICompletionsCompat struct {
	SupportsDeveloperRole                    bool
	SupportsStore                            bool
	SupportsReasoningEffort                  bool
	SupportsUsageInStreaming                 bool
	SupportsStrictMode                       bool
	SupportsOpenAIGrammarTools               bool
	SupportsLongCacheRetention               bool
	MaxTokensField                           string
	ThinkingFormat                           string
	CacheControlFormat                       string
	ZAIToolStream                            bool
	RequiresToolResultName                   bool
	RequiresAssistantAfterToolResult         bool
	RequiresThinkingAsText                   bool
	RequiresReasoningContentOnAssistant      bool
	RequiresReasoningContentOnAssistantTurns bool
	DeferredToolsMode                        string
	ChatTemplateKwargs                       map[string]any
}

func ResolveOpenAICompletionsCompat

func ResolveOpenAICompletionsCompat(model Model) OpenAICompletionsCompat

type OpenAICompletionsPayload

type OpenAICompletionsPayload struct {
	Model                string              `json:"model"`
	Messages             []OpenAIChatMessage `json:"messages"`
	Stream               bool                `json:"stream"`
	PromptCacheKey       string              `json:"prompt_cache_key,omitempty"`
	PromptCacheRetention string              `json:"prompt_cache_retention,omitempty"`
	StreamOptions        map[string]any      `json:"stream_options,omitempty"`
	Store                *bool               `json:"store,omitempty"`
	MaxTokens            int                 `json:"max_tokens,omitempty"`
	MaxCompletionTokens  int                 `json:"max_completion_tokens,omitempty"`
	Temperature          *float64            `json:"temperature,omitempty"`
	Tools                []OpenAIChatTool    `json:"tools,omitempty"`
	ToolChoice           any                 `json:"tool_choice,omitempty"`
	ToolStream           *bool               `json:"tool_stream,omitempty"`
	EnableThinking       *bool               `json:"enable_thinking,omitempty"`
	ChatTemplateKwargs   map[string]any      `json:"chat_template_kwargs,omitempty"`
	Thinking             map[string]any      `json:"thinking,omitempty"`
	Reasoning            map[string]any      `json:"reasoning,omitempty"`
	ReasoningEffort      string              `json:"reasoning_effort,omitempty"`
}

func BuildOpenAICompletionsPayload

func BuildOpenAICompletionsPayload(model Model, context Context, options OpenAICompletionsPayloadOptions) OpenAICompletionsPayload

func BuildOpenAICompletionsPayloadChecked

func BuildOpenAICompletionsPayloadChecked(model Model, context Context, options OpenAICompletionsPayloadOptions) (OpenAICompletionsPayload, error)

type OpenAICompletionsPayloadOptions

type OpenAICompletionsPayloadOptions struct {
	MaxTokens      int
	Temperature    *float64
	CacheRetention string
	SessionID      string
	Reasoning      string
	ToolChoice     any
	Headers        map[string]string
}

type OpenAICompletionsProvider

type OpenAICompletionsProvider struct {
	Client HTTPDoer
}

func NewOpenAICompletionsProvider

func NewOpenAICompletionsProvider(client HTTPDoer) OpenAICompletionsProvider

func (OpenAICompletionsProvider) Stream

func (p OpenAICompletionsProvider) Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)

func (OpenAICompletionsProvider) StreamSimple

func (p OpenAICompletionsProvider) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type OpenAICompletionsRequestState added in v0.82.0

type OpenAICompletionsRequestState struct {
	Compat                     OpenAICompletionsCompat
	ToolPlacement              DeferredToolSet
	GrammarToolInputProperties map[string]string
}

OpenAICompletionsRequestState is resolved once per request and shared by payload conversion and stream decoding.

func ResolveOpenAICompletionsRequestState added in v0.82.0

func ResolveOpenAICompletionsRequestState(
	model Model,
	context Context,
) (OpenAICompletionsRequestState, error)

type OpenAICompletionsStreamProcessor

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

func NewOpenAICompletionsStreamProcessor

func NewOpenAICompletionsStreamProcessor(model Model, output *Message) *OpenAICompletionsStreamProcessor

func NewOpenAICompletionsStreamProcessorWithOptions added in v0.82.0

func NewOpenAICompletionsStreamProcessorWithOptions(
	model Model,
	output *Message,
	options OpenAICompletionsStreamProcessorOptions,
) *OpenAICompletionsStreamProcessor

func (*OpenAICompletionsStreamProcessor) Process

func (*OpenAICompletionsStreamProcessor) Result

type OpenAICompletionsStreamProcessorOptions added in v0.82.0

type OpenAICompletionsStreamProcessorOptions struct {
	GrammarToolInputProperties map[string]string
}

type OpenAIResponsesCompat

type OpenAIResponsesCompat struct {
	SupportsDeveloperRole           bool
	SessionAffinityFormat           string
	SupportsLongCacheRetention      bool
	SupportsStrictMode              bool
	SupportsOpenAIGrammarTools      bool
	SupportsToolSearch              bool
	SupportsExplicitPromptCacheMode bool
}

func ResolveOpenAIResponsesCompat

func ResolveOpenAIResponsesCompat(model Model) OpenAIResponsesCompat

type OpenAIResponsesContentPart

type OpenAIResponsesContentPart struct {
	Type     string `json:"type"`
	Text     string `json:"text,omitempty"`
	Refusal  string `json:"refusal,omitempty"`
	Detail   string `json:"detail,omitempty"`
	ImageURL string `json:"image_url,omitempty"`
}

type OpenAIResponsesError added in v0.82.2

type OpenAIResponsesError struct {
	Code    string
	Message string
}

type OpenAIResponsesIncompleteDetails

type OpenAIResponsesIncompleteDetails struct {
	Reason string
}

type OpenAIResponsesInputItem

type OpenAIResponsesInputItem struct {
	Type                string                              `json:"type,omitempty"`
	Role                string                              `json:"role,omitempty"`
	Content             any                                 `json:"content,omitempty"`
	Summary             []OpenAIResponsesContentPart        `json:"summary,omitempty"`
	ID                  string                              `json:"id,omitempty"`
	CallID              string                              `json:"call_id,omitempty"`
	Name                string                              `json:"name,omitempty"`
	Arguments           string                              `json:"arguments,omitempty"`
	ToolSearchArguments *OpenAIResponsesToolSearchArguments `json:"-"`
	Input               string                              `json:"input,omitempty"`
	Output              any                                 `json:"output,omitempty"`
	Status              string                              `json:"status,omitempty"`
	Execution           string                              `json:"execution,omitempty"`
	Tools               []OpenAIResponsesTool               `json:"tools,omitempty"`
	Phase               string                              `json:"phase,omitempty"`
	EncryptedContent    string                              `json:"encrypted_content,omitempty"`
}

func ConvertOpenAIResponsesMessages

func ConvertOpenAIResponsesMessages(model Model, context Context, options ConvertOpenAIResponsesOptions) []OpenAIResponsesInputItem

func ConvertOpenAIResponsesMessagesChecked added in v0.82.0

func ConvertOpenAIResponsesMessagesChecked(
	model Model,
	context Context,
	options ConvertOpenAIResponsesOptions,
) ([]OpenAIResponsesInputItem, error)

func (OpenAIResponsesInputItem) MarshalJSON added in v0.82.0

func (item OpenAIResponsesInputItem) MarshalJSON() ([]byte, error)

func (*OpenAIResponsesInputItem) UnmarshalJSON added in v0.82.0

func (item *OpenAIResponsesInputItem) UnmarshalJSON(data []byte) error

type OpenAIResponsesInputTokenDetails

type OpenAIResponsesInputTokenDetails struct {
	CachedTokens     int
	CacheWriteTokens int
}

type OpenAIResponsesOutputContentPart

type OpenAIResponsesOutputContentPart struct {
	Type    string `json:"type,omitempty"`
	Text    string `json:"text,omitempty"`
	Refusal string `json:"refusal,omitempty"`
}

type OpenAIResponsesOutputItem

type OpenAIResponsesOutputItem struct {
	Type             string                             `json:"type,omitempty"`
	ID               string                             `json:"id,omitempty"`
	CallID           string                             `json:"call_id,omitempty"`
	Name             string                             `json:"name,omitempty"`
	Arguments        string                             `json:"arguments,omitempty"`
	Input            string                             `json:"input,omitempty"`
	Status           string                             `json:"status,omitempty"`
	Content          []OpenAIResponsesOutputContentPart `json:"content,omitempty"`
	Summary          []OpenAIResponsesOutputContentPart `json:"summary,omitempty"`
	Phase            string                             `json:"phase,omitempty"`
	EncryptedContent string                             `json:"encrypted_content,omitempty"`
}

type OpenAIResponsesOutputTokenDetails added in v0.82.0

type OpenAIResponsesOutputTokenDetails struct {
	ReasoningTokens int
}

type OpenAIResponsesPayload

type OpenAIResponsesPayload struct {
	Model                string                             `json:"model"`
	Input                []OpenAIResponsesInputItem         `json:"input"`
	Stream               bool                               `json:"stream"`
	PromptCacheKey       string                             `json:"prompt_cache_key,omitempty"`
	PromptCacheRetention string                             `json:"prompt_cache_retention,omitempty"`
	PromptCacheOptions   *OpenAIResponsesPromptCacheOptions `json:"prompt_cache_options,omitempty"`
	Store                bool                               `json:"store"`
	MaxOutputTokens      int                                `json:"max_output_tokens,omitempty"`
	Temperature          *float64                           `json:"temperature,omitempty"`
	ServiceTier          string                             `json:"service_tier,omitempty"`
	Tools                []OpenAIResponsesTool              `json:"tools,omitempty"`
	Reasoning            map[string]string                  `json:"reasoning,omitempty"`
	Include              []string                           `json:"include,omitempty"`
}

func BuildOpenAIResponsesPayload

func BuildOpenAIResponsesPayload(model Model, context Context, options OpenAIResponsesPayloadOptions) OpenAIResponsesPayload

func BuildOpenAIResponsesPayloadChecked

func BuildOpenAIResponsesPayloadChecked(model Model, context Context, options OpenAIResponsesPayloadOptions) (OpenAIResponsesPayload, error)

type OpenAIResponsesPayloadOptions

type OpenAIResponsesPayloadOptions struct {
	MaxTokens        int
	Temperature      *float64
	CacheRetention   string
	SessionID        string
	ReasoningEffort  string
	ReasoningSummary string
	ServiceTier      string
	Headers          map[string]string
}

type OpenAIResponsesPromptCacheOptions added in v0.82.0

type OpenAIResponsesPromptCacheOptions struct {
	Mode string `json:"mode"`
}

type OpenAIResponsesProvider

type OpenAIResponsesProvider struct {
	Client HTTPDoer
}

func NewOpenAIResponsesProvider

func NewOpenAIResponsesProvider(client HTTPDoer) OpenAIResponsesProvider

func (OpenAIResponsesProvider) Stream

func (p OpenAIResponsesProvider) Stream(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)

func (OpenAIResponsesProvider) StreamSimple

func (p OpenAIResponsesProvider) StreamSimple(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)

type OpenAIResponsesRequestState added in v0.82.0

type OpenAIResponsesRequestState struct {
	Sampling      OpenAIResponsesSamplingState
	ToolPlacement DeferredToolSet
}

OpenAIResponsesRequestState is the request-owned snapshot shared by payload construction and transcript replay. Grammar classification always sees the complete tool registry, while ToolPlacement controls which schemas are sent in the request prefix and which are loaded from transcript markers.

func ResolveOpenAIResponsesRequestState added in v0.82.0

func ResolveOpenAIResponsesRequestState(
	model Model,
	context Context,
	defaults OpenAIResponsesSamplingDefaults,
) (OpenAIResponsesRequestState, error)

type OpenAIResponsesResponseEvent

type OpenAIResponsesResponseEvent struct {
	ID                string
	Status            string
	ServiceTier       string
	Usage             *OpenAIResponsesUsage
	IncompleteDetails *OpenAIResponsesIncompleteDetails
	Error             *OpenAIResponsesError
}

type OpenAIResponsesSamplingDefaults added in v0.82.0

type OpenAIResponsesSamplingDefaults struct {
	SupportsStrictMode bool
	Strict             OpenAIResponsesStrictDefault
}

type OpenAIResponsesSamplingState added in v0.82.0

type OpenAIResponsesSamplingState struct {
	ToolOptions                OpenAIResponsesToolOptions
	GrammarToolInputProperties map[string]string
}

OpenAIResponsesSamplingState is the request-owned sampling snapshot shared by request conversion and stream decoding.

func ResolveOpenAIResponsesSamplingState added in v0.82.0

func ResolveOpenAIResponsesSamplingState(
	model Model,
	tools []Tool,
	defaults OpenAIResponsesSamplingDefaults,
) (OpenAIResponsesSamplingState, error)

type OpenAIResponsesStreamEvent

type OpenAIResponsesStreamEvent struct {
	Type        string
	OutputIndex int
	Response    *OpenAIResponsesResponseEvent
	Item        *OpenAIResponsesOutputItem
	Part        *OpenAIResponsesOutputContentPart
	Delta       string
	Arguments   string
	Input       string
	ErrorCode   string
	Error       string
}

func DecodeOpenAIResponsesSSEEvent

func DecodeOpenAIResponsesSSEEvent(data []byte) (OpenAIResponsesStreamEvent, error)

type OpenAIResponsesStreamProcessor

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

func NewOpenAIResponsesStreamProcessor

func NewOpenAIResponsesStreamProcessor(model Model, output *Message) *OpenAIResponsesStreamProcessor

func NewOpenAIResponsesStreamProcessorWithOptions added in v0.82.0

func NewOpenAIResponsesStreamProcessorWithOptions(
	model Model,
	output *Message,
	options OpenAIResponsesStreamProcessorOptions,
) *OpenAIResponsesStreamProcessor

func (*OpenAIResponsesStreamProcessor) Process

type OpenAIResponsesStreamProcessorOptions added in v0.82.0

type OpenAIResponsesStreamProcessorOptions struct {
	GrammarToolInputProperties map[string]string
}

type OpenAIResponsesStrictDefault added in v0.82.0

type OpenAIResponsesStrictDefault uint8
const (
	OpenAIResponsesStrictDefaultFalse OpenAIResponsesStrictDefault = iota
	OpenAIResponsesStrictDefaultTrue
	OpenAIResponsesStrictDefaultNull
)

type OpenAIResponsesTool

type OpenAIResponsesTool struct {
	Type         string                     `json:"type"`
	Name         string                     `json:"name"`
	Description  string                     `json:"description,omitempty"`
	Parameters   map[string]any             `json:"parameters,omitempty"`
	Strict       *bool                      `json:"-"`
	StrictNull   bool                       `json:"-"`
	Format       *OpenAIResponsesToolFormat `json:"format,omitempty"`
	DeferLoading bool                       `json:"defer_loading,omitempty"`
}

func ConvertOpenAIResponsesTools

func ConvertOpenAIResponsesTools(tools []Tool, strict bool) []OpenAIResponsesTool

ConvertOpenAIResponsesTools preserves the original convenience API. New request paths should use ConvertOpenAIResponsesToolsChecked so constrained sampling validation errors reach the caller.

func ConvertOpenAIResponsesToolsChecked added in v0.82.0

func ConvertOpenAIResponsesToolsChecked(
	tools []Tool,
	options OpenAIResponsesToolOptions,
) ([]OpenAIResponsesTool, error)

func (OpenAIResponsesTool) MarshalJSON added in v0.82.0

func (tool OpenAIResponsesTool) MarshalJSON() ([]byte, error)

func (*OpenAIResponsesTool) UnmarshalJSON added in v0.82.0

func (tool *OpenAIResponsesTool) UnmarshalJSON(data []byte) error

type OpenAIResponsesToolFormat added in v0.82.0

type OpenAIResponsesToolFormat struct {
	Type       string        `json:"type"`
	Syntax     GrammarFormat `json:"syntax"`
	Definition string        `json:"definition"`
}

type OpenAIResponsesToolOptions added in v0.82.0

type OpenAIResponsesToolOptions struct {
	DefaultStrict              OpenAIResponsesStrictDefault
	SupportsStrictMode         *bool
	SupportsOpenAIGrammarTools bool
	DeferLoading               bool
}

type OpenAIResponsesToolSearchArguments added in v0.82.0

type OpenAIResponsesToolSearchArguments struct {
	Query string `json:"query"`
	Limit int    `json:"limit"`
}

type OpenAIResponsesUsage

type OpenAIResponsesUsage struct {
	InputTokens         int
	OutputTokens        int
	TotalTokens         int
	InputTokensDetails  OpenAIResponsesInputTokenDetails
	OutputTokensDetails OpenAIResponsesOutputTokenDetails
}

type OpenRouterGeneratedImage

type OpenRouterGeneratedImage struct {
	ImageURL any `json:"image_url"`
}

type OpenRouterImagesChoice

type OpenRouterImagesChoice struct {
	Message OpenRouterImagesChoiceMessage `json:"message"`
}

type OpenRouterImagesChoiceMessage

type OpenRouterImagesChoiceMessage struct {
	Content string                     `json:"content,omitempty"`
	Images  []OpenRouterGeneratedImage `json:"images,omitempty"`
}

type OpenRouterImagesContentPart

type OpenRouterImagesContentPart struct {
	Type     string                    `json:"type"`
	Text     string                    `json:"text,omitempty"`
	ImageURL *OpenRouterImagesImageURL `json:"image_url,omitempty"`
}

type OpenRouterImagesImageURL

type OpenRouterImagesImageURL struct {
	URL string `json:"url"`
}

type OpenRouterImagesMessage

type OpenRouterImagesMessage struct {
	Role    string                        `json:"role"`
	Content []OpenRouterImagesContentPart `json:"content"`
}

type OpenRouterImagesPayload

type OpenRouterImagesPayload struct {
	Model      string                    `json:"model"`
	Messages   []OpenRouterImagesMessage `json:"messages"`
	Stream     bool                      `json:"stream"`
	Modalities []string                  `json:"modalities"`
}

func BuildOpenRouterImagesPayload

func BuildOpenRouterImagesPayload(model ImagesModel, imagesContext ImagesContext) OpenRouterImagesPayload

type OpenRouterImagesProvider

type OpenRouterImagesProvider struct {
	Client HTTPDoer
}

func NewOpenRouterImagesProvider

func NewOpenRouterImagesProvider(client HTTPDoer) OpenRouterImagesProvider

func (OpenRouterImagesProvider) GenerateImages

func (p OpenRouterImagesProvider) GenerateImages(model ImagesModel, imagesContext ImagesContext, options ImagesOptions) (AssistantImages, error)

type OpenRouterImagesResponse

type OpenRouterImagesResponse struct {
	ID      string                   `json:"id"`
	Usage   *OpenRouterImagesUsage   `json:"usage,omitempty"`
	Choices []OpenRouterImagesChoice `json:"choices"`
}

type OpenRouterImagesUsage

type OpenRouterImagesUsage struct {
	PromptTokens        int                           `json:"prompt_tokens"`
	CompletionTokens    int                           `json:"completion_tokens"`
	PromptTokensDetails OpenRouterPromptTokensDetails `json:"prompt_tokens_details"`
}

type OpenRouterOAuthOptions added in v0.82.0

type OpenRouterOAuthOptions struct {
	Client               HTTPDoer
	AuthContext          AuthContext
	CallbackHost         string
	LoginTimeout         time.Duration
	TokenExchangeTimeout time.Duration
}

OpenRouterOAuthOptions configures OpenRouter's loopback PKCE flow.

type OpenRouterPromptTokensDetails

type OpenRouterPromptTokensDetails struct {
	CachedTokens     int `json:"cached_tokens"`
	CacheWriteTokens int `json:"cache_write_tokens"`
}

type PKCE added in v0.82.0

type PKCE struct {
	Verifier  string
	Challenge string
}

PKCE contains an RFC 7636 verifier and its S256 challenge.

func GeneratePKCE added in v0.82.0

func GeneratePKCE() (PKCE, error)

GeneratePKCE creates a cryptographically random PKCE verifier and challenge.

type PiMessagesEvent added in v0.82.0

type PiMessagesEvent struct {
	Type             string                   `json:"type"`
	ContentIndex     int                      `json:"contentIndex,omitempty"`
	Delta            string                   `json:"delta,omitempty"`
	Content          string                   `json:"content,omitempty"`
	ContentSignature string                   `json:"contentSignature,omitempty"`
	Redacted         *bool                    `json:"redacted,omitempty"`
	ID               string                   `json:"id,omitempty"`
	ToolName         string                   `json:"toolName,omitempty"`
	ToolCall         ContentPart              `json:"toolCall,omitempty"`
	Reason           string                   `json:"reason,omitempty"`
	Usage            Usage                    `json:"usage,omitempty"`
	ErrorMessage     string                   `json:"errorMessage,omitempty"`
	ResponseID       string                   `json:"responseId,omitempty"`
	Rewrite          *PiMessagesRewriteImpact `json:"rewrite,omitempty"`
}

PiMessagesEvent is one serialized event from a pi-messages SSE response. Go uses one tagged struct for Pi's discriminated event union.

func (PiMessagesEvent) MarshalJSON added in v0.82.2

func (e PiMessagesEvent) MarshalJSON() ([]byte, error)

MarshalJSON keeps the internal event state unified while emitting the exact pi-messages discriminated union expected on the wire.

type PiMessagesProvider added in v0.82.0

type PiMessagesProvider struct {
	Client HTTPDoer
}

PiMessagesProvider implements the Radius pi-messages HTTP/SSE protocol.

func NewPiMessagesProvider added in v0.82.0

func NewPiMessagesProvider(client HTTPDoer) PiMessagesProvider

NewPiMessagesProvider creates a pi-messages transport with an injectable HTTP boundary. A nil client uses the package default.

func (PiMessagesProvider) Stream added in v0.82.0

func (p PiMessagesProvider) Stream(
	model Model,
	llmContext Context,
	options StreamOptions,
) (*AssistantMessageEventStream, error)

func (PiMessagesProvider) StreamSimple added in v0.82.0

func (p PiMessagesProvider) StreamSimple(
	model Model,
	llmContext Context,
	options SimpleStreamOptions,
) (*AssistantMessageEventStream, error)

type PiMessagesRequest added in v0.82.0

type PiMessagesRequest struct {
	Model   string                   `json:"model"`
	Context Context                  `json:"context"`
	Options PiMessagesRequestOptions `json:"options"`
}

PiMessagesRequest is the wire request accepted by Radius and compatible pi-messages backends.

type PiMessagesRequestOptions added in v0.82.0

type PiMessagesRequestOptions struct {
	Temperature    *float64 `json:"temperature,omitempty"`
	MaxTokens      int      `json:"maxTokens,omitempty"`
	Reasoning      string   `json:"reasoning,omitempty"`
	CacheRetention string   `json:"cacheRetention,omitempty"`
	SessionID      string   `json:"sessionId,omitempty"`
	ToolChoice     any      `json:"toolChoice,omitempty"`
}

PiMessagesRequestOptions contains only options understood by the wire protocol. Transport-only controls remain on StreamOptions.

type PiMessagesResponseError added in v0.82.0

type PiMessagesResponseError struct {
	Message           string
	Code              string
	DiagnosticDetails map[string]any
}

PiMessagesResponseError preserves structured gateway failure details for diagnostics while implementing Go's error contract.

func (*PiMessagesResponseError) Error added in v0.82.0

func (e *PiMessagesResponseError) Error() string

type PiMessagesRewriteImpact added in v0.82.0

type PiMessagesRewriteImpact struct {
	PolicyID            string `json:"policyId"`
	PolicyVersion       int    `json:"policyVersion"`
	Changed             bool   `json:"changed"`
	TokenCountChange    int    `json:"tokenCountChange"`
	MessageCountChange  int    `json:"messageCountChange"`
	SystemPromptChanged bool   `json:"systemPromptChanged"`
}

PiMessagesRewriteImpact describes a server-side message rewrite.

type ProcessAuthContext added in v0.82.0

type ProcessAuthContext struct{}

ProcessAuthContext resolves environment variables and local file presence. Its zero value is ready for use.

func (ProcessAuthContext) Env added in v0.82.0

func (ProcessAuthContext) FileExists added in v0.82.0

func (ProcessAuthContext) FileExists(ctx context.Context, path string) (bool, error)

type Provider added in v0.82.0

type Provider struct {
	ID      string
	Name    string
	BaseURL string
	Headers map[string]string
	Auth    ProviderAuth

	ModelSource       func() ([]Model, error)
	RefreshModelsFunc func(ctx context.Context, input RefreshModelsContext) error
	FilterModelsFunc  func(models []Model, credential *Credential) []Model
	StreamFunc        func(model Model, llmContext Context, options StreamOptions) (*AssistantMessageEventStream, error)
	StreamSimpleFunc  func(model Model, llmContext Context, options SimpleStreamOptions) (*AssistantMessageEventStream, error)
	// contains filtered or unexported fields
}

Provider is the concrete runtime unit owned by a Models collection. Callbacks are immutable after registration; dynamic model state belongs to the callback implementation or a Provider created with CreateProvider.

func BuiltinProviders added in v0.82.0

func BuiltinProviders() ([]*Provider, error)

BuiltinProviders constructs every built-in provider in Pi declaration order.

func CreateProvider added in v0.82.0

func CreateProvider(options CreateProviderOptions) (*Provider, error)

CreateProvider constructs a provider with clone-on-read model state, provider-scoped persistence, API dispatch, and coalesced refreshes.

func NewAmazonBedrockProvider added in v0.82.0

func NewAmazonBedrockProvider() (*Provider, error)

NewAmazonBedrockProvider returns the built-in Amazon Bedrock provider.

func NewAnthropicProvider added in v0.82.0

func NewAnthropicProvider() (*Provider, error)

NewAnthropicProvider returns the built-in Anthropic provider.

func NewBuiltinProvider added in v0.82.0

func NewBuiltinProvider(providerID string) (*Provider, error)

NewBuiltinProvider constructs a fresh runtime provider backed by the immutable release catalog.

func NewCloudflareAIGatewayProvider added in v0.82.0

func NewCloudflareAIGatewayProvider() (*Provider, error)

NewCloudflareAIGatewayProvider returns the built-in AI Gateway provider.

func NewCloudflareWorkersAIProvider added in v0.82.0

func NewCloudflareWorkersAIProvider() (*Provider, error)

NewCloudflareWorkersAIProvider returns the built-in Workers AI provider.

func NewGoogleVertexProvider added in v0.82.0

func NewGoogleVertexProvider() (*Provider, error)

NewGoogleVertexProvider returns the built-in Google Vertex provider.

func NewRadiusProvider added in v0.82.0

func NewRadiusProvider(options RadiusProviderOptions) (*Provider, error)

NewRadiusProvider creates an instance-scoped dynamic Radius provider.

func WithRemoteCatalog added in v0.82.0

func WithRemoteCatalog(
	provider *Provider,
	options RemoteCatalogOptions,
) (*Provider, error)

WithRemoteCatalog returns a provider whose immutable baseline is overlaid by a persisted, atomically published remote catalog. It creates fresh synchronization state instead of copying Provider's mutexes.

func (*Provider) FilterModels added in v0.82.0

func (p *Provider) FilterModels(models []Model, credential *Credential) []Model

FilterModels applies provider policy to a detached model snapshot.

func (*Provider) GetModels added in v0.82.0

func (p *Provider) GetModels() ([]Model, error)

GetModels returns a detached snapshot of the provider's current catalog.

func (*Provider) RefreshModels added in v0.82.0

func (p *Provider) RefreshModels(ctx context.Context, input RefreshModelsContext) error

RefreshModels restores or updates the provider's dynamic catalog. Concurrent calls share one in-flight refresh.

func (*Provider) Stream added in v0.82.0

func (p *Provider) Stream(
	model Model,
	llmContext Context,
	options StreamOptions,
) (*AssistantMessageEventStream, error)

Stream dispatches a request through this provider.

func (*Provider) StreamSimple added in v0.82.0

func (p *Provider) StreamSimple(
	model Model,
	llmContext Context,
	options SimpleStreamOptions,
) (*AssistantMessageEventStream, error)

StreamSimple dispatches a request through the provider's simple stream implementation, falling back to StreamFunc when necessary.

type ProviderAuth added in v0.82.0

type ProviderAuth struct {
	APIKey *APIKeyAuth
	OAuth  *OAuthAuth
}

ProviderAuth groups the authentication modes supported by a provider.

type ProviderEnv added in v0.82.0

type ProviderEnv map[string]string

ProviderEnv contains provider-scoped configuration resolved alongside a credential, such as Cloudflare account and gateway identifiers.

type ProviderError added in v0.82.0

type ProviderError struct {
	StatusCode int
	Headers    http.Header
	Body       string
	Err        error
	// contains filtered or unexported fields
}

ProviderError is the package-wide transport error contract. Provider adapters should preserve HTTP metadata here instead of flattening it into a string, so retry policy and user-facing formatting consume the same data.

func (*ProviderError) Error added in v0.82.0

func (e *ProviderError) Error() string

func (*ProviderError) Unwrap added in v0.82.0

func (e *ProviderError) Unwrap() error

type ProviderModelsStore added in v0.82.0

type ProviderModelsStore interface {
	ReadModels(ctx context.Context) (ModelsStoreEntry, bool, error)
	WriteModels(ctx context.Context, entry ModelsStoreEntry) error
	DeleteModels(ctx context.Context) error
}

ProviderModelsStore scopes model persistence to one provider so provider implementations cannot inspect or mutate another provider's catalog.

type ProviderRetryOptions added in v0.82.0

type ProviderRetryOptions struct {
	MaxRetries    int
	MaxRetryDelay *time.Duration
	BaseDelay     time.Duration
	Now           func() time.Time
	Sleep         func(context.Context, time.Duration) error
	Jitter        func() float64
}

ProviderRetryOptions configures retries around one provider request. A non-positive BaseDelay uses 500ms. A nil MaxRetryDelay applies DefaultMaxProviderRetryDelay; a pointer to zero explicitly disables the server-requested delay cap.

type RadiusGatewayConfig added in v0.82.0

type RadiusGatewayConfig struct {
	BaseURL string               `json:"baseUrl"`
	Models  []RadiusGatewayModel `json:"models"`
}

RadiusGatewayConfig is the validated dynamic catalog returned by /v1/config.

func GetRadiusCredentialConfig added in v0.82.0

func GetRadiusCredentialConfig(
	credential *Credential,
) (RadiusGatewayConfig, bool)

GetRadiusCredentialConfig reads and validates the catalog cached by Pi's pre-ModelsStore Radius credential format.

func LoadRadiusGatewayConfig added in v0.82.0

func LoadRadiusGatewayConfig(
	ctx context.Context,
	client HTTPDoer,
	gateway string,
	apiKey string,
) (RadiusGatewayConfig, error)

LoadRadiusGatewayConfig loads and validates one gateway catalog.

type RadiusGatewayModel added in v0.82.0

type RadiusGatewayModel struct {
	ID               string             `json:"id"`
	Name             string             `json:"name"`
	Reasoning        bool               `json:"reasoning"`
	ThinkingLevelMap map[string]*string `json:"thinkingLevelMap,omitempty"`
	Input            []string           `json:"input"`
	Cost             ModelCost          `json:"cost"`
	ContextWindow    int                `json:"contextWindow"`
	MaxTokens        int                `json:"maxTokens"`
}

RadiusGatewayModel is one model advertised by a Radius gateway.

type RadiusOAuthOptions added in v0.82.0

type RadiusOAuthOptions struct {
	Name    string
	Gateway string
	Client  HTTPDoer
}

RadiusOAuthOptions configures OAuth discovery and token exchange for one default or custom Radius gateway.

type RadiusProviderOptions added in v0.82.0

type RadiusProviderOptions struct {
	ID          string
	Name        string
	Gateway     string
	Client      HTTPDoer
	OAuthLoader OAuthAuthLoader
}

RadiusProviderOptions configures a default or custom Radius gateway.

type RandomBytesFunc added in v0.82.0

type RandomBytesFunc func([]byte) error

type RefreshModelsContext added in v0.82.0

type RefreshModelsContext struct {
	Credential   *Credential
	Store        ProviderModelsStore
	AllowNetwork bool
	Force        bool
}

RefreshModelsContext contains the provider-scoped state needed to restore or fetch a dynamic model catalog.

type RemoteCatalogOptions added in v0.82.0

type RemoteCatalogOptions struct {
	BaseURL          string
	Client           HTTPDoer
	UserAgent        string
	LocalGeneratedAt time.Time
	RefreshInterval  time.Duration

	// Now is intended for deterministic hosts and tests. The zero value uses
	// time.Now.
	Now func() time.Time
}

RemoteCatalogOptions supplies stable dependencies for a provider's remote catalog overlay. LocalGeneratedAt decides whether a persisted remote catalog is newer than the compiled catalog.

type RetryAttempt added in v0.82.0

type RetryAttempt struct {
	Attempt      int
	MaxAttempts  int
	Delay        time.Duration
	ErrorMessage string
}

RetryAttempt describes one scheduled retry. Attempt is one-indexed and MaxAttempts is the configured number of retries, excluding the initial call.

type RetryCallbacks added in v0.82.0

type RetryCallbacks struct {
	OnRetryScheduled    func(RetryAttempt)
	OnRetryAttemptStart func(attempt int)
	OnRetryFinished     func(RetryResult)
}

RetryCallbacks lets stateful runtimes project the stateless retry algorithm into lifecycle events without moving UI/session state into this package.

type RetryPolicy added in v0.82.0

type RetryPolicy struct {
	Enabled    bool
	MaxRetries int
	BaseDelay  time.Duration
}

RetryPolicy is the runtime policy for retrying terminal assistant messages. It intentionally contains no mutable attempt state and is safe to share.

type RetryResult added in v0.82.0

type RetryResult struct {
	Success    bool
	Attempt    int
	FinalError string
}

RetryResult is emitted exactly once after at least one retry was scheduled.

type Schema

type Schema struct {
	Type        any               `json:"type,omitempty"`
	Description string            `json:"description,omitempty"`
	Default     any               `json:"default,omitempty"`
	Properties  map[string]Schema `json:"properties,omitempty"`
	Required    []string          `json:"required,omitempty"`
	Items       *Schema           `json:"items,omitempty"`
	Enum        []any             `json:"enum,omitempty"`
}

func Boolean

func Boolean() Schema

func Integer

func Integer() Schema

func Null

func Null() Schema

func Number

func Number() Schema

func Object

func Object(properties map[string]Schema, required ...string) Schema

func String

func String() Schema

func StringEnum

func StringEnum(values ...string) Schema

func StringEnumWithOptions

func StringEnumWithOptions(values []string, options StringEnumOptions) Schema

func TypeUnion

func TypeUnion(types ...string) Schema

type SessionResourceCleanup

type SessionResourceCleanup func(sessionID string) error

type SessionResourceCleanupError

type SessionResourceCleanupError struct {
	Errors []error
}

func (SessionResourceCleanupError) Error

func (SessionResourceCleanupError) Unwrap

func (e SessionResourceCleanupError) Unwrap() []error

type SimpleStreamOptions

type SimpleStreamOptions = StreamOptions

type StreamOptions

type StreamOptions struct {
	Context                       context.Context
	Temperature                   *float64
	MaxTokens                     int
	APIKey                        string
	Project                       string
	Location                      string
	Transport                     string
	CacheRetention                string
	SessionID                     string
	Reasoning                     string
	ToolChoice                    any
	Debug                         bool
	ThinkingBudgets               map[string]int
	Headers                       map[string]string
	HeaderRemovals                []string
	Env                           ProviderEnv
	HTTPClient                    HTTPDoer
	Timeouts                      StreamTimeouts
	TimeoutMillis                 int
	WebSocketConnectTimeoutMillis int
	MaxRetries                    int
	MaxRetryDelayMs               int
	Metadata                      map[string]any
	OnPayload                     func(payload any, model Model) (any, bool, error)
	OnResponseStatus              func(status int, headers map[string]string, model Model) error
}

type StreamTimeouts added in v0.82.0

type StreamTimeouts struct {
	HTTPIdle         *time.Duration
	WebSocketConnect *time.Duration
}

StreamTimeouts is the canonical, presence-aware timeout configuration for one provider request. A nil field means that the caller did not configure the timeout; a non-nil zero duration explicitly disables it.

The legacy millisecond fields on StreamOptions remain for source compatibility. New code should prefer StreamTimeouts so zero is not overloaded as both "unset" and "disabled".

type StringEnumOptions

type StringEnumOptions struct {
	Description string
	Default     string
}

type ThinkingTokenAllocation added in v0.82.0

type ThinkingTokenAllocation struct {
	MaxTokens      int
	ThinkingBudget int
}

ThinkingTokenAllocation keeps the total output cap and the reasoning-token portion together so provider adapters cannot accidentally update one without the other.

func AdjustMaxTokensForThinking added in v0.82.0

func AdjustMaxTokensForThinking(
	baseMaxTokens int,
	modelMaxTokens int,
	reasoningLevel string,
	customBudgets map[string]int,
) ThinkingTokenAllocation

AdjustMaxTokensForThinking fits a provider's reasoning budget inside the model output cap. The returned allocation can then be constrained by the request's remaining context.

type Tool

type Tool struct {
	Name                string                     `json:"name"`
	Description         string                     `json:"description,omitempty"`
	Parameters          Schema                     `json:"parameters,omitempty"`
	ConstrainedSampling *ConstrainedSamplingConfig `json:"constrainedSampling,omitempty"`
}

type ToolNameNormalizer added in v0.82.0

type ToolNameNormalizer func(string) string

ToolNameNormalizer maps provider-facing aliases to one comparison key.

type TransformHeadersFunc added in v0.82.0

type TransformHeadersFunc func(ctx context.Context, headers map[string]string) (map[string]string, error)

TransformHeadersFunc transforms fully assembled request headers exactly once before provider dispatch.

type UUIDv7Generator added in v0.82.0

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

UUIDv7Generator owns the monotonic sequence state for one UUID stream. Separate application instances can use independent generators without sharing mutable package state.

func NewUUIDv7Generator added in v0.82.0

func NewUUIDv7Generator(randomBytes RandomBytesFunc, nowMillis NowMillisFunc) *UUIDv7Generator

func (*UUIDv7Generator) Generate added in v0.82.0

func (g *UUIDv7Generator) Generate() string

type Usage

type Usage struct {
	Input        int       `json:"input"`
	Output       int       `json:"output"`
	CacheRead    int       `json:"cacheRead"`
	CacheWrite   int       `json:"cacheWrite"`
	CacheWrite1h int       `json:"cacheWrite1h,omitempty"`
	Reasoning    *int      `json:"reasoning,omitempty"`
	TotalTokens  int       `json:"totalTokens"`
	Cost         UsageCost `json:"cost"`
}

func EmptyUsage

func EmptyUsage() Usage

func ParseGoogleUsage

func ParseGoogleUsage(raw GoogleUsageMetadata, model Model) Usage

func ParseMistralUsage

func ParseMistralUsage(raw MistralUsage, model Model) Usage

func ParseOpenAIChatUsage

func ParseOpenAIChatUsage(raw OpenAIChatUsage, model Model) Usage

func ParseOpenAIResponsesUsage

func ParseOpenAIResponsesUsage(raw OpenAIResponsesUsage, model Model) Usage

func ParseOpenRouterImagesUsage

func ParseOpenRouterImagesUsage(raw OpenRouterImagesUsage, model ImagesModel) Usage

type UsageCost

type UsageCost struct {
	Input      float64 `json:"input"`
	Output     float64 `json:"output"`
	CacheRead  float64 `json:"cacheRead"`
	CacheWrite float64 `json:"cacheWrite"`
	Total      float64 `json:"total"`
}

func CalculateCost

func CalculateCost(model Model, usage Usage) UsageCost

type XAIOAuthOptions added in v0.82.0

type XAIOAuthOptions struct {
	Client HTTPDoer
}

XAIOAuthOptions configures xAI OAuth HTTP execution.

Source Files

Directories

Path Synopsis
internal
cmd/conformance command
cmd/modelgen command
Command modelgen converts Pi's published provider model JSON into Gi's compiled Go catalog.
Command modelgen converts Pi's published provider model JSON into Gi's compiled Go catalog.
sse
Package sse implements the stateful wire framing shared by HTTP providers that consume Server-Sent Events.
Package sse implements the stateful wire framing shared by HTTP providers that consume Server-Sent Events.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL