model

package
v1.0.8 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: GPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package model defines the provider-neutral model transport boundary and the Azure OpenAI Responses API adapter.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrClosed reports that a response stream was explicitly closed.
	ErrClosed = errors.New("model stream closed")
	// ErrIncompleteStream reports EOF or [DONE] before a successful or failed
	// terminal Responses API event.
	ErrIncompleteStream = errors.New("model stream ended without a terminal response event")
	// ErrStreamWatchdog reports that no stream activity arrived before the
	// configured idle deadline.
	ErrStreamWatchdog = errors.New("model stream idle watchdog expired")
	// ErrRequestTimeout is an adapter-owned per-attempt deadline. It is distinct
	// from caller cancellation so the session cannot misreport provider latency
	// as a user cancellation.
	ErrRequestTimeout = errors.New("model provider request timed out")
	// ErrProtocol reports malformed or contradictory provider wire data.
	ErrProtocol = errors.New("invalid model protocol")
	// ErrInputMediaUnavailable reports that a provider cannot safely materialize
	// one or more provider-neutral attachment references for this request.
	ErrInputMediaUnavailable = errors.New("model input media is unavailable")
)

Functions

func ContainsAttachmentData added in v1.0.7 

func ContainsAttachmentData(value string) bool

ContainsAttachmentData reports whether provider-controlled text contains an exact supported attachment data-URL prefix or a conservatively long standalone base64-like run. It is intentionally stricter than proving an exact byte-for-byte reflection so public output fails closed before request media can enter logs, transcripts, tool arguments, or presentation streams.

func IsMediaRejection added in v1.0.7 

func IsMediaRejection(err error) bool

IsMediaRejection reports only trusted provider-adapter classification. It deliberately uses the package-owned error graph inspector rather than matching provider-controlled prose.

Types

type AttachmentSource added in v1.0.7 

type AttachmentSource interface {
	Resolve(ctx context.Context, id attachment.ID) (attachment.Manifest, []byte, error)
}

AttachmentSource resolves an immutable, runtime-owned attachment snapshot. Implementations must honor ctx and return a defensive byte slice. Provider adapters compare the returned manifest with the requested manifest before using the bytes.

type AzureClient 

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

AzureClient adapts the provider-neutral model boundary to Azure OpenAI's Responses API. Its credential fields are private, and String/GoString redact them to prevent accidental diagnostic disclosure.

func NewAzureClient 

func NewAzureClient(configuration config.Azure, options AzureOptions) (*AzureClient, error)

NewAzureClient validates and copies configuration into an immutable client. The configured Azure deployment, not a presentation label, is always sent as the wire model value.

func (*AzureClient) Format 

func (c *AzureClient) Format(state fmt.State, verb rune)

func (*AzureClient) GoString 

func (c *AzureClient) GoString() string

GoString prevents %#v from traversing the client's private credential field.

func (*AzureClient) InputMediaCapability added in v1.0.7 

func (c *AzureClient) InputMediaCapability() (InputMediaCapability, bool)

InputMediaCapability returns the exact media capability only for the positively qualified native Azure profile. Capability absence means text-only; deployment naming alone never enables media.

func (*AzureClient) ModelName 

func (c *AzureClient) ModelName() string

ModelName returns the logical model identity from configuration. Azure may use a differently named deployment on the wire.

func (*AzureClient) Stream 

func (c *AzureClient) Stream(ctx context.Context, request Request) (Stream, error)

Stream starts a stateless, streaming Responses API request. Transport and retry ownership transfer to the returned stream on success.

func (*AzureClient) String 

func (c *AzureClient) String() string

String deliberately exposes no credential material.

type AzureOptions 

type AzureOptions struct {
	HTTPClient *http.Client
	// CredentialSanitizer contains every configured credential that can reach
	// this provider request through contributed context or tool descriptors.
	// The API key is always unioned in by NewAzureClient.
	CredentialSanitizer *redact.Set
	RetryBase           time.Duration
	// RetryMaximum caps only ordinary exponential backoff. A valid provider
	// Retry-After value is honored directly when it fits inside RetryWindow.
	RetryMaximum time.Duration
	// RetryWindow bounds the wall-clock/planned-delay interval in which a
	// request may start replacement attempts. It does not impose a lifetime on
	// a successfully opened response stream.
	RetryWindow              time.Duration
	MaximumEventBytes        int
	MaximumErrorBytes        int64
	MaximumResponseBytes     int
	MaximumResponseEvents    int
	MaximumResponseItems     int
	MaximumToolCalls         int
	MaximumCallArgumentBytes int
	// AttachmentLimits must match or tighten the session attachment store.
	// The provider never accepts broader bounds than attachment.DefaultLimits.
	AttachmentLimits attachment.Limits
	// MaximumRequestMediaItems caps media across the complete provider request,
	// including retained historical messages. Zero selects 100.
	MaximumRequestMediaItems int
	// MaximumEncodedMediaBytes caps the sum of data-URL bytes before allocating
	// the provider request. Zero derives the exact upper bound from the decoded
	// media-byte and item-count limits.
	MaximumEncodedMediaBytes int64
	// MaximumRequestBytes caps the final JSON request body whenever media is
	// present. Zero selects 64 MiB.
	MaximumRequestBytes int64
	UserAgent           string
	Now                 func() time.Time
	Jitter              func(maximum time.Duration) time.Duration
	Sleep               func(ctx context.Context, delay time.Duration) error
	OnRetry             func(RetryInfo)
}

AzureOptions supplies operational dependencies. Zero values select safe defaults. The hooks primarily make backoff and time testable without a live service; they must not receive raw headers, bodies, or credentials.

type Content 

type Content struct {
	Type     ContentType          `json:"type"`
	Text     string               `json:"text,omitempty"`
	Manifest *attachment.Manifest `json:"attachment,omitempty"`
}

Content is one provider-neutral message part. Media parts contain only an immutable attachment manifest; bytes and source paths remain behind the request's AttachmentSource and are loaded only by the provider adapter.

type ContentType 

type ContentType string

ContentType identifies one message or reasoning content part. 

const (
	ContentInputText   ContentType = "input_text"
	ContentInputImage  ContentType = "input_image"
	ContentInputFile   ContentType = "input_file"
	ContentOutputText  ContentType = "output_text"
	ContentRefusal     ContentType = "refusal"
	ContentSummaryText ContentType = "summary_text"
)

type Event 

type Event struct {
	Type           EventType          `json:"type"`
	RawType        string             `json:"raw_type,omitempty"`
	SequenceNumber int64              `json:"sequence_number,omitempty"`
	RequestID      string             `json:"request_id,omitempty"`
	ResponseID     string             `json:"response_id,omitempty"`
	ItemID         string             `json:"item_id,omitempty"`
	OutputIndex    int                `json:"output_index,omitempty"`
	ContentIndex   int                `json:"content_index,omitempty"`
	Delta          string             `json:"delta,omitempty"`
	ReasoningKind  ReasoningDeltaKind `json:"reasoning_kind,omitempty"`
	Call           *Item              `json:"call,omitempty"`
	Usage          *Usage             `json:"usage,omitempty"`
	Response       *Response          `json:"response,omitempty"`
	Error          *ProviderError     `json:"error,omitempty"`
}

Event is a canonical stream event. SequenceNumber and item indexes preserve provider ordering and correlation without exposing the raw wire envelope.

func Drain 

func Drain(stream Stream) ([]Event, error)

Drain consumes a stream through an explicit terminal event. It is useful for bounded auxiliary calls and tests; the shared query engine normally handles events incrementally.

type EventType 

type EventType string

EventType identifies one normalized stream event. 

const (
	EventResponseCreated            EventType = "response_created"
	EventResponseInProgress         EventType = "response_in_progress"
	EventTextDelta                  EventType = "text_delta"
	EventReasoningDelta             EventType = "reasoning_delta"
	EventFunctionCallArgumentsDelta EventType = "function_call_arguments_delta"
	EventFunctionCallCompleted      EventType = "function_call_completed"
	EventUsage                      EventType = "usage"
	EventResponseCompleted          EventType = "response_completed"
	EventError                      EventType = "error"
)

type InputMediaCapability added in v1.0.7 

type InputMediaCapability struct {
	Attachment      attachment.Capability `json:"attachment"`
	MaxRequestItems int                   `json:"max_request_items"`
	MaxEncodedBytes int64                 `json:"max_encoded_media_bytes"`
	MaxRequestBytes int64                 `json:"max_request_bytes"`
}

InputMediaCapability is the exact provider-bound media contract advertised for a qualified Azure model/API configuration. Import limits remain owned by the attachment subsystem; the remaining limits apply to one model request.

type Item 

type Item struct {
	Type ItemType `json:"type"`
	ID   string   `json:"id,omitempty"`
	// APIResponseID is local projection provenance used to keep streamed
	// response siblings together during context reduction. Provider adapters
	// deliberately omit it from the wire request.
	APIResponseID    string    `json:"api_response_id,omitempty"`
	Role             Role      `json:"role,omitempty"`
	Status           string    `json:"status,omitempty"`
	Phase            string    `json:"phase,omitempty"`
	Content          []Content `json:"content,omitempty"`
	CallID           string    `json:"call_id,omitempty"`
	Name             string    `json:"name,omitempty"`
	Arguments        string    `json:"arguments,omitempty"`
	Output           string    `json:"output,omitempty"`
	EncryptedContent string    `json:"encrypted_content,omitempty"`
	Summary          []Content `json:"summary,omitempty"`
}

Item is a semantic Responses API input or output item. Only fields relevant to Type are used. Arguments remain a string because model-produced function arguments are untrusted and must be validated by the capability runtime.

func FunctionCall 

func FunctionCall(id, callID, name, arguments string) Item

FunctionCall creates a replayable assistant function-call item.

func FunctionCallOutput 

func FunctionCallOutput(callID, output string) Item

FunctionCallOutput creates a tool-result input correlated to callID.

func TextMessage 

func TextMessage(role Role, text string) Item

TextMessage constructs one provider-neutral text message. Assistant text is represented as output_text so manually replayed Responses items retain their original role semantics; all other roles use input_text.

type ItemType 

type ItemType string

ItemType identifies a provider-neutral conversation item. 

const (
	ItemMessage            ItemType = "message"
	ItemFunctionCall       ItemType = "function_call"
	ItemFunctionCallOutput ItemType = "function_call_output"
	ItemReasoning          ItemType = "reasoning"
)

type Provider 

type Provider interface {
	Stream(ctx context.Context, request Request) (Stream, error)
}

Provider starts one model response stream. A Stream is bound to ctx for its entire lifetime; callers must close it when they stop receiving events.

type ProviderError 

type ProviderError struct {
	StatusCode int    `json:"status_code,omitempty"`
	Code       string `json:"code,omitempty"`
	Type       string `json:"error_type,omitempty"`
	Param      string `json:"param,omitempty"`
	Message    string `json:"message"`
	RequestID  string `json:"request_id,omitempty"`
	Retryable  bool   `json:"retryable,omitempty"`
	// MediaRejected is trusted adapter classification for quarantine decisions.
	// It is deliberately not serialized or exposed as provider-controlled wire
	// data.
	MediaRejected bool `json:"-"`
	// contains filtered or unexported fields
}

ProviderError is a safe, structured provider failure. Error intentionally omits response bodies, request inputs, headers, and credentials.

func (*ProviderError) Error 

func (e *ProviderError) Error() string

func (*ProviderError) Format 

func (e *ProviderError) Format(state fmt.State, verb rune)

func (*ProviderError) GoString 

func (e *ProviderError) GoString() string

func (*ProviderError) String 

func (e *ProviderError) String() string

type Reasoning 

type Reasoning struct {
	Effort string `json:"effort,omitempty"`
}

Reasoning configures a model's reasoning policy. Empty Effort delegates to the configured provider default.

type ReasoningDeltaKind 

type ReasoningDeltaKind string

ReasoningDeltaKind distinguishes hidden reasoning content from a model-safe reasoning summary when a provider supplies either form. 

const (
	ReasoningContent ReasoningDeltaKind = "content"
	ReasoningSummary ReasoningDeltaKind = "summary"
)

type Request 

type Request struct {
	Model              string            `json:"model,omitempty"`
	Instructions       string            `json:"instructions,omitempty"`
	Input              []Item            `json:"input"`
	Tools              []Tool            `json:"tools,omitempty"`
	Reasoning          Reasoning         `json:"reasoning,omitempty"`
	MaxOutputTokens    int               `json:"max_output_tokens,omitempty"`
	PreviousResponseID string            `json:"previous_response_id,omitempty"`
	ParallelToolCalls  *bool             `json:"parallel_tool_calls,omitempty"`
	Metadata           map[string]string `json:"metadata,omitempty"`
	// AttachmentSource is an ephemeral provider-bound resolver. It is not part
	// of request serialization, transcript projection, or diagnostics.
	AttachmentSource AttachmentSource `json:"-"`
}

Request is the provider-neutral projection for one Responses API call. Model is the logical model identity used by the engine; a cloud adapter may route it through a configured deployment name on the wire.

func (Request) Validate 

func (r Request) Validate() error

Validate checks only provider-neutral request shape. Tool argument and output semantics remain untrusted data for the capability runtime.

type Response 

type Response struct {
	ID                 string `json:"id"`
	Model              string `json:"model,omitempty"`
	Status             string `json:"status,omitempty"`
	PreviousResponseID string `json:"previous_response_id,omitempty"`
	Output             []Item `json:"output,omitempty"`
	Usage              Usage  `json:"usage"`
}

Response is the provider-neutral terminal Responses API object. Output preserves reasoning and function-call items needed for stateless replay.

type RetryExhaustedError 

type RetryExhaustedError struct {
	Attempts    int
	Last        error
	RetryWindow time.Duration
	// contains filtered or unexported fields
}

RetryExhaustedError reports the final safe cause after the configured retry ceiling. Attempts includes the initial request.

func (*RetryExhaustedError) Error 

func (e *RetryExhaustedError) Error() string

func (*RetryExhaustedError) Format 

func (e *RetryExhaustedError) Format(state fmt.State, verb rune)

func (*RetryExhaustedError) GoString 

func (e *RetryExhaustedError) GoString() string

func (*RetryExhaustedError) String 

func (e *RetryExhaustedError) String() string

func (*RetryExhaustedError) Unwrap 

func (e *RetryExhaustedError) Unwrap() error

type RetryInfo 

type RetryInfo struct {
	Attempt     int
	MaxAttempts int
	Delay       time.Duration
	Error       error
	RequestID   string
	// contains filtered or unexported fields
}

RetryInfo describes a retry before any provider stream event has been delivered. Error is a detached, credential-redacted observation.

func (RetryInfo) Format 

func (i RetryInfo) Format(state fmt.State, verb rune)

func (RetryInfo) GoString 

func (i RetryInfo) GoString() string

func (RetryInfo) String 

func (i RetryInfo) String() string

type Role 

type Role string

Role is a message author's Responses API role. 

const (
	RoleSystem    Role = "system"
	RoleDeveloper Role = "developer"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
)

type Stream 

type Stream interface {
	Next() (Event, error)
	Close() error
}

Stream yields provider-neutral semantic events in wire order. Next is a single-consumer operation and must not be called concurrently. Close is safe to call concurrently and is idempotent.

type StreamRedactor 

type StreamRedactor interface {
	Write(string) string
	Flush() string
}

StreamRedactor removes sensitive material from ordered text chunks. Write may retain a bounded suffix that could complete a match in a later chunk; Flush returns the final safe suffix when the stream ends.

func NewLiteralStreamRedactor 

func NewLiteralStreamRedactor(literal string) StreamRedactor

NewLiteralStreamRedactor constructs a redactor for one exact sensitive literal. It delegates to the shared primitive used by non-model egress paths.

type Tool 

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

Tool is one model-callable function schema. Parameters must encode a JSON object schema. The capability runtime remains responsible for semantic input validation and authorization after the model selects a tool.

type Usage 

type Usage struct {
	InputTokens           int64 `json:"input_tokens"`
	OutputTokens          int64 `json:"output_tokens"`
	TotalTokens           int64 `json:"total_tokens"`
	CachedInputTokens     int64 `json:"cached_input_tokens,omitempty"`
	ReasoningOutputTokens int64 `json:"reasoning_output_tokens,omitempty"`
}

Usage is cumulative for one accepted provider response.

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.