@thinwrap/llm 1.0.0

package/src/providers/groq/README.md

@@ -0,0 +1,50 @@
+# Groq — `@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 `groq` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('groq', { apiKey: process.env.GROQ_API_KEY! });
+const res = await chat.complete({
+  model: 'llama-3.3-70b-versatile',
+  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.groq.com/openai/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://console.groq.com/keys>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.groq.com/openai/v1/chat/completions`
+
+### Notes / quirks
+
+- **Baseline-exception (handled):** in streaming, token usage is on `x_groq.usage` of the final chunk, not top-level `usage`. The connector relocates it so `ChatStreamDelta.usage` is populated the same as everywhere else (spec `streamUsagePath: 'x_groq'`).
+- Strict JSON-schema structured output is limited to `openai/gpt-oss-*` models and can't combine with streaming or tools; other models are best-effort.
+- Model ids are provider-namespaced (`openai/…`, `meta-llama/…`, `qwen/…`).
+
+## Embeddings
+
+Groq exposes no OpenAI-float embeddings surface, so there is no `Embeddings` support — `new Embeddings('groq', …)` 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://console.groq.com/docs/rate-limits>.

package/src/providers/lmstudio/README.md

@@ -0,0 +1,62 @@
+# LM Studio (self-host) — `@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 `lmstudio` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('lmstudio', {});
+const res = await chat.complete({
+  model: '<loaded-model>',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | no | — | Optional `Authorization: Bearer <apiKey>` (API-token auth since v0.4.0; off by default). |
+| `baseUrl` | no | `http://localhost:1234/v1` | Override for proxies / gateways. |
+| `fetch` | no | `globalThis.fetch` | Bring-your-own fetch. |
+| `headers` | no | — | Extra headers merged onto every request. |
+
+## Auth setup
+
+Local single-user server; auth is off by default (leave `apiKey` empty → no auth header). If you enabled API-token auth, pass the token as `apiKey`; it is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST http://localhost:1234/v1/chat/completions`
+
+### Notes / quirks
+
+- Self-host: local single-user server; override `baseUrl` if not on `:1234`.
+- With a single model loaded, the server ignores the requested model id and serves whatever is loaded.
+- Structured output is grammar-enforced (llama.cpp / MLX); small models can be unreliable.
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('lmstudio', {});
+const out = await emb.create({
+  model: '<embedding-model>',
+  input: ['hello', 'world'],
+});
+```
+
+`POST http://localhost:1234/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://lmstudio.ai/docs/app/api>.

package/src/providers/mistral/README.md

@@ -0,0 +1,61 @@
+# Mistral — `@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 `mistral` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('mistral', { apiKey: process.env.MISTRAL_API_KEY! });
+const res = await chat.complete({
+  model: 'mistral-large-latest',
+  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.mistral.ai/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://console.mistral.ai/api-keys>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.mistral.ai/v1/chat/completions`
+
+### Notes / quirks
+
+- **Baseline-exception (handled):** Mistral 422s on unknown params, so the connector omits OpenAI-only extras like `stream_options`. Keep `_passthrough.body` to known Mistral fields.
+- Model ids are date-stamped (e.g. `-YYMM`).
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('mistral', { apiKey: process.env.MISTRAL_API_KEY! });
+const out = await emb.create({
+  model: 'mistral-embed',
+  input: ['hello', 'world'],
+});
+```
+
+`POST https://api.mistral.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://docs.mistral.ai/admin/user-management-finops/tier>.

package/src/providers/ollama/README.md

@@ -0,0 +1,62 @@
+# Ollama (self-host) — `@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 `ollama` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('ollama', {});
+const res = await chat.complete({
+  model: 'llama3.1:8b',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | no | — | None by default (local server); if set, sent as `Authorization: Bearer <apiKey>`. |
+| `baseUrl` | no* | `http://localhost:11434/v1` | *Required for a non-default host. |
+| `fetch` | no | `globalThis.fetch` | Bring-your-own fetch. |
+| `headers` | no | — | Extra headers merged onto every request. |
+
+## Auth setup
+
+No auth by default — leave `apiKey` empty and no auth header is sent. Override `baseUrl` for a remote host.
+
+## Chat
+
+### Endpoint
+
+`POST http://localhost:11434/v1/chat/completions` (override `baseUrl` for a non-default host).
+
+### Notes / quirks
+
+- Self-host: no auth by default; override `baseUrl` for a non-default host.
+- Model ids are host-local `name:tag` (e.g. `llama3.1:8b`) — a 404 means the model isn't pulled (`ollama pull …`).
+- The `/v1` compat layer is documented-partial (drops `tool_choice`/`logit_bias`/`n`; base64-only images).
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('ollama', {});
+const out = await emb.create({
+  model: 'nomic-embed-text',
+  input: ['hello'],
+});
+```
+
+`POST http://localhost:11434/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.ollama.com/api>.

package/src/providers/openai/README.md

@@ -0,0 +1,62 @@
+# 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 `openai` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('openai', { apiKey: process.env.OPENAI_API_KEY! });
+const res = await chat.complete({
+  model: 'gpt-4o',
+  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.openai.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 an API key at <https://platform.openai.com/api-keys>. It is sent verbatim as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.openai.com/v1/chat/completions`
+
+### Notes / quirks
+
+- The reference provider — its Chat Completions shape is the canonical facade shape.
+- Reasoning models (o-series / GPT-5-class) reject `temperature`/`top_p`/penalties with a hard **HTTP 400** and require `max_completion_tokens` — guard by model family; don't blanket-pass sampling knobs.
+- OpenAI also ships the newer **Responses API**; this connector targets Chat Completions (D1).
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('openai', { apiKey: process.env.OPENAI_API_KEY! });
+const out = await emb.create({
+  model: 'text-embedding-3-small',
+  input: ['hello', 'world'],
+});
+```
+
+`POST https://api.openai.com/v1/embeddings` with `encoding_format: 'float'`. `dimensions` maps to `dimensions` (Matryoshka) 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://platform.openai.com/docs/guides/rate-limits>.

package/src/providers/openrouter/README.md

@@ -0,0 +1,62 @@
+# OpenRouter — `@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 `openrouter` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('openrouter', { apiKey: process.env.OPENROUTER_API_KEY! });
+const res = await chat.complete({
+  model: 'openai/gpt-4o',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Sent as `Authorization: Bearer <apiKey>`. |
+| `baseUrl` | no | `https://openrouter.ai/api/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://openrouter.ai/keys>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://openrouter.ai/api/v1/chat/completions`
+
+### Notes / quirks
+
+- Aggregator: model ids are `{provider}/{model}` (e.g. `anthropic/claude-sonnet-4.5`), with optional `:free`/`:nitro`/`:floor` suffixes.
+- Pass `HTTP-Referer` / `X-Title` via `headers` for app attribution.
+- Drops params an underlying provider lacks (unless `provider.require_parameters` is set via `_passthrough`); `n` is unsupported.
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('openrouter', { apiKey: process.env.OPENROUTER_API_KEY! });
+const out = await emb.create({
+  model: 'openai/text-embedding-3-small',
+  input: ['hello', 'world'],
+});
+```
+
+`POST https://openrouter.ai/api/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://openrouter.ai/docs/api-reference/limits>.

package/src/providers/perplexity/README.md

@@ -0,0 +1,50 @@
+# Perplexity (Sonar) — `@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 `perplexity` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('perplexity', { apiKey: process.env.PERPLEXITY_API_KEY! });
+const res = await chat.complete({
+  model: 'sonar',
+  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.perplexity.ai` | 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://www.perplexity.ai/settings/api>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.perplexity.ai/chat/completions`
+
+### Notes / quirks
+
+- **Baseline-exception (handled):** the Sonar chat surface has **no tool/function calling** (`tools` are not sent); tools live on Perplexity's separate Agent API.
+- Sampling surface is stripped (no `top_k`/penalties/`seed`/`n` on Sonar).
+- Model ids are `sonar` / `sonar-pro` / `sonar-reasoning-pro` / `sonar-deep-research`.
+
+## Embeddings
+
+Perplexity exposes no OpenAI-float embeddings surface, so there is no `Embeddings` support — `new Embeddings('perplexity', …)` 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://docs.perplexity.ai/guides/usage-tiers>.

package/src/providers/together/README.md

@@ -0,0 +1,61 @@
+# Together 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 `together` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('together', { apiKey: process.env.TOGETHER_API_KEY! });
+const res = await chat.complete({
+  model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+  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.together.ai/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://api.together.ai/settings/api-keys>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.together.ai/v1/chat/completions`
+
+### Notes / quirks
+
+- Model ids are namespaced `org/model` slugs — **OpenAI model strings like `gpt-4o` return 404**; use Together's ids.
+- `service_tier`, `store`, `metadata`, `prediction`, and the vision `detail` field are accepted but ignored; `seed` is best-effort.
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('together', { apiKey: process.env.TOGETHER_API_KEY! });
+const out = await emb.create({
+  model: 'BAAI/bge-large-en-v1.5',
+  input: ['hello', 'world'],
+});
+```
+
+`POST https://api.together.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://docs.together.ai/docs/rate-limits>.

package/src/providers/vllm/README.md

@@ -0,0 +1,62 @@
+# vLLM (self-host) — `@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 `vllm` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('vllm', { apiKey: process.env.VLLM_API_KEY! });
+const res = await chat.complete({
+  model: '<served-model-name>',
+  messages: [{ role: 'user', content: 'Say hi in one word.' }],
+});
+```
+
+## Configuration
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | no | — | Optional `Authorization: Bearer <apiKey>` (open if the server has no `--api-key`). |
+| `baseUrl` | no | `http://localhost:8000/v1` | Override for proxies / gateways. |
+| `fetch` | no | `globalThis.fetch` | Bring-your-own fetch. |
+| `headers` | no | — | Extra headers merged onto every request. |
+
+## Auth setup
+
+Open by default. If the server was launched with `--api-key`, pass that value as `apiKey`; it is sent as `Authorization: Bearer <apiKey>`. When `apiKey` is empty, no auth header is sent.
+
+## Chat
+
+### Endpoint
+
+`POST http://localhost:8000/v1/chat/completions`
+
+### Notes / quirks
+
+- Self-host: override `baseUrl` for a remote server; the compat server is vLLM's first-class interface.
+- Model ids are operator-defined (the HF repo id or `--served-model-name`).
+- `tool_choice: 'auto'` requires the server launched with `--enable-auto-tool-choice` + a model-matched `--tool-call-parser`.
+
+## Embeddings
+
+Supported (served by the shared `OpenAICompatEmbeddingsConnector`).
+
+```ts
+import { Embeddings } from '@thinwrap/llm';
+
+const emb = new Embeddings('vllm', { apiKey: process.env.VLLM_API_KEY! });
+const out = await emb.create({
+  model: '<embedding-model>',
+  input: ['hello', 'world'],
+});
+```
+
+`POST http://localhost:8000/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.vllm.ai/en/latest/serving/online_serving/openai_compatible_server/>.

package/src/providers/xai/README.md

@@ -0,0 +1,50 @@
+# xAI (Grok) — `@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 `xai` is just the provider id + `model`.
+
+## Quick start
+
+```ts
+import { Chat } from '@thinwrap/llm';
+
+const chat = new Chat('xai', { apiKey: process.env.XAI_API_KEY! });
+const res = await chat.complete({
+  model: 'grok-4',
+  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.x.ai/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://console.x.ai>. It is sent as `Authorization: Bearer <apiKey>`.
+
+## Chat
+
+### Endpoint
+
+`POST https://api.x.ai/v1/chat/completions`
+
+### Notes / quirks
+
+- Model ids are `grok-*`.
+- xAI positions Chat Completions as a **legacy** endpoint (it steers new work to its own Responses API); this connector targets Chat Completions.
+- In streaming, a tool/function call arrives **whole in a single chunk**, not as incremental argument deltas.
+
+## Embeddings
+
+xAI exposes no OpenAI-float embeddings surface, so there is no `Embeddings` support — `new Embeddings('xai', …)` 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://docs.x.ai/docs/rate-limits>.