SPB Git

Repository Public MIT

PROVIDER_MATRIX.md 18.6 KB 202 lines markdown

1# ORIX Astra — Provider matrix23State of the `AstraProviders` module on 2026-11-21. Every fact below was either read in the provider's documentation that4day or observed on the provider's live API that day (marked *live*). Model metadata rules are in5`Packages/AstraProviders/Sources/CuratedCatalog.swift`; background research is in `docs/RESEARCH.md`.67All adapters share the same contract: raw `URLRequest` through the injected `HTTPTransport`; one `.messageStarted` first and8one `.messageCompleted(reason)` last; failures are thrown as a typed `AstraError` (before any event for an HTTP failure, so a9retry is safe); `Retry-After` honoured; keys read at request time and scrubbed from every error; cancelling the consumer10cancels the HTTP stream; HTTP status, request id, time to headers and retry count reported to the `DiagnosticsSink` for11generation requests.1213## Summary1415| | OpenAI | Anthropic | Google Gemini | xAI | OpenRouter | Custom endpoint |16|---|---|---|---|---|---|---|17| Type | `OpenAIProvider` | `AnthropicProvider` | `GeminiProvider` | `XAIProvider` | `OpenRouterProvider` | `OpenAICompatibleProvider` |18| API | Responses | Messages | generateContent | Responses | Chat Completions | Chat Completions |19| 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` |20| 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` |21| `verify()` | models call | models call | models call | models call | `GET /api/v1/key` (+ `/credits`) | models call |22| 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 |23| Request id read from | `x-request-id` | `request-id` | none sent | `x-request-id` | `x-generation-id` | `x-request-id` / `request-id` |24| 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` |25| 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 |2627## OpenAI2829- **Why Responses**: OpenAI recommends it over Chat Completions for text generation, and tool calling on GPT-6.2 requires it.30- **Request**: `model`, `stream: true`, `store: false`, `input` items, `instructions` (system text), `tools` (flat function31  tools, `strict: false`), `max_output_tokens`, `reasoning: {effort, summary: "auto"}`, `temperature` / `top_p` only where accepted.32  GPT-6.2 appends top-level `instructions` after `input`, so for `gpt-6.2-*` the system text is sent as a leading `developer`33  message to keep it cacheable.34- **Input items**: user message with `input_image` (data URL, `detail: "auto"`) and `input_text` parts; assistant text as a35  message; tool calls as `function_call` items (no item id); results as `function_call_output`.36- **Stream events handled**: `response.created` / `in_progress` / `queued` (identity), `response.output_text.delta`,37  `response.refusal.delta`, `response.reasoning_summary_part.added`, `response.reasoning_summary_text.delta`,38  `response.output_item.added` / `.done` (function calls), `response.function_call_arguments.delta`, `response.completed`,39  `response.incomplete`, `response.failed`, `error`. Everything else is ignored, including `response.reasoning_text.delta`:40  only the summary is ever surfaced.41- **Stop reasons**: completed → `endOfTurn` (`toolCalls` when a call was emitted, `contentFilter` after a refusal);42  incomplete `max_output_tokens` → `maxTokens`, `content_filter` → `contentFilter`.43- **Usage**: `input_tokens` (already includes cached), `input_tokens_details.cached_tokens` / `.cache_write_tokens`,44  `output_tokens`, `output_tokens_details.reasoning_tokens`.45- **Parameter handling**: models in the curated table get only what they accept (reasoning-family models never get sampling46  parameters; `gpt-6.2-*` never get `effort: "none"`). For any other model the fields are sent and, on a 400 that names an47  unsupported parameter, removed and the request retried (at most 3 adjustments). *Live*: `400 Unsupported parameter:48  'temperature' is not supported with this model` (`param: "temperature"`) on `gpt-6-luna` and `gpt-5-nano`;49  `'reasoning.effort' is not supported` on `gpt-4.1-mini`.50- **Errors**: `{"error": {"message", "type", "code", "param"}}`; the stream `error` event is flat (`code`, `message`).51- **Not implemented, deliberately**: `stop` and `seed` (the Responses API has no such parameters; they are dropped);52  replay of encrypted reasoning items between turns (the core message model has nowhere to keep them; tool cycles work53  without, *live* on `gpt-6-luna` and `gpt-6.2-sol`); server-side conversation state (`store`, `previous_response_id`);54  hosted tools; structured outputs; audio; `service_tier`; `prompt_cache_key`.55- **Sources**: https://developers.openai.com/api/docs/guides/text, `/guides/streaming-responses`, `/guides/function-calling`,56  `/guides/reasoning`, `/guides/latest-model`, `/api/reference/resources/responses/streaming-events`, `/api/docs/models`,57  `/api/docs/pricing` — read 2026-11-21. Wire format confirmed against live captures the same day.5859## Anthropic6061- **Headers**: `x-api-key`, `anthropic-version: 2026-10-21`, `content-type: application/json`.62- **Request**: `model`, `max_tokens` (the user's value, else min(model maximum, 16,000); 4,096 for an unknown model),63  `stream: true`, `system` as one text block, `messages`, `tools` (`input_schema`, `eager_input_streaming: true`),64  `stop_sequences`, `thinking`, `output_config.effort`.65- **Sampling**: never sent. API version 2026-10-21 rejects `temperature`, `top_p` and `top_k` on every model66  (*live*: `400 temperature: Extra inputs are not permitted`). Staying on `2023-06-01` to keep temperature for the 4.x models67  was considered and not done.68- **Messages**: images as base64 `image` blocks before the text; assistant turns as `text` + `tool_use`; tool results as69  `tool_result` blocks in a user turn. Consecutive turns of the same wire role are merged, so parallel results share one70  user turn and roles always alternate.71- **Thinking**, per model (table in `CuratedCatalog.swift`): adaptive with `display: "summarized"` where summaries are72  opt-in; "off" maps to `{"type": "disabled"}`, to `{"type": "between_tools"}` on Sonnet 5.5, and to effort `low` on models73  that cannot stop thinking (Fable, Opus 5.5); Haiku 4.5 / Sonnet 4.5 / Opus 4.5 use `{"type": "enabled", "budget_tokens"}`74  with `max_tokens` raised by the budget. A rejected `thinking` or `output_config` is removed and the request retried.75- **Thinking blocks are never replayed.** Earlier turns go back as text and `tool_use` only. The API accepts this inside a76  tool cycle (*live*: `claude-haiku-5-5`, `claude-sonnet-5-5`, `claude-opus-5-5`, `claude-haiku-4-5`, thinking on), and with77  nothing replayed no signature can be invalidated by the app trimming or editing history. Thinking text is surfaced only as78  the summary the API returns, as `.reasoningSummaryDelta`; `signature_delta` and `redacted_thinking` are ignored.79- **Prompt caching**: `cache_control: {"type": "ephemeral"}` on the system block when the estimated tools + system prefix80  reaches the model's minimum (512 / 1,024 / 2,048 / 4,096 tokens depending on the model).81- **Stream events handled**: `message_start`, `content_block_start` (`text`, `thinking`, `tool_use`), `content_block_delta`82  (`text_delta`, `thinking_delta`, `input_json_delta`), `content_block_stop`, `message_delta`, `message_stop`, `error`;83  `ping` and unknown events are ignored.84- **Usage**: `inputTokens` = `input_tokens` + `cache_read_input_tokens` + `cache_creation_input_tokens` (Anthropic reports85  the uncached remainder only); the two cache counts are also reported as subsets; `output_tokens_details.thinking_tokens`86  → `reasoningTokens`. `message_delta` usage is cumulative and overrides field by field.87- **Stop reasons**: `end_turn` / `pause_turn` → `endOfTurn`, `max_tokens` / `model_context_window_exceeded` → `maxTokens`,88  `tool_use` → `toolCalls`, `stop_sequence` → `stopSequence`, `refusal` → `contentFilter`.89- **Errors**: `{"type": "error", "error": {"type", "message"}, "request_id"}`; mid-stream `error` events are mapped by type90  (`overloaded_error` → overloaded, `rate_limit_error` → rate limited, …).91- **Not implemented, deliberately**: server-side refusal fallbacks (beta; they would let a different model answer than the92  one selected); 1-hour cache TTL and message-level cache breakpoints; documents / PDF input; server tools; structured93  outputs; effort levels above `high`; batch; compaction.94- **Sources**: https://platform.claude.com/docs/en/build-with-claude/streaming, `/thinking`, `/effort`, `/prompt-caching`,95  `/api/errors`, `/api/migration-2026-10-21`, `/about-claude/pricing`, and `GET /v1/models` — read 2026-11-21.9697## Google Gemini9899- **Endpoint**: native API, `streamGenerateContent?alt=sse`; the key is the `x-goog-api-key` header.100- **Request**: `systemInstruction`, `contents` with `user` / `model` roles (consecutive same-role turns merged),101  `inlineData` images, `tools[].functionDeclarations[]` with `parametersJsonSchema` (the older `parameters` field rejects102  `additionalProperties`, *live*), `generationConfig` (`maxOutputTokens`, `temperature`, `topP`, `seed`, `stopSequences`,103  `thinkingConfig`).104- **Tool cycle**: `functionCall` parts in the model turn, `functionResponse` parts (`{"result": …}` or `{"error": …}`) in105  the next user turn. Gemini 3 and later return call ids, which are used as they are; Gemini 2.5 returns none, so stable ids106  are synthesised (`gemini-call-<responseId>-<n>`) and never sent back.107- **Thought signatures**: Gemini 3 / 4 put a `thoughtSignature` on the first `functionCall` part of a turn and answer 400108  (`Function call is missing a thought_signature`) when the replay omits it (*live*). Signatures are kept in memory by call109  id and echoed verbatim; when none is known (app restarted, history from another model) the documented placeholder110  `skip_thought_signature_validator` is sent (*live*: accepted by `gemini-3.1-flash-lite`, `gemini-4-hydrogen`,111  `gemini-2.5-flash-lite`).112- **Thinking**: `includeThoughts: true` unless reasoning is off; Gemini 2.5 takes `thinkingBudget` (0 = off, 128 on 2.5113  Pro), later models take `thinkingLevel` (`minimal` for off, then `low` / `medium` / `high`). A level the model refuses is114  lowered or removed and the request retried (*live*: `gemini-4-hydrogen` rejects `minimal`). Parts with `thought: true`115  become `.reasoningSummaryDelta`; the API does not always return a summary.116- **Usage**: `promptTokenCount` (whole prompt, cached included), `cachedContentTokenCount` (subset), output =117  `candidatesTokenCount` + `thoughtsTokenCount`, with the latter also reported as `reasoningTokens`.118- **Finish reasons**: `STOP` → `endOfTurn` (`toolCalls` when calls were emitted), `MAX_TOKENS` → `maxTokens`, `SAFETY`,119  `RECITATION`, `BLOCKLIST`, `PROHIBITED_CONTENT`, `SPII`, `LANGUAGE` and the image variants → `contentFilter`; a120  `promptFeedback.blockReason` with no candidate → `contentFilter`; `MALFORMED_FUNCTION_CALL` and the like → an error.121- **Errors**: `{"error": {"code", "message", "status", "details"}}`. A bad key arrives as HTTP 400 with reason122  `API_KEY_INVALID` (*live*) and is reported as unauthorized; a `RetryInfo.retryDelay` is honoured like `Retry-After`.123- **Model list**: `inputTokenLimit`, `outputTokenLimit`, `thinking` and `supportedGenerationMethods` from the API124  (`source: .providerAPI`); models that offer `generateContent` but do not answer with text (speech, image, music, video,125  agents, embeddings) are filtered by name. Prices and vision / tools badges come from the curated table where present.126- **Not implemented, deliberately**: the newer Interactions API; context caching objects; safety settings; grounding and127  other built-in tools; audio / video / file input; structured outputs; `countTokens`.128- **Sources**: https://aistudio.google.com/docs/thinking, `/docs/thought-signatures`, `/docs/pricing`129  (ai.google.dev/gemini-api/docs/* redirects there), read 2026-11-21. The current guides describe the Interactions API, so130  the `generateContent` field names above (`thinkingConfig`, `thought`, `thoughtSignature`, `usageMetadata`,131  `parametersJsonSchema`) are confirmed by live requests that day rather than by a reference page.132133## xAI134135- **Why Responses**: xAI documents Chat Completions as a legacy endpoint; new features go to `/v1/responses`. The adapter136  shares the Responses encoder and decoder with OpenAI.137- **Differences from OpenAI** (*live*): sampling parameters are accepted; `usage.cost_in_usd_ticks` is read into138  `reportedCostUSD` (1e10 ticks per dollar, checked against the listed prices); error bodies are139  `{"code": "...", "error": "<message>"}`; a bad key arrives as HTTP 400 `Incorrect API key provided` and is reported as140  unauthorized; "model not found" messages name the team id, which is removed.141- **Reasoning**: `reasoning: {effort, summary: "auto"}`; "off" sends `effort: "none"`, and when the model refuses `none`142  (`grok-4.7`) the request is retried with `low`. Models whose id contains `non-reasoning` never get the field.143- **Model list**: `/v1/language-models` gives modalities, prices (units of 1e-4 USD per million tokens) and reasoning144  efforts; `/v1/models` gives `context_length`. Everything is `source: .providerAPI`; tools are not reported by the API and145  are therefore not badged, although they work.146- **Not implemented, deliberately**: server-side search tools, stored responses, encrypted reasoning replay, long-context147  price tiers (the listed price is the under-200k one).148- **Sources**: https://docs.x.ai/docs/models, https://docs.x.ai/docs/guides/chat-completions — read 2026-11-21. The149  Responses guide URL returned 404 that day, so the request and event shapes are confirmed by live requests.150151## OpenRouter152153- **Request**: OpenAI chat format; `max_tokens`, `temperature`, `top_p`, `seed`, `stop`, `tools`, `reasoning: {effort}`154  (`"none"` for off); routing from `RoutingPreferences`: `provider.order`, `provider.allow_fallbacks: false`,155  `provider.data_collection: "deny"`, and `models` as the fallback list. Usage is not requested: OpenRouter always sends it.156- **Stream**: `: OPENROUTER PROCESSING` comment lines are skipped; `model` and `provider` of the first chunk become157  `reportedModel` / `servedBy`; tool-call fragments are accumulated by `index`; `delta.reasoning` → `.reasoningSummaryDelta`;158  the finish reason arrives twice (once more on the usage chunk) and produces one terminal event at `[DONE]`.159- **Errors**: HTTP errors `{"error": {"code", "message", "metadata"}}`; a chunk with a top-level `error` inside a 200 stream160  (including as the only chunk) is thrown as a typed error, using its numeric code as the status.161- **Usage**: `prompt_tokens`, `completion_tokens`, cached / cache-write / reasoning details, and `usage.cost` →162  `reportedCostUSD`.163- **Model list**: `context_length`, `architecture.input_modalities` (vision, audio, files), `pricing.prompt` / `.completion`164  / cache prices (USD per token → per million; negative router prices are dropped), `supported_parameters` (→165  `ModelInfo.supportedParameters` and the tools / reasoning / structured-output badges), `top_provider.max_completion_tokens`.166  Models that do not output text are left out.167- **`verify()`**: `GET /api/v1/key`; `remainingCreditUSD` is `limit_remaining`, or `total_credits − total_usage` from168  `GET /api/v1/credits` when the key has no limit of its own.169- **Not implemented, deliberately**: replay of `reasoning_details` (tool cycles work without, *live* on Claude and Gemini170  upstreams); the Responses and Messages endpoints; `X-OpenRouter-Metadata`; provider `sort` / `only` / `ignore` / `zdr`;171  presets; the `:online` and other plugins.172- **Sources**: https://openrouter.ai/docs/api/reference/streaming, `/errors-and-debugging`,173  `/docs/guides/routing/provider-selection`, and the pages listed in `docs/RESEARCH.md` §3 — read 2026-11-21.174175## Custom OpenAI-compatible endpoint176177- `EndpointProfile.validated()` runs on every request: https only, or http with the explicit flag and a host on the local178  network; no credentials in the URL; no credential-bearing extra headers.179- Same encoder and decoder as OpenRouter, with `stream_options: {"include_usage": true}` and `reasoning_effort` for180  low / medium / high. Optional fields a server rejects are removed one at a time and the request retried181  (`stream_options`, `reasoning_effort`, `seed`, `top_p`, `temperature`, `stop`; `max_tokens` is renamed182  `max_completion_tokens` when the server asks for it).183- Tolerated server behaviours: no `[DONE]`; no tool-call ids (synthesised); `finish_reason: "stop"` after tool calls;184  `reasoning_content` instead of `reasoning`; a whole JSON completion instead of a stream; HTML error pages (never shown raw).185- Model list: ids from `data[]` / `models[]`; context and output limits and capabilities only when the endpoint reports186  them; `source: .providerAPI`, or `.user` for the model id typed in the profile. No prices.187- Verified *live* against the owner's server (`maclustr-qwen3`): list, text, tool round trip.188189## What was exercised for real on 2026-11-21190191- Smoke suite (6 adapters): `verify()`, `listModels()`, streamed text, tool-call round trip (call, result, answer),192  reasoning summary, image input (a generated red PNG, answered "Red" by all five cloud providers), rejected key.193  A real 429 ("model at capacity") from xAI was observed during the runs and mapped to `rateLimited`.194- Opt-in matrix (`ASTRA_LIVE_MATRIX=1`): one bounded request with a temperature and a reasoning effort to every chat model195  listed — OpenAI 41 (the `-pro` tier excluded), Anthropic 15, Gemini 22, xAI 7, custom 1, and 4 OpenRouter models (of 441):196  90 of 90 completed.197- 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`,198  `claude-haiku-4-5`, `claude-haiku-5-5`, `gemini-4-hydrogen`, `gemini-2.5-flash-lite`, `gemini-3.1-flash-lite`, `grok-4.7`,199  `grok-4.20-0309-non-reasoning`, and Claude and Gemini through OpenRouter.200- Not exercised live: image input on the custom endpoint; prompt-cache hits; rate-limit, quota, overload and content-filter responses (fixtures201  only); OpenAI `-pro` models; Claude Mythos models (not available to this key); the other 437 OpenRouter models.202
Files main
Menu

Theme