provider

package
v1.3.3 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2026 License: AGPL-3.0, AGPL-3.0 Imports: 23 Imported by: 0

Documentation

Overview

Package provider defines the inward contract between exchange orchestration and exact outbound provider backends.

Exchange owns attempts, rounds, routing, fallback, session resolution, and control state. Provider values contain only the target and canonical/wire facts required to encode, send, and decode one provider request. Concrete implementations live under internal/adapters/outbound/providers and must not import exchange. Provider adapters also own factual failure classification: unsupported, unavailable, rejected, invalid request, cancelled, or internal. Exchange may apply recovery policy to those types only after combining them with the adapter-owned execution possibility and the final attempt's replay safety. Availability alone is never replay permission. Untyped issued-call errors conservatively mean provider execution may have occurred.

Exchange passes an exchange-scoped read-through image resolver into provider encoding. URL-native codecs preserve locators without invoking it; byte-only codecs resolve through the existing bounded fetch policy, inspection, and cache. Fetched bytes never enter canonical history or checkpoints. Codecs solely own exact target-grammar projection. Successful projection returns non-exact semantic changes as values. Local projection failures retain their owning canonical error and never authorize another provider attempt. Provider/protocol identity, encoder availability, model names, backend prose, and choosing a portable projection do not establish support. Provider runtime facets resolve exact-target evidence independently from backend construction. TargetFacts is the narrow exception for empirically learned wire dialect: an attempt-private typed getter selects between two codec-owned projections, records every value used, and defaults unknown to the preferred form. It is never capability metadata, admission, routing, or recovery policy. AttemptToolNames owns one immutable canonical-key to wire-name bijection for an attempt. It preserves safe request-level literals and gives every generated alias a readable semantic prefix plus a stable digest of the complete canonical identity. Generic naming never infers transport provenance from namespace text; typed transformations remove transport-only structure before this edge. Protocol-specific response identity stays in typed canonical native handles. Session resolution materializes unfinished tool-turn compute continuity into the effective canonical request before this boundary. Routing-owned target ID and version bind provider-owned native response handles. Self-contained opaque thinking remains attached to its canonical reasoning item and replays unchanged through the Messages protocol or exact OpenRouter provider hook. TargetSnapshot is an atomic execution projection. Provider-specific execution facts occupy one closed options arm fixed by construction; adapters read them through accessors and cannot complete snapshots through later mutation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Cancelled 

func Cancelled(err error) error

func Internal 

func Internal(err error) error

func InvalidRequest 

func InvalidRequest(err error) error

func NormalizeFailure 

func NormalizeFailure(err error) error

NormalizeFailure closes the provider cause vocabulary. Execution possibility remains a separate AttemptFailure fact; this function never grants replay.

func Rejected 

func Rejected(err error) error

func RetryNotBefore added in v1.1.3 

func RetryNotBefore(err error, now time.Time) (time.Time, bool)

RetryNotBefore extracts the standard backend retry timing fact without choosing routing or backoff policy. Invalid, negative, expired, and absent hints are ignored.

func TimedOut added in v1.3.2 

func TimedOut(err error) error

func TransportFailure 

func TransportFailure(ctx context.Context, err error) error

TransportFailure classifies a failed provider I/O attempt without losing invocation cancellation behind a generic availability wrapper.

func Unavailable 

func Unavailable(err error) error

func ValidateIngress 

func ValidateIngress(ingress Ingress) error

ValidateIngress proves one transport result is a non-empty provider-ingress carrier before the selected backend codec receives it.

Types

type AttemptFailure 

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

AttemptFailure is the validated terminal fact for one provider attempt. Bound transports conservatively wrap an untyped error as ExecutionMayHaveOccurred; only the exact adapter may claim an earlier fact.

func AsAttemptFailure 

func AsAttemptFailure(err error) (AttemptFailure, bool)

AsAttemptFailure extracts a validated issued-call fact.

func AttemptMayHaveExecuted 

func AttemptMayHaveExecuted(cause error) AttemptFailure

func AttemptNotDispatched 

func AttemptNotDispatched(cause error) AttemptFailure

func AttemptRejectedBeforeExecution 

func AttemptRejectedBeforeExecution(cause error) AttemptFailure

func (AttemptFailure) Cause 

func (e AttemptFailure) Cause() error

func (AttemptFailure) Error 

func (e AttemptFailure) Error() string

func (AttemptFailure) Execution 

func (e AttemptFailure) Execution() ExecutionPossibility

func (AttemptFailure) Unwrap 

func (e AttemptFailure) Unwrap() error

type AttemptToolNames 

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

AttemptToolNames is one provider attempt's immutable bidirectional mapping between canonical callable identity and provider-valid wire labels. It never enters canonical history, checkpoint state, sessions, or durable config.

func BuildAttemptToolNames 

func BuildAttemptToolNames(semantic canonical.CanonicalRequest) (AttemptToolNames, []compat.Change, error)

BuildAttemptToolNames allocates labels from the complete post-MCP semantic context. Ordinary namespace children and historical calls participate; MCP catalog children participate only after Exchange materializes them as ordinary functions, while fixed built-ins do not.

func (AttemptToolNames) CanonicalKey 

func (n AttemptToolNames) CanonicalKey(wireName string) (canonical.ToolKey, bool)

CanonicalKey resolves one provider-returned callable label to its canonical source key. Wire labels are globally unique per attempt, so provenance—not a guessed wire kind—selects the canonical lifecycle.

func (AttemptToolNames) WireName 

func (n AttemptToolNames) WireName(key canonical.ToolKey) (string, error)

WireName returns the exact provider label allocated for key.

type Backend 

type Backend struct {
	Target    TargetSnapshot
	Codec     Codec
	Transport Transport
}

Backend binds one exact target generation to its codec and document-only transport.

func (Backend) CharacterizeTargetFact added in v1.3.1 

func (b Backend) CharacterizeTargetFact(ctx context.Context, fact TargetFact) TargetFactResolution

CharacterizeTargetFact delegates one isolated fact to the exact backend codec. Codecs without empirical dialect branches return inconclusive.

func (Backend) Validate 

func (b Backend) Validate() error

Validate proves the backend is complete before exchange execution.

type BackendResolver 

type BackendResolver interface {
	ResolveBackend(TargetSnapshot) (Backend, error)
}

BackendResolver composes one exact backend for a selected target snapshot. Resolution preserves the target exactly and performs no network I/O.

type CancelledError 

type CancelledError struct{ Cause error }

CancelledError means invocation cancellation stopped provider execution.

func (CancelledError) Error 

func (e CancelledError) Error() string

func (CancelledError) Unwrap 

func (e CancelledError) Unwrap() error

type Codec 

type Codec interface {
	Encode(Request) (carrier.Document, []compat.Change, error)
	Decode(context.Context, Request, Ingress) (DecodedResponse, error)
}

Codec owns final canonical/provider-wire conversion for one exact backend. Compatibility changes are processing results; persisting them as evidence is outside this interface and cannot alter the codec result.

type DecodedResponse 

type DecodedResponse struct {
	Stream canonical.ResponseStream
	// Changes contains facts known when decoding begins. ProgressiveChanges
	// returns the immutable facts accumulated once Stream reaches terminal.
	Changes            []compat.Change
	ProgressiveChanges func() []compat.Change
}

DecodedResponse is one invocation-bound provider decode result. All durable response semantics enter the canonical stream.

type Discovery 

type Discovery interface {
	ProbeTarget(context.Context, TargetSnapshot) (TargetProbeResult, error)
}

Discovery performs one truthful provider-owned catalog probe.

type DocumentIngress 

type DocumentIngress struct{ Document carrier.Document }

DocumentIngress carries one buffered provider wire document.

type EncodeContext 

type EncodeContext struct {
	Context      context.Context
	ResolveImage func(context.Context, canonical.URLImage) (InspectedImage, error)
	// HasNextRouteCandidate is transient exchange execution context. It is not
	// canonical intent, target capability, or persisted routing configuration.
	HasNextRouteCandidate bool
}

EncodeContext carries request-scoped capabilities that an exact provider codec may invoke while lowering canonical input. URL-native codecs leave ResolveImage untouched; byte-only codecs call it only for URL images.

type ExecutionPossibility 

type ExecutionPossibility uint8

ExecutionPossibility records only what Swobu can prove about one issued provider call. It is independent of the provider failure class. 

const (
	ExecutionNotDispatched ExecutionPossibility = iota + 1
	ExecutionRejectedBeforeExecution
	ExecutionMayHaveOccurred
)

type FetchedImageResult 

type FetchedImageResult struct {
	Bytes             []byte
	DeclaredMediaType canonical.ImageMediaType
}

FetchedImageResult contains bounded response bytes and the origin's explicit media declaration when present. Pure inspection determines the actual image type.

type HostPattern 

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

HostPattern is one validated exact host or leading-wildcard suffix.

func NewHostPattern 

func NewHostPattern(raw string) (HostPattern, error)

func (HostPattern) Matches 

func (p HostPattern) Matches(host string) bool

type ImageFetchPolicy 

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

func DefaultImageFetchPolicy 

func DefaultImageFetchPolicy() ImageFetchPolicy

func DisabledImageFetchPolicy 

func DisabledImageFetchPolicy() ImageFetchPolicy

DisabledImageFetchPolicy forbids URL materialization and carries no unreachable network configuration.

func NewImageFetchPolicy 

func NewImageFetchPolicy(network NetworkPolicy, totalPreparationTimeout time.Duration) (ImageFetchPolicy, error)

NewImageFetchPolicy enables materialization under one validated network policy.

func (ImageFetchPolicy) Clone 

func (p ImageFetchPolicy) Clone() ImageFetchPolicy

func (ImageFetchPolicy) NetworkPolicy 

func (p ImageFetchPolicy) NetworkPolicy() (NetworkPolicy, bool)

func (ImageFetchPolicy) TotalPreparationTimeout 

func (p ImageFetchPolicy) TotalPreparationTimeout() time.Duration

func (ImageFetchPolicy) Validate 

func (p ImageFetchPolicy) Validate() error

type ImageFetcher 

type ImageFetcher interface {
	FetchImage(context.Context, canonical.URLImage, NetworkPolicy, int64) (FetchedImageResult, error)
}

ImageFetcher performs only authorized, bounded URL I/O.

type Ingress 

type Ingress interface {
	// contains filtered or unexported methods
}

Ingress is one truthful provider transport result variant.

type InspectedImage 

type InspectedImage struct {
	MediaType canonical.ImageMediaType
	Bytes     []byte
	Width     int
	Height    int
}

InspectedImage is the validated operational view of canonical image bytes.

func InspectImage 

func InspectImage(declared canonical.ImageMediaType, data []byte, limits MediaLimits) (InspectedImage, error)

InspectImage applies the same byte, type, dimension, pixel, and animation policy to inline and fetched image carriers.

type InternalError 

type InternalError struct{ Cause error }

InternalError means provider execution failed without a safe routing classification. Unknown errors fail closed as internal.

func (InternalError) Error 

func (e InternalError) Error() string

func (InternalError) Unwrap 

func (e InternalError) Unwrap() error

type InvalidRequestError 

type InvalidRequestError struct{ Cause error }

InvalidRequestError means provider execution could not begin because the selected request or backend configuration is invalid.

func (InvalidRequestError) Error 

func (e InvalidRequestError) Error() string

func (InvalidRequestError) Unwrap 

func (e InvalidRequestError) Unwrap() error

type MediaLimits 

type MediaLimits struct {
	MaxImages          int
	MaxImageBytes      int64
	MaxTotalImageBytes int64
	MaxPixelsPerImage  int64
	MaxImageDimension  int
}

MediaLimits bounds image inspection and materialization independently of ingress transport and checkpoint-retention policy.

func DefaultMediaLimits 

func DefaultMediaLimits() MediaLimits

func (MediaLimits) Validate 

func (l MediaLimits) Validate() error

type NetworkAccess 

type NetworkAccess string
const (
	NetworkPublicOnly  NetworkAccess = "public_only"
	NetworkAllowlisted NetworkAccess = "allowlisted"
)

type NetworkPolicy 

type NetworkPolicy struct {
	Access              NetworkAccess
	AllowedHosts        []HostPattern
	DeniedHosts         []HostPattern
	MaxRedirects        int
	PerImageTimeout     time.Duration
	AllowHTTPSDowngrade bool
}

type PreviousHistory added in v1.1.0 

type PreviousHistory struct {
	Response  canonical.ResponseRef
	OmitStart uint32
	OmitEnd   uint32
}

PreviousHistory authorizes one exact provider codec to replace a contiguous complete-request history range with its typed native continuation handle. The closed ResponseRef remains the handle authority; no provider-generic ID or metadata map can be introduced at this seam.

type ProviderID 

type ProviderID string

ProviderID identifies one fixed provider implementation.

type RejectedError 

type RejectedError struct{ Cause error }

RejectedError means the backend returned a response rejecting this exact target. A complete 4xx is target-local evidence; it does not prove canonical invalidity or absence of execution. Exact-target rejection is combined with execution possibility and replay safety by the route reducer, so this type is never itself a public client error and never grants replay.

func (RejectedError) Error 

func (e RejectedError) Error() string

func (RejectedError) Unwrap 

func (e RejectedError) Unwrap() error

type Request 

type Request struct {
	// ExchangeID correlates progressive response events for this invocation. It
	// is execution context, not part of canonical request semantics.
	ExchangeID string
	// CacheLocality is attempt-scoped cache placement. It is neither
	// conversation identity nor model intent, cache materialization, or
	// persistence policy.
	CacheLocality cachelocality.Key
	Canonical     canonical.CanonicalRequest
	// TargetFacts is one attempt-private empirical dialect reader. Codecs call
	// only the typed getter at a branch they execute; nil reads as preferred.
	TargetFacts     *TargetFacts
	PreviousHistory *PreviousHistory
	EncodeContext   EncodeContext
	Delivery        delivery.Delivery
	// ToolNames is transient provider-attempt representation state.
	ToolNames AttemptToolNames
}

Request contains only the provider-facing input for one provider call. Canonical is always the complete effective canonical request and is the only request-history authority. PreviousHistory is optional exact-target lowering data; it never changes Canonical's meaning.

type StreamIngress 

type StreamIngress struct{ Stream carrier.ByteStream }

StreamIngress carries one provider wire byte stream.

type TargetFact added in v1.3.1 

type TargetFact uint8

TargetFact is the closed set of empirically learnable target-dialect questions. Each value selects between two codec-owned wire projections; it never describes semantic capability, model quality, or routing preference. 

const (
	AcceptsParallelToolCallsFalse TargetFact = iota + 1
	AcceptsMaxCompletionTokens
	AcceptsReasoningEffortMax
	AcceptsReasoningDisabled
	AcceptsFunctionCallOutputArray
)

type TargetFactCharacterizer added in v1.3.1 

type TargetFactCharacterizer interface {
	CharacterizeTargetFact(context.Context, TargetSnapshot, TargetFact, Transport) TargetFactResolution
}

TargetFactCharacterizer owns isolated, target-local fixture execution for the target facts its codec reads. Exchange decides when characterization is admissible; the codec owns the fixture and its two wire projections.

type TargetFactLookup added in v1.3.1 

type TargetFactLookup func(TargetFact) (bool, bool)

TargetFactLookup reads process-scoped knowledge for one target generation. Absence is not rejection: TargetFacts uses the preferred representation.

type TargetFactResolution added in v1.3.1 

type TargetFactResolution struct {
	Value      bool
	Conclusive bool
}

TargetFactResolution is conclusive only when the preferred fixture succeeds or its typed rejection is distinguished by a successful control fixture.

type TargetFacts added in v1.3.1 

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

TargetFacts is one attempt-private dialect reader. Repeated reads are stable and Reads returns the exact branch values that influenced encoding.

func NewTargetFacts added in v1.3.1 

func NewTargetFacts(lookup TargetFactLookup) *TargetFacts

func (*TargetFacts) AcceptsFunctionCallOutputArray added in v1.3.1 

func (f *TargetFacts) AcceptsFunctionCallOutputArray() bool

func (*TargetFacts) AcceptsMaxCompletionTokens added in v1.3.1 

func (f *TargetFacts) AcceptsMaxCompletionTokens() bool

func (*TargetFacts) AcceptsParallelToolCallsFalse added in v1.3.1 

func (f *TargetFacts) AcceptsParallelToolCallsFalse() bool

func (*TargetFacts) AcceptsReasoningDisabled added in v1.3.1 

func (f *TargetFacts) AcceptsReasoningDisabled() bool

func (*TargetFacts) AcceptsReasoningEffortMax added in v1.3.1 

func (f *TargetFacts) AcceptsReasoningEffortMax() bool

func (*TargetFacts) Reads added in v1.3.1 

func (f *TargetFacts) Reads() map[TargetFact]bool

Reads returns a detached snapshot of every fact and value used by encoding.

type TargetProbeResult 

type TargetProbeResult struct {
	Options     []profile.ModelAuthoringOption
	Diagnostics []byte
}

TargetProbeResult keeps provider-specific authoring diagnostics opaque to generic dispatch and transport layers. Diagnostics is optional provider- owned JSON interpreted only by that provider's operator surface.

type TargetSnapshot 

type TargetSnapshot struct {
	TargetID      string
	TargetVersion uint64
	ProviderSpec  string
	BaseURL       string
	CredentialRef string

	Model            string
	ProtocolKind     protocolkind.ProtocolKind
	ProviderProtocol string
	ProviderDelivery delivery.Delivery
	// contains filtered or unexported fields
}

TargetSnapshot is the complete execution projection of one configured routing target. Provider-specific facts (the custom auth header, the Bedrock signing region) are fixed during construction by a provider-specific constructor and exposed only through accessors, so no incomplete snapshot can be completed by post-construction mutation. It carries no workspace, route, fallback, or attempt state.

func NewBedrockTargetSnapshot 

func NewBedrockTargetSnapshot(targetID, baseURL, credentialRef string, protocol protocolkind.ProtocolKind, providerProtocol, region string, providerDelivery delivery.Delivery) TargetSnapshot

NewBedrockTargetSnapshot constructs a Bedrock execution target carrying the durable AWS signing region as a provider-specific fact fixed at construction. The endpoint host never owns the signing region; region is an authored first-class fact threaded here, not parsed from the endpoint URL.

func NewCustomTargetSnapshot 

func NewCustomTargetSnapshot(targetID, baseURL, credentialRef string, protocol protocolkind.ProtocolKind, providerProtocol, authHeader string, providerDelivery delivery.Delivery) TargetSnapshot

NewCustomTargetSnapshot constructs a custom-endpoint execution target carrying the auth header name as a provider-specific fact fixed at construction.

func NewTargetSnapshot 

func NewTargetSnapshot(targetID, providerSpec, baseURL, credentialRef string, protocol protocolkind.ProtocolKind, providerProtocol string, providerDelivery delivery.Delivery) TargetSnapshot

NewTargetSnapshot constructs one provider execution target projection for a provider whose execution carries no provider-specific fact. providerProtocol is the exact concrete provider protocol name. providerDelivery is the delivery selected by that concrete provider contract and must be supplied by the profile/exchange boundary; it is never derived here.

func (TargetSnapshot) AuthHeader 

func (t TargetSnapshot) AuthHeader() string

AuthHeader returns the custom-endpoint auth header name. It is empty unless the target was constructed with NewCustomTargetSnapshot.

func (TargetSnapshot) BedrockRegion 

func (t TargetSnapshot) BedrockRegion() string

BedrockRegion returns the durable AWS signing region. It is empty unless the target was constructed with NewBedrockTargetSnapshot.

func (TargetSnapshot) Clone 

func (t TargetSnapshot) Clone() TargetSnapshot

Clone returns a detached target value.

func (TargetSnapshot) Equal 

func (t TargetSnapshot) Equal(other TargetSnapshot) bool

Equal reports exact target equality. Backend resolution must preserve this value so exchange never has two target authorities that can disagree.

func (TargetSnapshot) ProviderID 

func (t TargetSnapshot) ProviderID() string

ProviderID returns the fixed provider implementation identifier.

func (TargetSnapshot) ValidateExecutionProtocol 

func (t TargetSnapshot) ValidateExecutionProtocol() error

ValidateExecutionProtocol proves that the concrete provider protocol names the same semantic family and upstream delivery as this target projection. Client delivery remains transient Exchange input and is intentionally not stored here.

type TimeoutError added in v1.3.2 

type TimeoutError struct{ Cause error }

TimeoutError identifies provider-transport deadline exhaustion while the caller context remains live. It is availability evidence, not cancellation.

func (TimeoutError) Error added in v1.3.2 

func (e TimeoutError) Error() string

func (TimeoutError) Unwrap added in v1.3.2 

func (e TimeoutError) Unwrap() error

type Transport 

type Transport interface {
	Send(context.Context, carrier.Document) (Ingress, error)
}

Transport performs external I/O over a final provider wire document. It has no canonical request input and therefore cannot re-encode canonical state.

func BindTransport 

func BindTransport(target TargetSnapshot, send func(context.Context, TargetSnapshot, carrier.Document) (Ingress, error)) Transport

BindTransport closes over the exact target during backend construction so a caller cannot substitute a second target after codec/key resolution.

type TransportFunc 

type TransportFunc func(context.Context, carrier.Document) (Ingress, error)

TransportFunc adapts one backend-bound send operation to Transport.

func (TransportFunc) Send 

func (f TransportFunc) Send(ctx context.Context, document carrier.Document) (Ingress, error)

type UnavailableError 

type UnavailableError struct{ Cause error }

UnavailableError means provider I/O could not produce a usable backend response. It does not state whether provider execution occurred or whether replay is safe.

func (UnavailableError) Error 

func (e UnavailableError) Error() string

func (UnavailableError) Unwrap 

func (e UnavailableError) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.