provider

Documentation

Overview

Package provider builds an OpenAI-compatible HTTP client for any configured provider. Every provider in Lightcode speaks the OpenAI API schema; the only per-provider variation is base URL, API key, and model-level options.

Index

• Variables
• func SerializeMessages(history []message.Message, target *catalog.Model, provider *catalog.Provider) ([]map[string]any, error)
• type Adapter
  • func NewAdapter(client *Client) *Adapter
  • func (a *Adapter) Chat(ctx context.Context, req modelclient.ChatRequest) (modelclient.ChatResponse, error)
  • func (a *Adapter) ChatStream(ctx context.Context, req modelclient.ChatRequest) (modelclient.ChatStream, error)
  • func (a *Adapter) Model() string
  • func (a *Adapter) ModelRef() coremodel.ModelRef
  • func (a *Adapter) ProtocolWarnings(messages []message.Message) []modelclient.ProtocolWarning
• type Client
  • func New(provider *catalog.Provider, model *catalog.Model, apiKey string) *Client
  • func (c *Client) Chat(ctx context.Context, messages []message.Message, tools []openai.Tool) (openai.ChatCompletionResponse, error)
  • func (c *Client) ChatStream(ctx context.Context, messages []message.Message, tools []openai.Tool, ...) (*Stream, error)
  • func (c *Client) Model() string
  • func (c *Client) ModelID() string
  • func (c *Client) ModelRef() coremodel.ModelRef
  • func (c *Client) ProtocolWarnings(messages []message.Message) []ProtocolWarning
• type HTTPStatusError
  • func (e *HTTPStatusError) Error() string
  • func (e *HTTPStatusError) Retryable() bool
• type ProtocolWarning
  • func ProtocolWarnings(history []message.Message, target *catalog.Model, provider *catalog.Provider) []ProtocolWarning
• type ReservedKeyError
  • func (e *ReservedKeyError) Error() string
• type Stream
  • func NewStream(body io.ReadCloser) *Stream
  • func (s *Stream) Close() error
  • func (s *Stream) Recv() (StreamChunk, error)
  • func (s *Stream) SetDebugChunkPath(path string)
• type StreamChunk
• type StreamDelta
  • func ParseChunk(raw json.RawMessage) (StreamDelta, error)

Variables

var ErrAuthFailed = errors.New("authentication failed")

ErrAuthFailed is returned on 401/403 responses.

var ErrIncompleteModel = errors.New("model is incomplete")

ErrIncompleteModel is returned when a catalog provider/model is missing.

Functions

func SerializeMessages

func SerializeMessages(history []message.Message, target *catalog.Model, provider *catalog.Provider) ([]map[string]any, error)

SerializeMessages converts canonical messages to the OpenAI-compatible message maps used in provider request bodies.

Types

type Adapter

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

Adapter exposes Client through the engine-facing modelclient interfaces.

func NewAdapter

func NewAdapter(client *Client) *Adapter

NewAdapter returns an engine-facing adapter over a concrete provider client.

func (*Adapter) Chat

func (a *Adapter) Chat(ctx context.Context, req modelclient.ChatRequest) (modelclient.ChatResponse, error)

Chat performs a non-streaming chat completion.

func (*Adapter) ChatStream

func (a *Adapter) ChatStream(ctx context.Context, req modelclient.ChatRequest) (modelclient.ChatStream, error)

ChatStream opens a parsed streaming chat completion.

func (*Adapter) Model

func (a *Adapter) Model() string

Model returns the catalog model ID string.

func (*Adapter) ModelRef

func (a *Adapter) ModelRef() coremodel.ModelRef

ModelRef returns the resolved provider/model identity.

func (*Adapter) ProtocolWarnings

func (a *Adapter) ProtocolWarnings(messages []message.Message) []modelclient.ProtocolWarning

ProtocolWarnings returns non-fatal protocol metadata diagnostics.

type Client

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

Client is a thin HTTP client that talks to an OpenAI-compatible endpoint using catalog-resolved provider and model metadata.

func New

func New(provider *catalog.Provider, model *catalog.Model, apiKey string) *Client

New returns a Client configured with catalog-resolved provider and model metadata. Construction is cheap and performs no I/O.

func (*Client) Chat

func (c *Client) Chat(ctx context.Context, messages []message.Message, tools []openai.Tool) (openai.ChatCompletionResponse, error)

Chat performs a single non-streaming chat completion request. It is kept for compaction while the rest of the runtime moves to the streaming client.

func (*Client) ChatStream

func (c *Client) ChatStream(ctx context.Context, messages []message.Message, tools []openai.Tool, runtimeExtras map[string]any) (*Stream, error)

ChatStream opens a streaming chat completion request and returns a Stream. The caller must call Stream.Close() when done.

func (*Client) Model

func (c *Client) Model() string

Model returns the catalog model ID string (alias for ModelID, kept for backward compatibility with callers that used the old interface).

func (*Client) ModelID

func (c *Client) ModelID() string

ModelID returns the catalog model ID string.

func (*Client) ModelRef

func (c *Client) ModelRef() coremodel.ModelRef

ModelRef returns the resolved provider/model identity for messages produced by this client.

func (*Client) ProtocolWarnings

func (c *Client) ProtocolWarnings(messages []message.Message) []ProtocolWarning

ProtocolWarnings returns non-fatal protocol metadata diagnostics for the next request body this client would build.

type HTTPStatusError

type HTTPStatusError struct {
	StatusCode int
	StatusText string
	Message    string
}

HTTPStatusError represents a non-2xx response from the API endpoint.

func (*HTTPStatusError) Error

func (e *HTTPStatusError) Error() string

func (*HTTPStatusError) Retryable

func (e *HTTPStatusError) Retryable() bool

Retryable returns true for 429 (rate limit) and 5xx (server) errors.

type ProtocolWarning

type ProtocolWarning = modelclient.ProtocolWarning

ProtocolWarning describes a non-fatal protocol metadata diagnostic.

func ProtocolWarnings

func ProtocolWarnings(history []message.Message, target *catalog.Model, provider *catalog.Provider) []ProtocolWarning

ProtocolWarnings returns request-build diagnostics for protocol metadata.

type ReservedKeyError

type ReservedKeyError struct {
	Keys []string
}

ReservedKeyError indicates a sidecar body contains keys owned by the request builder (model, messages, tools, etc.).

func (*ReservedKeyError) Error

func (e *ReservedKeyError) Error() string

type Stream

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

Stream wraps an HTTP response body for Server-Sent Events parsing. It yields typed chunks with the raw JSON payload and returns io.EOF on data:[DONE] or stream end.

func NewStream

func NewStream(body io.ReadCloser) *Stream

NewStream creates a Stream from a response body.

func (*Stream) Close

func (s *Stream) Close() error

Close closes the underlying response body.

func (*Stream) Recv

func (s *Stream) Recv() (StreamChunk, error)

Recv reads the next SSE event and returns it as a StreamChunk. Returns io.EOF when the stream is finished.

func (*Stream) SetDebugChunkPath

func (s *Stream) SetDebugChunkPath(path string)

SetDebugChunkPath wires a file path that each raw SSE chunk is appended to. Pass "" to disable. Used by the provider's wire-debug toggle.

type StreamChunk

type StreamChunk struct {
	Typed openai.ChatCompletionStreamResponse
	Raw   json.RawMessage
}

StreamChunk is one SSE payload decoded into the SDK type while preserving the original JSON for provider-specific metadata parsing.

type StreamDelta

type StreamDelta = modelclient.StreamDelta

StreamDelta is the provider-owned parsed view of one streaming chunk.

func ParseChunk

func ParseChunk(raw json.RawMessage) (StreamDelta, error)

ParseChunk parses one raw SSE JSON payload into canonical deltas plus provider-specific Extra captured at message, tool-call, and content scopes.