@absolutejs/ai 0.6.5 → 0.6.7

package/dist/src/ai/contextPolicy.d.ts

@@ -1,3 +1,4 @@
+import { type AIProviderFallback } from "./providerFallback";
 import type { AIChunk, AIProviderConfig, AIProviderMessage, AIProviderStreamParams } from "../../types/ai";
 import { type AIInputCapacity } from "./inputCapacity";
 /** Token budgets, never character approximations or guessed model limits. */
@@ -26,6 +27,7 @@ export type AIContextEvent = {
     after: AIContextCapacity;
 };
 export type AIContextPolicy = AIContextBudget & {
+    providerFallback?: AIProviderFallback;
     /** Called at most once per model turn, before any output. Preserve originals
      * in application storage; return compacted/retrieved messages, never effects.
      * Tool IDs/inputs, signed thinking, media, provider data and system messages

package/dist/src/ai/errors/providerError.d.ts

@@ -37,3 +37,5 @@ export declare class ProviderError extends Error {
      */
     static from(err: unknown, provider: string): ProviderError;
 }
+/** Provider entrypoints are independently bundled; preserve their error contract. */
+export declare const isProviderError: (error: unknown) => error is ProviderError;

package/dist/src/ai/index.d.ts

@@ -51,3 +51,6 @@ export type { AIContextBudget, AIContextCapacity, AIContextPolicy, AIContextEven
 export { createAIStoredToolResultRecovery } from "./storedToolResultRecovery";
 export { createAIProviderRouter } from "./providerRouter";
 export { streamWithProviderFallback } from "./providerFallback";
+export { isProviderError } from "./errors/providerError";
+export { isAIProviderFailure, isPermanentAIProviderFailure, inspectWithProviderFallback, } from "./providerFallback";
+export type { AIProviderFallback } from "./providerFallback";

package/dist/src/ai/inputCapacity.d.ts

@@ -1,3 +1,4 @@
+import { ProviderError } from "./errors/providerError";
 import type { AIProviderConfig, AIProviderStreamParams } from "../../types/ai";
 /** Provider-reported limits. Some providers have separate input/output windows. */
 export type AIModelLimits = {
@@ -20,7 +21,8 @@ export declare class AIInputError extends Error {
     readonly code: "capacity_unavailable" | "input_too_large" | "unsupported_content";
     readonly providerStatus?: number | undefined;
     readonly requestId?: string | undefined;
-    constructor(code: "capacity_unavailable" | "input_too_large" | "unsupported_content", message: string, providerStatus?: number | undefined, requestId?: string | undefined);
+    readonly providerError?: ProviderError | undefined;
+    constructor(code: "capacity_unavailable" | "input_too_large" | "unsupported_content", message: string, providerStatus?: number | undefined, requestId?: string | undefined, providerError?: ProviderError | undefined);
 }
 export declare const positiveTokenLimit: (value: unknown) => number;
 export declare const inputTokenCount: (value: unknown) => number;
@@ -28,4 +30,4 @@ export declare const inputTokenCount: (value: unknown) => number;
 export declare const inspectAIInput: (provider: AIProviderConfig, params: AIProviderStreamParams) => Promise<AIInputCapacity>;
 /** Cache metadata per provider instance; use a zero TTL with rotating auth/headers. never cache failures. */
 export declare const cacheModelLimits: (load: (params: AIProviderStreamParams) => Promise<AIModelLimits>, ttlMs?: number) => (params: AIProviderStreamParams) => Promise<AIModelLimits>;
-export declare const capacityJson: (response: Response) => Promise<Record<string, unknown>>;
+export declare const capacityJson: (response: Response, provider?: string) => Promise<Record<string, unknown>>;

package/dist/src/ai/prepareTextInput.d.ts

@@ -1,5 +1,6 @@
 import { type AIContextBudget } from "./contextPolicy";
 import type { AIProviderConfig, AIProviderStreamParams, AIUsage } from "../../types/ai";
+import { type AIProviderFallback } from "./providerFallback";
 export type AITextPreparationCheckpoint = {
     version: 1;
     taskHash: string;
@@ -14,6 +15,7 @@ export type PreparedAITextInput = {
     sectionsProcessed: number;
 };
 export type PrepareAITextInputOptions = {
+    providerFallback?: AIProviderFallback;
     contextBudget?: AIContextBudget;
     /** Optional model on the same provider for source-note preparation only.
      * The final request retains params.model. Validate quality for your workload

package/dist/src/ai/providerFallback.d.ts

@@ -1,14 +1,33 @@
 import type { AIChunk } from "../../types/ai";
-import { ProviderError } from "./errors/providerError";
-/** Execute approved, individually metered alternatives. Never replay a stream
- * after any chunk (including tools or usage), or after caller cancellation. */
-export declare function streamWithProviderFallback(options: {
-    models: readonly string[];
-    stream: (model: string) => AsyncIterable<AIChunk>;
-    signal?: AbortSignal;
+export type AIProviderFallback = {
+    models: readonly string[] | ((model: string) => readonly string[]);
     onFallback?: (event: {
         from: string;
         to: string;
-        error: ProviderError;
+        error: Error;
     }) => void | Promise<void>;
+};
+export declare const providerFallbackModels: (model: string, recovery?: AIProviderFallback) => string[];
+/** Provider-specific failures may use an approved alternative. Application,
+ * cancellation and accounting errors must never be hidden by fallback. */
+export declare const isAIProviderFailure: (error: unknown) => error is Error;
+export declare const isPermanentAIProviderFailure: (error: unknown) => boolean;
+/** Only for side-effect-free checks. Each selected provider performs its own
+ * tokenizer/limits validation; no cross-provider token estimate is reused. */
+export declare const inspectWithProviderFallback: <T>(options: {
+    model: string;
+    recovery?: AIProviderFallback;
+    signal?: AbortSignal;
+    inspect: (model: string) => Promise<T>;
+}) => Promise<{
+    model: string;
+    value: T;
+}>;
+/** Never replay a stream after any chunk (including tools or usage), or after
+ * caller cancellation. Each candidate owns its own preflight and metering. */
+export declare function streamWithProviderFallback(options: {
+    models: readonly string[];
+    stream: (model: string) => AsyncIterable<AIChunk>;
+    signal?: AbortSignal;
+    onFallback?: AIProviderFallback["onFallback"];
 }): AsyncIterable<AIChunk>;

package/dist/src/ai/providers/openaiSchema.d.ts

@@ -0,0 +1,4 @@
+/** Losslessly lower finite-key records (including Zod partialRecord) into
+ * named optional properties. Never discard arbitrary key constraints. */
+export declare const openaiSchema: (schema: Record<string, unknown>) => Record<string, unknown>;
+export declare const isStrictCompatible: (schema: unknown) => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/ai",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "homepage": "https://github.com/absolutejs/ai",
   "bugs": {
     "url": "https://github.com/absolutejs/ai/issues"