octaflow 0.14.0

package/dist/ai/index.d.ts

@@ -0,0 +1,397 @@
+import { K as FlowErrorShape, T as RetryPolicy, h as TypedWorkflow, m as TypedStepContext, p as TypedStep, q as Result } from "../index-D_fOYfmf.js";
+import { n as Logger } from "../logger-BCus3AOa.js";
+import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-CDRFQZbT.js";
+import { z } from "zod";
+import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
+//#region src/ai/instrumented-model.d.ts
+interface AccumulatedUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  modelId: string;
+}
+interface UsageAccumulator {
+  /** Record usage from a single LLM call (additive — supports multiple calls per step). */
+  record(usage: AccumulatedUsage): void;
+  /** Total accumulated usage across all calls. */
+  get(): AccumulatedUsage;
+  /** Whether any usage was recorded. */
+  hasUsage(): boolean;
+}
+declare function createUsageAccumulator(): UsageAccumulator;
+/**
+ * Wrap a language model with usage-tracking middleware. The accumulator collects
+ * token usage from every doGenerate/doStream call routed through the wrapped model.
+ */
+declare function createInstrumentedModel(model: LanguageModelV4, accumulator: UsageAccumulator): LanguageModelV4;
+//#endregion
+//#region src/ai/instrumented-embedding-model.d.ts
+interface EmbeddingAccumulatedUsage {
+  inputTokens: number;
+  callCount: number;
+  modelId: string;
+}
+interface EmbeddingUsageAccumulator {
+  /** Record usage from a single doEmbed call (additive — supports multiple calls per batch). */
+  record(tokens: number, modelId: string): void;
+  /** Total accumulated usage across all calls. */
+  get(): EmbeddingAccumulatedUsage;
+  /** Whether any usage was recorded. */
+  hasUsage(): boolean;
+  /** Clear all accumulated state — used when a long-lived accumulator is reused across flushes. */
+  reset(): void;
+}
+declare function createEmbeddingUsageAccumulator(): EmbeddingUsageAccumulator;
+/**
+ * Wrap an embedding model with usage-tracking middleware. The accumulator collects
+ * token usage from every doEmbed call routed through the wrapped model — both
+ * `embed()` (single value) and `embedMany()` (batched values) invoke doEmbed one or
+ * more times, and each invocation is recorded.
+ */
+declare function createInstrumentedEmbeddingModel(model: EmbeddingModelV4, accumulator: EmbeddingUsageAccumulator): EmbeddingModelV4;
+//#endregion
+//#region src/ai/cost.d.ts
+/**
+ * Token → cost estimation. Cost is computed in **microdollars**
+ * (1 USD = 1,000,000 microdollars) to avoid float accumulation.
+ *
+ * The pricing table is injectable: pass your own to `createCostEstimator` for a
+ * different provider/model set. A default Anthropic/OpenAI-embedding table ships.
+ */
+interface ModelPricing {
+  inputPerMillion: number;
+  outputPerMillion: number;
+  cacheReadPerMillion: number;
+  cacheWritePerMillion: number;
+}
+interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+/** Default pricing (USD per million tokens), as of 2026-04. */
+declare const DEFAULT_MODEL_PRICING: Record<string, ModelPricing>;
+interface CostEstimatorOptions {
+  /** Pricing table keyed by model id. Defaults to `DEFAULT_MODEL_PRICING`. */
+  pricing?: Record<string, ModelPricing>;
+  /** Pricing used for unknown model ids. Defaults to the priciest entry in the table (safe overcounting). */
+  fallback?: ModelPricing;
+}
+type CostEstimator = (usage: TokenUsage, modelId: string) => number;
+/** Build a cost estimator returning microdollars. */
+declare function createCostEstimator(options?: CostEstimatorOptions): CostEstimator;
+/** Convenience estimator using the default pricing table. */
+declare const estimateCostMicros: CostEstimator;
+//#endregion
+//#region src/ai/context.d.ts
+/**
+ * The `TContext` flow-core threads through AI workflows. Produced by the
+ * `buildStepContext` hook in `createAiWorkflowHooks` and consumed by AI step
+ * handlers (which read `ctx.context.model` / `ctx.context.host`).
+ */
+interface AiContext<THost = unknown> {
+  /** Instrumented language model — token usage is captured automatically. */
+  model: LanguageModelV4;
+  /** Host-provided per-step context (DI scope, domain services, …). */
+  host: THost;
+  /**
+   * Internal: the per-step usage accumulator. The `onAfterStep` hook reads this
+   * back off the context to persist token/cost. Handlers should not touch it.
+   */
+  readonly usage: UsageAccumulator;
+}
+//#endregion
+//#region src/ai/define-ai-step.d.ts
+/** An AI workflow step — a flow-core `TypedStep` whose context is an `AiContext`. */
+type AiTypedStep<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}> = TypedStep<TInput, TOutput, TDeps, AiContext<THost>>;
+interface DefineAiStepConfig<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>>> {
+  type: string;
+  workflowInputSchema: z.ZodType<TInput>;
+  outputSchema: z.ZodType<TOutput>;
+  dependencies?: TDeps;
+  handler: (ctx: TypedStepContext<TInput, TDeps, AiContext<THost>>) => Promise<TOutput>;
+  /** Optional retry policy (max attempts, backoff) — e.g. for provider 429s. */
+  retry?: RetryPolicy;
+  /** Optional per-step wall-clock timeout in ms. */
+  timeoutMs?: number;
+  /** Optional durable start delay in ms — held in the queue once the step is ready. */
+  delayMs?: number;
+}
+/**
+ * Define a type-safe AI workflow step. Identical to flow-core's `defineStep`
+ * except the handler context is fixed to `AiContext<THost>`, so handlers get a
+ * ready-to-use `ctx.context.model` (instrumented) and `ctx.context.host`.
+ */
+declare function defineAiStep<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: DefineAiStepConfig<TInput, TOutput, THost, TDeps>): AiTypedStep<TInput, TOutput, THost, TDeps>;
+/** Build a typed AI workflow from `defineAiStep` definitions. */
+declare function buildAiWorkflow<TInput extends Record<string, unknown>, THost = unknown, TSteps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: {
+  type: string;
+  inputSchema: z.ZodType<TInput>;
+  steps: TSteps;
+}): TypedWorkflow<TInput, AiContext<THost>>;
+//#endregion
+//#region src/ai/hooks.d.ts
+interface AiModelResolver<THost = unknown> {
+  /** Resolve the base (uninstrumented) model for a step. */
+  resolveModel(args: BuildStepContextArgs): Promise<LanguageModelV4> | LanguageModelV4;
+  /** Optional host context (DI scope, services) exposed to handlers as `ctx.context.host`. */
+  resolveHost?(args: BuildStepContextArgs): Promise<THost> | THost;
+  /**
+   * Which key paid for the run — stamped into workflow metadata for usage
+   * rollups. Any string; `'platform' | 'tenant'` is the usual convention.
+   * When absent, rollups default to `'platform'`.
+   */
+  resolveKeySource?(): Promise<string> | string;
+}
+interface AiUsageRecorder {
+  /** Persist per-step token usage + cost (e.g. onto the step row). */
+  recordStepUsage(args: {
+    workflowId: number;
+    stepId: number;
+    usage: AccumulatedUsage;
+    costMicros: number;
+  }): Promise<void>;
+  /** Atomically add this step's usage + cost to the workflow's running totals. */
+  incrementWorkflowUsage(args: {
+    workflowId: number;
+    usage: AccumulatedUsage;
+    costMicros: number;
+  }): Promise<void>;
+  /**
+   * Roll the completed workflow's totals into a daily aggregate. The host reads
+   * the workflow's accumulated totals from its own store and UPSERTs the rollup.
+   */
+  recordWorkflowDaily?(args: {
+    workflowId: number;
+    workflowType: string;
+    keySource: string;
+    date: string;
+  }): Promise<void>;
+}
+interface AiQuotaPolicy {
+  /** Return an error (e.g. `ai_quota_exceeded`) to reject a workflow start. */
+  checkQuota(): Promise<Result<void, FlowErrorShape>>;
+}
+interface CreateAiWorkflowHooksDeps<THost = unknown> {
+  modelResolver: AiModelResolver<THost>;
+  usageRecorder: AiUsageRecorder;
+  /** Optional quota guard. BYOK exemption etc. is the policy's concern. */
+  quotaPolicy?: AiQuotaPolicy;
+  /** Defaults to `createCostEstimator()` (the built-in pricing table). */
+  costEstimator?: CostEstimator;
+  /** Clock injection for tests. */
+  now?: () => Date;
+}
+/**
+ * Wire the AI behaviors (model instrumentation, token/cost capture, quota,
+ * usage rollups) into a set of flow-core lifecycle hooks. Pass the result as the
+ * engine's `hooks`. flow-core stays AI-free; everything AI lives here.
+ */
+declare function createAiWorkflowHooks<THost = unknown>(deps: CreateAiWorkflowHooksDeps<THost>): WorkflowHooks<AiContext<THost>>;
+//#endregion
+//#region src/ai/quota.d.ts
+/**
+ * Resolved quota limits for a scope. `null` on any window means **unlimited**
+ * for that window (the check is skipped). The {@link AiQuotaConfigResolver} may
+ * return `null` for the whole config to exempt a scope entirely (e.g. a
+ * bring-your-own-key caller that shouldn't be metered against platform quota).
+ */
+interface AiQuotaConfig {
+  /** Max simultaneously-running workflows. `null` = unlimited. */
+  maxConcurrentWorkflows: number | null;
+  /** Max workflows started per calendar day (UTC). `null` = unlimited. */
+  maxWorkflowsPerDay: number | null;
+  /** Max workflows started per calendar month (UTC). `null` = unlimited. */
+  maxWorkflowsPerMonth: number | null;
+}
+/**
+ * Convenience defaults a consumer can spread over partial per-scope limits.
+ * flow does **not** apply these automatically — resolution policy lives in the
+ * injected {@link AiQuotaConfigResolver}.
+ */
+declare const DEFAULT_AI_QUOTA: AiQuotaConfig;
+/**
+ * Resolves the quota limits for a scope. Returning `null` exempts the scope
+ * from all quota enforcement (the check short-circuits to success).
+ */
+type AiQuotaConfigResolver = (partitionKey: string) => AiQuotaConfig | null | Promise<AiQuotaConfig | null>;
+/** A `[startDate, endDate]` inclusive query over the daily-usage rollup (dates are `YYYY-MM-DD`). */
+interface AiUsageCountQuery {
+  partitionKey: string;
+  /** Inclusive lower bound, `YYYY-MM-DD`. */
+  startDate: string;
+  /** Inclusive upper bound, `YYYY-MM-DD`. */
+  endDate: string;
+}
+/**
+ * The reads quota enforcement needs from storage. The consumer implements these
+ * with its own queries (over the in-flight workflow table and the daily-usage
+ * rollup); flow supplies no implementation. Any workflow-type filtering policy
+ * (e.g. excluding synthetic embedding rows from the count) lives in the
+ * consumer's SQL, keeping this layer policy-agnostic.
+ */
+interface AiQuotaStore {
+  /** Number of workflows currently `running` for the scope. */
+  countRunningWorkflows(partitionKey: string): Promise<number>;
+  /** Sum of `workflowCount` in the daily rollup over the inclusive date range. */
+  sumWorkflowCount(query: AiUsageCountQuery): Promise<number>;
+}
+/** Reason a start was rejected — which window tripped. */
+type AiQuotaExceededReason = 'concurrent_limit' | 'daily_limit' | 'monthly_limit';
+/** Expected error value when a start is rejected by quota. Extends flow's structural error. */
+interface AiQuotaExceededError {
+  key: 'ai_quota_exceeded';
+  reason: AiQuotaExceededReason;
+  message: string;
+  /** The limit that was hit. */
+  limit: number;
+  /** The observed count at rejection (includes in-flight runs for the day/month windows). */
+  current: number;
+}
+interface CreateAiQuotaServiceDeps {
+  /** Count reads over the in-flight workflow table + daily rollup. */
+  store: AiQuotaStore;
+  /** Per-scope limit resolver. Return `null` to exempt the scope. */
+  getQuota: AiQuotaConfigResolver;
+  /** Clock injection for window computation (tests). Defaults to `() => new Date()`. */
+  now?: () => Date;
+}
+interface AiQuotaService {
+  /**
+   * Check all quota windows for the scope. Resolves `ok` when the start is
+   * allowed, or an {@link AiQuotaExceededError} naming the window that tripped.
+   * The day and month counts include currently-running (not-yet-aggregated)
+   * workflows, matching the source semantics.
+   */
+  checkQuota(partitionKey: string): Promise<Result<void, AiQuotaExceededError>>;
+}
+/**
+ * Build a store-agnostic AI quota service. Enforcement order is concurrent →
+ * day → month; the first tripped window short-circuits with its error.
+ */
+declare function createAiQuotaService(deps: CreateAiQuotaServiceDeps): AiQuotaService;
+//#endregion
+//#region src/ai/usage-aggregation.d.ts
+/** An additive write into the daily-usage rollup for one run (workflow completion or embedding batch). */
+interface DailyUsageDelta {
+  partitionKey: string;
+  /** Calendar day of the run, `YYYY-MM-DD`. */
+  date: string;
+  workflowType: string;
+  /** Which key paid for the run (free-form; e.g. `'platform' | 'tenant'`). */
+  keySource: string;
+  /** How much to add to `workflowCount` — always `1` for the built-in recorders. */
+  workflowCount: number;
+  /** Token totals to add. Embeddings set only `inputTokens` (the rest are `0`). */
+  usage: TokenUsage;
+  /** Cost to add, in microdollars (1 USD = 1,000,000). */
+  estimatedCostMicros: number;
+}
+/** Inclusive `[startDate, endDate]` range query for the aggregate reads (`YYYY-MM-DD`). */
+interface AiUsageRangeQuery {
+  partitionKey: string;
+  startDate: string;
+  endDate: string;
+}
+/** One row of the per-day aggregate (GROUP BY date). */
+interface UsageSummaryRow {
+  date: string;
+  workflowCount: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  estimatedCostMicros: number;
+}
+/** One row of the per-type aggregate (GROUP BY workflowType, keySource). */
+interface UsageByTypeRow {
+  workflowType: string;
+  keySource: string;
+  workflowCount: number;
+  inputTokens: number;
+  outputTokens: number;
+  estimatedCostMicros: number;
+}
+/**
+ * The reads/writes usage aggregation needs from storage. Extends
+ * {@link AiQuotaStore} so a single consumer implementation backs both the quota
+ * and aggregation engines. The `addDailyUsage` UPSERT and the two aggregate
+ * reads are the consumer's SQL; flow owns everything above the seam.
+ */
+interface AiUsageStore extends AiQuotaStore {
+  /** UPSERT-add a run's usage into the daily rollup (unique on partition+date+type+keySource). */
+  addDailyUsage(delta: DailyUsageDelta): Promise<void>;
+  /** Per-day totals over the range, ascending by date. */
+  aggregateByDate(query: AiUsageRangeQuery): Promise<UsageSummaryRow[]>;
+  /** Per-(type, keySource) totals over the range. */
+  aggregateByWorkflowType(query: AiUsageRangeQuery): Promise<UsageByTypeRow[]>;
+}
+/** A completed LLM workflow's usage to roll up. */
+interface WorkflowUsageInput {
+  partitionKey: string;
+  /** Calendar day of completion, `YYYY-MM-DD`. */
+  date: string;
+  workflowType: string;
+  keySource: string;
+  usage: TokenUsage;
+  estimatedCostMicros: number;
+}
+/**
+ * A flushed embedding batch's usage to roll up. Embeddings have only input
+ * tokens (no output, no cache); `workflowCount` increments once per flushed
+ * batch, not per inner embed call.
+ */
+interface EmbeddingUsageInput {
+  partitionKey: string;
+  /** Calendar day of the flush, `YYYY-MM-DD`. */
+  date: string;
+  /** Synthetic type, e.g. `embedding:index-sync`. */
+  workflowType: string;
+  keySource: string;
+  inputTokens: number;
+  estimatedCostMicros: number;
+}
+/** Current-window usage snapshot for a scope. */
+interface CurrentQuotaUsage {
+  today: {
+    workflowCount: number;
+  };
+  thisMonth: {
+    workflowCount: number;
+  };
+  running: {
+    count: number;
+  };
+}
+/** Expected error value from aggregation reads/writes. Extends flow's structural error. */
+interface AiUsageError {
+  key: 'ai_usage_error';
+  message: string;
+}
+interface CreateAiUsageAggregationServiceDeps {
+  store: AiUsageStore;
+  /** Clock injection for the current-window computation (tests). Defaults to `() => new Date()`. */
+  now?: () => Date;
+  /** Optional logger for write failures. Defaults to a no-op. */
+  logger?: Logger;
+}
+interface AiUsageAggregationService {
+  /** Roll a completed LLM workflow's totals into the daily aggregate (UPSERT +1). */
+  recordWorkflowCompletion(data: WorkflowUsageInput): Promise<Result<void, AiUsageError>>;
+  /** Roll a flushed embedding batch into the daily aggregate (output/cache tokens = 0). */
+  recordEmbeddingUsage(data: EmbeddingUsageInput): Promise<Result<void, AiUsageError>>;
+  /** Per-day usage totals over an inclusive date range. */
+  getUsageSummary(params: AiUsageRangeQuery): Promise<Result<UsageSummaryRow[], AiUsageError>>;
+  /** Per-(type, keySource) usage totals over an inclusive date range. */
+  getUsageByWorkflowType(params: AiUsageRangeQuery): Promise<Result<UsageByTypeRow[], AiUsageError>>;
+  /** Today's / this-month's workflow counts and the current running count. */
+  getCurrentQuotaUsage(params: {
+    partitionKey: string;
+  }): Promise<Result<CurrentQuotaUsage, AiUsageError>>;
+}
+/** Build a store-agnostic AI usage-aggregation service. */
+declare function createAiUsageAggregationService(deps: CreateAiUsageAggregationServiceDeps): AiUsageAggregationService;
+//#endregion
+export { AccumulatedUsage, AiContext, AiModelResolver, AiQuotaConfig, AiQuotaConfigResolver, AiQuotaExceededError, AiQuotaExceededReason, AiQuotaPolicy, AiQuotaService, AiQuotaStore, AiTypedStep, AiUsageAggregationService, AiUsageCountQuery, AiUsageError, AiUsageRangeQuery, AiUsageRecorder, AiUsageStore, CostEstimator, CostEstimatorOptions, CreateAiQuotaServiceDeps, CreateAiUsageAggregationServiceDeps, CreateAiWorkflowHooksDeps, CurrentQuotaUsage, DEFAULT_AI_QUOTA, DEFAULT_MODEL_PRICING, DailyUsageDelta, EmbeddingAccumulatedUsage, EmbeddingUsageAccumulator, EmbeddingUsageInput, ModelPricing, TokenUsage, UsageAccumulator, UsageByTypeRow, UsageSummaryRow, WorkflowUsageInput, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createUsageAccumulator, defineAiStep, estimateCostMicros };