agents 0.23.0 → 0.25.0

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

@@ -0,0 +1,313 @@
+import {
+  a as CloudflareAIError,
+  c as GatewayOptions,
+  d as CloudflareEmbeddingModelId,
+  i as CloudflareAIAttempt,
+  l as ModelOptions,
+  n as GATEWAY_PROVIDER_NAMES,
+  o as CloudflareAIErrorCode,
+  r as GatewayProviderName,
+  s as AISettings,
+  v as WorkersAIModelId
+} from "../../transport-PfFnt-Ld.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.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+declare const CLOUDFLARE_AI_IMAGES_API = "cloudflare-ai-images";
+/** @experimental This surface is experimental and may change. */
+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.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+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}.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+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.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+declare const CLOUDFLARE_AI_API = "cloudflare-ai";
+/** @experimental This surface is experimental and may change. */
+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`.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+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}.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type CloudflareModel = Model<CloudflareAIApi>;
+/** @experimental This surface is experimental and may change. */
+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)`.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+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.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+/**
+ * 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.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+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.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+interface AI {
+  /** A Workers AI model: Cloudflare's own catalog, on the run path. */
+  (modelId: WorkersAIModelId, 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<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.
+ *
+ * The Workers AI binding is the only way in — Workers AI models go through
+ * `env.AI.run`, vendor models through `env.AI.gateway(id).run`, and there is
+ * no HTTP transport and no API token. 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-4.7-flash");
+ * ai(anthropicModel, { fallback: ["@cf/zai-org/glm-4.7-flash"] });
+ * new Agent({ streamFn: ai.streamFn, initialState: { model: ai(openaiModel) } });
+ * ```
+ *
+ * @experimental This surface is experimental and may change.
+ */
+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,
+  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