provider

type APIKeyDiscoveryConfig ¶

type APIKeyDiscoveryConfig struct {
	ProviderName string
	Entry        ProviderEntry
	HTTPClient   *http.Client
}

APIKeyDiscoveryConfig is the input to DiscoverAPIKeyModels. ProviderName is used only in error surface text; Entry supplies the base URL and the resolved auth header (ProviderEntry.ResolveAuthHeader); HTTPClient is an optional injection point for tests (nil uses http.DefaultClient). Timeout and cancellation are the caller's responsibility via ctx — no client-level timeout is set here.

type Adapter ¶

type Adapter struct {
	Name              string
	DefaultBaseURL    string
	DefaultAuthHeader AuthHeader
}

type AskUserQuestion ¶

type AskUserQuestion struct {
	ID          string
	Prompt      string
	Options     []string
	MultiSelect bool
	AllowCustom bool
}

AskUserQuestion and AskUserRequest are one accepted `ask_user` call. They are the single definition of what a valid call is: production dispatch maps an accepted request onto the TUI form, and /resume replay runs a saved call's raw arguments back through the same checker, so a call the live form would refuse can never render on replay.

type AskUserRequest ¶

type AskUserRequest struct {
	Context   string
	Questions []AskUserQuestion
}

func DecodeAskUserRequest(arguments string) (AskUserRequest, error)

type AuthHeader ¶

type AuthHeader struct {
	Name  string
	Value string
}

AuthHeader is the runtime form of a provider's optional auth_header object: the header name and its value template, where any {api_key} literal is substituted at resolve time.

type AuthKind ¶

type AuthKind string

AuthKind classifies how a selectable provider resolves its request credentials, so turn dispatch can pick the credential source from the provider id without re-deriving it and never attaches ChatGPT session state to a custom provider.

const (
	// AuthKindConfigured resolves credentials from provider.<name>.api_key and the
	// configured auth_header (custom OpenAI-compatible providers and OpenRouter).
	AuthKindConfigured AuthKind = "configured"
	// AuthKindPlatform is the OpenAI Platform provider: the key resolves from
	// OPENAI_API_KEY when set and non-empty, otherwise from provider.openai.api_key
	// (see [ResolvePlatformAPIKey]).
	AuthKindPlatform AuthKind = "platform"
	// AuthKindChatGPTSession is the built-in OpenAI ChatGPT provider: credentials
	// come from the stored auth.openai-chatgpt session and OPENAI_API_KEY is ignored.
	AuthKindChatGPTSession AuthKind = "chatgpt_session"
)

type Catalog ¶

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

Catalog is the merged, ordered set of selectable providers: configured providers first (in sorted provider-id order) followed by built-in selectable providers. It is read-only after BuildCatalog; its accessors return defensive copies so a caller cannot mutate the cached session view.

func BuildCatalog(configured map[string]ProviderEntry, chatGPTDiscovered []ChatGPTStoreModel, discoveredConfigured map[string][]DiscoveredConfiguredModel) Catalog

func (c Catalog) Entries() []CatalogEntry

func (c Catalog) Entry(id string) (CatalogEntry, bool)

func (c Catalog) SupportedEffort(providerID, modelID string) []string

func (c Catalog) SupportsTools(providerID, modelID string) bool

type CatalogEntry ¶

type CatalogEntry struct {
	ID          string
	DisplayName string
	Models      []string
	AuthKind    AuthKind
	Origin      ModelOrigin
	Builtin     bool
}

CatalogEntry is one selectable provider in the merged catalog: its stable provider id (persisted in model.active / model.last_used and matched at resume recovery), its human-facing display name, the selectable model id allowlist, the auth kind, the model origin, and whether it is a built-in row not read from settings. Models is in configured declaration order for configured providers and in built-in list order for built-ins. Stable provider ids — not display names — are persisted, emitted in events, and validated; display names are metadata for the picker.

type ChatGPTClientConfig ¶

type ChatGPTClientConfig struct {
	AccessToken string
	AccountID   string
	// HTTPClient is optional and lets tests point the adapter at a stub server. It
	// changes only the transport, never the pinned origin: the request
	// URL stays chatgpt.com so a test redirects with a RoundTripper, not a base-URL
	// override. Production leaves it nil; either way the adapter wraps it in a
	// redirect-pinned copy (see pinRedirects) so credentials never follow a 3xx off
	// the approved origin.
	HTTPClient *http.Client
}

ChatGPTClientConfig carries the per-turn ChatGPT credentials the adapter needs. The production wiring loads and, where needed, refreshes the stored auth.openai-chatgpt session and supplies the already-resolved access token and account id here; the adapter never reads global settings, chooses providers, or refreshes tokens itself.

type ChatGPTStoreModel ¶

type ChatGPTStoreModel struct {
	ID              string
	DisplayName     string
	ContextWindow   int64
	InputModalities []string
	Capabilities    map[string]any
}

ChatGPTStoreModel is one discovered ChatGPT model adapted to the shared discovered-model store's neutral shape: selection/capability metadata only. It is the boundary type the connect-path writer consumes so the provider package need not import internal/config (which would cycle); the CLI maps it onto the store's own record type. Capabilities carries the remaining whitelisted ChatGPT fields (reasoning levels, verbosity, …) as a generic map, so no prompt-bearing or raw-response data can ride along — chatGPTModel has no field for those.

type Classification ¶

type Classification struct {
	Phase                string
	Reason               string
	HTTPStatus           *int64
	PartialResponseChars int64
	ErrorDetail          string
}

Classification is the provider_request_failed tuple a transport, TLS decode, stream-drop, or empty-response failure maps to. Its fields line up one-to-one with events.EmitProviderRequestFailed's arguments: HTTPStatus is non-nil only for the http phase (required for http_no_body, optional for http_truncated, forbidden elsewhere); PartialResponseChars is meaningful only for stream_drop; ErrorDetail is always the diagnostic message and is never empty so the event validator accepts it.

func ClassifyEmptyCompletion(c *openai.ChatCompletion) (Classification, bool)

func ClassifyRequestError(err error) (Classification, bool)

func ClassifyStreamDrop(err error, partialResponseChars int64) Classification

func EmptyStreamClassification() Classification

func NoBodyHTTPFailure(status int64) Classification

func TruncatedHTTPFailure(status *int64) Classification

type Client ¶

type Client interface {
	ChatCompletion(ctx context.Context, req Request) (Response, error)
}

Client is codemeld's internal provider interface over chat completions, covering both the non-streaming and streaming response forms.

func NewChatGPTClient(cfg ChatGPTClientConfig) Client

func NewClient(cfg ClientConfig) Client

type ClientConfig ¶

type ClientConfig struct {
	Name          string
	BaseURL       string
	AuthHeader    string
	AuthValue     string
	Attribution   bool
	Routing       Routing
	HTTPClient    *http.Client
	MinThroughput func(ctx context.Context, model string) (float64, bool)
}

ClientConfig holds the resolved per-provider values a Client needs. AuthHeader and AuthValue are the name/value returned by ProviderEntry.ResolveAuthHeader. Name is the provider's display name, woven into the HTTP-error surface prefix. HTTPClient is optional and lets tests point the client at a stub server.

type ContentPart ¶

type ContentPart struct {
	Type     string
	Text     string
	ImageURL string
}

ContentPart is one part of a multi-part user message in the provider contract. Type is "text" or "image_url": a text part carries its text in Text, and an image_url part carries its image reference (a data: URI or a URL) in ImageURL. codemeld only synthesizes these two shapes.

type CredentialUnavailableError ¶

type CredentialUnavailableError struct {
	Surface string
}

CredentialUnavailableError is returned by a provider.Client when the selected provider has no usable credential for the turn and the turn must fail without falling back to another provider. It is a pre-request failure — no HTTP request reached the network — so it is distinct from *HTTPError and *HTTPBodyError and is never routed through the transport classifier. Surface is a safe, provider-named, credential-free remediation message the turn layer renders verbatim as the failure notice. No provider_request_failed event is emitted for it: the reason set has no auth phase and there is no transport outcome to record (the OpenAI ChatGPT wiring raises it for a missing/invalid/expired session or a failed token refresh).

func (e *CredentialUnavailableError) Error() string

type DiscoveredConfiguredModel ¶

type DiscoveredConfiguredModel struct {
	ID              string
	InputModalities []string
	Capabilities    map[string]any
}

DiscoveredConfiguredModel is one model surfaced by OpenAI-compatible /models discovery: its sanitized id plus, when the provider advertises reasoning-effort capability metadata in one of the shapes [effortShapes] declares, a whitelisted capabilities map (nil otherwise). It is what DiscoverAPIKeyModels returns and the shape BuildCatalog consumes for a configured provider's discovered models.

func DiscoverAPIKeyModels(ctx context.Context, cfg APIKeyDiscoveryConfig) ([]DiscoveredConfiguredModel, error)

func FilterPlatformDiscoveredModels(models []DiscoveredConfiguredModel) []DiscoveredConfiguredModel

type HTTPBodyError ¶

type HTTPBodyError struct {
	Status    int
	Truncated bool
	Err       error
}

HTTPBodyError reports a 2xx provider response whose body could not be consumed as a usable completion: Truncated is false when a status line arrived but the body was absent (http_no_body) and true when the body was cut off mid-transfer (http_truncated). Status is the received HTTP status line. It is the seam between the provider client (which detects the condition at the transport, the only place the status survives the SDK's body read) and the turn layer (which maps it to NoBodyHTTPFailure/TruncatedHTTPFailure and emits the event). It is distinct from *HTTPError: a non-2xx response stays on the verbatim path and never becomes an HTTPBodyError.

Err is the underlying transport read error on the streaming path, where the failure surfaces from the SSE body reader rather than a buffered read; it is exposed via Unwrap so a truncation that followed partial assistant content can still be classified as a stream_drop with its original io.EOF/ErrUnexpectedEOF fidelity. It is nil on the non-streaming path, where the status is enough.

func (e *HTTPBodyError) Error() string

func (e *HTTPBodyError) Unwrap() error

type HTTPError ¶

type HTTPError struct {
	Status  int
	Body    string
	Surface string
	// RetryAfter is the verbatim Retry-After response-header value when the
	// provider sent one (a delta-seconds count or an HTTP-date), or "" when
	// absent. It is carried — unlike the rest of the response headers, which the
	// typed error drops — so the auto-retry engine can honor a 429/503's requested
	// backoff. It is never persisted: only Body becomes the durable
	// provider_request_failed error_detail.
	RetryAfter string
}

HTTPError is a provider chat-completions response with a non-2xx HTTP status. Body holds the response body as received from the HTTP client: it is a Go string so arbitrary bytes, including invalid UTF-8 and binary payloads, can be carried to the notice path. Surface is a one-line human-readable prefix naming the provider and status followed by Body; it is the Go error text, no longer the direct on-screen TUI line — the notice path renders the friendly FriendlyHTTPMessage instead. Body is the source the friendly extractor parses. Every non-2xx status — including 429/503 quota/rate-limit responses — flows through this single path; no retry or throttle branching occurs. The turn layer persists Body through provider_request_failed{http, http_error}, where the event append layer applies UTF-8 normalization before storage, but still sends no rate-limit signal to the scheduler.

func (e *HTTPError) Error() string

type MaxPrice ¶

type MaxPrice struct {
	Prompt        float64
	Completion    float64
	HasPrompt     bool
	HasCompletion bool
}

type Message ¶

type Message struct {
	Role    string
	Content string
	// Parts carries a user message's content as an ordered list of content parts
	// (text and image_url) instead of a plain string. When non-empty on a
	// Role=="user" message it takes precedence over Content, and the message is
	// sent as a `content` array rather than a string. It is
	// ignored for every other role. The provider package stays free of a sessions
	// import: the turn package translates sessions.ContentPart into this shape.
	Parts []ContentPart
	// ToolCalls is the assistant message's tool calls. It is set only on
	// Role=="assistant" messages that requested tools; an empty list sends a plain
	// assistant message.
	ToolCalls []ToolCall
	// ToolCallID correlates a Role=="tool" result message to the assistant
	// tool-call entry it answers. It is empty for every other role.
	ToolCallID string
}

Message is one chat-completion message in codemeld's internal provider contract. Role is "system", "user", "assistant", or "tool". An assistant message that invoked tools carries them in ToolCalls; a tool-result message (Role "tool") carries the id of the assistant tool-call entry it answers in ToolCallID, so the OpenAI-compatible tool-call continuation round-trips back to the provider.

type ModelOrigin ¶

type ModelOrigin string

ModelOrigin records non-overridable provenance for a built-in provider's models. It is catalog metadata only and is empty for configured providers.

const (
	// OriginNone is the origin of a configured provider's models (no built-in
	// provenance).
	OriginNone ModelOrigin = ""
	// OriginChatGPTCodex marks the OpenAI ChatGPT provider's models as served by the
	// ChatGPT/Codex flow, not the OpenAI Platform chat-completions surface.
	OriginChatGPTCodex ModelOrigin = "chatgpt-codex"
)

type OpenRouterEndpointStore ¶

type OpenRouterEndpointStore struct {
	HTTPClient *http.Client
	Now        func() time.Time
	// contains filtered or unexported fields
}

func (s *OpenRouterEndpointStore) Estimate(entry ProviderEntry, authName, authValue, model, sortMode string, fetched func()) (OpenRouterEstimate, bool)

func (s *OpenRouterEndpointStore) SpeedBar(ctx context.Context, entry ProviderEntry, authName, authValue, model string) (float64, bool)

type OpenRouterEstimate ¶

type OpenRouterEstimate struct {
	PromptPerM     float64
	CompletionPerM float64
	Discount       float64
}

type ProviderEntry ¶

type ProviderEntry struct {
	BaseURL    string
	APIKey     string
	AuthHeader *AuthHeader
	Routing    Routing
}

ProviderEntry is the runtime form of one provider.<name> config entry. APIKey is held in plaintext at runtime. AuthHeader is non-nil after ParseProviders, carrying the configured header or the Bearer default.

func (p ProviderEntry) ResolveAuthHeader() (name, value string)

type Request ¶

type Request struct {
	Model            string
	Messages         []Message
	Effort           string
	Stream           bool
	Tools            []ToolDefinition
	PromptCacheKey   string
	IgnoredProviders []string
}

Request is one chat-completion call. Effort is sent unchanged when non-empty; an empty value omits the reasoning parameter. Stream selects the streaming response form. Tools is the turn's mode-filtered advertised tool set: when non-empty ChatCompletion sends it as `tools` with automatic tool choice; when empty it sends neither field. The request builder owns assembling and mode-filtering this set — ChatCompletion never inspects the registry or mode state.

type Response ¶

type Response struct {
	Completion *openai.ChatCompletion
	Stream     *ssestream.Stream[openai.ChatCompletionChunk]
}

Response carries the result of a ChatCompletion call in exactly one form: for a non-streaming request Completion is set and Stream is nil; for a streaming request Stream is set and Completion is nil. The OpenAI chat-completions shape is codemeld's internal provider contract, so the openai-go result types are surfaced directly.

type Routing ¶

type Routing struct {
	Sort              string
	DataCollection    string
	RequireParameters bool
	MaxPrice          map[string]MaxPrice
}

type RoutingExhaustionError ¶

type RoutingExhaustionError struct {
	Model              string
	MaxPrice           MaxPrice
	DataCollectionDeny bool
	RequireParameters  bool
	Ignore             []string
	HTTP               *HTTPError
}

func (e *RoutingExhaustionError) Error() string

func (e *RoutingExhaustionError) Unwrap() error

type ToolCall ¶

type ToolCall struct {
	ID        string
	Name      string
	Arguments string
}

ToolCall is one OpenAI-compatible function tool call carried on an assistant provider message. Arguments is the raw JSON-encoded arguments string as the model produced it (phase 1 supports only the "function" tool-call type).

type ToolDefinition ¶

type ToolDefinition struct {
	Name        string
	Description string
	Parameters  map[string]any
}

ToolDefinition is one advertised tool in codemeld's internal provider contract: a stable Name (a registry name such as `vcs_commit`, or the pinned `bash`), a one-line Description the model reads to choose when to call it, and Parameters — a JSON-Schema object in the OpenAI function-tool shape describing the call's arguments. It is provider-agnostic so request builders assemble it without importing any provider SDK; ChatCompletion maps it onto the openai-go function tool. A nil Parameters advertises a function with no parameters.

func AskUserToolDefinition() ToolDefinition

func BashToolDefinition() ToolDefinition

func SuggestFollowupToolDefinition() ToolDefinition