@gullabs/xai 0.5.1 → 0.6.1

package/README.md

@@ -58,12 +58,77 @@ const result = await client.generate(
 )
 ```
 
+### Function-calling seam (no agent loop)
+
+```ts
+const tools = [
+  {
+    name: 'get_temperature',
+    description: 'Get current temperature for a location',
+    inputJsonSchema: {
+      type: 'object',
+      properties: { location: { type: 'string' } },
+      required: ['location'],
+    },
+  },
+]
+
+const first = await client.generate(
+  {
+    provider: 'xai',
+    model: 'grok-4.6',
+    messages: [{ role: 'user', parts: [{ kind: 'text', text: 'Temperature in SF?' }] }],
+    tools,
+    toolChoice: 'required',
+  },
+  { auth: { apiKey: 'YOUR_XAI_API_KEY' } },
+)
+// first.finishReason === 'tool_calls'
+// first.toolCalls === [{ toolCallId, toolName, args }]
+
+const call = first.toolCalls![0]!
+const replay = await client.generate(
+  {
+    provider: 'xai',
+    model: 'grok-4.6',
+    messages: [
+      { role: 'user', parts: [{ kind: 'text', text: 'Temperature in SF?' }] },
+      {
+        role: 'assistant',
+        parts: [
+          {
+            kind: 'tool-call',
+            toolCallId: call.toolCallId,
+            toolName: call.toolName,
+            args: call.args,
+          },
+        ],
+      },
+      {
+        role: 'user',
+        parts: [
+          {
+            kind: 'tool-result',
+            toolCallId: call.toolCallId,
+            toolName: call.toolName,
+            result: { temperature: 59 },
+          },
+        ],
+      },
+    ],
+    tools,
+  },
+  { auth: { apiKey: 'YOUR_XAI_API_KEY' } },
+)
+// replay.text — model answer after the host dispatched the tool
+```
+
 ## grok-4.5 and grok-4.6
 
 The default registry ships two canonical models (500k token context window each). They route through this adapter and support:
 
 - **Reasoning** — level-api (`reasoningApi: 'level'`), mapped to the Responses API `reasoning.effort` field. There is no `budgetTokens` field (xAI uses level-style reasoning) — passing it throws `bad_request`. The schema does not set a default effort; if `reasoning` is omitted, no `reasoning` field is sent and xAI's own server-side default (`high`) applies.
-  - `grok-4.5`: `admittedReasoningEfforts: ['low', 'high']`. `'none'`, `'medium'`, and `'xhigh'` are rejected by `Grok45ConfigSchema` (frozen 2026-07-09 live probe; do not silently widen).
+  - `grok-4.5`: `admittedReasoningEfforts: ['low', 'medium', 'high']` (live-verified 2026-08-24; `'medium'` is now accepted). `'none'` and `'xhigh'` are rejected. `'none'` remains rejected ("reasoning cannot be disabled").
   - `grok-4.6`: `admittedReasoningEfforts: ['low', 'medium', 'high', 'xhigh']` (live-verified 2026-08-12). `'none'` is rejected by the live API.
 - **Structured output** — native. `output.jsonSchema` maps to the Responses API's `text.format` field with `{ type: 'json_schema', name, schema, strict: true }`, **not** `response_format` — this differs from OpenAI's own convention for the same underlying concept.
 - **`strict: true` performs no OpenAI-style compile-time schema validation, as of the 2026-07-09 live probes.** 2026-07-09 live verification against the real xAI Responses API — 13 single-variant probes plus 1 combined probe (14 calls total, all accepted HTTP 200; the combined probe is recorded as fixture `10-non-strict-schema-accepted.json`) — verified that `text.format` with `strict: true` accepted every one of the following schema shapes that OpenAI's own strict mode rejects at compile time: schemas (root and nested) missing `additionalProperties: false`; properties omitted from `required` (optional properties); `format`, `minLength`, `pattern`, and `default` keywords; `anyOf`; `$defs`/`$ref`; `enum`/`const`; and nullable unions (`type: [T, 'null']`). `strict: false` on the same surface showed no observed behavioral divergence from `strict: true`. This adapter forwards schemas to xAI verbatim — no rewriting, no preflight validation, and no injection of `additionalProperties: false` or `required` completion — so OpenAI-strict schema rewriting (including `@gullabs/codex-cli`'s `toOpenAiStrictOutputSchema` helper) is unnecessary for xai as of that verification date. (Reject-don't-map still applies to genuinely invalid input the xai schema/types layer itself rejects; this note is only about strict-mode compile-time schema-shape enforcement.) `packages/xai/src/__fixtures__/10-non-strict-schema-accepted.json` records one live example combining three of these — missing root `additionalProperties: false`, an optional property, and a `format` keyword — in a single accepted call.
@@ -85,7 +150,7 @@ const store = new XaiFileStore({
 
 const handle = await store.upload({
   data: pdfBytes,
-  filename: 'matter.pdf',
+  filename: 'document.pdf',
   mimeType: 'application/pdf',
   expiresAfterSeconds: 86_400, // 24h; range 3600…2592000
 })
@@ -116,7 +181,7 @@ try {
 | ZDR teams                   | New uploads and `file_id` attachments are blocked by xAI; errors mention Zero Data Retention when detectable                                                                                                  |
 | Max size                    | 48 MiB (conservative vs docs 48–50 MB)                                                                                                                                                                        |
 
-**Billing note:** attaching files on Responses implicitly enables xAI's `attachment_search` agentic tool. Expect tool-invocation fees and reasoning tokens beyond a plain completion. When xAI returns numeric counters such as `num_server_side_tools_used` / `num_sources_used`, they appear on `usage.details` under those raw names (and full payload in `usage.raw`) for host visibility — they are **not** folded into `computeXaiCost` token lanes yet (no tool Cost lane). Collections / public URL minting are out of scope for this store.
+**Billing note:** attaching files on Responses implicitly enables xAI's `attachment_search` agentic tool. Live 2026-08-24 pins `web_search_calls` and `x_search_calls` in `usage.server_side_tool_usage_details` (flattened into `usage.details`). The attachment_search counter is **not** live-pinned (ZDR blocks file attach on this key); a `file-ref` call sets synthetic `usage.details.attachment_search_unpinned = 1` and `Cost.confidence: 'estimated'` — it is never reported as exact `$0`. `server_tools_requested = 1` is adapter-owned. Missing expected web/X counters → `tools: 0`, `estimated`, plus an adapter warning.
 
 **Host tests:** `@gullabs/testing` exports `FakeXaiFileStore` (in-memory upload/get/delete with optional TTL clock and `failClosed`).
 
@@ -135,7 +200,14 @@ xAI caching is automatic — there is no explicit cache-create/cache-store API c
 
 ## Pricing
 
-`XAI_PRICING` is a frozen, versioned snapshot (`xaiPricingVersion: 'xai-2026-08-12'`) — a point-in-time capture from `/v1/models`, not a live lookup (ADR-005). Rates are in µUSD per million tokens:
+`XAI_PRICING` is a frozen, versioned snapshot (`xaiPricingVersion: 'xai-2026-08-24'`) — a point-in-time capture from `/v1/models`, not a live lookup (ADR-005). Rates are in µUSD per million tokens. Tool invocations add `Cost.details.tools` (`microUsd = input + cached + output + tools`):
+
+| Counter (raw `usage.details` key) | Rate       |
+| --------------------------------- | ---------- |
+| `web_search_calls`                | $5 / 1,000 |
+| `x_search_calls`                  | $5 / 1,000 |
+
+Enable Live Search with `providerOptions.xai.tools` (`web_search` / `x_search`). Citations land on `result.citations`. `countTokens` uses `POST /v1/tokenize-text` and returns `accuracy: 'lower-bound'` (text parts only; media / file parts are `bad_request`).
 
 | Model      | Tier                         | Input   | Cached input | Output   |
 | ---------- | ---------------------------- | ------- | ------------ | -------- |