# PROVIDER-REUSE.md — Zyquo Router

Study of the Zyquo Cloud repository (../zyquo-cloud) for provider-layer reuse.

Source repo studied: /Users/simon-pierreboucher/Desktop/zyquo-cloud (Swift 5.9 SPM executable, macOS 13+, single dependency swift-markdown — see Package.swift:12-39). Catalog and research were compiled/verified by Cloud with live keys on 2026-07-30 (docs/PROVIDERS.md:8-13, Phase 7 amendments at docs/PROVIDERS.md:1638-1719). Every claim below is traceable to a file/line in that repo.

# 1. How each provider's API is called in Zyquo Cloud

# 1.1 Architecture — two clients, one registry

Cloud's entire provider layer is four files in Sources/ZyquoCloud/Providers/ plus one shared networking service:

There is NO GeminiClient.swift in Zyquo Cloud. Gemini is driven through its OpenAI-compatible endpoint https://generativelanguage.googleapis.com/v1beta/openai with Bearer auth (Sources/ZyquoCloud/Models/ProviderID.swift:64), through OpenAICompatibleClient like the other OpenAI-shaped providers. Cloud's research notes the compat endpoint's limitations and that a native client would be needed for rich thinking display (docs/PROVIDERS.md:560), but Cloud shipped compat-only. Zyquo Router's CLAUDE.md assumes a native GeminiClient exists — it does not; the Router must either keep the compat path (near-pass-through, easiest) or write the native translator itself per Phase 0.A research (see §5 caveats).

The protocol (ProviderProtocol.swift:31-42):

protocol ProviderClient {
    var providerID: ProviderID { get }
    func streamChat(_ request: ChatRequest, apiKey: String) -> AsyncThrowingStream<ChatEvent, Error>
    func complete(_ request: ChatRequest, apiKey: String) async throws -> Message
    func listModelIDs(apiKey: String) async throws -> [String]
}

The provider-agnostic request/event types (ProviderProtocol.swift:13-28):

struct ChatRequest {
    var model: AIModel
    var systemPrompt: String?
    var messages: [Message]
    var parameters: ChatParameters
    var stream: Bool = true
}
enum ChatEvent {
    case reasoningDelta(String)
    case textDelta(String)
    case citations([Citation])
    case usage(TokenUsage)
    case finished(reason: String?)
}

A default-protocol extension provides testKey(_:fallbackModel:) async throws -> TimeInterval (ProviderProtocol.swift:49-68): calls listModelIDs where available, else a 16-token "Reply with exactly: OK" completion (Perplexity has no /models — returns 404, ProviderID.swift:77-79, docs/PROVIDERS.md:27).

ProviderRegistry (ProviderRegistry.swift:13-34) resolves clients purely from ProviderID.wireFormat:

switch model.provider.wireFormat {
case .anthropicMessages:      return AnthropicClient()
case .openAIChatCompletions:  return OpenAICompatibleClient(provider: model.provider,
                                                            baseURLOverride: model.customBaseURL)
}

WireFormat has exactly two cases (ProviderID.swift:88-93): .openAIChatCompletions (11/12 providers) and .anthropicMessages.

# 1.2 Provider identity, base URLs, auth

ProviderID is a 13-case enum (Sources/ZyquoCloud/Models/ProviderID.swift:12-25): openai, anthropic, xai, mistral, gemini, qwen, deepseek, kimi, perplexity, together, deepinfra, cerebras, custom. Exact defaultBaseURL constants (ProviderID.swift:58-74):

Paths are appended with base.appendingPathComponent(path) so multi-segment bases (…/compatible-mode/v1, …/v1beta/openai) are preserved (OpenAICompatibleClient.swift:229-241). Chat endpoint path is "chat/completions"; Anthropic's is "messages". Anthropic constants: apiVersion = "2023-06-01", defaultMaxTokens = 8192 (AnthropicClient.swift:19-20).

# 1.3 OpenAICompatibleClient — request/response wire types

All wire types are private nested Codable structs (an adaptation point for the Router — see §5).

Request (OpenAICompatibleClient.swift:28-103) — WireRequest: model, messages: [WireMessage], stream, streamOptions (stream_options.include_usage), temperature, topP (top_p), maxTokens (max_tokens), maxCompletionTokens (max_completion_tokens), frequencyPenalty, presencePenalty, reasoningEffort (reasoning_effort), enableThinking (enable_thinking). WireMessage { role: String, content: WireContent }; WireContent encodes either a plain string or [WirePart] where WirePart is .text(String) or .imageURL(String) (encoded as {"type":"image_url","image_url":{"url":"data:<mime>;base64,…"}}). Images are always sent as base64 data URIs (OpenAICompatibleClient.swift:302-320).

Body construction (buildBody(_:), OpenAICompatibleClient.swift:257-300) is gated by the model's ParameterSupport (see §2): only supported params are encoded. Notable per-provider logic:

• wantsStreamOptions (OpenAICompatibleClient.swift:243-255): stream_options:{include_usage:true} sent to openai, xai, gemini, deepseek, kimi, together, cerebras, custom; omitted for mistral (rejects unknown params), qwen, deepinfra, perplexity (usage arrives automatically).
• Mistral reasoning_effort only accepts "high"/"none" → client maps low → none, else high (OpenAICompatibleClient.swift:286-293; docs/PROVIDERS.md:1703).
• Qwen/DashScope enable_thinking is only legal on streaming requests (OpenAICompatibleClient.swift:294-297).
• usesMaxCompletionTokens switches max_tokens → max_completion_tokens (OpenAI reasoning models, Cerebras, Kimi K-series) (OpenAICompatibleClient.swift:277-283).
• System prompt injected as a leading {"role":"system"} message (OpenAICompatibleClient.swift:259-261).
• Text-file attachments are inlined into the message text fenced with the file name (OpenAICompatibleClient.swift:306-309).

Response (OpenAICompatibleClient.swift:107-223) — decoded with plain JSONDecoder, unknown fields ignored:

• WireChunk { choices: [WireChoice]?, usage: WireUsage?, citations: [String]?, searchResults: [WireSearchResult]? } (search_results = Perplexity).
• WireChoice { delta: WireDelta?, message: WireDelta?, text: String?, finishReason: String? } — the same struct decodes both streaming chunks (delta) and non-streaming responses (message); text is the Together completions-style fallback (choices[].text instead of delta.content, OpenAICompatibleClient.swift:119-131; docs/PROVIDERS.md:1712-1713).
• WireDelta { content, reasoningContent ("reasoning_content"), reasoning } with a custom init(from:) (OpenAICompatibleClient.swift:143-167): content is normally a string, but Mistral reasoning models return an array of ContentChunks ({type:"thinking"|"text",…} with nested thinking:[{type:"text",text:…}]) which are flattened into text + reasoning.
• WireUsage { promptTokens, completionTokens, completionTokensDetails.reasoningTokens } → TokenUsage (OpenAICompatibleClient.swift:187-210).
• /models decoding tries {"data":[{id}]} then a bare array (Together), and strips the models/ prefix Gemini's compat endpoint adds (listModelIDs, OpenAICompatibleClient.swift:407-421).

Streaming loop (streamChat, OpenAICompatibleClient.swift:324-372): wraps everything in an AsyncThrowingStream whose backing Task is cancelled onTermination; iterates StreamingService.sseEvents(for:provider:); breaks on data: [DONE]; silently skips undecodable chunks (keep-alives, unknown shapes); yields .reasoningDelta (from reasoning_content or reasoning), .textDelta (from delta.content or choices[].text), .citations (once, Perplexity), .usage, then a final .finished(reason:) carrying the last finish_reason seen.

Non-streaming (complete, OpenAICompatibleClient.swift:374-405): plain POST via StreamingService.postJSON, decodes the same WireChunk (reading choice.message ?? choice.delta), builds a Message with reasoning, citations, usage, and estimatedCost computed from model.pricing.cost(inputTokens:outputTokens:). If parameterSupport.requiresStreaming is set the client transparently aggregates the stream instead (completeViaStream, OpenAICompatibleClient.swift:425-454).

Perplexity citations (OpenAICompatibleClient.swift:468-476): top-level citations (array of URL strings) merged with search_results titles into numbered Citation values (Sources/ZyquoCloud/Models/Message.swift:93-105).

# 1.4 AnthropicClient — native Messages API

Sources/ZyquoCloud/Providers/AnthropicClient.swift. Headers: x-api-key + anthropic-version: 2023-06-01 (AnthropicClient.swift:142-154). Never routed through the OpenAI client (wantsStreamOptions explicitly notes "never routed here", OpenAICompatibleClient.swift:252-253).

Request (WireRequest, AnthropicClient.swift:24-48): model, mandatory max_tokens (default 8192 when the user set none), messages: [WireMessage] (system messages filtered out), top-level system: String?, stream, temperature, top_p, and thinking: {type: "enabled", budget_tokens: 8000} | {type: "disabled"} when the model has thinkingToggle (AnthropicClient.swift:156-181). Content is block-structured: WireBlock.text and WireBlock.image(mediaType:base64:) encoding {"type":"image","source":{"type":"base64","media_type":…,"data":…}} (AnthropicClient.swift:55-78). Empty text is sent as " " (Anthropic rejects empty blocks, AnthropicClient.swift:196). Note per-model gating: Claude 4.7+/5 removed temperature/top_p — encoded in each model's ParameterSupport (AnthropicClient.swift:171-174, ModelCatalogData.swift:249,257,266).

Streaming (streamChat, AnthropicClient.swift:202-259) decodes the named SSE events (the event name comes from sse.event ?? event.type):

There is no [DONE] sentinel on Anthropic streams. .usage and .finished(reason: stopReason) are yielded at stream end. Non-streaming (complete, AnthropicClient.swift:261-287) joins content[].type == "text" and "thinking" blocks. listModelIDs GETs messages-sibling models?limit=100 (AnthropicClient.swift:289-299).

# 1.5 SSE parsing — StreamingService / SSEParser

Sources/ZyquoCloud/Services/StreamingService.swift. SSEEvent { event: String?, data: String } (StreamingService.swift:12-17). SSEParser (StreamingService.swift:22-47) is a line-fed incremental parser: accumulates event:/data: fields (multi-line data: joined with \n), emits a complete event at the blank-line separator, ignores : comment lines (DeepSeek sends : keep-alive) and id:/retry:/unknown fields. Unit-tested in Tests/ZyquoCloudTests/SSEParserTests.swift.

StreamingService.sseEvents(for:provider:) (StreamingService.swift:63-118):

• Shared URLSession with timeoutIntervalForRequest = 120, timeoutIntervalForResource = 900 (long streams), User-Agent: ZyquoCloud/1.0 (macOS) (StreamingService.swift:53-59).
• Uses session.bytes(for:); non-2xx → drains the full error body and throws ProviderError.from(status:body:provider:).
• Splits bytes on \n manually (handling \r\n) because AsyncBytes.lines skips empty lines, which are the SSE event separators (StreamingService.swift:80-95) — a real pitfall the Router must keep.
• Flushes a trailing partial line/event at EOF; checks Task.isCancelled per byte-boundary; cancellation surfaces as ProviderError.cancelled.

Retry policy: postJSON (StreamingService.swift:122-156) retries 3 attempts on 429/5xx with Retry-After honored when present, else exponential backoff pow(2, attempt) * 2 seconds (4s, 8s). getJSON delegates to postJSON (same mapping). Streaming requests are NOT retried (single attempt).

# 1.6 Error types

ProviderError (ProviderProtocol.swift:73-146), a LocalizedError: invalidAPIKey(ProviderID), rateLimited(ProviderID, retryAfter:), serverError(ProviderID, status:, message:), badRequest(ProviderID, message:), networkError(underlying:), invalidResponse(ProviderID, detail:), missingAPIKey(ProviderID), noModelAvailable(ProviderID), cancelled. Status mapping (from(status:body:provider:)): 401/403 → invalidAPIKey; 429 → rateLimited (retryAfter not parsed here); 400/404/422 → badRequest; else serverError. extractMessage(from:) (ProviderProtocol.swift:127-145) probes the provider error shapes {"error":{"message":…}}, {"error":"…"}, {"message":…}, {"detail":…}, and Gemini's top-level array form, falling back to the first 300 bytes of the body. The Router's error translation to OpenAI wire format ({"error":{message,type,param,code}} + proper status) maps directly onto these cases.

# 2. The complete model catalog

Swift types (Sources/ZyquoCloud/Models/AIModel.swift):

• AIModel (AIModel.swift:15-43): id (exact upstream model ID), provider: ProviderID, displayName, contextWindow: Int, maxOutputTokens: Int?, capabilities: ModelCapabilities, pricing: ModelPricing?, parameterSupport: ParameterSupport, isLegacy, isRecommended, customBaseURL: URL?.
• ModelCapabilities (AIModel.swift:47-60): vision, tools, reasoning, streaming (default true), jsonMode, citations.
• ModelPricing (AIModel.swift:64-72): USD per 1M tokens, inputPerMTok / outputPerMTok, with func cost(inputTokens:outputTokens:) -> Double. Cached/tiered pricing intentionally simplified to base rate; UI labels costs "estimates". This is where the Router's cost meter gets its numbers.
• ParameterSupport (AIModel.swift:77-93): temperature, topP, frequencyPenalty, presencePenalty, usesMaxCompletionTokens, reasoningEffort, thinkingToggle, requiresStreaming; preset .openAIDefault = ParameterSupport(frequencyPenalty: true, presencePenalty: true).
• TokenUsage (AIModel.swift:96-111): inputTokens, outputTokens, reasoningTokens? + +.

Data lives in Sources/ZyquoCloud/Services/ModelCatalogData.swift (1365 lines; static let all = openai + anthropic + xai + mistral + gemini + qwen + deepseek + kimi + perplexity + together + deepinfra + cerebras, ModelCatalogData.swift:1361-1363), generated from docs/PROVIDERS.md and docs/research/*.md on 2026-07-30, live-verified (Phase 7 amendments, docs/PROVIDERS.md:1638-1719). Runtime access via @MainActor final class ModelCatalog: ObservableObject (Sources/ZyquoCloud/Services/ModelCatalog.swift:17-72) which layers dynamic /models refreshes (applyLiveListing, unknownLiveIDs) and user custom models on top, and provides cheapestModel(for:) (non-reasoning preferred, min outputPerMTok).

Scope note (ModelCatalogData.swift:13-16): chat-completions-capable chat models only — embeddings, audio, realtime, image/video gen, moderation, and Responses-API-only models are excluded by design.

Total: 170 models across 12 providers. The Router exposes ALL of them as provider/model-id (e.g. anthropic/claude-opus-5, qwen/qwen3.7-max, together/moonshotai/Kimi-K3 — note Together/ DeepInfra IDs already contain /, so the Router's namespacing must split on the first / only). Legend: V=vision, T=tools, R=reasoning, J=jsonMode, C=citations; prices are USD per MTok in/out; ✩=isRecommended, †=isLegacy.

# OpenAI (27) — ModelCatalogData.swift:33-239

Preset openAIReasoning (ModelCatalogData.swift:26-29): no temperature/top_p, max_completion_tokens, reasoning_effort.

# Anthropic (11) — ModelCatalogData.swift:243-327

# xAI (5) — ModelCatalogData.swift:331-369

Note: grok-4.20, grok-4.20-non-reasoning, grok-code-fast-1 resolve on chat completions but do not appear in xAI /models (docs/PROVIDERS.md:1706).

# Mistral (10) — ModelCatalogData.swift:373-451

# Google Gemini (14) — ModelCatalogData.swift:455-559 (all max out 65,536 except Gemma 32,768)

# Alibaba Qwen / DashScope (32) — ModelCatalogData.swift:563-799 (pricing mostly unrecorded)

# DeepSeek (2) — ModelCatalogData.swift:803-820

(deepseek-chat/deepseek-reasoner were retired 2026-07-24, docs/PROVIDERS.md:42-44.)

# Kimi / Moonshot (12) — ModelCatalogData.swift:824-920

# Perplexity (4) — ModelCatalogData.swift:924-955 (all citations: true; no /models endpoint)

# Together AI (16) — ModelCatalogData.swift:959-1077

# DeepInfra (34) — ModelCatalogData.swift:1081-1328

(google/gemma-4-31B-it was removed from DeepInfra 2026-07-30 — endpoint hangs 60s+ with zero bytes, ModelCatalogData.swift:1326-1327, docs/PROVIDERS.md:1714-1715.)

# Cerebras (3) — ModelCatalogData.swift:1332-1357 (all max out 40,000; max_completion_tokens required)

# 3. The secure key vault — SecureKeyStore

Sources/ZyquoCloud/Services/SecureKeyStore.swift (174 lines). Confirmed: deliberately NOT the macOS Keychain — the header says so verbatim (SecureKeyStore.swift:8). The only Security.framework usage in the file is SecRandomCopyBytes(kSecRandomDefault, …) for salt generation (SecureKeyStore.swift:161-166) — no SecItem* / keychain item APIs anywhere. A repo grep confirms no other Keychain usage in Zyquo Cloud.

# File location & format

• Vault file: ~/Library/Application Support/ZyquoCloud/vault.zq — built as PersistenceService.shared.rootDirectory.appendingPathComponent("vault.zq") (SecureKeyStore.swift:56-57; root dir from Sources/ZyquoCloud/Services/PersistenceService.swift:24-27). Router equivalent: ~/Library/Application Support/ZyquoRouter/vault.zq (same format).
• Binary layout (SecureKeyStore.swift:11-13): [salt 32B][AES-GCM nonce 12B][ciphertext+tag 16B] — everything after the salt is the CryptoKit AES.GCM.SealedBox.combined representation (nonce ‖ ciphertext ‖ tag), opened with AES.GCM.SealedBox(combined:) + AES.GCM.open(_:using:) (SecureKeyStore.swift:71-72) and produced by AES.GCM.seal(_:using:).combined (SecureKeyStore.swift:84-85). Nonce is generated by CryptoKit per seal (fresh every save).
• Plaintext: a JSON dictionary {"openai": "sk-…", "anthropic": "sk-ant-…", …} — keys are ProviderID.rawValue strings (SecureKeyStore.swift:13, key(for:)/setKey(_:for:) at SecureKeyStore.swift:94-108).
• Written atomically with .completeFileProtection (SecureKeyStore.swift:91); the directory is created on demand.

# Master key derivation (SecureKeyStore.swift:118-159)

HKDF<SHA256>.deriveKey(
    inputKeyMaterial: SymmetricKey(data: machineEntropy() ‖ pepper),
    salt: <32-byte vault salt>,
    info: Data("ZyquoCloud.vault.v1".utf8),
    outputByteCount: 32                       // AES-256 key
)

• machineEntropy = IOPlatformUUID (read from IOKit's IOPlatformExpertDevice registry entry via IORegistryEntryCreateCFProperty(…, kIOPlatformUUIDKey, …), SecureKeyStore.swift:138-148) ‖ NSHomeDirectory() — binds the vault to this machine and account. Injectable via init for tests (SecureKeyStore.swift:52-59, Tests/ZyquoCloudTests/SecureKeyStoreTests.swift).
• Pepper: 30 compiled-in bytes, stored XOR 0x5A so the value never appears verbatim in the binary, reassembled at runtime (pepper(), SecureKeyStore.swift:152-159).
• Salt: 32 random bytes (SecRandomCopyBytes) generated on first save; re-saves reuse the existing salt (existingSalt(), SecureKeyStore.swift:169-173) so the derived key stays stable.
• Constants: saltLength = 32, keyLength = 32 (SecureKeyStore.swift:45-46).

# Public API surface (SecureKeyStore.swift:61-114)

init(vaultURL: URL? = nil, machineEntropy: (() throws -> Data)? = nil)
func loadKeys() throws -> [String: String]          // empty dict if no vault file
func saveKeys(_ keys: [String: String]) throws      // atomic full-dictionary rewrite
func key(for provider: ProviderID) throws -> String?
func setKey(_ apiKey: String, for provider: ProviderID) throws
func deleteKey(for provider: ProviderID) throws
static func redacted(_ apiKey: String) -> String    // "••••abcd" (last 4 only)

Errors: VaultError.corrupted ("The key vault is damaged or belongs to another machine." — also thrown when GCM auth fails, i.e. wrong machine) and VaultError.machineIdentityUnavailable (SecureKeyStore.swift:31-43).

The UI-facing wrapper is @MainActor final class KeyVaultStore: ObservableObject (Sources/ZyquoCloud/ViewModels/KeyVaultStore.swift:16-93): per-provider KeyStatus (unset/saved/testing/verified(latency:)/failed(message:)), redacted display strings, and testKey(for:catalog:) using ProviderRegistry + ModelCatalog.cheapestModel(for:). Keys are decrypted on demand and never retained beyond the call (KeyVaultStore.swift:55-61).

Router decision for identical UX: reuse SecureKeyStore byte-for-byte in design. Two constants differ per app: the vault path root (ZyquoRouter folder) and the HKDF info string ("ZyquoCloud.vault.v1"). Keeping info identical AND pointing at Cloud's vault file would let the apps literally share one vault; the Zyquo Router CLAUDE.md asks for the same design and format (users manage keys identically), not necessarily the same file — decide in Phase 2/3. If the Router keeps its own vault, use info: "ZyquoRouter.vault.v1" and its own vault.zq under ~/Library/Application Support/ZyquoRouter/. Either way: no Keychain, ever.

# 4. Provider streaming quirks the Router's translation layer must normalize

All recorded in code and in docs/PROVIDERS.md (cross-provider notes at lines 32-46; Phase 7 amendments at lines 1638-1719):

1. Reasoning content field zoo — normalize to one field (Router decision: reasoning_content on message/delta, per OpenAI-compat majority):
   • delta.reasoning_content: DeepSeek (on by default for v4-flash), Qwen, Kimi K-series, some DeepInfra models (OpenAICompatibleClient.swift:133-146).
   • delta.reasoning (no _content): some hosts (decoded as fallback, OpenAICompatibleClient.swift:344); Together exposes message.reasoning for hosted reasoning models (docs/PROVIDERS.md:28).
   • Anthropic: thinking_delta inside content_block_delta events; non-streaming thinking content blocks (AnthropicClient.swift:226-232,270-271).
   • Mistral: content arrives as an array of ThinkChunk/TextChunk objects ({type:"thinking",thinking:[{type:"text",text:…}]}) — must be flattened (OpenAICompatibleClient.swift:143-184; docs/PROVIDERS.md:1704).
   • Perplexity sonar-reasoning-pro: reasoning arrives as inline <think>…</think> text in the content itself (docs/PROVIDERS.md:27,37) — Cloud does not split it; the Router must decide (pass through or extract).
   • OpenAI: no reasoning text at all on chat completions — only usage.completion_tokens_details.reasoning_tokens (docs/PROVIDERS.md:178).
2. Usage-in-stream behavior (OpenAICompatibleClient.swift:243-255; docs/PROVIDERS.md:38-39): stream_options:{include_usage:true} needed for OpenAI, xAI, Gemini-compat, DeepSeek, Kimi, Together, Cerebras (final chunk has empty choices + usage); Qwen, DeepInfra, Perplexity include usage automatically (and Mistral rejects the param). Anthropic splits usage: input_tokens in message_start, final output_tokens in message_delta.
3. Keep-alive comments: DeepSeek sends : keep-alive SSE comment lines — SSEParser drops any :-prefixed line (StreamingService.swift:36). Undecodable data chunks are skipped, not fatal (OpenAICompatibleClient.swift:339-342).
4. Finish-reason quirks: Together emits nonstandard finish_reason: "eos" (docs/PROVIDERS.md:35) — the Router must map it to stop. Anthropic uses stop_reason (end_turn, max_tokens, stop_sequence, tool_use) delivered in message_delta, which the Router maps to OpenAI finish_reason (stop/length/stop/tool_calls).
5. Together completions-style streams: some models (Qwen/Qwen3.5-9B, google/gemma-4-31B-it) stream tokens in choices[].text instead of delta.content (OpenAICompatibleClient.swift:122-124; docs/PROVIDERS.md:1712-1713).
6. Models that reject non-streaming calls (ParameterSupport.requiresStreaming, AIModel.swift:88-90): Qwen qvq-max/qwq-plus; Together Qwen3.7-Max/-Plus, Qwen3.6-Plus, Qwen3.5-9B, google/gemma-4-31B-it; DeepInfra moonshotai/Kimi-K2.5. For a non-streaming router request, aggregate the stream (Cloud's completeViaStream pattern).
7. Perplexity citations: top-level citations: [String] (URLs) + search_results (titles) on chunks and responses — surfaced once per stream (OpenAICompatibleClient.swift:356-359,468-476). No /models endpoint (404): the Router must serve Perplexity models from the built-in catalog only.
8. Gemini compat endpoint: /models IDs prefixed models/ (stripped, OpenAICompatibleClient.swift:411,420); unknown fields like extra_content/thought_signature in deltas must be ignored; native-only features (thought summaries, thoughtsTokenCount) are not exposed on the compat endpoint (docs/PROVIDERS.md:560).
9. Unknown-field tolerance generally: OpenAI adds obfuscation fields; decoders must ignore unknown JSON keys everywhere (docs/PROVIDERS.md:34-35).
10. Anthropic mid-stream errors: an error SSE event can arrive with HTTP 200 (AnthropicClient.swift:240-243) — the Router must convert it into an OpenAI-format error (or a terminal chunk if the stream already started).
11. Parameter strip tables (per-model ParameterSupport): OpenAI reasoning models and Claude 4.7+/5 reject temperature/top_p; Cerebras + OpenAI reasoning + Kimi K-series require max_completion_tokens; Mistral reasoning_effort accepts only high/none; Qwen enable_thinking only when streaming; xAI grok-4.20/grok-code-fast-1 reject reasoning_effort. This is exactly the Router's CompatAdjuster data.
12. Vision minimums: xAI and Qwen reject images smaller than 8px (docs/PROVIDERS.md:1707).
13. Anthropic streams have no data: [DONE] — termination is the message_stop event; the Router's SSEWriter must synthesize [DONE] itself for downstream OpenAI clients.

# 5. Reuse plan — files to port from Cloud → Router

# 5.1 Port nearly verbatim (change header Zyquo Cloud → Zyquo Router; keep type names)

KeyVaultStore.swift (ViewModel) ports with light edits for the Router's Keys screen (Provider Keys tab is spec'd "identical UX to Zyquo Cloud").

# 5.2 What Cloud's clients DON'T give the Router (must be added, not just ported)

Cloud is a chat app; its clients expose a UI-oriented, lossy event stream. The Router needs a spec-complete OpenAI surface. Gaps found in the code:

1. No tool calling anywhere. WireRequest has no tools/tool_choice; WireDelta decodes no tool_calls; ChatEvent has no tool case; Anthropic's client sends no tools and ignores tool_use/input_json_delta (grep of Sources/ZyquoCloud/Providers/ for "tool" → zero hits). The Router must extend the wire types and ChatEvent (e.g. .toolCallDelta(index:id:name:argumentsDelta:)) and implement Anthropic tool_use/tool_result ↔ OpenAI tool_calls/role:"tool" translation per docs/ROUTER-RESEARCH.md.
2. No response_format/JSON mode, stop, n, seed, logprobs, user in WireRequest — the catalog tracks jsonMode capability but Cloud never sends it. Add these fields (gated by CompatAdjuster).
3. Lossy events: ChatEvent collapses per-choice structure (only choices.first is read, OpenAICompatibleClient.swift:343), drops chunk id/created/model/system_fingerprint, and merges role/content deltas. Fine for a chat UI; the Router must emit byte-perfect chat.completion.chunks. Recommended approach: keep Cloud's request-construction + StreamingService/SSEParser + auth/quirk logic as-is, but widen the response path — either (a) make the wire response types non-private and add a raw-chunk streaming API (streamRawChunks(_:apiKey:) -> AsyncThrowingStream<Data, Error> yielding upstream SSE data payloads for OpenAI-compatible providers, enabling near-pass-through), plus a translated path for Anthropic; or (b) enrich ChatEvent to carry everything (finish per choice, tool deltas, ids, raw usage). Option (a) is closest to how LiteLLM/OpenRouter behave for compat upstreams and preserves fidelity; the Anthropic translator then builds spec-exact chunks from the named events already parsed in AnthropicClient.streamChat.
4. ChatRequest is UI-shaped (model: AIModel, messages: [Message] with attachments). The Router receives OpenAI wire JSON; it should define a canonical internal request (Translate/OpenAINormalizer.swift) and map it into the ported clients' body builders — or refactor buildBody to accept the canonical type. Keep ParameterSupport gating exactly as Cloud does; it is the per-provider param strip/translate table (CompatAdjuster seed data).
5. ChatParameters lives in Sources/ZyquoCloud/Models/Conversation.swift (temperature, topP, maxTokens, frequency/presencePenalty, reasoningEffort, thinkingEnabled) — port the struct (or inline it) since both clients consume it.
6. Retry semantics: Cloud retries only non-streaming calls (3 attempts in StreamingService.postJSON). The Router's RetryPolicy (Phase 2 layout) should own this and also handle pre-first-byte retry for streaming + Retry-After propagation to clients.
7. Gemini: no native client exists (see §1.1). Near-term: reuse the compat path (verified live by Cloud, including vision via data URIs and reasoning_effort). If Phase 3's gate demands the native generateContent translation, GeminiTranslator.swift is net-new work guided by docs/ROUTER-RESEARCH.md — nothing to port from Cloud beyond docs/PROVIDERS.md:524-696 research.
8. Usage estimation: when upstream omits usage, Cloud just shows nothing. The Router spec requires estimated-and-flagged usage — net-new (token estimation), though TokenUsage and ModelPricing.cost port directly for the metering.

# 5.3 Destination layout (matches Router CLAUDE.md Phase 2)

Sources/ZyquoRouter/
├── Models/        ProviderID.swift, AIModel.swift, Message.swift (+ChatParameters)   ← ported
├── Providers/     ProviderProtocol.swift, ProviderRegistry.swift,
│                  OpenAICompatibleClient.swift, AnthropicClient.swift               ← ported + extended
│                  (GeminiClient.swift only if native path chosen — net-new)
├── Services/      StreamingService.swift, SecureKeyStore.swift,
│                  ModelCatalog.swift, ModelCatalogData.swift, PersistenceService.swift ← ported
├── Translate/     OpenAINormalizer.swift, AnthropicTranslator.swift,
│                  GeminiTranslator.swift, CompatAdjuster.swift                       ← new (seeded by ParameterSupport + §4)
├── Router/        RequestRouter.swift, RetryPolicy.swift, UsageMeter.swift           ← new (RetryPolicy absorbs postJSON backoff)
└── Server/        …                                                                  ← new

# 5.4 Porting checklist

• Rewrite every file header comment Zyquo Cloud → Zyquo Router (mandatory header sweep).
• ZyquoCloud/1.0 User-Agent → ZyquoRouter/1.0; HKDF info + vault path decision recorded.
• Keep type names Cloud uses: ProviderClient, ProviderID, WireFormat, AIModel, ModelCatalog, SecureKeyStore, SSEParser, TokenUsage, ProviderError (Router CLAUDE.md's uniform-naming rule already includes ProviderClient).
• ModelCatalogData.swift stays byte-identical to Cloud's (modulo header) — single source of truth for the GET /v1/models catalog and pricing/cost metering.
• Extend wire types for tools / response_format / stop / n / seed; add raw-chunk streaming path.
• Port fixture-worthy behaviors into unit tests: SSE blank-line handling, : keep-alive, Mistral ThinkChunk flattening, Together choices[].text, Anthropic event mapping, Gemini models/ prefix strip, finish_reason:"eos" → stop.