SPB Git

Repository Public MIT

PROVIDER_MATRIX.md 18.6 KB

# ORIX Astra — Provider matrix

State of the AstraProviders module on 2026-11-21. Every fact below was either read in the provider's documentation that day or observed on the provider's live API that day (marked live). Model metadata rules are in Packages/AstraProviders/Sources/CuratedCatalog.swift; background research is in docs/RESEARCH.md.

All adapters share the same contract: raw URLRequest through the injected HTTPTransport; one .messageStarted first and one .messageCompleted(reason) last; failures are thrown as a typed AstraError (before any event for an HTTP failure, so a retry is safe); Retry-After honoured; keys read at request time and scrubbed from every error; cancelling the consumer cancels the HTTP stream; HTTP status, request id, time to headers and retry count reported to the DiagnosticsSink for generation requests.

# Summary

OpenAI Anthropic Google Gemini xAI OpenRouter Custom endpoint
Type OpenAIProvider AnthropicProvider GeminiProvider XAIProvider OpenRouterProvider OpenAICompatibleProvider
API Responses Messages generateContent Responses Chat Completions Chat Completions
Generation POST /v1/responses POST /v1/messages POST /v1beta/models/{id}:streamGenerateContent?alt=sse POST /v1/responses POST /api/v1/chat/completions POST {base}/chat/completions
Models GET /v1/models GET /v1/models?limit=1000 (paged) GET /v1beta/models?pageSize=1000 (paged) GET /v1/language-models + GET /v1/models GET /api/v1/models GET {base}/models
verify() models call models call models call models call GET /api/v1/key (+ /credits) models call
Auth Authorization: Bearer x-api-key + anthropic-version: 2026-10-21 x-goog-api-key (never in the URL) Authorization: Bearer Authorization: Bearer + HTTP-Referer, X-Title, X-OpenRouter-Title Authorization: Bearer if a key is set, plus the profile's extra headers
Request id read from x-request-id request-id none sent x-request-id x-generation-id x-request-id / request-id
Metadata source curated table (docs) or .providerAPI with text only curated table + API limits API limits + curated prices API (modalities, prices, efforts) API API or .user
Live test model gpt-6-luna claude-haiku-5-5 gemini-3.1-flash-lite grok-4.3 openai/gpt-6-luna first listed model

# OpenAI

  • Why Responses: OpenAI recommends it over Chat Completions for text generation, and tool calling on GPT-6.2 requires it.
  • Request: model, stream: true, store: false, input items, instructions (system text), tools (flat function tools, strict: false), max_output_tokens, reasoning: {effort, summary: "auto"}, temperature / top_p only where accepted. GPT-6.2 appends top-level instructions after input, so for gpt-6.2-* the system text is sent as a leading developer message to keep it cacheable.
  • Input items: user message with input_image (data URL, detail: "auto") and input_text parts; assistant text as a message; tool calls as function_call items (no item id); results as function_call_output.
  • Stream events handled: response.created / in_progress / queued (identity), response.output_text.delta, response.refusal.delta, response.reasoning_summary_part.added, response.reasoning_summary_text.delta, response.output_item.added / .done (function calls), response.function_call_arguments.delta, response.completed, response.incomplete, response.failed, error. Everything else is ignored, including response.reasoning_text.delta: only the summary is ever surfaced.
  • Stop reasons: completed → endOfTurn (toolCalls when a call was emitted, contentFilter after a refusal); incomplete max_output_tokens → maxTokens, content_filter → contentFilter.
  • Usage: input_tokens (already includes cached), input_tokens_details.cached_tokens / .cache_write_tokens, output_tokens, output_tokens_details.reasoning_tokens.
  • Parameter handling: models in the curated table get only what they accept (reasoning-family models never get sampling parameters; gpt-6.2-* never get effort: "none"). For any other model the fields are sent and, on a 400 that names an unsupported parameter, removed and the request retried (at most 3 adjustments). Live: 400 Unsupported parameter: 'temperature' is not supported with this model (param: "temperature") on gpt-6-luna and gpt-5-nano; 'reasoning.effort' is not supported on gpt-4.1-mini.
  • Errors: {"error": {"message", "type", "code", "param"}}; the stream error event is flat (code, message).
  • Not implemented, deliberately: stop and seed (the Responses API has no such parameters; they are dropped); replay of encrypted reasoning items between turns (the core message model has nowhere to keep them; tool cycles work without, live on gpt-6-luna and gpt-6.2-sol); server-side conversation state (store, previous_response_id); hosted tools; structured outputs; audio; service_tier; prompt_cache_key.
  • Sources: https://developers.openai.com/api/docs/guides/text, /guides/streaming-responses, /guides/function-calling, /guides/reasoning, /guides/latest-model, /api/reference/resources/responses/streaming-events, /api/docs/models, /api/docs/pricing — read 2026-11-21. Wire format confirmed against live captures the same day.

# Anthropic

  • Headers: x-api-key, anthropic-version: 2026-10-21, content-type: application/json.
  • Request: model, max_tokens (the user's value, else min(model maximum, 16,000); 4,096 for an unknown model), stream: true, system as one text block, messages, tools (input_schema, eager_input_streaming: true), stop_sequences, thinking, output_config.effort.
  • Sampling: never sent. API version 2026-10-21 rejects temperature, top_p and top_k on every model (live: 400 temperature: Extra inputs are not permitted). Staying on 2023-06-01 to keep temperature for the 4.x models was considered and not done.
  • Messages: images as base64 image blocks before the text; assistant turns as text + tool_use; tool results as tool_result blocks in a user turn. Consecutive turns of the same wire role are merged, so parallel results share one user turn and roles always alternate.
  • Thinking, per model (table in CuratedCatalog.swift): adaptive with display: "summarized" where summaries are opt-in; "off" maps to {"type": "disabled"}, to {"type": "between_tools"} on Sonnet 5.5, and to effort low on models that cannot stop thinking (Fable, Opus 5.5); Haiku 4.5 / Sonnet 4.5 / Opus 4.5 use {"type": "enabled", "budget_tokens"} with max_tokens raised by the budget. A rejected thinking or output_config is removed and the request retried.
  • Thinking blocks are never replayed. Earlier turns go back as text and tool_use only. The API accepts this inside a tool cycle (live: claude-haiku-5-5, claude-sonnet-5-5, claude-opus-5-5, claude-haiku-4-5, thinking on), and with nothing replayed no signature can be invalidated by the app trimming or editing history. Thinking text is surfaced only as the summary the API returns, as .reasoningSummaryDelta; signature_delta and redacted_thinking are ignored.
  • Prompt caching: cache_control: {"type": "ephemeral"} on the system block when the estimated tools + system prefix reaches the model's minimum (512 / 1,024 / 2,048 / 4,096 tokens depending on the model).
  • Stream events handled: message_start, content_block_start (text, thinking, tool_use), content_block_delta (text_delta, thinking_delta, input_json_delta), content_block_stop, message_delta, message_stop, error; ping and unknown events are ignored.
  • Usage: inputTokens = input_tokens + cache_read_input_tokens + cache_creation_input_tokens (Anthropic reports the uncached remainder only); the two cache counts are also reported as subsets; output_tokens_details.thinking_tokens → reasoningTokens. message_delta usage is cumulative and overrides field by field.
  • Stop reasons: end_turn / pause_turn → endOfTurn, max_tokens / model_context_window_exceeded → maxTokens, tool_use → toolCalls, stop_sequence → stopSequence, refusal → contentFilter.
  • Errors: {"type": "error", "error": {"type", "message"}, "request_id"}; mid-stream error events are mapped by type (overloaded_error → overloaded, rate_limit_error → rate limited, …).
  • Not implemented, deliberately: server-side refusal fallbacks (beta; they would let a different model answer than the one selected); 1-hour cache TTL and message-level cache breakpoints; documents / PDF input; server tools; structured outputs; effort levels above high; batch; compaction.
  • Sources: https://platform.claude.com/docs/en/build-with-claude/streaming, /thinking, /effort, /prompt-caching, /api/errors, /api/migration-2026-10-21, /about-claude/pricing, and GET /v1/models — read 2026-11-21.

# Google Gemini

  • Endpoint: native API, streamGenerateContent?alt=sse; the key is the x-goog-api-key header.
  • Request: systemInstruction, contents with user / model roles (consecutive same-role turns merged), inlineData images, tools[].functionDeclarations[] with parametersJsonSchema (the older parameters field rejects additionalProperties, live), generationConfig (maxOutputTokens, temperature, topP, seed, stopSequences, thinkingConfig).
  • Tool cycle: functionCall parts in the model turn, functionResponse parts ({"result": …} or {"error": …}) in the next user turn. Gemini 3 and later return call ids, which are used as they are; Gemini 2.5 returns none, so stable ids are synthesised (gemini-call-<responseId>-<n>) and never sent back.
  • Thought signatures: Gemini 3 / 4 put a thoughtSignature on the first functionCall part of a turn and answer 400 (Function call is missing a thought_signature) when the replay omits it (live). Signatures are kept in memory by call id and echoed verbatim; when none is known (app restarted, history from another model) the documented placeholder skip_thought_signature_validator is sent (live: accepted by gemini-3.1-flash-lite, gemini-4-hydrogen, gemini-2.5-flash-lite).
  • Thinking: includeThoughts: true unless reasoning is off; Gemini 2.5 takes thinkingBudget (0 = off, 128 on 2.5 Pro), later models take thinkingLevel (minimal for off, then low / medium / high). A level the model refuses is lowered or removed and the request retried (live: gemini-4-hydrogen rejects minimal). Parts with thought: true become .reasoningSummaryDelta; the API does not always return a summary.
  • Usage: promptTokenCount (whole prompt, cached included), cachedContentTokenCount (subset), output = candidatesTokenCount + thoughtsTokenCount, with the latter also reported as reasoningTokens.
  • Finish reasons: STOP → endOfTurn (toolCalls when calls were emitted), MAX_TOKENS → maxTokens, SAFETY, RECITATION, BLOCKLIST, PROHIBITED_CONTENT, SPII, LANGUAGE and the image variants → contentFilter; a promptFeedback.blockReason with no candidate → contentFilter; MALFORMED_FUNCTION_CALL and the like → an error.
  • Errors: {"error": {"code", "message", "status", "details"}}. A bad key arrives as HTTP 400 with reason API_KEY_INVALID (live) and is reported as unauthorized; a RetryInfo.retryDelay is honoured like Retry-After.
  • Model list: inputTokenLimit, outputTokenLimit, thinking and supportedGenerationMethods from the API (source: .providerAPI); models that offer generateContent but do not answer with text (speech, image, music, video, agents, embeddings) are filtered by name. Prices and vision / tools badges come from the curated table where present.
  • Not implemented, deliberately: the newer Interactions API; context caching objects; safety settings; grounding and other built-in tools; audio / video / file input; structured outputs; countTokens.
  • Sources: https://aistudio.google.com/docs/thinking, /docs/thought-signatures, /docs/pricing (ai.google.dev/gemini-api/docs/* redirects there), read 2026-11-21. The current guides describe the Interactions API, so the generateContent field names above (thinkingConfig, thought, thoughtSignature, usageMetadata, parametersJsonSchema) are confirmed by live requests that day rather than by a reference page.

# xAI

  • Why Responses: xAI documents Chat Completions as a legacy endpoint; new features go to /v1/responses. The adapter shares the Responses encoder and decoder with OpenAI.
  • Differences from OpenAI (live): sampling parameters are accepted; usage.cost_in_usd_ticks is read into reportedCostUSD (1e10 ticks per dollar, checked against the listed prices); error bodies are {"code": "...", "error": "<message>"}; a bad key arrives as HTTP 400 Incorrect API key provided and is reported as unauthorized; "model not found" messages name the team id, which is removed.
  • Reasoning: reasoning: {effort, summary: "auto"}; "off" sends effort: "none", and when the model refuses none (grok-4.7) the request is retried with low. Models whose id contains non-reasoning never get the field.
  • Model list: /v1/language-models gives modalities, prices (units of 1e-4 USD per million tokens) and reasoning efforts; /v1/models gives context_length. Everything is source: .providerAPI; tools are not reported by the API and are therefore not badged, although they work.
  • Not implemented, deliberately: server-side search tools, stored responses, encrypted reasoning replay, long-context price tiers (the listed price is the under-200k one).
  • Sources: https://docs.x.ai/docs/models, https://docs.x.ai/docs/guides/chat-completions — read 2026-11-21. The Responses guide URL returned 404 that day, so the request and event shapes are confirmed by live requests.

# OpenRouter

  • Request: OpenAI chat format; max_tokens, temperature, top_p, seed, stop, tools, reasoning: {effort} ("none" for off); routing from RoutingPreferences: provider.order, provider.allow_fallbacks: false, provider.data_collection: "deny", and models as the fallback list. Usage is not requested: OpenRouter always sends it.
  • Stream: : OPENROUTER PROCESSING comment lines are skipped; model and provider of the first chunk become reportedModel / servedBy; tool-call fragments are accumulated by index; delta.reasoning → .reasoningSummaryDelta; the finish reason arrives twice (once more on the usage chunk) and produces one terminal event at [DONE].
  • Errors: HTTP errors {"error": {"code", "message", "metadata"}}; a chunk with a top-level error inside a 200 stream (including as the only chunk) is thrown as a typed error, using its numeric code as the status.
  • Usage: prompt_tokens, completion_tokens, cached / cache-write / reasoning details, and usage.cost → reportedCostUSD.
  • Model list: context_length, architecture.input_modalities (vision, audio, files), pricing.prompt / .completion / cache prices (USD per token → per million; negative router prices are dropped), supported_parameters (→ ModelInfo.supportedParameters and the tools / reasoning / structured-output badges), top_provider.max_completion_tokens. Models that do not output text are left out.
  • verify(): GET /api/v1/key; remainingCreditUSD is limit_remaining, or total_credits − total_usage from GET /api/v1/credits when the key has no limit of its own.
  • Not implemented, deliberately: replay of reasoning_details (tool cycles work without, live on Claude and Gemini upstreams); the Responses and Messages endpoints; X-OpenRouter-Metadata; provider sort / only / ignore / zdr; presets; the :online and other plugins.
  • Sources: https://openrouter.ai/docs/api/reference/streaming, /errors-and-debugging, /docs/guides/routing/provider-selection, and the pages listed in docs/RESEARCH.md §3 — read 2026-11-21.

# Custom OpenAI-compatible endpoint

  • EndpointProfile.validated() runs on every request: https only, or http with the explicit flag and a host on the local network; no credentials in the URL; no credential-bearing extra headers.
  • Same encoder and decoder as OpenRouter, with stream_options: {"include_usage": true} and reasoning_effort for low / medium / high. Optional fields a server rejects are removed one at a time and the request retried (stream_options, reasoning_effort, seed, top_p, temperature, stop; max_tokens is renamed max_completion_tokens when the server asks for it).
  • Tolerated server behaviours: no [DONE]; no tool-call ids (synthesised); finish_reason: "stop" after tool calls; reasoning_content instead of reasoning; a whole JSON completion instead of a stream; HTML error pages (never shown raw).
  • Model list: ids from data[] / models[]; context and output limits and capabilities only when the endpoint reports them; source: .providerAPI, or .user for the model id typed in the profile. No prices.
  • Verified live against the owner's server (maclustr-qwen3): list, text, tool round trip.

# What was exercised for real on 2026-11-21

  • Smoke suite (6 adapters): verify(), listModels(), streamed text, tool-call round trip (call, result, answer), reasoning summary, image input (a generated red PNG, answered "Red" by all five cloud providers), rejected key. A real 429 ("model at capacity") from xAI was observed during the runs and mapped to rateLimited.
  • Opt-in matrix (ASTRA_LIVE_MATRIX=1): one bounded request with a temperature and a reasoning effort to every chat model listed — OpenAI 41 (the -pro tier excluded), Anthropic 15, Gemini 22, xAI 7, custom 1, and 4 OpenRouter models (of 441): 90 of 90 completed.
  • Tool round trip with reasoning on: gpt-6.2-sol, gpt-4.1-mini, claude-sonnet-5-5 (low and off), claude-opus-5-5, claude-haiku-4-5, claude-haiku-5-5, gemini-4-hydrogen, gemini-2.5-flash-lite, gemini-3.1-flash-lite, grok-4.7, grok-4.20-0309-non-reasoning, and Claude and Gemini through OpenRouter.
  • Not exercised live: image input on the custom endpoint; prompt-cache hits; rate-limit, quota, overload and content-filter responses (fixtures only); OpenAI -pro models; Claude Mythos models (not available to this key); the other 437 OpenRouter models.
Files main
Menu

Theme