@gullabs/xai 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+import { AuthMaterial, LlmError, ProviderAdapter, ModelDescriptor, ModelRegistry, Usage, Cost, PricingSource, ProviderPlugin } from '@gullabs/core';
+import { z } from 'zod';
+
+/**
+ * xAI-specific provider options for `@gullabs/xai`.
+ *
+ * Importing anything from this module (including this type-only re-export)
+ * pulls in the `declare module '@gullabs/core'` augmentation below, which
+ * adds the `xai` key to `ProviderOptionsMap`. `packages/xai/src/index.ts`
+ * re-exports these types unconditionally so the augmentation always loads
+ * when anything is imported from `@gullabs/xai`.
+ *
+ * @module
+ */
+type XaiProviderOptions = {
+    /** xAI conversation-routing cache key — maps to Responses API `prompt_cache_key`. */
+    promptCacheKey?: string;
+};
+declare module '@gullabs/core' {
+    interface ProviderOptionsMap {
+        xai?: XaiProviderOptions;
+    }
+}
+
+/**
+ * Structural XaiClientLike interface + buildXaiClient factory.
+ *
+ * This module defines the structural interface the adapter depends on.
+ * The real `openai` SDK is imported ONLY in buildXaiClient so tests can
+ * inject a fake without pulling in the real SDK. This is the ONLY file in
+ * `packages/xai/src` that imports `openai`.
+ *
+ * @module
+ */
+
+/**
+ * Narrows {@link AuthMaterial} to its `apiKey` string, rejecting the
+ * dev-only `CliSessionAuth` variant.
+ *
+ * xAI is a production API provider and only ever accepts API-key
+ * credentials; `{ cliSession: true }` is reserved for the dev-only CLI
+ * provider packages (`@gullabs/claude-cli`, `@gullabs/codex-cli`).
+ */
+declare function requireApiKey(auth: AuthMaterial): string;
+/** A text content item within an xAI Responses API input message. */
+interface XaiInputTextPart {
+    type: 'input_text';
+    text: string;
+}
+/**
+ * An image content item within an xAI Responses API input message.
+ * `image_url` may be a data URL (`data:image/png;base64,...`) or a public URL.
+ */
+interface XaiInputImagePart {
+    type: 'input_image';
+    image_url: string;
+}
+/** Union of content-part shapes an input message may carry. */
+type XaiInputContentPart = XaiInputTextPart | XaiInputImagePart;
+/** A single role+content input item constructed by the (future) adapter. */
+interface XaiInputItem {
+    role: 'user' | 'assistant' | 'system' | 'developer';
+    content: XaiInputContentPart[];
+}
+/**
+ * Structured-output text-format request shape.
+ * Real xAI field: `text.format`, NOT `response_format`.
+ * `name` and `strict` are included per xAI's Structured Outputs docs
+ * conventions even though the live fixture's request-echo does not surface
+ * them (only the schema is echoed back).
+ */
+type XaiTextFormat = {
+    type: 'json_schema';
+    name: string;
+    schema: unknown;
+    strict: boolean;
+} | {
+    type: 'text';
+};
+/**
+ * Parameters for `client.responses.create`.
+ * Structurally modeled from live-captured xAI Responses API fixtures
+ * (see docs/provider-plugins-and-xai-grok-4-5-plan.md §3.1), not from the
+ * `openai` npm package's TS types — xAI's actual endpoint shape differs.
+ */
+interface XaiResponseCreateParams {
+    model: string;
+    input: XaiInputItem[];
+    instructions?: string;
+    reasoning?: {
+        effort: 'low' | 'high';
+    };
+    text?: {
+        format: XaiTextFormat;
+    };
+    temperature?: number;
+    top_p?: number;
+    max_output_tokens?: number;
+    prompt_cache_key?: string;
+    /** Always `false` — this library never relies on xAI-side conversation storage. */
+    store: false;
+}
+/** A single summary-text segment of a `type: 'reasoning'` output item. */
+interface XaiReasoningSummaryPart {
+    type: 'summary_text';
+    text: string;
+}
+/** A `type: 'reasoning'` item in `output`. */
+interface XaiReasoningOutputItem {
+    type: 'reasoning';
+    id?: string;
+    summary: XaiReasoningSummaryPart[];
+    status?: string;
+}
+/** A single text content segment of a `type: 'message'` output item. */
+interface XaiOutputTextPart {
+    type: 'output_text';
+    text: string;
+    logprobs?: unknown[];
+    annotations?: unknown[];
+}
+/** A `type: 'message'` item in `output`. */
+interface XaiMessageOutputItem {
+    type: 'message';
+    id?: string;
+    role?: string;
+    status?: string;
+    content: XaiOutputTextPart[];
+}
+/** Union of output-item shapes the Responses API may return. */
+type XaiOutputItem = XaiReasoningOutputItem | XaiMessageOutputItem;
+/**
+ * Token usage metadata returned alongside an xAI response.
+ *
+ * Kept loose/open: the known fields are typed, but xAI has been observed to
+ * add additional numeric fields (e.g. `num_sources_used`,
+ * `cost_in_usd_ticks`, `context_details`) that must not break this type.
+ */
+interface XaiUsageShape {
+    input_tokens: number;
+    input_tokens_details?: {
+        cached_tokens?: number;
+    };
+    output_tokens: number;
+    output_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+    total_tokens?: number;
+    /** Additional provider-specific usage fields, passed through raw. */
+    [otherKeys: string]: unknown;
+}
+/**
+ * Structural equivalent of the xAI Responses API response body.
+ * Only the fields the (future) adapter reads are represented here.
+ */
+interface XaiResponseShape {
+    id: string;
+    model: string;
+    /**
+     * Real field: `status`. Observed values: "completed", "incomplete" — kept
+     * as a plain `string` since xAI may add further status values over time.
+     */
+    status: string;
+    incomplete_details?: {
+        reason?: string;
+    } | null;
+    output: XaiOutputItem[];
+    usage: XaiUsageShape;
+    reasoning?: {
+        effort?: string;
+        summary?: string;
+    };
+    store?: boolean;
+    prompt_cache_key?: string | null;
+    /**
+     * Response-level metadata (e.g. `system_fingerprint`) — surfaced into
+     * `AdapterResult.providerMetadata` by the adapter when present.
+     */
+    metadata?: {
+        [key: string]: unknown;
+    } | null;
+}
+/**
+ * Structural interface for the `openai` SDK's `client.responses` surface
+ * the adapter uses.
+ *
+ * Satisfied by:
+ * - The real `openai` `OpenAI` client (via `buildXaiClient` wrapper), pointed
+ *   at xAI's `https://api.x.ai/v1` base URL.
+ * - `FakeXaiClient` from `@gullabs/testing`.
+ */
+interface XaiClientLike {
+    responses: {
+        create(params: XaiResponseCreateParams, options?: {
+            signal?: AbortSignal;
+        }): Promise<XaiResponseShape>;
+    };
+}
+/**
+ * Build a real `openai`-SDK-backed client from AuthMaterial, pointed at
+ * xAI's Responses API endpoint.
+ *
+ * Only API-key authentication is supported.
+ *
+ * @param auth - API key credentials ({ apiKey }).
+ */
+declare function buildXaiClient(auth: AuthMaterial): Promise<XaiClientLike>;
+
+/**
+ * xaiAdapter — @gullabs/xai xAI Grok provider adapter.
+ *
+ * Pure request⇄response mapping over the xAI Responses API (via
+ * XaiClientLike). Never persists, never computes cost, never loops.
+ *
+ * @module
+ */
+
+/**
+ * Classify a raw error thrown from the xAI Responses API call into a typed
+ * {@link LlmError}.
+ *
+ * xAI's Responses API returns HTTP 400 (NOT 401) for an invalid API key, so
+ * generic {@link classifyHttpStatus}-based classification (which maps 400 →
+ * `bad_request`) is wrong for this one case. This function special-cases it:
+ * a 400 response whose STRUCTURED parsed body matches the exact recorded
+ * xAI auth-failure signature (`code: 'invalid-argument'` AND message prefix
+ * `"Incorrect API key provided"` — see fixture 09) is reclassified as
+ * `invalid_auth`. Free-form `Error.message` text is never scanned, so a 400
+ * whose message merely *mentions* an API key (e.g. schema validation echoing
+ * user content) stays `bad_request`. When the structured body is unavailable
+ * or unparseable, classification falls through to the status-based
+ * `classifyError` from `@gullabs/core`.
+ */
+declare function classifyXaiError(rawErr: unknown): LlmError;
+interface XaiAdapterOptions {
+    /**
+     * Inject a pre-built client (real or fake).
+     * When omitted, `buildXaiClient` is called with `ctx.auth` at call time,
+     * inside the classified try/catch so any construction failure is wrapped
+     * as a typed `LlmError`.
+     */
+    client?: XaiClientLike;
+    /**
+     * @internal Testing-only.
+     *
+     * Override the default `buildXaiClient` factory. Allows unit tests to
+     * simulate construction failures without importing the real `openai` SDK.
+     * Never set this in production code. Mirrors `GeminiAdapterOptions._clientFactory`.
+     */
+    _clientFactory?: (auth: AuthMaterial) => XaiClientLike | Promise<XaiClientLike>;
+}
+/**
+ * Create an xAI Grok provider adapter (Responses API).
+ *
+ * @param opts.client - Optional pre-built client (e.g. for testing).
+ */
+declare function xaiAdapter(opts?: XaiAdapterOptions): ProviderAdapter;
+
+/**
+ * Strict Zod config schema for xAI's `grok-4.5` model.
+ *
+ * Mirrors `@gullabs/core`'s `packages/core/src/model-config/*.ts` doc-density
+ * style, but is a single self-contained `z.strictObject` — unlike Gemini's
+ * schemas, xai has no service-tier branching (no `z.union` of tier variants
+ * needed), no `topK`, and only a single reasoning-effort union (`'low'|'high'`).
+ *
+ * @module
+ */
+
+declare const Grok45ConfigSchema: z.ZodObject<{
+    temperature: z.ZodOptional<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoning: z.ZodOptional<z.ZodObject<{
+        effort: z.ZodEnum<{
+            low: "low";
+            high: "high";
+        }>;
+    }, z.core.$strict>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    providerOptions: z.ZodOptional<z.ZodObject<{
+        xai: z.ZodOptional<z.ZodObject<{
+            promptCacheKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+/**
+ * Model descriptor + registry for @gullabs/xai.
+ *
+ * v1 ships exactly one model: `grok-4.5` (canonical id only — the
+ * `grok-4.5-latest` / `grok-build-latest` aliases visible in xAI's
+ * `/v1/models` listing are intentionally NOT registered as separate
+ * descriptors; reject-don't-map, callers must use `grok-4.5` verbatim).
+ *
+ * @module
+ */
+
+declare const grok45ModelDescriptor: ModelDescriptor;
+/** Every model descriptor `@gullabs/xai` contributes. v1 ships only grok-4.5. */
+declare const xaiModelDescriptors: ModelDescriptor[];
+declare const xaiRegistry: ModelRegistry;
+
+/**
+ * xAI pricing snapshot + cost computation for @gullabs/xai.
+ *
+ * All rates are in **micro-USD per million tokens** (µUSD/M), matching
+ * `@gullabs/core`'s `ModelRates` convention exactly: `cost_µUSD = N *
+ * ratePerM / 1_000_000`.
+ *
+ * This is a SELF-CONTAINED, xai-owned reimplementation — it does NOT import
+ * core's Gemini-specific `computeCost`/`GEMINI_PRICING`/`geminiPricingSource`
+ * (those are Gemini-only). `PricingSource` is provider-scoped by contract
+ * (see `packages/core/src/ports.ts`); this module is xai's own.
+ *
+ * **Long-context tier.** grok-4.5 charges a premium when the GROSS input
+ * token count exceeds 200,000 (`long_context_threshold` in xAI's
+ * `/v1/models` listing). Selected by `inputTokens` (incl. cached), not by
+ * billable input — mirrors core's `selectRates` convention exactly (strictly
+ * greater than 200,000).
+ *
+ * **Service tiers.** xAI has no service-tier concept for grok-4.5 — there is
+ * no `TIER_FACTOR`-equivalent here. `price()`'s `tier` param is accepted for
+ * `PricingSource` structural conformance but any *defined* tier is treated
+ * as unrecognized → unpriced (reject-don't-map), mirroring core's own
+ * defensive stance for an unrecognized tier. `undefined` (no tier requested,
+ * the only value xAI adapters ever pass — `xaiAdapter` rejects `serviceTier`
+ * upstream) prices normally.
+ *
+ * **Conversion factor.** xAI's `/v1/models` raw `*_token_price` fields are
+ * in hundred-thousandths of a dollar per token (i.e. divide the raw integer
+ * by 10,000 to get USD per million tokens): e.g. `grok-4.5`'s raw
+ * `prompt_text_token_price: 20000` ÷ 10,000 = $2.00/M, which matches the
+ * confirmed live-verified figure.
+ *
+ * Verified against `/v1/models` fixture captured 2026-07-09 (see
+ * `docs/provider-plugins-and-xai-grok-4-5-plan.md` and the live-verification
+ * fixture directory referenced in the commit-3 task brief).
+ *
+ * @module
+ */
+
+/** Identifies this pricing snapshot — bump the date when rates change. */
+declare const xaiPricingVersion: "xai-2026-07-09";
+/**
+ * Per-model rate entry (all values in µUSD per million tokens).
+ *
+ * `gt200k` (when present) applies when GROSS input tokens > 200,000.
+ */
+interface XaiModelRates {
+    /** µUSD per million input tokens (billable = gross − cached). */
+    inputPerM: number;
+    /** µUSD per million cache-read tokens. */
+    cachedPerM: number;
+    /** µUSD per million output tokens (reasoning tokens are folded in). */
+    outputPerM: number;
+    /** Optional high-tier rates for long-context (GROSS input > 200k). */
+    gt200k?: {
+        inputPerM: number;
+        cachedPerM: number;
+        outputPerM: number;
+    };
+}
+/**
+ * Frozen xAI pricing snapshot (per-1M in µUSD).
+ *
+ * Keys are EXACT canonical model identifiers — no prefix or alias matching.
+ * xAI aliases (e.g. `grok-4.5-latest`, `grok-build-latest`) are deliberately
+ * NOT registered/priced (reject-don't-map): callers must use the canonical
+ * id; anything else resolves to the unpriced path.
+ */
+declare const XAI_PRICING: Readonly<Record<string, XaiModelRates>>;
+/**
+ * Compute the cost of an xAI LLM call given a model name and usage data.
+ *
+ * Pure function — no side effects, always returns a well-formed {@link Cost}.
+ *
+ * **Algorithm** (mirrors `@gullabs/core`'s `computeCost` exactly, xai-owned):
+ * 1. Look up rates for `model`; if not found, return an unpriced `Cost`
+ *    (`microUsd: null`) naming the model.
+ * 2. A defined `tier` is always unpriced (xai has no tiers; reject-don't-map).
+ *    `undefined` prices normally.
+ * 3. Select base vs. `>200k` long-context rates from GROSS `inputTokens`.
+ * 4. Billable input = `inputTokens − (cachedInputTokens ?? 0)`, clamped to 0.
+ * 5. Round each component (input, cached, output) independently to the
+ *    nearest integer micro-USD.
+ * 6. `microUsd` is the sum of the three components — guarantees
+ *    `details.input + details.cached + details.output === microUsd` exactly.
+ */
+declare function computeXaiCost(model: string, usage: Usage, tier?: string): Cost;
+/**
+ * Factory that returns the **xai-scoped** {@link PricingSource} port
+ * implementation backed by {@link XAI_PRICING}.
+ *
+ * @example
+ * ```ts
+ * import { xaiPricingSource } from '@gullabs/xai'
+ *
+ * const pricing = xaiPricingSource()
+ * const cost = pricing.price('grok-4.5', usage)
+ * ```
+ */
+declare function xaiPricingSource(): PricingSource;
+
+/**
+ * `xaiProvider` — {@link ProviderPlugin} factory for @gullabs/xai.
+ *
+ * Bundles the xAI Grok adapter, the `grok-4.5` model descriptor, and the
+ * xai pricing source into a single plugin for {@link composeProviders}.
+ *
+ * @module
+ */
+
+/**
+ * Create a {@link ProviderPlugin} for the xAI Grok provider.
+ *
+ * @param opts - Forwarded to {@link xaiAdapter}.
+ * @returns A plugin bundling the xAI adapter, the `grok-4.5` model
+ *   descriptor, and the built-in xai pricing source.
+ *
+ * @example
+ * ```ts
+ * import { createClient, composeProviders } from '@gullabs/core'
+ * import { xaiProvider } from '@gullabs/xai'
+ *
+ * const client = createClient({
+ *   ...composeProviders([xaiProvider()]),
+ * })
+ * ```
+ */
+declare function xaiProvider(opts?: XaiAdapterOptions): ProviderPlugin;
+
+export { Grok45ConfigSchema, XAI_PRICING, type XaiAdapterOptions, type XaiClientLike, type XaiInputContentPart, type XaiInputImagePart, type XaiInputItem, type XaiInputTextPart, type XaiMessageOutputItem, type XaiModelRates, type XaiOutputItem, type XaiOutputTextPart, type XaiProviderOptions, type XaiReasoningOutputItem, type XaiReasoningSummaryPart, type XaiResponseCreateParams, type XaiResponseShape, type XaiTextFormat, type XaiUsageShape, buildXaiClient, classifyXaiError, computeXaiCost, grok45ModelDescriptor, requireApiKey, xaiAdapter, xaiModelDescriptors, xaiPricingSource, xaiPricingVersion, xaiProvider, xaiRegistry };