@thinwrap/llm 1.0.0

package/dist/esm/types/passthrough.type.d.ts

@@ -0,0 +1,15 @@
+export interface Passthrough {
+    /**
+     * Merged into the outbound request JSON body; overrides connector-built fields
+     * on key collision. Never transformed or validated — if you populate this from
+     * untrusted input, sanitize it yourself (you own the keys that reach the wire).
+     */
+    body?: Record<string, unknown>;
+    /** Merged into request headers. */
+    headers?: Record<string, string>;
+    /** Appended to the request URL query string. */
+    query?: Record<string, string>;
+}
+export type WithPassthrough<T> = T & {
+    _passthrough?: Passthrough;
+};

package/dist/esm/types/passthrough.type.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/provider-id.enum.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Provider ids implemented so far — the 15 first-class OpenAI-compatible
+ * providers (one shared connector) plus native-adapter providers as they land
+ * (`anthropic`). Remaining natives (bedrock, gemini, vertex, cohere) are added
+ * when their adapters ship.
+ */
+export declare const LLM_PROVIDER_IDS: readonly ["openai", "azure-openai", "openrouter", "groq", "together", "fireworks", "deepseek", "xai", "mistral", "perplexity", "deepinfra", "cloudflare", "vllm", "ollama", "lmstudio", "anthropic", "bedrock", "gemini"];
+export type LlmProviderId = (typeof LLM_PROVIDER_IDS)[number];

package/dist/esm/types/provider-id.enum.js

@@ -0,0 +1,26 @@
+/**
+ * Provider ids implemented so far — the 15 first-class OpenAI-compatible
+ * providers (one shared connector) plus native-adapter providers as they land
+ * (`anthropic`). Remaining natives (bedrock, gemini, vertex, cohere) are added
+ * when their adapters ship.
+ */
+export const LLM_PROVIDER_IDS = [
+    'openai',
+    'azure-openai',
+    'openrouter',
+    'groq',
+    'together',
+    'fireworks',
+    'deepseek',
+    'xai',
+    'mistral',
+    'perplexity',
+    'deepinfra',
+    'cloudflare',
+    'vllm',
+    'ollama',
+    'lmstudio',
+    'anthropic',
+    'bedrock',
+    'gemini',
+];

package/dist/esm/types/provider.interface.d.ts

@@ -0,0 +1,7 @@
+import type { ChatInput, ChatResult, ChatStreamDelta } from './chat.types.js';
+/** The contract every chat connector satisfies — shared-compat or native adapter. */
+export interface IChatConnector {
+    readonly id: string;
+    complete(input: ChatInput): Promise<ChatResult>;
+    stream(input: ChatInput): AsyncIterable<ChatStreamDelta>;
+}

package/dist/esm/types/provider.interface.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@thinwrap/llm",
+  "version": "1.0.0",
+  "description": "Unified, zero-dependency TypeScript facade over LLM chat-completion (and embeddings) providers. Stateless, BYO fetch, no vendor SDKs.",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src/providers/*/README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run build:cjs && npm run build:esm && node scripts/fix-esm-imports.mjs",
+    "build:cjs": "tsc -p tsconfig.build.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "check:dist": "node scripts/check-dist.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "openai",
+    "anthropic",
+    "claude",
+    "gpt",
+    "chat-completions",
+    "embeddings",
+    "gateway",
+    "zero-dependency",
+    "lightweight",
+    "bring-your-own-fetch",
+    "stateless"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thinwrap/llm-ts"
+  },
+  "homepage": "https://thinwrap.dev",
+  "bugs": {
+    "url": "https://github.com/thinwrap/llm-ts/issues"
+  },
+  "author": "Dmitry Polyanovsky",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "typescript": "^5.9.3",
+    "vite": "^6.4.3",
+    "vitest": "^3.2.4"
+  }
+}

package/src/providers/anthropic/README.md

@@ -0,0 +1,64 @@
+# Anthropic (Claude) — `@thinwrap/llm`
+
+Native adapter over the Anthropic **Messages API** (`POST /v1/messages`). Anthropic does not speak OpenAI's Chat Completions shape, so this connector is a full translation layer — it produces the identical normalized `ChatResult` / `ChatStreamDelta` / `ConnectorError` as every other connector, so switching to/from `anthropic` is still just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('anthropic', { apiKey: process.env.ANTHROPIC_API_KEY! });
+const res = await chat.complete({
+  model: 'claude-sonnet-4-5',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Sent as `x-api-key` (not `Authorization: Bearer`). |
+| `baseUrl` | no | `https://api.anthropic.com/v1` | Override for proxies / gateways. |
+| `anthropicVersion` | no | `2023-06-01` | `anthropic-version` header. |
+| `defaultMaxTokens` | no | `4096` | Anthropic **requires** `max_tokens`; used when `maxOutputTokens` is omitted. |
+| `fetch` | no | `globalThis.fetch` | BYO HTTP client. |
+
+## Auth setup
+
+Create an API key in the Anthropic Console. It is sent as the `x-api-key` header along with `anthropic-version`. No environment inference — pass `apiKey` explicitly (or read it from your own env as above).
+
+## Chat
+
+### Endpoint
+
+`POST <baseUrl>/messages` (default `https://api.anthropic.com/v1/messages`).
+
+### Notes / quirks
+
+How the normalized shape maps:
+
+- **System message** → hoisted to the top-level `system` field (multiple system messages are concatenated).
+- **`role: 'tool'` messages** → carried inside a `user` turn as `tool_result` blocks; consecutive tool messages coalesce into one turn (native Anthropic requirement).
+- **Assistant `toolCalls`** → `tool_use` content blocks; **`tools`** → `{ name, description, input_schema }` (JSON Schema in `input_schema`, not nested under `function`).
+- **`toolChoice`** → `auto`→`{type:'auto'}`, `required`→`{type:'any'}`, `none`→`{type:'none'}`, `{function:{name}}`→`{type:'tool', name}`.
+- **Images** → `{ type:'image', source:{ type:'base64', media_type, data } }`.
+- **`stop`** → `stop_sequences`. **`reasoning.effort`** → `thinking:{ type:'enabled', budget_tokens }` (low/medium/high ≈ 1024/4096/12288; sampling params are dropped while thinking is enabled, per Anthropic's constraint).
+- **Usage** → `{ inputTokens, outputTokens, totalTokens }` (Anthropic reports no total; it is summed).
+- **`stop_reason`** → `finishReason` (`end_turn`/`stop_sequence`→`stop`, `max_tokens`→`length`, `tool_use`→`tool_calls`, `refusal`→`content_filter`).
+
+Not normalized (passthrough / raw — never emulated):
+
+- **`responseFormat`** — Anthropic has no `response_format`; use tool-based structured output via `_passthrough`. This connector does **not** apply `responseFormat`.
+- **Reasoning CoT output** — `thinking` blocks are surfaced only in `ChatResult.raw` (D2: reasoning output is not normalized).
+- **Prompt caching** — pass `cache_control` markers via `_passthrough.body`; cached-token counts appear in `raw`.
+
+## Embeddings
+
+Anthropic exposes no OpenAI-float embeddings surface (its embeddings partner is Voyage), so there is no `Embeddings` support — `new Embeddings('anthropic', …)` throws `ConnectorError` (`invalid_request`).
+
+## Error mapping & passthrough
+
+- `ConnectorError.providerCode`: `401/403`→`auth_failed`, `429`→`rate_limited`, `500/502/503/529`→`provider_unavailable`, `400/413/422`→`invalid_request` (or `context_length_exceeded` when the message indicates a context overflow). The raw error body is on `cause.raw`; `Retry-After` (when present) on `cause.retryAfter` / `cause.retryAfterSeconds`.
+- Provider-specific request fields go through `_passthrough.body` / `.headers` / `.query`; vendor response extras stay on `ChatResult.raw`.
+- Rate-limit guidance: <https://docs.anthropic.com/en/api/rate-limits>.

package/src/providers/azure-openai/README.md

@@ -0,0 +1,62 @@
+# Azure OpenAI — `@thinwrap/llm`
+
+First-class OpenAI-compatible provider — served by the shared `OpenAICompatConnector` via a row in `src/providers/_shared/spec.ts` (no per-provider connector class). It emits the identical normalized `ChatResult` / `ChatStreamDelta` / `ConnectorError` as every other connector, so switching to/from `azure-openai` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('azure-openai', { apiKey: process.env.AZURE_OPENAI_API_KEY!, baseUrl: '<resource URL — see quirks>' });
+const res = await chat.complete({
+  model: '<your-deployment-name>',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Sent as the `api-key: <apiKey>` header (Microsoft Entra OAuth is also accepted on the v1 GA API). |
+| `baseUrl` | yes | — | Required — no public default (see Chat notes). |
+| `fetch` | no | `globalThis.fetch` | Bring-your-own fetch. |
+| `headers` | no | — | Extra headers merged onto every request. |
+
+## Auth setup
+
+Get the key and resource endpoint from the Azure portal. The connector sends it as the `api-key` header; Microsoft Entra OAuth bearer tokens are also accepted on the v1 GA API — supply that token via `headers` instead.
+
+## Chat
+
+### Endpoint
+
+`POST https://<resource>.openai.azure.com/openai/v1/chat/completions`
+
+### Notes / quirks
+
+- **`baseUrl` is required**: `https://<resource>.openai.azure.com/openai/v1` (v1 GA API, opt-in Aug 2025 — no `api-version` needed).
+- The `model` field is the per-resource **deployment name**, not a portable global model id.
+- Auth is dual-mode: `api-key` header or an Entra bearer token (supply the latter via `headers`).
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('azure-openai', { apiKey: process.env.AZURE_OPENAI_API_KEY!, baseUrl: '<resource URL — see quirks>' });
+const out = await emb.create({
+  model: '<embedding-model>',
+  input: ['hello', 'world'],
+});
+```
+
+`POST https://<resource>.openai.azure.com/openai/v1/embeddings` with `encoding_format: 'float'`. `dimensions` maps to `dimensions` when set. Vectors are returned in input order on `out.embeddings`.
+
+## Error mapping & passthrough
+
+- Non-2xx responses throw `ConnectorError` with a 7-value `providerCode` (`auth_failed` / `rate_limited` / `provider_unavailable` / `invalid_request` / `context_length_exceeded` / `content_filtered` / `unknown`). The raw vendor body is on `cause.raw`; retry hints (when present) on `cause.retryAfter` / `cause.retryAfterSeconds`.
+- Sub-baseline features — `topK`, `seed`, `frequency`/`presence_penalty`, `logitBias`, `n`, reasoning control beyond `reasoning.effort`, prompt caching — ride through `_passthrough` (request) / `raw` (result). They are never emulated.
+- Rate-limit guidance: <https://learn.microsoft.com/azure/ai-services/openai/quotas-limits>.

package/src/providers/bedrock/README.md

@@ -0,0 +1,71 @@
+# AWS Bedrock — `@thinwrap/llm`
+
+Native adapter over Amazon Bedrock's unified **Converse API** (`POST /model/{modelId}/converse`). Requests are signed with **hand-rolled AWS SigV4** on `node:crypto` — no `@aws-sdk/*`, no third-party crypto (same zero-dep approach as the notifications SES/SNS connectors). Emits the identical normalized `ChatResult` / `ChatStreamDelta` / `ConnectorError` as every other connector.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('bedrock', {
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  // sessionToken: process.env.AWS_SESSION_TOKEN,  // for temporary creds
+});
+const res = await chat.complete({
+  model: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `region` | yes | — | e.g. `us-east-1`. No environment inference. |
+| `accessKeyId` / `secretAccessKey` | yes | — | SigV4 credentials. |
+| `sessionToken` | no | — | STS temporary-credential token → `X-Amz-Security-Token`. |
+| `baseUrl` | no | `https://bedrock-runtime.<region>.amazonaws.com` | Override origin (VPC endpoint / proxy). |
+| `defaultMaxTokens` | no | `4096` | Converse `inferenceConfig.maxTokens` when `maxOutputTokens` is omitted. |
+| `fetch` | no | `globalThis.fetch` | BYO HTTP client. |
+
+## Auth setup
+
+Uses standard AWS SigV4 (service `bedrock`) hand-rolled on `node:crypto` — no AWS SDK. Supply `accessKeyId` / `secretAccessKey` (and `sessionToken` for temporary credentials). The body is serialized once and those exact bytes are signed together with the canonical path so URL, body, and signature all agree.
+
+## Chat
+
+### Endpoint
+
+`POST <origin>/model/{modelId}/converse` where `origin` defaults to `https://bedrock-runtime.<region>.amazonaws.com`. The model id is percent-encoded for the path (e.g. `...-v2:0` → `...-v2%3A0`) so the SigV4 canonical URI matches the wire URL exactly.
+
+### Notes / quirks
+
+How the normalized shape maps:
+
+- **System message** → top-level `system: [{ text }]`.
+- **`role: 'tool'` messages** → `toolResult` blocks inside a `user` turn; consecutive tool messages coalesce into one turn.
+- **Assistant `toolCalls`** → `toolUse` blocks; **`tools`** → `toolConfig.tools[].toolSpec` with the JSON Schema under `inputSchema.json`.
+- **`toolChoice`** → `auto`→`{auto:{}}`, `required`→`{any:{}}`, `{function:{name}}`→`{tool:{name}}` (`none` → `toolConfig` omitted).
+- **Images** → `{ image: { format, source: { bytes } } }` (`format` derived from `mediaType`).
+- **Sampling** → `inferenceConfig` `{ maxTokens, temperature, topP, stopSequences }`.
+- **Usage** → Converse `usage` maps directly to `{ inputTokens, outputTokens, totalTokens }`.
+- **`stopReason`** → `finishReason` (`end_turn`/`stop_sequence`→`stop`, `max_tokens`→`length`, `tool_use`→`tool_calls`, `content_filtered`/`guardrail_intervened`→`content_filter`).
+
+v1 limitations (documented, not silent):
+
+- **Streaming is non-incremental in v1.** Bedrock's `converse-stream` uses AWS's binary event-stream framing (`application/vnd.amazon.eventstream`), not SSE. v1 does not parse that binary protocol — `stream()` issues one Converse call and yields the full result as deltas. A true incremental binary-event-stream parser is a planned follow-up.
+- **Reasoning is not auto-mapped.** Reasoning control on Bedrock is model-dependent; pass `additionalModelRequestFields` via `_passthrough.body`.
+- **`responseFormat`** is not mapped (use tool-based structured output via `_passthrough`); **prompt caching** via `_passthrough` (`cachePoint` blocks).
+- **SigV4 signature is not yet pinned to an external cross-verified vector** (structural tests only); pinning a known AWS test vector is a follow-up, matching the notifications SES/SNS specs.
+
+## Embeddings
+
+Bedrock has no OpenAI-float embeddings surface (Amazon Titan embeddings are not a Converse/OpenAI-float shape), so there is no `Embeddings` support — `new Embeddings('bedrock', …)` throws `ConnectorError` (`invalid_request`).
+
+## Error mapping & passthrough
+
+- `ConnectorError.providerCode`: `401/403`→`auth_failed`, `429`→`rate_limited`, `5xx`→`provider_unavailable`, `400/404/422`→`invalid_request` (or `rate_limited` for throttling, `context_length_exceeded` on context overflow). Raw body on `cause.raw`; `Retry-After` (when present) on `cause.retryAfter` / `cause.retryAfterSeconds`.
+- Provider-specific request fields go through `_passthrough.body` / `.headers` / `.query`; vendor response extras stay on `ChatResult.raw`.
+- Rate-limit / quota guidance: <https://docs.aws.amazon.com/bedrock/latest/userguide/quotas.html>.

package/src/providers/cloudflare/README.md

@@ -0,0 +1,62 @@
+# Cloudflare Workers AI — `@thinwrap/llm`
+
+First-class OpenAI-compatible provider — served by the shared `OpenAICompatConnector` via a row in `src/providers/_shared/spec.ts` (no per-provider connector class). It emits the identical normalized `ChatResult` / `ChatStreamDelta` / `ConnectorError` as every other connector, so switching to/from `cloudflare` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('cloudflare', { apiKey: process.env.CLOUDFLARE_API_TOKEN!, baseUrl: '<resource URL — see quirks>' });
+const res = await chat.complete({
+  model: '@cf/meta/llama-3.1-8b-instruct',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Sent as `Authorization: Bearer <apiKey>`. |
+| `baseUrl` | yes | — | Required — no public default (embeds your account id; see Chat notes). |
+| `fetch` | no | `globalThis.fetch` | Bring-your-own fetch. |
+| `headers` | no | — | Extra headers merged onto every request. |
+
+## Auth setup
+
+Create an API token (Workers AI scope) in the Cloudflare dashboard. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.cloudflare.com/client/v4/accounts/<accountId>/ai/v1/chat/completions`
+
+### Notes / quirks
+
+- **`baseUrl` is required**: `https://api.cloudflare.com/client/v4/accounts/<accountId>/ai/v1`.
+- Model ids are `@cf/{provider}/{model}` (some `@hf/…`), required verbatim.
+- JSON mode is **not strict** (no schema-adherence guarantee) and can't stream.
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('cloudflare', { apiKey: process.env.CLOUDFLARE_API_TOKEN!, baseUrl: '<resource URL — see quirks>' });
+const out = await emb.create({
+  model: '@cf/baai/bge-large-en-v1.5',
+  input: ['hello', 'world'],
+});
+```
+
+`POST https://api.cloudflare.com/client/v4/accounts/<accountId>/ai/v1/embeddings` with `encoding_format: 'float'`. `dimensions` maps to `dimensions` when set. Vectors are returned in input order on `out.embeddings`.
+
+## Error mapping & passthrough
+
+- Non-2xx responses throw `ConnectorError` with a 7-value `providerCode` (`auth_failed` / `rate_limited` / `provider_unavailable` / `invalid_request` / `context_length_exceeded` / `content_filtered` / `unknown`). The raw vendor body is on `cause.raw`; retry hints (when present) on `cause.retryAfter` / `cause.retryAfterSeconds`.
+- Sub-baseline features — `topK`, `seed`, `frequency`/`presence_penalty`, `logitBias`, `n`, reasoning control beyond `reasoning.effort`, prompt caching — ride through `_passthrough` (request) / `raw` (result). They are never emulated.
+- Rate-limit guidance: <https://developers.cloudflare.com/workers-ai/platform/limits/>.

package/src/providers/deepinfra/README.md

@@ -0,0 +1,61 @@
+# DeepInfra — `@thinwrap/llm`
+
+First-class OpenAI-compatible provider — served by the shared `OpenAICompatConnector` via a row in `src/providers/_shared/spec.ts` (no per-provider connector class). It emits the identical normalized `ChatResult` / `ChatStreamDelta` / `ConnectorError` as every other connector, so switching to/from `deepinfra` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('deepinfra', { apiKey: process.env.DEEPINFRA_API_KEY! });
+const res = await chat.complete({
+  model: 'meta-llama/Meta-Llama-3.1-70B-Instruct',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Sent as `Authorization: Bearer <apiKey>`. |
+| `baseUrl` | no | `https://api.deepinfra.com/v1/openai` | Override for proxies / gateways. |
+| `fetch` | no | `globalThis.fetch` | Bring-your-own fetch. |
+| `headers` | no | — | Extra headers merged onto every request. |
+
+## Auth setup
+
+Create a token at <https://deepinfra.com/dash/api_keys>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.deepinfra.com/v1/openai/chat/completions`
+
+### Notes / quirks
+
+- Model ids are HuggingFace-style `org/model` slugs (case-sensitive).
+- Runs on a vLLM backend (superset of OpenAI); `usage` adds a non-standard `estimated_cost`; vision `detail` is ignored.
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('deepinfra', { apiKey: process.env.DEEPINFRA_API_KEY! });
+const out = await emb.create({
+  model: 'BAAI/bge-large-en-v1.5',
+  input: ['hello', 'world'],
+});
+```
+
+`POST https://api.deepinfra.com/v1/openai/embeddings` with `encoding_format: 'float'`. `dimensions` maps to `dimensions` when set. Vectors are returned in input order on `out.embeddings`.
+
+## Error mapping & passthrough
+
+- Non-2xx responses throw `ConnectorError` with a 7-value `providerCode` (`auth_failed` / `rate_limited` / `provider_unavailable` / `invalid_request` / `context_length_exceeded` / `content_filtered` / `unknown`). The raw vendor body is on `cause.raw`; retry hints (when present) on `cause.retryAfter` / `cause.retryAfterSeconds`.
+- Sub-baseline features — `topK`, `seed`, `frequency`/`presence_penalty`, `logitBias`, `n`, reasoning control beyond `reasoning.effort`, prompt caching — ride through `_passthrough` (request) / `raw` (result). They are never emulated.
+- Rate-limit guidance: <https://docs.deepinfra.com/account/rate-limits>.

package/src/providers/deepseek/README.md

@@ -0,0 +1,50 @@
+# DeepSeek — `@thinwrap/llm`
+
+First-class OpenAI-compatible provider — served by the shared `OpenAICompatConnector` via a row in `src/providers/_shared/spec.ts` (no per-provider connector class). It emits the identical normalized `ChatResult` / `ChatStreamDelta` / `ConnectorError` as every other connector, so switching to/from `deepseek` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('deepseek', { apiKey: process.env.DEEPSEEK_API_KEY! });
+const res = await chat.complete({
+  model: 'deepseek-chat',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Sent as `Authorization: Bearer <apiKey>`. |
+| `baseUrl` | no | `https://api.deepseek.com/v1` | Override for proxies / gateways. |
+| `fetch` | no | `globalThis.fetch` | Bring-your-own fetch. |
+| `headers` | no | — | Extra headers merged onto every request. |
+
+## Auth setup
+
+Create a key at <https://platform.deepseek.com/api_keys>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.deepseek.com/v1/chat/completions`
+
+### Notes / quirks
+
+- The OpenAI-compatible endpoint is first-class (the native API).
+- **No strict `json_schema`** — `response_format` supports only `text`/`json_object`; a `json_schema` request degrades to best-effort JSON.
+- `frequency_penalty` / `presence_penalty` are silently ignored; reasoning is exposed via `reasoning_content` (in `raw`).
+
+## Embeddings
+
+DeepSeek exposes no OpenAI-float embeddings surface, so there is no `Embeddings` support — `new Embeddings('deepseek', …)` is a type error and throws `ConnectorError` (`invalid_request`).
+
+## Error mapping & passthrough
+
+- Non-2xx responses throw `ConnectorError` with a 7-value `providerCode` (`auth_failed` / `rate_limited` / `provider_unavailable` / `invalid_request` / `context_length_exceeded` / `content_filtered` / `unknown`). The raw vendor body is on `cause.raw`; retry hints (when present) on `cause.retryAfter` / `cause.retryAfterSeconds`.
+- Sub-baseline features — `topK`, `seed`, `frequency`/`presence_penalty`, `logitBias`, `n`, reasoning control beyond `reasoning.effort`, prompt caching — ride through `_passthrough` (request) / `raw` (result). They are never emulated.
+- Rate-limit guidance: <https://api-docs.deepseek.com/quick_start/rate_limit>.

package/src/providers/fireworks/README.md

@@ -0,0 +1,62 @@
+# Fireworks AI — `@thinwrap/llm`
+
+First-class OpenAI-compatible provider — served by the shared `OpenAICompatConnector` via a row in `src/providers/_shared/spec.ts` (no per-provider connector class). It emits the identical normalized `ChatResult` / `ChatStreamDelta` / `ConnectorError` as every other connector, so switching to/from `fireworks` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('fireworks', { apiKey: process.env.FIREWORKS_API_KEY! });
+const res = await chat.complete({
+  model: 'accounts/fireworks/models/llama-v3p3-70b-instruct',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Sent as `Authorization: Bearer <apiKey>`. |
+| `baseUrl` | no | `https://api.fireworks.ai/inference/v1` | Override for proxies / gateways. |
+| `fetch` | no | `globalThis.fetch` | Bring-your-own fetch. |
+| `headers` | no | — | Extra headers merged onto every request. |
+
+## Auth setup
+
+Create a key at <https://fireworks.ai/account/api-keys>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.fireworks.ai/inference/v1/chat/completions`
+
+### Notes / quirks
+
+- The OpenAI-compatible endpoint **is** the native API (a superset).
+- Model ids are account-namespaced (`accounts/fireworks/models/…`); bare OpenAI names won't resolve.
+- Reasoning chain-of-thought is exposed via `reasoning_content` (in `raw`).
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('fireworks', { apiKey: process.env.FIREWORKS_API_KEY! });
+const out = await emb.create({
+  model: 'nomic-ai/nomic-embed-text-v1.5',
+  input: ['hello', 'world'],
+});
+```
+
+`POST https://api.fireworks.ai/inference/v1/embeddings` with `encoding_format: 'float'`. `dimensions` maps to `dimensions` when set. Vectors are returned in input order on `out.embeddings`.
+
+## Error mapping & passthrough
+
+- Non-2xx responses throw `ConnectorError` with a 7-value `providerCode` (`auth_failed` / `rate_limited` / `provider_unavailable` / `invalid_request` / `context_length_exceeded` / `content_filtered` / `unknown`). The raw vendor body is on `cause.raw`; retry hints (when present) on `cause.retryAfter` / `cause.retryAfterSeconds`.
+- Sub-baseline features — `topK`, `seed`, `frequency`/`presence_penalty`, `logitBias`, `n`, reasoning control beyond `reasoning.effort`, prompt caching — ride through `_passthrough` (request) / `raw` (result). They are never emulated.
+- Rate-limit guidance: <https://docs.fireworks.ai/guides/quotas_usage/rate-limits>.

package/src/providers/gemini/README.md

@@ -0,0 +1,67 @@
+# Google Gemini (AI Studio) — `@thinwrap/llm`
+
+Native adapter for the Gemini `generateContent` API (`generativelanguage.googleapis.com/v1beta`). Gemini uses `contents[]`/`parts[]` (roles `user`/`model`), a top-level `systemInstruction`, and `functionDeclarations`, so this is a full translation layer emitting the identical normalized `ChatResult`/`ChatStreamDelta`/`ConnectorError`. **Streaming is real SSE** (`:streamGenerateContent?alt=sse`) — genuinely incremental, unlike the Bedrock v1 fallback.
+
+> This is the **AI Studio** Gemini API (`gemini` provider id). Vertex AI Gemini is a separate provider (`vertex`, a future connector) with different auth (GCP OAuth/ADC) and endpoints.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('gemini', { apiKey: process.env.GEMINI_API_KEY! });
+const res = await chat.complete({
+  model: 'gemini-2.5-flash',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Sent as `x-goog-api-key`. |
+| `baseUrl` | no | `https://generativelanguage.googleapis.com/v1beta` | Override for proxies. |
+| `defaultMaxTokens` | no | — | `generationConfig.maxOutputTokens` when `maxOutputTokens` is omitted. |
+| `fetch` | no | `globalThis.fetch` | BYO HTTP client. |
+
+## Auth setup
+
+Create an API key in Google AI Studio. It is sent as the `x-goog-api-key` header (the key is not placed in the query string). No environment inference — pass `apiKey` explicitly.
+
+## Chat
+
+### Endpoint
+
+`POST <baseUrl>/models/{model}:generateContent` (non-streaming) and `POST <baseUrl>/models/{model}:streamGenerateContent?alt=sse` (streaming). The model is path-escaped. Default base URL `https://generativelanguage.googleapis.com/v1beta`.
+
+### Notes / quirks
+
+How the normalized shape maps:
+
+- **System message** → top-level `systemInstruction`.
+- **Roles** → `assistant`→`model`, `user`→`user`.
+- **`role: 'tool'` messages** → `functionResponse` parts inside a `user` turn, keyed by function **NAME** (Gemini has no tool-call ids). The name is resolved from the matching prior assistant tool call (`toolCallId`→name), or `message.name`, falling back to `toolCallId`. Consecutive tool messages coalesce into one turn.
+- **Assistant `toolCalls`** → `functionCall` parts; **`tools`** → `[{ functionDeclarations: [...] }]`.
+- **`toolChoice`** → `functionCallingConfig.mode`: `auto`→`AUTO`, `required`→`ANY`, `none`→`NONE`, `{function:{name}}`→`ANY` + `allowedFunctionNames`.
+- **Images** → `{ inlineData: { mimeType, data } }`.
+- **Sampling** → `generationConfig` `{ maxOutputTokens, temperature, topP, stopSequences }`.
+- **`responseFormat`** → **mapped** (unlike Anthropic): `json_object`→`responseMimeType: application/json`; `json_schema`→ that plus `responseSchema` (Gemini honors a JSON-Schema subset).
+- **`reasoning.effort`** → `generationConfig.thinkingConfig.thinkingBudget` (low/medium/high ≈ 1024/8192/24576).
+- **Usage** → `usageMetadata` `{ promptTokenCount, candidatesTokenCount, totalTokenCount }` → `{ inputTokens, outputTokens, totalTokens }`.
+- **`finishReason`** → `STOP`→`stop`, `MAX_TOKENS`→`length`, `SAFETY`/`RECITATION`/etc.→`content_filter`; a `functionCall` part maps to `tool_calls`.
+
+Not normalized (passthrough / raw):
+
+- **Gemini-3 `thought_signature`** round-trip and reasoning CoT output → `raw` / `_passthrough` (the wrapper does not persist or re-send signatures automatically).
+- **Prompt caching** (`cachedContent`), safety settings, and video params → `_passthrough.body`.
+
+## Embeddings
+
+Gemini's native embeddings use a different (non-OpenAI-float) shape, so there is no `Embeddings` support here — `new Embeddings('gemini', …)` throws `ConnectorError` (`invalid_request`). A dedicated embeddings surface is a future connector.
+
+## Error mapping & passthrough
+
+- `ConnectorError.providerCode`: `401/403`→`auth_failed`, `429`→`rate_limited`, `5xx`→`provider_unavailable`, `400/404/422`→`invalid_request` (or `context_length_exceeded`). Gemini emits **no rate-limit headers** — retry timing is parsed from the 429 body's `RetryInfo.retryDelay` into `cause.retryAfterSeconds`. Raw body on `cause.raw`.
+- Provider-specific request fields go through `_passthrough.body` / `.headers` / `.query`; vendor response extras stay on `ChatResult.raw`.
+- Rate-limit guidance: <https://ai.google.dev/gemini-api/docs/rate-limits>.