agents/dist/models/pi-ai/index.d.ts

A home for your AI agents

import {
  _ as DynamicRouteId,
  a as CloudflareAIError,
  b as WorkersAIModelId,
  c as GatewayOptions,
  f as CloudflareEmbeddingModelId,
  i as CloudflareAIAttempt,
  l as ModelOptions,
  n as GATEWAY_PROVIDER_NAMES,
  o as CloudflareAIErrorCode,
  r as GatewayProviderName,
  s as AISettings
} from "../../transport-5moD2pW5.js";
import {
  Api,
  AssistantImages,
  AssistantMessage,
  Context,
  ImageModel,
  ImagesContext,
  ImagesOptions,
  Model,
  Provider,
  SimpleStreamOptions,
  StreamOptions
} from "@earendil-works/pi-ai";

//#region src/models/core/chat-completions/quirks.d.ts
/**
 * Where a Cloudflare catalog model departs from strict OpenAI chat
 * completions, and how. Every entry is backed by a live capture from the
 * conformance probes (`research/40-*.json`, `41-*.json`); the default for an
 * unknown id is strict OpenAI, so a new conformant model needs no code here.
 *
 * Framework-neutral: both the AI SDK and the pi-ai providers consult this.
 */
/** A request feature that had to be changed or dropped for a model. */
interface CompatWarning {
  feature: string;
  message: string;
}
//#endregion
//#region src/models/pi-ai/models/image.d.ts
/**
 * The `api` marker on image models from this provider.
 */
declare const CLOUDFLARE_AI_IMAGES_API = "cloudflare-ai-images";
type CloudflareImagesModel = ImageModel<typeof CLOUDFLARE_AI_IMAGES_API>;
/**
 * Per-model options for image models: gateway options plus the generation
 * knobs Workers AI understands. Anything given here is the default for every
 * call; `generateImages` options override it.
 */
interface PiImagesModelOptions extends ModelOptions {
  name?: string;
  width?: number;
  height?: number;
  /** Diffusion steps, for models that accept it. */
  steps?: number;
  /** Classifier-free guidance scale, for models that accept it. */
  guidance?: number;
  negativePrompt?: string;
  seed?: number;
}
/** Per-call options for {@link generateImages}. */
interface PiImagesCallOptions extends ImagesOptions {
  width?: number;
  height?: number;
  steps?: number;
  guidance?: number;
  negativePrompt?: string;
  seed?: number;
}
/**
 * pi-ai's `AssistantImages` has no warnings channel, so a knob this catalog
 * drops is reported the way the language wires report theirs: as a diagnostic
 * of type {@link COMPAT_DIAGNOSTIC}.
 */
interface CloudflareAssistantImages extends AssistantImages {
  diagnostics?: {
    type: string;
    timestamp: number;
    details: {
      warnings: CompatWarning[];
    };
  }[];
}
//#endregion
//#region src/models/pi-ai/catalog.d.ts
/**
 * The `api` marker Workers AI models from this provider carry. It is not a
 * wire format: Workers AI runs on `env.AI.run`, and the compat layer maps that
 * onto strict OpenAI chat completions.
 */
declare const CLOUDFLARE_AI_API = "cloudflare-ai";
type CloudflareAIApi = typeof CLOUDFLARE_AI_API;
/**
 * The pi-ai provider id. A `Models` registry resolves specifiers as
 * `cloudflare/<id>`, e.g. `cloudflare/anthropic/claude-opus-4.8`.
 */
declare const CLOUDFLARE_PROVIDER_ID = "cloudflare";
/**
 * A Workers AI model produced by this provider. `id` is the `@cf/` id exactly
 * as given; `api` is {@link CLOUDFLARE_AI_API}.
 */
type CloudflareModel = Model<CloudflareAIApi>;
type ModelCost = Model<Api>["cost"];
/**
 * A model this provider routes: a Workers AI model or any pi-ai model the
 * caller handed to `ai(model)`.
 */
type RoutedModel = Model<Api>;
/**
 * Per-model options: the gateway options, client-side fallback, headers and
 * session affinity, plus pi-ai model metadata overrides and the stream idle
 * deadline. Metadata overrides only apply to the `@cf/` form — a model object
 * brings its own metadata, and this module never second-guesses it.
 */
/**
 * A fallback leg: a Workers AI id, a `<slug>/<id>` pi-ai's gateway registry
 * knows, or a model object. A raw vendor id is refused when the chain is built.
 */
type PiFallbackLeg = WorkersAIModelId | Model<Api> | (string & {});
interface PiModelOptions extends ModelOptions<PiFallbackLeg> {
  /** Display name. Defaults to the catalog name, else the id. */
  name?: string;
  /** Context window in tokens. Defaults to the catalog value, else 128000. */
  contextWindow?: number;
  /** Maximum output tokens. Defaults to the catalog value, else 8192. */
  maxTokens?: number;
  /** Whether the model can reason. Defaults to the catalog value, else true. */
  reasoning?: boolean;
  /** Accepted input modalities. Defaults to the catalog value. */
  input?: ("text" | "image")[];
  /** Cost per million tokens, used by pi-ai's usage accounting. */
  cost?: ModelCost;
  /**
   * Fail a stream that delivers no bytes for this long, in milliseconds. The
   * timer only runs while a read is outstanding, so consumer backpressure
   * never trips it. `0` disables the guard. Default 300000 (five minutes).
   */
  streamIdleTimeoutMs?: number;
}
//#endregion
//#region src/models/pi-ai/models/fallback.d.ts
/** A leg that was tried and failed before producing output. */
interface FallbackAttempt {
  model: string;
  errorMessage: string | undefined;
}
/** Diagnostic type under which abandoned legs are recorded. */
declare const FALLBACK_DIAGNOSTIC = "cloudflare-fallback";
//#endregion
//#region src/models/pi-ai/errors.d.ts
/** Diagnostic type under which a failed dispatch is recorded. */
declare const CLOUDFLARE_ERROR_DIAGNOSTIC = "cloudflare-error";
//#endregion
//#region src/models/pi-ai/wires/shared.d.ts
/** Diagnostic type under which gateway correlation ids are recorded. */
declare const CLOUDFLARE_DIAGNOSTIC = "cloudflare";
//#endregion
//#region src/models/pi-ai/index.d.ts
/**
 * pi-agent-core's `streamFn` shape: what `Agent` calls to run a turn.
 */
type StreamFn = (
  model: Model<string>,
  context: Context,
  options?: SimpleStreamOptions
) => ReturnType<Provider["streamSimple"]>;
/**
 * The provider `createAI` returns. Call it with a Workers AI id or with a
 * pi-ai model to get a model this instance routes; use `stream`/`complete` to
 * run it, `streamFn` with pi-agent-core's `Agent`, and `provider` with a pi-ai
 * `Models` registry.
 */
interface AI {
  /** A Workers AI model: Cloudflare's own catalog, on the run path. */
  (modelId: WorkersAIModelId, options?: PiModelOptions): CloudflareModel;
  /** An AI Gateway dynamic route, `dynamic/<route>`, on the Workers AI wire. */
  (route: DynamicRouteId, options?: PiModelOptions): CloudflareModel;
  /** Any pi-ai model, routed through AI Gateway with its metadata intact. */
  <TApi extends Api>(model: Model<TApi>, options?: PiModelOptions): Model<TApi>;
  /**
   * A `<slug>/<id>` id from pi-ai's Cloudflare AI Gateway catalog, or either
   * form when the caller only knows which at runtime.
   */
  (target: string | Model<Api>, options?: PiModelOptions): RoutedModel;
  /** Same as calling the provider directly. */
  model(modelId: WorkersAIModelId, options?: PiModelOptions): CloudflareModel;
  model(route: DynamicRouteId, options?: PiModelOptions): CloudflareModel;
  model<TApi extends Api>(
    model: Model<TApi>,
    options?: PiModelOptions
  ): Model<TApi>;
  model(target: string | Model<Api>, options?: PiModelOptions): RoutedModel;
  /**
   * The pi-ai `Provider` (id `cloudflare`) for `Models.setProvider` and
   * frameworks built on the registry. Its static model list is every Workers
   * AI id plus every `<slug>/<id>` in pi-ai's Cloudflare AI Gateway catalog;
   * any other model still streams when passed to `ai(model)`.
   */
  readonly provider: Provider;
  /** Full-options streaming, like pi-ai's `stream`. */
  stream(
    model: Model<string>,
    context: Context,
    options?: StreamOptions
  ): ReturnType<Provider["stream"]>;
  /** Full-options completion, like pi-ai's `complete`. */
  complete(
    model: Model<string>,
    context: Context,
    options?: StreamOptions
  ): Promise<AssistantMessage>;
  /** Simple streaming, with `reasoning` as a level, like pi-ai's `streamSimple`. */
  streamSimple(
    model: Model<string>,
    context: Context,
    options?: SimpleStreamOptions
  ): ReturnType<Provider["streamSimple"]>;
  /** Simple completion, like pi-ai's `completeSimple`. */
  completeSimple(
    model: Model<string>,
    context: Context,
    options?: SimpleStreamOptions
  ): Promise<AssistantMessage>;
  /** `streamSimple`, bound, for pi-agent-core's `Agent({ streamFn })`. */
  readonly streamFn: StreamFn;
  /** A pi-ai image model over a Workers AI text-to-image id. */
  images(
    modelId: string,
    options?: PiImagesModelOptions
  ): CloudflareImagesModel;
  /** Generates images with a model from {@link AI.images}, like pi-ai's `generateImages`. */
  generateImages(
    model: CloudflareImagesModel,
    context: ImagesContext,
    options?: PiImagesCallOptions
  ): Promise<CloudflareAssistantImages>;
}
/**
 * Creates a pi-ai provider over Cloudflare's AI.
 *
 * Workers AI and catalog models go through `env.AI.run`, other model objects
 * through the binding's `fetch` to AI Gateway's provider-native path. With
 * `{ accountId, apiToken }` instead of `binding`, the same requests go to the
 * REST API and to `gateway.ai.cloudflare.com`. Gateway options may be given flat
 * (`{ binding, id: "prod", cacheTtl: 60 }`) or nested under `gateway`;
 * per-model options and per-call pi-ai options (`headers`, `metadata`,
 * `sessionId`) override them in that order.
 *
 * ```ts
 * const ai = createAI({ binding: env.AI, id: "prod" });
 * ai("@cf/zai-org/glm-5.3-flash");
 * ai(anthropicModel, { fallback: ["@cf/zai-org/glm-5.3-flash"] });
 * new Agent({ streamFn: ai.streamFn, initialState: { model: ai(openaiModel) } });
 * ```
 */
declare function createAI(settings: AISettings): AI;
//#endregion
export {
  AI,
  type AISettings,
  CLOUDFLARE_AI_API,
  CLOUDFLARE_AI_IMAGES_API,
  CLOUDFLARE_DIAGNOSTIC,
  CLOUDFLARE_ERROR_DIAGNOSTIC,
  CLOUDFLARE_PROVIDER_ID,
  type CloudflareAIApi,
  type CloudflareAIAttempt,
  CloudflareAIError,
  type CloudflareAIErrorCode,
  type CloudflareAssistantImages,
  type CloudflareEmbeddingModelId,
  type CloudflareImagesModel,
  type CloudflareModel,
  type DynamicRouteId,
  FALLBACK_DIAGNOSTIC,
  type FallbackAttempt,
  GATEWAY_PROVIDER_NAMES,
  type GatewayOptions,
  type GatewayProviderName,
  type ModelCost,
  type ModelOptions,
  type PiImagesCallOptions,
  type PiImagesModelOptions,
  type PiModelOptions,
  type RoutedModel,
  StreamFn,
  type WorkersAIModelId,
  createAI
};
//# sourceMappingURL=index.d.ts.map