ai-props 2.3.0 → 2.4.0

package/dist/durable-cascade.d.ts

@@ -0,0 +1,280 @@
+/**
+ * DurableCascadeExecutor - Durable tiered execution with cascade pattern for Workers
+ *
+ * Combines the cascade pattern (code -> generative -> agentic -> human)
+ * with Cloudflare Workflows durability guarantees for use in worker contexts.
+ *
+ * ## Features
+ *
+ * - **Durable Execution**: Steps are persisted and can resume after failures
+ * - **AI Gateway Integration**: Helpers for Cloudflare AI Gateway configuration
+ * - **Automatic Checkpointing**: Each tier creates a durable checkpoint
+ * - **Tier Escalation**: Automatic escalation on failure
+ * - **5W+H Audit Events**: Full audit trail support
+ *
+ * ## Basic Usage
+ *
+ * @example
+ * ```typescript
+ * import { DurableCascadeExecutor, createAIGatewayConfig } from 'ai-props/worker'
+ *
+ * const cascade = new DurableCascadeExecutor('generate-content', {
+ *   code: async (input) => {
+ *     if (input.template) return { content: input.template }
+ *     throw new Error('No template')
+ *   },
+ *   generative: async (input, ctx) => {
+ *     const result = await ctx.ai.run('@cf/meta/llama-3-8b-instruct', {
+ *       messages: [{ role: 'user', content: 'Generate content' }]
+ *     })
+ *     return { content: result.response }
+ *   }
+ * })
+ *
+ * // In workflow
+ * const result = await cascade.run(step, { topic: 'AI' })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { CascadeExecutor, type CascadeConfig, type CascadeResult, type CascadeContext, type TierContext, type TierHandler, type CapabilityTier, type FiveWHEvent, type TierResult, TIER_ORDER, DEFAULT_TIER_TIMEOUTS, createCascadeContext, recordStep, AllTiersFailedError, CascadeTimeoutError } from './cascade.js';
+export { CascadeExecutor, type CascadeConfig, type CascadeResult, type CascadeContext, type TierContext, type TierHandler, type CapabilityTier, type FiveWHEvent, type TierResult, TIER_ORDER, DEFAULT_TIER_TIMEOUTS, createCascadeContext, recordStep, AllTiersFailedError, CascadeTimeoutError, };
+/**
+ * Configuration for retry behavior (Cloudflare Workflows format)
+ */
+export interface DurableRetryConfig {
+    /** Maximum number of retry attempts */
+    limit: number;
+    /** Delay between retries (string like '1 second' or number in ms) */
+    delay?: string | number;
+    /** Backoff strategy */
+    backoff?: 'constant' | 'linear' | 'exponential';
+}
+/**
+ * Configuration for a durable step
+ */
+export interface DurableStepConfig {
+    /** Retry configuration */
+    retries?: DurableRetryConfig;
+    /** Timeout for the step (string like '30 seconds' or number in ms) */
+    timeout?: string | number;
+}
+/**
+ * Interface for Cloudflare Workflows step object
+ */
+export interface WorkflowStep {
+    do<T>(name: string, callback: () => Promise<T>): Promise<T>;
+    do<T>(name: string, config: DurableStepConfig, callback: () => Promise<T>): Promise<T>;
+    sleep(name: string, duration: string | number): Promise<void>;
+    sleepUntil(name: string, timestamp: Date | number): Promise<void>;
+}
+/**
+ * AI binding interface (matches Cloudflare AI binding)
+ */
+export interface AiBinding {
+    run<T = unknown>(model: string, options: {
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+    }): Promise<T & {
+        response?: string;
+    }>;
+}
+/**
+ * Human review request
+ */
+export interface HumanReviewRequest {
+    type: string;
+    data: unknown;
+    assignee?: string;
+}
+/**
+ * Context provided to durable cascade tier handlers
+ */
+export interface DurableCascadeTierContext<TInput = unknown> extends TierContext<TInput> {
+    /** AI binding for generative/agentic tiers */
+    ai: AiBinding;
+    /** Request human review */
+    requestHumanReview: (request: HumanReviewRequest) => Promise<{
+        reviewId: string;
+        status: string;
+    }>;
+    /** Workflow step for nested durable operations */
+    workflowStep: WorkflowStep;
+}
+/**
+ * Code tier handler (deterministic, fast)
+ */
+export type CodeTierHandler<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
+/**
+ * AI tier handler (generative or agentic)
+ */
+export type AiTierHandler<TInput, TOutput> = (input: TInput, ctx: DurableCascadeTierContext<TInput>) => Promise<TOutput>;
+/**
+ * Human tier handler
+ */
+export type HumanTierHandler<TInput, TOutput> = (input: TInput, ctx: DurableCascadeTierContext<TInput>) => Promise<TOutput>;
+/**
+ * Configuration for DurableCascadeExecutor
+ */
+export interface DurableCascadeConfig<TInput = unknown, TOutput = unknown> {
+    /** Code tier handler (deterministic, fast) */
+    code?: CodeTierHandler<TInput, TOutput>;
+    /** Generative AI tier handler */
+    generative?: AiTierHandler<TInput, TOutput>;
+    /** Agentic AI tier handler (multi-step reasoning) */
+    agentic?: AiTierHandler<TInput, TOutput>;
+    /** Human tier handler (human-in-the-loop) */
+    human?: HumanTierHandler<TInput, TOutput>;
+    /** Per-tier timeout configuration (in ms) */
+    timeouts?: Partial<Record<CapabilityTier, number>>;
+    /** Total cascade timeout (in ms) */
+    totalTimeout?: number;
+    /** Per-tier retry configuration */
+    tierConfig?: Partial<Record<CapabilityTier, {
+        retries?: {
+            limit: number;
+            delay?: number;
+            backoff?: 'constant' | 'linear' | 'exponential';
+        };
+        successCondition?: (result: unknown) => boolean;
+        onError?: (error: Error, tier: CapabilityTier) => void;
+    }>>;
+    /** Event callback for 5W+H audit events */
+    onEvent?: (event: FiveWHEvent) => void;
+    /** Actor identifier for audit trail */
+    actor?: string;
+}
+/**
+ * AI Gateway configuration for Cloudflare Workers
+ */
+export interface AIGatewayConfig {
+    /** Gateway ID */
+    gatewayId: string;
+    /** Account ID */
+    accountId: string;
+    /** Cache TTL in seconds (0 to disable) */
+    cacheTtl?: number;
+    /** Skip cache for this request */
+    skipCache?: boolean;
+    /** Custom metadata to attach to requests */
+    metadata?: Record<string, string>;
+}
+/**
+ * Create AI Gateway configuration for use with cascades
+ *
+ * @example
+ * ```typescript
+ * const gatewayConfig = createAIGatewayConfig({
+ *   gatewayId: 'my-gateway',
+ *   accountId: env.CF_ACCOUNT_ID,
+ *   cacheTtl: 3600, // 1 hour
+ * })
+ *
+ * // Use with AI binding
+ * const result = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
+ *   messages: [...],
+ *   ...gatewayConfig.toRequestOptions()
+ * })
+ * ```
+ */
+export declare function createAIGatewayConfig(config: AIGatewayConfig): {
+    config: AIGatewayConfig;
+    toRequestOptions: () => Record<string, unknown>;
+    getCacheKey: (input: unknown) => string;
+};
+/**
+ * DurableCascadeExecutor - Durable tiered execution with cascade pattern
+ *
+ * Combines the cascade pattern (code -> generative -> agentic -> human)
+ * with Cloudflare Workflows durability guarantees. Each tier execution
+ * creates a durable checkpoint that survives process restarts.
+ */
+export declare class DurableCascadeExecutor<TInput = unknown, TOutput = unknown> {
+    /** Cascade name */
+    readonly name: string;
+    /** Cascade configuration */
+    readonly config: DurableCascadeConfig<TInput, TOutput>;
+    /** AI binding (injected at runtime) */
+    private ai?;
+    /** Human review handler */
+    private humanReviewHandler?;
+    constructor(name: string, config: DurableCascadeConfig<TInput, TOutput>);
+    /**
+     * Set the AI binding for generative/agentic tiers
+     */
+    setAi(ai: AiBinding): this;
+    /**
+     * Set the human review handler
+     */
+    setHumanReviewHandler(handler: (request: HumanReviewRequest) => Promise<{
+        reviewId: string;
+        status: string;
+    }>): this;
+    /**
+     * Run the cascade with durable execution
+     */
+    run(workflowStep: WorkflowStep, input: TInput, options?: {
+        ai?: AiBinding;
+        humanReviewHandler?: (request: HumanReviewRequest) => Promise<{
+            reviewId: string;
+            status: string;
+        }>;
+    }): Promise<CascadeResult<TOutput>>;
+    /**
+     * Execute a single tier with durability
+     */
+    private executeTier;
+    /**
+     * Get the handler for a tier
+     */
+    private getTierHandler;
+    /**
+     * Get the next configured tier
+     */
+    private getNextConfiguredTier;
+    /**
+     * Emit a 5W+H event
+     */
+    private emitEvent;
+    /**
+     * Create a mock AI binding for testing
+     */
+    private createMockAi;
+}
+/**
+ * Create a durable cascade step for common AI props patterns
+ *
+ * @example
+ * ```typescript
+ * const titleCascade = createDurableCascadeStep({
+ *   name: 'generate-title',
+ *   code: async (input) => {
+ *     if (input.template) return { title: input.template }
+ *     throw new Error('No template')
+ *   },
+ *   generative: async (input, ctx) => {
+ *     const result = await ctx.ai.run('@cf/meta/llama-3-8b-instruct', {
+ *       messages: [{ role: 'user', content: `Generate a title for: ${input.topic}` }]
+ *     })
+ *     return { title: result.response }
+ *   }
+ * })
+ *
+ * // In workflow
+ * const result = await titleCascade.run(step, { topic: 'AI' })
+ * ```
+ */
+export declare function createDurableCascadeStep<TInput = unknown, TOutput = unknown>(config: {
+    name: string;
+    code?: CodeTierHandler<TInput, TOutput>;
+    generative?: AiTierHandler<TInput, TOutput>;
+    agentic?: AiTierHandler<TInput, TOutput>;
+    human?: HumanTierHandler<TInput, TOutput>;
+    timeouts?: Partial<Record<CapabilityTier, number>>;
+    tierConfig?: DurableCascadeConfig<TInput, TOutput>['tierConfig'];
+    onEvent?: (event: FiveWHEvent) => void;
+    actor?: string;
+}): DurableCascadeExecutor<TInput, TOutput>;
+//# sourceMappingURL=durable-cascade.d.ts.map

package/dist/durable-cascade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-cascade.d.ts","sourceRoot":"","sources":["../src/durable-cascade.ts"],"names":[],"mappings":"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"}