@gullabs/any-llm 0.7.0 → 0.8.1

package/README.md

@@ -20,15 +20,14 @@ This installs the core engine, Gemini adapter, and `@google/genai`.
 ```ts
 import {
   createClient,
+  composeProviders,
   defaultGeminiRegistry,
   defineCallSite,
-  geminiAdapter,
-  geminiPricingSource,
+  googleProvider,
 } from '@gullabs/any-llm'
 
 const client = createClient({
-  adapters: [geminiAdapter()],
-  pricingSources: { google: geminiPricingSource() },
+  ...composeProviders([googleProvider()]),
 })
 
 const summarize = defineCallSite({
@@ -71,17 +70,20 @@ intended. `priority` remains rejected by the library for now.
 ## Key exports
 
 This package re-exports the full public API of `@gullabs/core` and `@gullabs/google` verbatim —
-`createClient`, `defineCallSite`, `geminiAdapter`, `geminiPricingSource`, `LlmError`, and every
-other named export from both packages. See their READMEs for details:
-
-| Export                  | What it is                                                 |
-| ----------------------- | ---------------------------------------------------------- |
-| `createClient(config)`  | Wires ports into a `{ generate, runStructured }` client    |
-| `defineCallSite(opts)`  | Defines a typed, reusable prompt template bound to a model |
-| `geminiAdapter(opts?)`  | The Gemini `ProviderAdapter`, from `@gullabs/google`       |
-| `geminiPricingSource()` | Built-in Gemini pricing snapshot                           |
-| `LlmError`              | Typed error class — always thrown on call failure          |
-| `ANY_LLM_VERSION`       | This package's version, sourced from `package.json`        |
+`createClient`, `composeProviders`, `defineCallSite`, `googleProvider`, `geminiAdapter`,
+`geminiPricingSource`, `LlmError`, and every other named export from both packages. See their
+READMEs for details:
+
+| Export                      | What it is                                                  |
+| --------------------------- | ----------------------------------------------------------- |
+| `createClient(config)`      | Wires ports into a `{ generate, runStructured }` client     |
+| `composeProviders(plugins)` | Merges `ProviderPlugin`s into `ClientConfig` fields         |
+| `defineCallSite(opts)`      | Defines a typed, reusable prompt template bound to a model  |
+| `googleProvider(opts?)`     | The Gemini `ProviderPlugin` factory, from `@gullabs/google` |
+| `geminiAdapter(opts?)`      | The Gemini `ProviderAdapter`, from `@gullabs/google`        |
+| `geminiPricingSource()`     | Built-in Gemini pricing snapshot, from `@gullabs/google`    |
+| `LlmError`                  | Typed error class — always thrown on call failure           |
+| `ANY_LLM_VERSION`           | This package's version, sourced from `package.json`         |
 
 Use `@gullabs/core` and `@gullabs/google` directly only when you want modular dependency control.
 

package/dist/index.cjs

@@ -6,7 +6,7 @@ var google = require('@gullabs/google');
 // src/index.ts
 
 // package.json
-var version = "0.7.0";
+var version = "0.8.1";
 
 // src/index.ts
 var ANY_LLM_VERSION = version;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";;;;;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,eAAA,GAA0B","file":"index.cjs","sourcesContent":["{\n  \"name\": \"@gullabs/any-llm\",\n  \"version\": \"0.7.0\",\n  \"description\": \"Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/gullabs/any-llm.git\",\n    \"directory\": \"packages/any-llm\"\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"require\": \"./dist/index.cjs\"\n    }\n  },\n  \"files\": [\n    \"dist\",\n    \"skills\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup\"\n  },\n  \"dependencies\": {\n    \"@google/genai\": \"^1.45.0 || ^2\",\n    \"@gullabs/core\": \"workspace:*\",\n    \"@gullabs/google\": \"workspace:*\"\n  },\n  \"engines\": {\n    \"node\": \">=20.9.0\"\n  },\n  \"sideEffects\": false,\n  \"keywords\": [\n    \"llm\",\n    \"gemini\",\n    \"google-genai\",\n    \"ai\",\n    \"tokens\",\n    \"cost\",\n    \"usage\",\n    \"observability\",\n    \"typescript\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"homepage\": \"https://github.com/gullabs/any-llm/tree/main/packages/any-llm#readme\",\n  \"bugs\": \"https://github.com/gullabs/any-llm/issues\"\n}\n","/**\n * @gullabs/any-llm — batteries-included public entrypoint.\n *\n * This package is the default client install path. It re-exports the core\n * engine and Gemini adapter while depending on the Gemini SDK for a one-package\n * setup.\n *\n * @module\n */\n\nexport * from '@gullabs/core'\nexport * from '@gullabs/google'\n\nimport { version } from '../package.json'\n\n/** Library version, sourced from package.json at build time. */\nexport const ANY_LLM_VERSION: string = version\n"]}
+{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";;;;;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,eAAA,GAA0B","file":"index.cjs","sourcesContent":["{\n  \"name\": \"@gullabs/any-llm\",\n  \"version\": \"0.8.1\",\n  \"description\": \"Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/gullabs/any-llm.git\",\n    \"directory\": \"packages/any-llm\"\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"require\": \"./dist/index.cjs\"\n    }\n  },\n  \"files\": [\n    \"dist\",\n    \"skills\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup\"\n  },\n  \"dependencies\": {\n    \"@google/genai\": \"^1.45.0 || ^2\",\n    \"@gullabs/core\": \"workspace:*\",\n    \"@gullabs/google\": \"workspace:*\"\n  },\n  \"engines\": {\n    \"node\": \">=20.9.0\"\n  },\n  \"sideEffects\": false,\n  \"keywords\": [\n    \"llm\",\n    \"gemini\",\n    \"google-genai\",\n    \"ai\",\n    \"tokens\",\n    \"cost\",\n    \"usage\",\n    \"observability\",\n    \"typescript\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"homepage\": \"https://github.com/gullabs/any-llm/tree/main/packages/any-llm#readme\",\n  \"bugs\": \"https://github.com/gullabs/any-llm/issues\"\n}\n","/**\n * @gullabs/any-llm — batteries-included public entrypoint.\n *\n * This package is the default client install path. It re-exports the core\n * engine and Gemini adapter while depending on the Gemini SDK for a one-package\n * setup.\n *\n * @module\n */\n\nexport * from '@gullabs/core'\nexport * from '@gullabs/google'\n\nimport { version } from '../package.json'\n\n/** Library version, sourced from package.json at build time. */\nexport const ANY_LLM_VERSION: string = version\n"]}

package/dist/index.js

@@ -4,7 +4,7 @@ export * from '@gullabs/google';
 // src/index.ts
 
 // package.json
-var version = "0.7.0";
+var version = "0.8.1";
 
 // src/index.ts
 var ANY_LLM_VERSION = version;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";;;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,eAAA,GAA0B","file":"index.js","sourcesContent":["{\n  \"name\": \"@gullabs/any-llm\",\n  \"version\": \"0.7.0\",\n  \"description\": \"Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/gullabs/any-llm.git\",\n    \"directory\": \"packages/any-llm\"\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"require\": \"./dist/index.cjs\"\n    }\n  },\n  \"files\": [\n    \"dist\",\n    \"skills\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup\"\n  },\n  \"dependencies\": {\n    \"@google/genai\": \"^1.45.0 || ^2\",\n    \"@gullabs/core\": \"workspace:*\",\n    \"@gullabs/google\": \"workspace:*\"\n  },\n  \"engines\": {\n    \"node\": \">=20.9.0\"\n  },\n  \"sideEffects\": false,\n  \"keywords\": [\n    \"llm\",\n    \"gemini\",\n    \"google-genai\",\n    \"ai\",\n    \"tokens\",\n    \"cost\",\n    \"usage\",\n    \"observability\",\n    \"typescript\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"homepage\": \"https://github.com/gullabs/any-llm/tree/main/packages/any-llm#readme\",\n  \"bugs\": \"https://github.com/gullabs/any-llm/issues\"\n}\n","/**\n * @gullabs/any-llm — batteries-included public entrypoint.\n *\n * This package is the default client install path. It re-exports the core\n * engine and Gemini adapter while depending on the Gemini SDK for a one-package\n * setup.\n *\n * @module\n */\n\nexport * from '@gullabs/core'\nexport * from '@gullabs/google'\n\nimport { version } from '../package.json'\n\n/** Library version, sourced from package.json at build time. */\nexport const ANY_LLM_VERSION: string = version\n"]}
+{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";;;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,eAAA,GAA0B","file":"index.js","sourcesContent":["{\n  \"name\": \"@gullabs/any-llm\",\n  \"version\": \"0.8.1\",\n  \"description\": \"Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/gullabs/any-llm.git\",\n    \"directory\": \"packages/any-llm\"\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"require\": \"./dist/index.cjs\"\n    }\n  },\n  \"files\": [\n    \"dist\",\n    \"skills\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup\"\n  },\n  \"dependencies\": {\n    \"@google/genai\": \"^1.45.0 || ^2\",\n    \"@gullabs/core\": \"workspace:*\",\n    \"@gullabs/google\": \"workspace:*\"\n  },\n  \"engines\": {\n    \"node\": \">=20.9.0\"\n  },\n  \"sideEffects\": false,\n  \"keywords\": [\n    \"llm\",\n    \"gemini\",\n    \"google-genai\",\n    \"ai\",\n    \"tokens\",\n    \"cost\",\n    \"usage\",\n    \"observability\",\n    \"typescript\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"homepage\": \"https://github.com/gullabs/any-llm/tree/main/packages/any-llm#readme\",\n  \"bugs\": \"https://github.com/gullabs/any-llm/issues\"\n}\n","/**\n * @gullabs/any-llm — batteries-included public entrypoint.\n *\n * This package is the default client install path. It re-exports the core\n * engine and Gemini adapter while depending on the Gemini SDK for a one-package\n * setup.\n *\n * @module\n */\n\nexport * from '@gullabs/core'\nexport * from '@gullabs/google'\n\nimport { version } from '../package.json'\n\n/** Library version, sourced from package.json at build time. */\nexport const ANY_LLM_VERSION: string = version\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gullabs/any-llm",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,8 +25,8 @@
   ],
   "dependencies": {
     "@google/genai": "^1.45.0 || ^2",
-    "@gullabs/core": "0.7.0",
-    "@gullabs/google": "0.7.0"
+    "@gullabs/core": "0.8.0",
+    "@gullabs/google": "0.8.0"
   },
   "engines": {
     "node": ">=20.9.0"

package/skills/any-llm/SKILL.md

@@ -2,31 +2,42 @@
 name: any-llm
 description: >-
   Guidance for writing, reviewing, or debugging TypeScript code that calls
-  @gullabs/any-llm, @gullabs/core, or @gullabs/google to talk to Gemini models.
-  Applies when adding a new LLM call site, wiring createClient/generate/runStructured,
+  @gullabs/any-llm, @gullabs/core, @gullabs/google, or @gullabs/xai to talk to Gemini
+  or xAI Grok models. Applies when adding a new LLM call site, composing provider
+  plugins with composeProviders, wiring createClient/generate/runStructured/countTokens,
   defining a defineCallSite prompt template, requesting structured JSON output,
-  catching or narrowing an LlmError, configuring reasoning/thinking budgets, or wiring
-  a UsageSink for cost tracking. Also applies whenever the user mentions any-llm, the
-  Gemini adapter, Gemini Flex tier, structured-output validation, or per-call auth for
-  this library. Covers the mandatory per-call `{ auth: { apiKey } }` pattern (there is
-  no env-var or ambient auth), the caller-owned output-validation contract, the
-  descriptor-owned strict model-config boundary (`configSchema` / `configJsonSchema`),
-  and the reject-don't-map error philosophy — the things a developer used to other
-  LLM SDKs would otherwise get wrong by default.
+  catching or narrowing an LlmError, configuring reasoning/thinking budgets, wiring a
+  UsageSink for cost tracking, augmenting ProviderOptionsMap for a new provider
+  package, using GoogleCacheStore for Gemini context caching, or migrating raw
+  @google/genai prompts via geminiContentToMessages. Also applies whenever the user
+  mentions any-llm, the Gemini adapter, the xAI/Grok adapter, Gemini Flex tier,
+  structured-output validation, token counting, or per-call auth for this library.
+  Covers the mandatory per-call `{ auth: { apiKey } }` pattern (there is no env-var or
+  ambient auth), the caller-owned output-validation contract, the descriptor-owned
+  strict model-config boundary (`configSchema` / `configJsonSchema`), the
+  provider-qualified `(provider, model)` identity contract, and the reject-don't-map
+  error philosophy — the things a developer used to other LLM SDKs would otherwise get
+  wrong by default.
 ---
 
 # any-llm
 
-Typed, provider-agnostic-by-design (currently Gemini-only) LLM call engine with cost
-tracking, retries, rate limiting, structured output, and per-call observability.
+Typed, provider-agnostic-by-design LLM call engine with cost tracking, retries, rate
+limiting, structured output, and per-call observability. Providers are plugged in
+explicitly via `composeProviders` — nothing is auto-wired.
 
-Three packages:
+Core packages:
 
-- `@gullabs/core` — engine (`createClient`), types, errors, `defineCallSite`.
-- `@gullabs/google` — Gemini adapter (`geminiAdapter`) over `@google/genai`.
-- `@gullabs/any-llm` — batteries-included: re-exports both of the above plus `@google/genai` as a dependency.
+- `@gullabs/core` — engine (`createClient`), types, errors, `defineCallSite`,
+  `composeProviders`.
+- `@gullabs/google` — Gemini + Gemma adapter (`geminiAdapter`) over `@google/genai`.
+- `@gullabs/xai` — xAI Grok adapter (`xaiAdapter`) over the Responses API.
+- `@gullabs/any-llm` — batteries-included: re-exports `@gullabs/core` + `@gullabs/google`
+  plus `@google/genai` as a dependency. Does **not** bundle `@gullabs/xai` or any other
+  provider package — install those separately and compose them alongside.
 
-Install `@gullabs/any-llm` for a one-package setup, or the two modular packages for
+Install `@gullabs/any-llm` for a one-package Gemini setup, or `@gullabs/core` plus
+whichever provider package(s) you need (`@gullabs/google`, `@gullabs/xai`, ...) for
 explicit dependency control. Import names are identical either way.
 
 ## #1 gotcha: auth is per-call, always
@@ -39,8 +50,7 @@ explicitly. `createClient()` itself takes no credentials.
 // WRONG — GenerateOptions.auth is a required field; this will not type-check, and if
 // bypassed with `as any` it throws LlmError({ kind: 'invalid_auth' }) before any I/O.
 const client = createClient({
-  adapters: [geminiAdapter()],
-  pricingSources: { google: geminiPricingSource() },
+  ...composeProviders([googleProvider()]),
 })
 await client.generate(request, {} as GenerateOptions)
 
@@ -69,12 +79,12 @@ same bare model id can exist under multiple providers with different config sche
 ## Quickstart
 
 ```ts
-import { createClient, geminiPricingSource, geminiAdapter } from '@gullabs/any-llm'
-// (or: from '@gullabs/core' / '@gullabs/google' respectively, if using modular install)
+import { createClient, composeProviders, googleProvider } from '@gullabs/any-llm'
+// (or: composeProviders from '@gullabs/core', googleProvider from '@gullabs/google',
+// if using modular install)
 
 const client = createClient({
-  adapters: [geminiAdapter()],
-  pricingSources: { google: geminiPricingSource() },
+  ...composeProviders([googleProvider()]),
 })
 
 const result = await client.generate(
@@ -95,6 +105,130 @@ console.log(result.cost?.microUsd) // integer micro-USD, or null if unpriced
 `{ kind: 'text', text }`, `{ kind: 'inline-media', mimeType, data /* raw base64, no data: prefix */ }`,
 and `{ kind: 'file-uri', uri, mimeType }` freely in one `parts` array.
 
+## Counting tokens without generating
+
+`client.countTokens` is a metadata-only dry run — no generation, no cost, no
+`result.output`. Same `(provider, model)` routing and required `auth` as `generate`;
+throws `LlmError('bad_request')` when the pair is unregistered or the resolved adapter
+doesn't implement token counting (`ProviderAdapter.countTokens` is optional).
+
+```ts
+const count = await client.countTokens(
+  {
+    provider: 'google',
+    model: 'gemini-2.5-flash',
+    system: 'You are a concise summarizer.',
+    messages: [{ role: 'user', parts: [{ kind: 'text', text: 'Hello!' }] }],
+  },
+  { auth: { apiKey: myResolvedGeminiKey } },
+)
+
+console.log(count.totalTokens) // number
+console.log(count.details) // optional per-category breakdown, e.g. { cached: 128 }
+console.log(count.raw) // provider's raw token-count response, verbatim
+```
+
+`TokenCountRequest` is deliberately narrower than a generate request — no `config`, no
+`output`, no `providerOptions`; token counting only needs `provider`, `model`,
+`system`, and `messages`.
+
+## Composing multiple providers — xAI Grok example
+
+`composeProviders` takes any number of plugins; pass every provider a single client
+should route to. `@gullabs/xai`'s `xaiProvider()` follows the identical plugin shape
+as `googleProvider()`:
+
+```ts
+import { createClient, composeProviders } from '@gullabs/core'
+import { googleProvider } from '@gullabs/google'
+import { xaiProvider } from '@gullabs/xai'
+
+const client = createClient({
+  ...composeProviders([googleProvider(), xaiProvider()]),
+})
+
+const result = await client.generate(
+  {
+    provider: 'xai',
+    model: 'grok-4.5',
+    messages: [{ role: 'user', parts: [{ kind: 'text', text: 'Hello, Grok.' }] }],
+    config: { reasoning: { effort: 'high' } },
+  },
+  { auth: { apiKey: myResolvedXaiKey } },
+)
+```
+
+`grok-4.5`'s `reasoning.effort` admits only `'low' | 'high'` (live-verified) —
+`'none'`, `'medium'`, and `'xhigh'` are rejected by both the live API and
+`Grok45ConfigSchema`. Unlike Gemini, xai has no `serviceTier` concept and no `topK`;
+its config schema is a single strict object with no tier branching.
+
+## xAI structured-output schemas vs. OpenAI-strict / codex-cli schemas
+
+As of the 2026-07-09 live probes, xAI's `strict: true` structured-output validation
+on `text.format` json_schema performed no OpenAI-style compile-time schema checks —
+schemas missing root/nested `additionalProperties: false`, properties omitted from
+`required` (optional properties), `format`/other keywords, `anyOf`, `$defs`/`$ref`,
+and nullable unions (`type: [T, 'null']`) were all accepted with HTTP 200.
+`@gullabs/xai`'s adapter forwards schemas to xAI verbatim; no rewriting is applied.
+
+`@gullabs/codex-cli`, by contrast, targets the codex CLI's own `--output-schema`
+backend, which (verified 2026-07-09 via live probes against the real codex CLI
+binary/backend) enforces exactly two structural rules: every object node must carry
+`additionalProperties: false`, and `required` must be present and include every key
+in `properties` (optional semantics are preserved by adding `null` to that
+property's type, not by simply marking it required). `@gullabs/codex-cli` exports
+`toOpenAiStrictOutputSchema` — an explicit opt-in transformer, never called
+automatically by the adapter — that rewrites a schema to satisfy those two rules.
+codex-cli's local preflight (`assertOpenAiStrictOutputSchema` in
+`packages/codex-cli/src/adapter.ts`) enforces both rules locally before dispatch,
+turning what used to be a live-round-trip provider 400 into an immediate local
+`bad_request`.
+
+This preflight/transformer pair is specific to codex-cli's own `--output-schema`
+contract, not a general any-llm behavior — it is not applied to xai, which has no
+such preflight (see the xAI Grok section above).
+
+## Migrating raw `@google/genai` prompts
+
+`geminiContentToMessages` (from `@gullabs/google`) converts hand-authored
+`@google/genai` `Content[]` into any-llm's normalized `{ system?, messages }` shape.
+Reject-don't-map: a missing/unrecognized `Content.role` (only `'user'` and `'model'`
+are accepted, never inferred), a `systemInstruction` containing anything other than
+plain text parts, or any `Part` sub-field this library can't losslessly represent
+(function calls, executable code, tool results, thought-flagged parts,
+`thoughtSignature`, unknown future fields, etc.) throws `LlmError('bad_request')`
+naming the offending field — nothing is ever silently dropped.
+
+```ts
+import { geminiContentToMessages } from '@gullabs/google'
+import type { Content } from '@google/genai'
+
+const contents: Content[] = [
+  {
+    role: 'user',
+    parts: [
+      { text: 'Describe this image.' },
+      { inlineData: { mimeType: 'image/png', data } },
+    ],
+  },
+  { role: 'model', parts: [{ text: 'A red bicycle leaning against a brick wall.' }] },
+]
+
+const { system, messages } = geminiContentToMessages({
+  contents,
+  systemInstruction: 'You are a concise visual describer.',
+})
+
+const result = await client.generate(
+  { provider: 'google', model: 'gemini-2.5-pro', system, messages },
+  { auth: { apiKey: myResolvedGeminiKey } },
+)
+```
+
+`system` is derived only from the explicit `systemInstruction` input — never inferred
+from `contents`.
+
 ## `defineCallSite` — reusable prompt templates
 
 ```ts
@@ -125,7 +259,7 @@ the selected descriptor's strict runtime schema before dispatch.
 Treat model config as descriptor-owned:
 
 ```ts
-import { defaultGeminiRegistry } from '@gullabs/core'
+import { defaultGeminiRegistry } from '@gullabs/google'
 
 const descriptor = defaultGeminiRegistry.resolve('google', 'gemini-3.5-flash')
 if (!descriptor) throw new Error('unknown model')
@@ -148,6 +282,47 @@ Important distinctions:
 - `providerOptions.google` is a typed provider-extension lane, not a caller-wins
   override lane for `serviceTier`, sampling, reasoning, or response schema.
 
+## Extending `ProviderOptionsMap` for a third-party provider
+
+`GenConfig.providerOptions` is typed as `ProviderOptions`, an alias for
+`ProviderOptionsMap` — an empty, augmentable interface owned by `@gullabs/core`. It
+carries no keys until a provider package augments it via TypeScript declaration
+merging. `@gullabs/google` and `@gullabs/xai` are the two reference implementations
+(`packages/google/src/types.ts`, `packages/xai/src/types.ts`):
+
+```ts
+declare module '@gullabs/core' {
+  interface ProviderOptionsMap {
+    google?: GoogleProviderOptions
+  }
+}
+```
+
+A third-party provider package follows the identical pattern. For a hypothetical
+`@acme/my-provider` package:
+
+```ts
+// packages/my-provider/src/types.ts
+export type MyProviderOptions = {
+  someAllowlistedKnob?: string
+}
+
+declare module '@gullabs/core' {
+  interface ProviderOptionsMap {
+    myProvider?: MyProviderOptions
+  }
+}
+```
+
+Importing anything from that module — even a type-only import — pulls in the
+augmentation, so re-export it unconditionally from the package's `index.ts` (the way
+`packages/google/src/index.ts` and `packages/xai/src/index.ts` both do) to guarantee
+the `myProvider` key is visible on `ProviderOptionsMap` whenever a caller imports
+anything from the package. Once loaded, `config.providerOptions.myProvider`
+type-checks at call sites — but the model's `configSchema` must also allowlist that
+key for the value to survive validation; the Zod schema remains the runtime boundary,
+the type augmentation only makes the shape visible to the compiler.
+
 ## Structured output — auth + validation together
 
 `request.output = { jsonSchema }` (or `callSite.jsonSchema`) is forwarded to the
@@ -156,12 +331,11 @@ response and sets `outputParsed`; `result.output` is always `unknown`. **The cal
 owns shape validation** — this library does not validate output shape itself.
 
 ```ts
-import { createClient, geminiPricingSource, geminiAdapter } from '@gullabs/any-llm'
+import { createClient, composeProviders, googleProvider } from '@gullabs/any-llm'
 import type { StandardSchemaV1 } from '@gullabs/core'
 
 const client = createClient({
-  adapters: [geminiAdapter()],
-  pricingSources: { google: geminiPricingSource() },
+  ...composeProviders([googleProvider()]),
 })
 
 const result = await client.generate(
@@ -273,6 +447,47 @@ Exact model reminders:
 - Omit `serviceTier` for provider-standard; set `flex` explicitly
 - `priority` remains rejected by the library even though Google documents it
 
+## Context caching — `GoogleCacheStore`
+
+`GoogleCacheStore` (from `@gullabs/google`) is a thin, **process-scoped** wrapper over
+the Gemini Context Cache API (`create` / `getOrCreate` / `refreshIfExpiringSoon` /
+`delete`). Pass the resulting `cacheName` as `providerOptions.google.cachedContent` on
+a request. Reuse is only within this store instance's in-memory map — it is not
+shared across processes, workers, or restarts.
+
+Optional preflight gate: pass `preflight` to the constructor to refuse a cache
+`create()` — including through `getOrCreate()` and its coalesced in-flight path —
+when the token-bearing payload (`model` + `contents` + `systemInstruction` only;
+`ttl` and `displayName` are excluded) doesn't clear a minimum token count. This
+mirrors Gemini's own explicit-caching minimum (2048 tokens on 3.x) without
+hard-coding it into the store.
+
+```ts
+import { GoogleCacheStore } from '@gullabs/google'
+
+const cacheStore = new GoogleCacheStore({
+  auth: { apiKey: myResolvedGeminiKey },
+  preflight: {
+    minTokens: 2048,
+    // Receives genai-native Content[]/Content|string — NOT the library's
+    // Message[] shape; there is no automatic conversion. Hosts building from
+    // Message[] should call client.countTokens separately instead.
+    countTokens: async (payload) => {
+      const result = await genaiClient.models.countTokens(payload)
+      return result.totalTokens ?? 0
+    },
+  },
+})
+
+const handle = await cacheStore.create({
+  model: 'gemini-3.1-pro-preview',
+  ttlSeconds: 3600,
+  contents: myGenaiContents,
+})
+// Throws LlmError('bad_request') before any I/O if preflight.countTokens resolves
+// below minTokens — nothing is silently allowed through under the minimum.
+```
+
 ## Rate limiting and cost tracking
 
 - Pre-send backpressure is a `RateLimiter` port (`ClientConfig.rateLimiter`); default