@seanhogg/builderforce-sdk 0.9.0 → 2026.6.30

package/dist/index.d.cts

@@ -8,19 +8,37 @@ type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
  * upstream — e.g. all `openrouter` means a saturated shared key, not a
  * model-specific issue.
  */
+/**
+ * Coarse failure class for one failover attempt. Branch on this instead of
+ * regex-sniffing the error message. `'schema'` means the upstream rejected the
+ * `response_format.json_schema` as too complex for its constrained-decoding
+ * engine (see `FailoverEvent.reason === 'schema_too_complex'`); `'content_filter'`
+ * means a safety system blocked the generation. Open string union for
+ * forward-compat — a newer gateway may add classes an older SDK doesn't list.
+ */
+type FailoverKind = 'rate_limit' | 'timeout' | 'auth' | 'server_error' | 'client_error' | 'schema' | 'content_filter' | 'network' | 'skipped' | (string & {});
 interface FailoverEvent {
     model: string;
-    /** `'openrouter' | 'cerebras' | 'nvidia' | 'ollama'` */
+    /** `'openrouter' | 'cerebras' | 'nvidia' | 'ollama' | 'googleai' | …` */
     vendor: string;
-    /** HTTP status code, or 0 for embedded errors / network failures. */
+    /** Gateway-normalized status, or 0 for embedded errors / network failures.
+     *  For a schema rejection this is `422` (the request-error class); the REAL
+     *  upstream status is in `upstreamStatus`. */
     code: number;
     /** Wall-clock time the gateway spent on this attempt, ms. Present on newer
      *  gateway versions; absent on older ones. */
     durationMs?: number;
-    /** Coarse failure class — `'rate_limit' | 'timeout' | 'auth' | 'server_error'
-     *  | 'client_error' | 'network' | 'skipped'`. The full upstream error text is
-     *  NOT exposed to callers; quote `traceId` to support for that. */
-    kind?: string;
+    /** Coarse failure class — see {@link FailoverKind}. The full upstream error
+     *  text is NOT exposed to callers; quote `traceId` to support for that. */
+    kind?: FailoverKind;
+    /** Stable machine-readable cause slug when one applies — e.g.
+     *  `'schema_too_complex'`. Branch on this for structured handling instead of
+     *  parsing `message`. Absent for unclassified failures. */
+    reason?: string;
+    /** The REAL upstream HTTP status before the gateway normalized it into `code`
+     *  — e.g. a Gemini schema 400 surfaces as `code: 422` with `upstreamStatus: 400`.
+     *  Absent when `code` already IS the upstream status. */
+    upstreamStatus?: number;
 }
 interface TextContentPart {
     type: 'text';
@@ -153,9 +171,15 @@ interface ChatCompletionCreateParams extends PerCallOptions {
      *  gateway-side schema validation with retry across the failover chain. */
     response_format?: ResponseFormat;
     /**
-     * Opaque telemetry slug. The gateway treats this as a free-form string —
-     * persisted to `llm_usage_log.use_case` and echoed back in `_builderforce.useCase`
-     * for confirmation, but **never used for routing**. The taxonomy is yours.
+     * Telemetry slug — persisted to `llm_usage_log.use_case` and echoed back in
+     * `_builderforce.useCase`. The taxonomy is yours, BUT a few well-known patterns
+     * also *influence routing* (the gateway substring-matches them):
+     *   - `…ocr…` → prefers OCR/vision-capable models.
+     *   - quality-critical work (`resume`, `cover_letter`, `tailor`, `proposal`,
+     *     `cv`, …) → leads with the best models your PLAN unlocks (premium writers
+     *     on paid plans). Failover + the funded reliability backstop still apply.
+     * Slugs that don't match any pattern are pure telemetry. Routing is always
+     * gateway-owned; this only nudges model selection.
      */
     useCase?: string;
     /** Free-form key/value pairs persisted to `llm_usage_log.metadata` for billing
@@ -236,6 +260,15 @@ interface ChatCompletionResponse {
         effectivePlan?: string;
         /** Number of vendor retries the gateway performed for json_schema conformance. */
         schemaRetries?: number;
+        /**
+         * `true` when the gateway AUTO-DOWNGRADED a too-complex `response_format.json_schema`
+         * to loose `json_object` and re-ran the cascade so you still got a structured
+         * result instead of a terminal `schema_too_complex` error. The strict-schema
+         * guarantee was relaxed — **validate the returned JSON yourself** (it parses,
+         * but wasn't constrained-decoded against your schema). Pre-empt the round-trip
+         * with `deriveResponseFormat` when you know the schema is large.
+         */
+        schemaDowngraded?: boolean;
         /** Echo of `request.useCase` (opaque telemetry slug). */
         useCase?: string;
         /** Echo of `request.metadata` for caller-side billing trace-back. */
@@ -630,4 +663,146 @@ declare class BuilderforceClient {
     constructor(options: BuilderforceClientOptions);
 }
 
-export { type AiCapability, BuilderforceApiError, BuilderforceClient, type BuilderforceClientOptions, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionResponse, ChatCompletionStream, type ChatMessage, type ChatRole, type ContentPart, type EmbeddingObject, EmbeddingsApi, type EmbeddingsCreateParams, type EmbeddingsResponse, type FailoverEvent, type FunctionDefinition, type ImageGenerationCreateParams, type ImageGenerationDataEntry, type ImageGenerationResponse, type ImageUrlContentPart, ImagesApi, type JsonSchemaSpec, type ModelInfo, ModelsApi, type ModelsListResponse, type PerCallOptions, type ResponseFormat, type TextContentPart, type ToolCall, type ToolCallDelta, type ToolCallFunction, type ToolChoice, type ToolSpec, type UsageByDay, type UsageByModel, type UsageByUser, type UsageGetParams, type UsageResponse };
+/**
+ * Coarse, stable error class for a failed gateway call — keyed off the gateway's
+ * OWN failure taxonomy (`error.code` + `terminal` + the failover breakdown), NOT
+ * raw HTTP-status guessing. Branch on this instead of reinventing a classifier
+ * per consumer (which inevitably drifts).
+ *
+ *   rate_limit          — the gateway's whole cascade was rate-limited (429
+ *                         `cascade_exhausted`). Retry later (`retryAfter`).
+ *   token_cap           — a per-TENANT cap was hit (plan/monthly/host/claw token
+ *                         or image-credit limit). TERMINAL for this billing
+ *                         window — a different model won't help.
+ *   schema_too_complex  — every candidate rejected the `response_format.json_schema`
+ *                         as too complex for its constrained-decoding engine.
+ *                         TERMINAL: simplify the schema or drop to `json_object`.
+ *   invalid_request     — malformed payload (400/422) every model rejected. TERMINAL.
+ *   auth                — bad/missing API key (401/403). TERMINAL.
+ *   model_unavailable   — a strict-pinned model is on cooldown / unconfigured (503).
+ *                         Not terminal: drop the pin or pick another model.
+ *   timeout             — the request (or a single vendor attempt) timed out (408).
+ *   service_unavailable — infrastructure ceiling (503 `worker_subrequest_exhausted`)
+ *                         or transient upstream outage (5xx). Retry after a backoff.
+ *   content_filter      — a safety system blocked the generation.
+ *   network             — the request never reached the gateway (DNS/TLS/reset).
+ *   aborted             — the caller's AbortSignal fired (499 / AbortError).
+ *   unknown             — none of the above matched.
+ */
+type ErrorKind = 'rate_limit' | 'token_cap' | 'schema_too_complex' | 'invalid_request' | 'auth' | 'model_unavailable' | 'timeout' | 'service_unavailable' | 'content_filter' | 'network' | 'aborted' | 'unknown';
+interface ErrorClassification {
+    kind: ErrorKind;
+    /**
+     * `true` when retrying the SAME request on a DIFFERENT model will NOT help —
+     * the consumer's own failover chain should short-circuit. Sourced from the
+     * gateway's `error.terminal` flag when present, with a kind-based fallback.
+     */
+    terminal: boolean;
+    /**
+     * `true` when the SAME request is safe to retry as-is (idempotently), usually
+     * after `retryAfter` seconds — e.g. a transient rate-limit/outage/timeout.
+     * `false` for deterministic rejections (schema, invalid request, auth, caps).
+     */
+    retryable: boolean;
+    /** Seconds the caller should wait before retrying, when the gateway supplied it. */
+    retryAfter?: number;
+    /** HTTP status, when the error reached the gateway. */
+    status?: number;
+    /** Gateway error code slug, when present (`schema_too_complex`, `plan_token_limit_exceeded`, …). */
+    code?: string;
+    /** Human-readable message (the gateway's, or the thrown error's). */
+    message: string;
+}
+/**
+ * Classify any caught error from a Builderforce SDK call into a structured,
+ * actionable verdict. Accepts `unknown` so a consumer can pass a raw `catch`
+ * binding — non-`BuilderforceApiError` values (network throws, `AbortError`,
+ * plain `Error`) are classified too.
+ *
+ * This is the FIRST-PARTY classifier the gateway feedback asked for: keyed off
+ * the gateway's own taxonomy so every consumer agrees on what "terminal" and
+ * "retryable" mean instead of hand-rolling `429/408/401/5xx → kind` guesses that
+ * drift apart.
+ */
+declare function classifyError(err: unknown): ErrorClassification;
+
+/**
+ * deriveResponseFormat — pick the strongest `response_format` a request can SAFELY
+ * use given how complex its JSON-Schema is and (optionally) which vendor will
+ * serve it.
+ *
+ * The problem this solves: a strict `json_schema` gives the best conformance, but
+ * some vendors' constrained-decoding engines reject a schema that's too complex
+ * (Gemini's "too many states for serving"). The gateway now surfaces that as a
+ * terminal `schema_too_complex` error — but the cleaner fix is to NOT send a
+ * strict schema a vendor can't honour in the first place. This utility is the
+ * pre-flight guard: it emits `{ type: 'json_schema', strict }` when the schema is
+ * within the (vendor-specific or conservative-default) complexity ceiling, and
+ * falls back to `{ type: 'json_object' }` (loose JSON mode — universally
+ * supported) when it isn't.
+ *
+ * The SDK is zero-dependency, so this takes a plain JSON-Schema object — convert
+ * a Zod schema first with `zod-to-json-schema` (`deriveResponseFormat(zodToJsonSchema(MySchema), …)`).
+ */
+interface DeriveResponseFormatOptions {
+    /** Schema name sent as `json_schema.name` (default `'response'`). */
+    name?: string;
+    /** Set `json_schema.strict` when a strict schema is emitted (default `true`). */
+    strict?: boolean;
+    /**
+     * The vendor that will serve the request, when known (the consumer pinned a
+     * `model`). Selects that vendor's specific complexity ceiling. Omit when
+     * routing is gateway-owned — the conservative default ceiling (the lowest
+     * common denominator across vendors) is used so the schema is accepted
+     * whichever vendor the gateway picks.
+     */
+    vendor?: string;
+    /**
+     * Override the complexity ceiling (max schema "nodes"; see
+     * {@link estimateSchemaComplexity}). Above this, loose `json_object` is emitted.
+     * Wins over the vendor/default ceiling.
+     */
+    maxComplexity?: number;
+}
+interface SchemaComplexity {
+    /** Total schema nodes — every property, array `items`, and enum value counts one. */
+    nodes: number;
+    /** Deepest nesting level reached. */
+    maxDepth: number;
+    /** Total enum values across the whole schema (the main driver of constrained-
+     *  decoding state blow-up). */
+    totalEnumValues: number;
+    /** Single rolled-up score compared against the ceiling: `nodes + totalEnumValues`. */
+    score: number;
+}
+/**
+ * Conservative cross-vendor ceiling, used when no `vendor` is supplied (gateway-
+ * owned routing). Tuned below the lowest-ceiling vendor (Gemini's constrained-
+ * decoding "too many states" limit) so a schema that passes here is accepted by
+ * ANY vendor the gateway might route to.
+ */
+declare const DEFAULT_SCHEMA_COMPLEXITY_CEILING = 80;
+/**
+ * Estimate a JSON-Schema's complexity. The dominant cost for constrained decoding
+ * is the number of distinct states the engine must track, which grows with the
+ * node count and (especially) the total number of enum values. Pure + cheap.
+ */
+declare function estimateSchemaComplexity(schema: unknown): SchemaComplexity;
+/**
+ * True when a strict `json_schema` is safe for the given schema + vendor (i.e.
+ * within the complexity ceiling, and the vendor isn't strict-schema-incapable).
+ * Exposed so callers can branch (e.g. log a downgrade) without re-deriving.
+ */
+declare function canUseStrictSchema(schema: unknown, opts?: DeriveResponseFormatOptions): boolean;
+/**
+ * Derive the strongest safe `response_format`:
+ *   • within the ceiling → `{ type: 'json_schema', json_schema: { name, schema, strict } }`
+ *   • over the ceiling   → `{ type: 'json_object' }` (loose JSON; instruct the
+ *     model to follow the shape in your prompt)
+ *
+ * Pure — returns a value the consumer drops straight into
+ * `chat.completions.create({ response_format })`.
+ */
+declare function deriveResponseFormat(schema: Record<string, unknown>, opts?: DeriveResponseFormatOptions): ResponseFormat;
+
+export { type AiCapability, BuilderforceApiError, BuilderforceClient, type BuilderforceClientOptions, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionResponse, ChatCompletionStream, type ChatMessage, type ChatRole, type ContentPart, DEFAULT_SCHEMA_COMPLEXITY_CEILING, type DeriveResponseFormatOptions, type EmbeddingObject, EmbeddingsApi, type EmbeddingsCreateParams, type EmbeddingsResponse, type ErrorClassification, type ErrorKind, type FailoverEvent, type FailoverKind, type FunctionDefinition, type ImageGenerationCreateParams, type ImageGenerationDataEntry, type ImageGenerationResponse, type ImageUrlContentPart, ImagesApi, type JsonSchemaSpec, type ModelInfo, ModelsApi, type ModelsListResponse, type PerCallOptions, type ResponseFormat, type SchemaComplexity, type TextContentPart, type ToolCall, type ToolCallDelta, type ToolCallFunction, type ToolChoice, type ToolSpec, type UsageByDay, type UsageByModel, type UsageByUser, type UsageGetParams, type UsageResponse, canUseStrictSchema, classifyError, deriveResponseFormat, estimateSchemaComplexity };

package/dist/index.d.ts

@@ -8,19 +8,37 @@ type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
  * upstream — e.g. all `openrouter` means a saturated shared key, not a
  * model-specific issue.
  */
+/**
+ * Coarse failure class for one failover attempt. Branch on this instead of
+ * regex-sniffing the error message. `'schema'` means the upstream rejected the
+ * `response_format.json_schema` as too complex for its constrained-decoding
+ * engine (see `FailoverEvent.reason === 'schema_too_complex'`); `'content_filter'`
+ * means a safety system blocked the generation. Open string union for
+ * forward-compat — a newer gateway may add classes an older SDK doesn't list.
+ */
+type FailoverKind = 'rate_limit' | 'timeout' | 'auth' | 'server_error' | 'client_error' | 'schema' | 'content_filter' | 'network' | 'skipped' | (string & {});
 interface FailoverEvent {
     model: string;
-    /** `'openrouter' | 'cerebras' | 'nvidia' | 'ollama'` */
+    /** `'openrouter' | 'cerebras' | 'nvidia' | 'ollama' | 'googleai' | …` */
     vendor: string;
-    /** HTTP status code, or 0 for embedded errors / network failures. */
+    /** Gateway-normalized status, or 0 for embedded errors / network failures.
+     *  For a schema rejection this is `422` (the request-error class); the REAL
+     *  upstream status is in `upstreamStatus`. */
     code: number;
     /** Wall-clock time the gateway spent on this attempt, ms. Present on newer
      *  gateway versions; absent on older ones. */
     durationMs?: number;
-    /** Coarse failure class — `'rate_limit' | 'timeout' | 'auth' | 'server_error'
-     *  | 'client_error' | 'network' | 'skipped'`. The full upstream error text is
-     *  NOT exposed to callers; quote `traceId` to support for that. */
-    kind?: string;
+    /** Coarse failure class — see {@link FailoverKind}. The full upstream error
+     *  text is NOT exposed to callers; quote `traceId` to support for that. */
+    kind?: FailoverKind;
+    /** Stable machine-readable cause slug when one applies — e.g.
+     *  `'schema_too_complex'`. Branch on this for structured handling instead of
+     *  parsing `message`. Absent for unclassified failures. */
+    reason?: string;
+    /** The REAL upstream HTTP status before the gateway normalized it into `code`
+     *  — e.g. a Gemini schema 400 surfaces as `code: 422` with `upstreamStatus: 400`.
+     *  Absent when `code` already IS the upstream status. */
+    upstreamStatus?: number;
 }
 interface TextContentPart {
     type: 'text';
@@ -153,9 +171,15 @@ interface ChatCompletionCreateParams extends PerCallOptions {
      *  gateway-side schema validation with retry across the failover chain. */
     response_format?: ResponseFormat;
     /**
-     * Opaque telemetry slug. The gateway treats this as a free-form string —
-     * persisted to `llm_usage_log.use_case` and echoed back in `_builderforce.useCase`
-     * for confirmation, but **never used for routing**. The taxonomy is yours.
+     * Telemetry slug — persisted to `llm_usage_log.use_case` and echoed back in
+     * `_builderforce.useCase`. The taxonomy is yours, BUT a few well-known patterns
+     * also *influence routing* (the gateway substring-matches them):
+     *   - `…ocr…` → prefers OCR/vision-capable models.
+     *   - quality-critical work (`resume`, `cover_letter`, `tailor`, `proposal`,
+     *     `cv`, …) → leads with the best models your PLAN unlocks (premium writers
+     *     on paid plans). Failover + the funded reliability backstop still apply.
+     * Slugs that don't match any pattern are pure telemetry. Routing is always
+     * gateway-owned; this only nudges model selection.
      */
     useCase?: string;
     /** Free-form key/value pairs persisted to `llm_usage_log.metadata` for billing
@@ -236,6 +260,15 @@ interface ChatCompletionResponse {
         effectivePlan?: string;
         /** Number of vendor retries the gateway performed for json_schema conformance. */
         schemaRetries?: number;
+        /**
+         * `true` when the gateway AUTO-DOWNGRADED a too-complex `response_format.json_schema`
+         * to loose `json_object` and re-ran the cascade so you still got a structured
+         * result instead of a terminal `schema_too_complex` error. The strict-schema
+         * guarantee was relaxed — **validate the returned JSON yourself** (it parses,
+         * but wasn't constrained-decoded against your schema). Pre-empt the round-trip
+         * with `deriveResponseFormat` when you know the schema is large.
+         */
+        schemaDowngraded?: boolean;
         /** Echo of `request.useCase` (opaque telemetry slug). */
         useCase?: string;
         /** Echo of `request.metadata` for caller-side billing trace-back. */
@@ -630,4 +663,146 @@ declare class BuilderforceClient {
     constructor(options: BuilderforceClientOptions);
 }
 
-export { type AiCapability, BuilderforceApiError, BuilderforceClient, type BuilderforceClientOptions, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionResponse, ChatCompletionStream, type ChatMessage, type ChatRole, type ContentPart, type EmbeddingObject, EmbeddingsApi, type EmbeddingsCreateParams, type EmbeddingsResponse, type FailoverEvent, type FunctionDefinition, type ImageGenerationCreateParams, type ImageGenerationDataEntry, type ImageGenerationResponse, type ImageUrlContentPart, ImagesApi, type JsonSchemaSpec, type ModelInfo, ModelsApi, type ModelsListResponse, type PerCallOptions, type ResponseFormat, type TextContentPart, type ToolCall, type ToolCallDelta, type ToolCallFunction, type ToolChoice, type ToolSpec, type UsageByDay, type UsageByModel, type UsageByUser, type UsageGetParams, type UsageResponse };
+/**
+ * Coarse, stable error class for a failed gateway call — keyed off the gateway's
+ * OWN failure taxonomy (`error.code` + `terminal` + the failover breakdown), NOT
+ * raw HTTP-status guessing. Branch on this instead of reinventing a classifier
+ * per consumer (which inevitably drifts).
+ *
+ *   rate_limit          — the gateway's whole cascade was rate-limited (429
+ *                         `cascade_exhausted`). Retry later (`retryAfter`).
+ *   token_cap           — a per-TENANT cap was hit (plan/monthly/host/claw token
+ *                         or image-credit limit). TERMINAL for this billing
+ *                         window — a different model won't help.
+ *   schema_too_complex  — every candidate rejected the `response_format.json_schema`
+ *                         as too complex for its constrained-decoding engine.
+ *                         TERMINAL: simplify the schema or drop to `json_object`.
+ *   invalid_request     — malformed payload (400/422) every model rejected. TERMINAL.
+ *   auth                — bad/missing API key (401/403). TERMINAL.
+ *   model_unavailable   — a strict-pinned model is on cooldown / unconfigured (503).
+ *                         Not terminal: drop the pin or pick another model.
+ *   timeout             — the request (or a single vendor attempt) timed out (408).
+ *   service_unavailable — infrastructure ceiling (503 `worker_subrequest_exhausted`)
+ *                         or transient upstream outage (5xx). Retry after a backoff.
+ *   content_filter      — a safety system blocked the generation.
+ *   network             — the request never reached the gateway (DNS/TLS/reset).
+ *   aborted             — the caller's AbortSignal fired (499 / AbortError).
+ *   unknown             — none of the above matched.
+ */
+type ErrorKind = 'rate_limit' | 'token_cap' | 'schema_too_complex' | 'invalid_request' | 'auth' | 'model_unavailable' | 'timeout' | 'service_unavailable' | 'content_filter' | 'network' | 'aborted' | 'unknown';
+interface ErrorClassification {
+    kind: ErrorKind;
+    /**
+     * `true` when retrying the SAME request on a DIFFERENT model will NOT help —
+     * the consumer's own failover chain should short-circuit. Sourced from the
+     * gateway's `error.terminal` flag when present, with a kind-based fallback.
+     */
+    terminal: boolean;
+    /**
+     * `true` when the SAME request is safe to retry as-is (idempotently), usually
+     * after `retryAfter` seconds — e.g. a transient rate-limit/outage/timeout.
+     * `false` for deterministic rejections (schema, invalid request, auth, caps).
+     */
+    retryable: boolean;
+    /** Seconds the caller should wait before retrying, when the gateway supplied it. */
+    retryAfter?: number;
+    /** HTTP status, when the error reached the gateway. */
+    status?: number;
+    /** Gateway error code slug, when present (`schema_too_complex`, `plan_token_limit_exceeded`, …). */
+    code?: string;
+    /** Human-readable message (the gateway's, or the thrown error's). */
+    message: string;
+}
+/**
+ * Classify any caught error from a Builderforce SDK call into a structured,
+ * actionable verdict. Accepts `unknown` so a consumer can pass a raw `catch`
+ * binding — non-`BuilderforceApiError` values (network throws, `AbortError`,
+ * plain `Error`) are classified too.
+ *
+ * This is the FIRST-PARTY classifier the gateway feedback asked for: keyed off
+ * the gateway's own taxonomy so every consumer agrees on what "terminal" and
+ * "retryable" mean instead of hand-rolling `429/408/401/5xx → kind` guesses that
+ * drift apart.
+ */
+declare function classifyError(err: unknown): ErrorClassification;
+
+/**
+ * deriveResponseFormat — pick the strongest `response_format` a request can SAFELY
+ * use given how complex its JSON-Schema is and (optionally) which vendor will
+ * serve it.
+ *
+ * The problem this solves: a strict `json_schema` gives the best conformance, but
+ * some vendors' constrained-decoding engines reject a schema that's too complex
+ * (Gemini's "too many states for serving"). The gateway now surfaces that as a
+ * terminal `schema_too_complex` error — but the cleaner fix is to NOT send a
+ * strict schema a vendor can't honour in the first place. This utility is the
+ * pre-flight guard: it emits `{ type: 'json_schema', strict }` when the schema is
+ * within the (vendor-specific or conservative-default) complexity ceiling, and
+ * falls back to `{ type: 'json_object' }` (loose JSON mode — universally
+ * supported) when it isn't.
+ *
+ * The SDK is zero-dependency, so this takes a plain JSON-Schema object — convert
+ * a Zod schema first with `zod-to-json-schema` (`deriveResponseFormat(zodToJsonSchema(MySchema), …)`).
+ */
+interface DeriveResponseFormatOptions {
+    /** Schema name sent as `json_schema.name` (default `'response'`). */
+    name?: string;
+    /** Set `json_schema.strict` when a strict schema is emitted (default `true`). */
+    strict?: boolean;
+    /**
+     * The vendor that will serve the request, when known (the consumer pinned a
+     * `model`). Selects that vendor's specific complexity ceiling. Omit when
+     * routing is gateway-owned — the conservative default ceiling (the lowest
+     * common denominator across vendors) is used so the schema is accepted
+     * whichever vendor the gateway picks.
+     */
+    vendor?: string;
+    /**
+     * Override the complexity ceiling (max schema "nodes"; see
+     * {@link estimateSchemaComplexity}). Above this, loose `json_object` is emitted.
+     * Wins over the vendor/default ceiling.
+     */
+    maxComplexity?: number;
+}
+interface SchemaComplexity {
+    /** Total schema nodes — every property, array `items`, and enum value counts one. */
+    nodes: number;
+    /** Deepest nesting level reached. */
+    maxDepth: number;
+    /** Total enum values across the whole schema (the main driver of constrained-
+     *  decoding state blow-up). */
+    totalEnumValues: number;
+    /** Single rolled-up score compared against the ceiling: `nodes + totalEnumValues`. */
+    score: number;
+}
+/**
+ * Conservative cross-vendor ceiling, used when no `vendor` is supplied (gateway-
+ * owned routing). Tuned below the lowest-ceiling vendor (Gemini's constrained-
+ * decoding "too many states" limit) so a schema that passes here is accepted by
+ * ANY vendor the gateway might route to.
+ */
+declare const DEFAULT_SCHEMA_COMPLEXITY_CEILING = 80;
+/**
+ * Estimate a JSON-Schema's complexity. The dominant cost for constrained decoding
+ * is the number of distinct states the engine must track, which grows with the
+ * node count and (especially) the total number of enum values. Pure + cheap.
+ */
+declare function estimateSchemaComplexity(schema: unknown): SchemaComplexity;
+/**
+ * True when a strict `json_schema` is safe for the given schema + vendor (i.e.
+ * within the complexity ceiling, and the vendor isn't strict-schema-incapable).
+ * Exposed so callers can branch (e.g. log a downgrade) without re-deriving.
+ */
+declare function canUseStrictSchema(schema: unknown, opts?: DeriveResponseFormatOptions): boolean;
+/**
+ * Derive the strongest safe `response_format`:
+ *   • within the ceiling → `{ type: 'json_schema', json_schema: { name, schema, strict } }`
+ *   • over the ceiling   → `{ type: 'json_object' }` (loose JSON; instruct the
+ *     model to follow the shape in your prompt)
+ *
+ * Pure — returns a value the consumer drops straight into
+ * `chat.completions.create({ response_format })`.
+ */
+declare function deriveResponseFormat(schema: Record<string, unknown>, opts?: DeriveResponseFormatOptions): ResponseFormat;
+
+export { type AiCapability, BuilderforceApiError, BuilderforceClient, type BuilderforceClientOptions, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionResponse, ChatCompletionStream, type ChatMessage, type ChatRole, type ContentPart, DEFAULT_SCHEMA_COMPLEXITY_CEILING, type DeriveResponseFormatOptions, type EmbeddingObject, EmbeddingsApi, type EmbeddingsCreateParams, type EmbeddingsResponse, type ErrorClassification, type ErrorKind, type FailoverEvent, type FailoverKind, type FunctionDefinition, type ImageGenerationCreateParams, type ImageGenerationDataEntry, type ImageGenerationResponse, type ImageUrlContentPart, ImagesApi, type JsonSchemaSpec, type ModelInfo, ModelsApi, type ModelsListResponse, type PerCallOptions, type ResponseFormat, type SchemaComplexity, type TextContentPart, type ToolCall, type ToolCallDelta, type ToolCallFunction, type ToolChoice, type ToolSpec, type UsageByDay, type UsageByModel, type UsageByUser, type UsageGetParams, type UsageResponse, canUseStrictSchema, classifyError, deriveResponseFormat, estimateSchemaComplexity };

package/dist/index.mjs

@@ -258,7 +258,9 @@ var BuilderforceApiError = class extends Error {
                 vendor: e.vendor,
                 code: e.code,
                 ...typeof ev.durationMs === "number" ? { durationMs: ev.durationMs } : {},
-                ...typeof ev.kind === "string" ? { kind: ev.kind } : {}
+                ...typeof ev.kind === "string" ? { kind: ev.kind } : {},
+                ...typeof ev.reason === "string" ? { reason: ev.reason } : {},
+                ...typeof ev.upstreamStatus === "number" ? { upstreamStatus: ev.upstreamStatus } : {}
               });
             }
           }
@@ -437,12 +439,173 @@ var BuilderforceClient = class {
     this.usage = new UsageApi(http);
   }
 };
+
+// src/application/classifyError.ts
+var TOKEN_CAP_CODES = /* @__PURE__ */ new Set([
+  "plan_token_limit_exceeded",
+  "plan_monthly_token_limit_exceeded",
+  "agent_host_token_limit_exceeded",
+  "claw_token_limit_exceeded",
+  "image_credit_limit_exceeded"
+]);
+function classifyError(err) {
+  if (!(err instanceof BuilderforceApiError)) {
+    const name = err?.name;
+    const message2 = err instanceof Error ? err.message : String(err);
+    if (name === "AbortError") {
+      return { kind: "aborted", terminal: true, retryable: false, message: message2 };
+    }
+    if (err instanceof TypeError) {
+      return { kind: "network", terminal: false, retryable: true, message: message2 };
+    }
+    return { kind: "unknown", terminal: false, retryable: false, message: message2 };
+  }
+  const { status, code, terminal, retryAfter, message } = err;
+  const base = {
+    ...retryAfter !== void 0 ? { retryAfter } : {},
+    ...status !== void 0 ? { status } : {},
+    ...code !== void 0 ? { code } : {},
+    message
+  };
+  if (code === "schema_too_complex" || lastFailoverReason(err) === "schema_too_complex") {
+    return { kind: "schema_too_complex", terminal: terminal ?? true, retryable: false, ...base };
+  }
+  if (code && TOKEN_CAP_CODES.has(code)) {
+    return { kind: "token_cap", terminal: terminal ?? true, retryable: false, ...base };
+  }
+  if (code === "model_unavailable") {
+    return { kind: "model_unavailable", terminal: terminal ?? false, retryable: false, ...base };
+  }
+  if (code === "worker_subrequest_exhausted") {
+    return { kind: "service_unavailable", terminal: false, retryable: true, ...base };
+  }
+  if (code === "aborted") {
+    return { kind: "aborted", terminal: true, retryable: false, ...base };
+  }
+  if (code === "content_filter") {
+    return { kind: "content_filter", terminal: terminal ?? true, retryable: false, ...base };
+  }
+  if (status === 408 || code === "timeout") {
+    return { kind: "timeout", terminal: false, retryable: true, ...base };
+  }
+  if (status === 401 || status === 403) {
+    return { kind: "auth", terminal: terminal ?? true, retryable: false, ...base };
+  }
+  if (status === 429) {
+    return { kind: "rate_limit", terminal: terminal ?? false, retryable: !(terminal ?? false), ...base };
+  }
+  if (status === 400 || status === 422) {
+    return { kind: "invalid_request", terminal: terminal ?? true, retryable: false, ...base };
+  }
+  if (status === 503) {
+    return { kind: "service_unavailable", terminal: false, retryable: true, ...base };
+  }
+  if (status !== void 0 && status >= 500) {
+    return { kind: "service_unavailable", terminal: false, retryable: true, ...base };
+  }
+  return { kind: "unknown", terminal: terminal ?? false, retryable: false, ...base };
+}
+function lastFailoverReason(err) {
+  const f = err.failovers;
+  if (!f || f.length === 0) return void 0;
+  return f[f.length - 1]?.reason;
+}
+
+// src/application/deriveResponseFormat.ts
+var DEFAULT_SCHEMA_COMPLEXITY_CEILING = 80;
+var VENDOR_SCHEMA_CEILINGS = {
+  // Low constrained-decoding ceiling — the vendor that motivated this guard.
+  googleai: 60,
+  google: 60,
+  gemini: 60,
+  // High-ceiling, robust strict-schema vendors.
+  openai: 600,
+  anthropic: 600,
+  cerebras: 300,
+  nvidia: 300,
+  openrouter: 200
+};
+var MAX_SCHEMA_WALK_DEPTH = 64;
+function estimateSchemaComplexity(schema) {
+  let nodes = 0;
+  let totalEnumValues = 0;
+  let maxDepth = 0;
+  const walk = (node, depth) => {
+    if (depth > MAX_SCHEMA_WALK_DEPTH || node === null || typeof node !== "object") return;
+    if (depth > maxDepth) maxDepth = depth;
+    const s = node;
+    const enumVals = s["enum"];
+    if (Array.isArray(enumVals)) totalEnumValues += enumVals.length;
+    const props = s["properties"];
+    if (props && typeof props === "object") {
+      for (const key of Object.keys(props)) {
+        nodes += 1;
+        walk(props[key], depth + 1);
+      }
+    }
+    const items = s["items"];
+    if (Array.isArray(items)) items.forEach((it) => {
+      nodes += 1;
+      walk(it, depth + 1);
+    });
+    else if (items && typeof items === "object") {
+      nodes += 1;
+      walk(items, depth + 1);
+    }
+    for (const comb of ["anyOf", "oneOf", "allOf"]) {
+      const arr = s[comb];
+      if (Array.isArray(arr)) arr.forEach((sub) => {
+        nodes += 1;
+        walk(sub, depth + 1);
+      });
+    }
+    for (const defsKey of ["$defs", "definitions"]) {
+      const defs = s[defsKey];
+      if (defs && typeof defs === "object") {
+        for (const key of Object.keys(defs)) walk(defs[key], depth + 1);
+      }
+    }
+  };
+  walk(schema, 0);
+  return { nodes, maxDepth, totalEnumValues, score: nodes + totalEnumValues };
+}
+function ceilingFor(opts) {
+  if (opts?.maxComplexity != null && opts.maxComplexity >= 0) return opts.maxComplexity;
+  if (opts?.vendor) {
+    const v = opts.vendor.toLowerCase();
+    if (v in VENDOR_SCHEMA_CEILINGS) return VENDOR_SCHEMA_CEILINGS[v];
+  }
+  return DEFAULT_SCHEMA_COMPLEXITY_CEILING;
+}
+function canUseStrictSchema(schema, opts) {
+  const ceiling = ceilingFor(opts);
+  if (ceiling === 0) return false;
+  return estimateSchemaComplexity(schema).score <= ceiling;
+}
+function deriveResponseFormat(schema, opts) {
+  if (!canUseStrictSchema(schema, opts)) {
+    return { type: "json_object" };
+  }
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: opts?.name ?? "response",
+      schema,
+      strict: opts?.strict ?? true
+    }
+  };
+}
 export {
   BuilderforceApiError,
   BuilderforceClient,
   ChatCompletionStream,
+  DEFAULT_SCHEMA_COMPLEXITY_CEILING,
   EmbeddingsApi,
   ImagesApi,
-  ModelsApi
+  ModelsApi,
+  canUseStrictSchema,
+  classifyError,
+  deriveResponseFormat,
+  estimateSchemaComplexity
 };
 //# sourceMappingURL=index.mjs.map