model

package
v0.1.0-preview.7 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package model owns provider-neutral request, stream, and provider SPIs.

@import { NamedInterface } from "github.com/spice-framework/spice/annotation/modulith" @NamedInterface("model")

Index

Constants

View Source 
const (
	// MaximumTextDeltaBytes bounds one provider stream text item.
	MaximumTextDeltaBytes = 256 << 10
	// MaximumOperationTextBytes bounds all text observed in one operation.
	MaximumOperationTextBytes = 4 << 20
	// MaximumOperationToolCalls bounds all calls observed in one operation.
	MaximumOperationToolCalls = 128
)

Variables

This section is empty.

Functions

func RequireCompletion 

func RequireCompletion(err error, terminal bool) error

RequireCompletion converts premature EOF into a contract error.

Types

type EventKind 

type EventKind string

EventKind identifies a model stream item. 

const (
	EventTextDelta EventKind = "text_delta"
	EventToolCall  EventKind = "tool_call"
	EventCompleted EventKind = "completed"
	EventFailed    EventKind = "failed"
)

type Metadata 

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

Metadata is one provider-neutral, namespaced, immutable JSON value. Provider adapters may expose safe response identity and service metadata, but must never include credentials, authorization values, prompts, or other secrets.

func NewMetadata 

func NewMetadata(namespace string, value json.RawMessage) (Metadata, error)

NewMetadata validates and defensively copies one namespaced JSON value.

func (Metadata) Clone 

func (metadata Metadata) Clone() Metadata

func (Metadata) Namespace 

func (metadata Metadata) Namespace() string

func (Metadata) Validate 

func (metadata Metadata) Validate() error

func (Metadata) Value 

func (metadata Metadata) Value() json.RawMessage

type OperationError 

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

OperationError is a host-observed model failure. BeforeStream is computed by the engine and cannot be asserted by a provider.

func NewOperationError 

func NewOperationError(problem Problem, observed bool, cause error) (*OperationError, error)

NewOperationError records whether any stream item was already observable.

func (*OperationError) BeforeStream 

func (failure *OperationError) BeforeStream() bool

BeforeStream reports host-observed retry position.

func (*OperationError) Error 

func (failure *OperationError) Error() string

func (*OperationError) Problem 

func (failure *OperationError) Problem() Problem

Problem returns typed metadata.

func (*OperationError) Retryable 

func (failure *OperationError) Retryable() bool

Retryable reports safe retry only when the provider permits it and no stream item was observed by the host.

func (*OperationError) Unwrap 

func (failure *OperationError) Unwrap() error

type OperationID 

type OperationID string

OperationID identifies one provider request for tracing and idempotency.

type Problem 

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

Problem is immutable provider-neutral typed failure metadata.

func NewProblem 

func NewProblem(code, problemMessage string, retryable bool, metadata ...Metadata) (Problem, error)

NewProblem validates one provider failure.

func (Problem) Code 

func (problem Problem) Code() string

Code returns the stable failure category.

func (Problem) Message 

func (problem Problem) Message() string

Message returns safe provider-neutral detail.

func (Problem) Metadata 

func (problem Problem) Metadata() []Metadata

Metadata returns defensive provider extension metadata.

func (Problem) Retryable 

func (problem Problem) Retryable() bool

Retryable reports provider-declared retry safety. The host additionally requires that no stream item was observed.

func (Problem) Validate 

func (problem Problem) Validate() error

Validate rejects a zero or corrupted problem.

type Provider 

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

Provider starts one model operation. Implementations must be safe for concurrent calls and must not retry after any stream item is observable. Cancellation is cooperative for trusted in-process implementations.

type ProviderError 

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

ProviderError preserves a typed failure returned before a stream exists.

func NewProviderError 

func NewProviderError(problem Problem, cause error) (*ProviderError, error)

NewProviderError constructs a typed provider-start failure.

func (*ProviderError) Error 

func (failure *ProviderError) Error() string

Error implements error.

func (*ProviderError) Problem 

func (failure *ProviderError) Problem() Problem

Problem returns immutable typed metadata.

func (*ProviderError) Unwrap 

func (failure *ProviderError) Unwrap() error

Unwrap returns the provider-owned cause, which must not contain secrets.

type Request 

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

Request is an immutable snapshot of one model operation.

func NewRequest 

func NewRequest(operationID OperationID, modelName string, messages []message.Message, tools []tool.Definition) (Request, error)

NewRequest validates and copies one provider request.

func (Request) Messages 

func (request Request) Messages() []message.Message

Messages returns a defensive copy of immutable messages.

func (Request) Model 

func (request Request) Model() string

Model returns the selected provider model name. It is the authoritative model selection; provider configuration owns transport defaults, not model choice.

func (Request) OperationID 

func (request Request) OperationID() OperationID

OperationID returns the provider operation identity.

func (Request) Tools 

func (request Request) Tools() []tool.Definition

Tools returns deep defensive copies.

type Stream 

type Stream interface {
	Recv(context.Context) (StreamEvent, error)
	Close() error
}

Stream supplies ordered model events. Recv returns io.EOF only after a valid completed or failed event has already been returned.

type StreamError 

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

StreamError preserves a typed provider failure returned by Stream.Recv. Retry position is host-observed and is not supplied by this value.

func NewStreamError 

func NewStreamError(problem Problem, cause error) (*StreamError, error)

NewStreamError constructs a typed provider stream failure.

func (*StreamError) Error 

func (failure *StreamError) Error() string

func (*StreamError) Problem 

func (failure *StreamError) Problem() Problem

Problem returns immutable typed metadata.

func (*StreamError) Unwrap 

func (failure *StreamError) Unwrap() error

type StreamEvent 

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

StreamEvent is an immutable strict tagged union.

func Completed 

func Completed(usage Usage, metadata ...Metadata) (StreamEvent, error)

Completed constructs one terminal success event.

func Failed 

func Failed(problem Problem) (StreamEvent, error)

Failed constructs one terminal failure event.

func TextDelta 

func TextDelta(text string) (StreamEvent, error)

TextDelta constructs one bounded text event.

func ToolCallEvent 

func ToolCallEvent(call tool.Call) (StreamEvent, error)

ToolCallEvent constructs one tool-call event.

func (StreamEvent) Call 

func (streamEvent StreamEvent) Call() (tool.Call, bool)

Call returns a defensive call and whether the event is a tool call.

func (StreamEvent) Kind 

func (streamEvent StreamEvent) Kind() EventKind

Kind returns the discriminator.

func (StreamEvent) Metadata 

func (streamEvent StreamEvent) Metadata() ([]Metadata, bool)

Metadata returns success metadata for completed events. Failed-event metadata is carried by Problem.Metadata.

func (StreamEvent) Problem 

func (streamEvent StreamEvent) Problem() (Problem, bool)

Problem returns failure metadata and whether the event failed.

func (StreamEvent) Text 

func (streamEvent StreamEvent) Text() (string, bool)

Text returns text and whether the event is a text delta.

func (StreamEvent) Usage 

func (streamEvent StreamEvent) Usage() (Usage, bool)

Usage returns accounting and whether the event completed successfully.

func (StreamEvent) Validate 

func (streamEvent StreamEvent) Validate() error

Validate reconstructs the active union member and rejects zero/corruption.

type Usage 

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

Usage contains provider-normalized token accounting. Zero means unknown.

func NewUsage 

func NewUsage(inputTokens, outputTokens uint64) Usage

NewUsage constructs token accounting.

func (Usage) InputTokens 

func (usage Usage) InputTokens() uint64

InputTokens returns provider input-token usage.

func (Usage) OutputTokens 

func (usage Usage) OutputTokens() uint64

OutputTokens returns provider output-token usage.

func (Usage) TotalTokens 

func (usage Usage) TotalTokens() uint64

TotalTokens returns the overflow-safe sum, saturating at uint64 maximum.

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.