/** * Native judgment client: the {@link Judge} backend for catalog models whose * API answers typed questions directly ({@link isJudgmentApi}). * * Each judgment API is one wire dialect: TypeSafe's System One route * (`POST /v1/systemone`), OpenRouter Decisions (`POST /api/alpha/decisions`, * same body), Cloudflare Workers AI (`POST /ai/run/{model}`, same body plus * top-level data URL images; `systemone.ts`), OpenAI Decisions * (`POST /v1/decisions`, translated both ways; `openai-decisions.ts`), and * Gemini Decisions (`POST /v1beta/decisions`, positional question keys and an * `x-goog-api-key` credential; `google-decisions.ts`). * Credentials flow through {@link withAuth}, so a stored key rotates on * 401/403 exactly like chat providers; transient 429/5xx responses retry with * bounded, `retry-after`-aware backoff. Endpoints that cap the questions per * request (the catalog's `judgment-questions-max`, e.g. OpenJEV at 16) get * oversized requests split into chunks under `maxQuestions`, at most * {@link CHUNK_PARALLEL} in flight at once. * * Environment (mirrors the official TypeSafe SDK, for judges built without an * explicit model): `TYPESAFE_API_KEY` is resolved by the auth registry * (`rules/auth/typesafe.kdl`), `TYPESAFE_BASE_URL` overrides the API root, * `TYPESAFE_DEFAULT_MODEL` the model. */ import { type JudgmentImageInput } from "@oh-my-pi-zen/pi-catalog/compat/judgment-images"; import type { Api, FetchImpl } from "@oh-my-pi-zen/pi-catalog/types"; import { type ApiKey } from "../auth-retry.js"; import * as AIError from "../error/index.js"; import type { ImageContent, Model, Usage } from "../types.js"; import { type Judge, type JudgeOptions, type JudgmentRequest, type JudgmentResult, type Questions } from "./types.js"; import type { JudgmentImageAssets, JudgmentWire } from "./wire.js"; export type { JudgmentImageAssets } from "./wire.js"; export declare const TYPESAFE_PROVIDER = "typesafe"; export declare const TYPESAFE_DEFAULT_MODEL = "jev-latest"; declare const JUDGMENT_WIRES: { readonly typesafe: JudgmentWire; readonly "openrouter-decisions": JudgmentWire; readonly "workers-ai-systemone": JudgmentWire; readonly "openai-decisions": JudgmentWire; readonly "google-decisions": JudgmentWire; readonly "liquid-systemone": JudgmentWire; readonly "nace-systemone": JudgmentWire; }; /** APIs {@link NativeJudge} can serve. */ export type JudgmentApi = keyof typeof JUDGMENT_WIRES; /** Whether a catalog API answers judgments natively. */ export declare function isJudgmentApi(api: Api): api is JudgmentApi; /** Whether both the native protocol and catalog model support image input. */ export declare function nativeJudgmentSupportsImages(model: Model): boolean; /** Whether `model`'s native judgment takes images and its wire forwards box questions. The model itself may still refuse them (Box needs Jev 1.14+). */ export declare function nativeJudgmentSupportsBoxes(model: Model): boolean; /** * Every image bound `model`'s native judgment enforces: its wire's transport limits tightened by the * catalog's model bounds. `undefined` when it takes no images. Native APIs reject images outside these * rather than resizing them, so callers size images to them first. */ export declare function nativeJudgmentImageBounds(model: Model): JudgmentImageInput | undefined; /** Whether `model`'s native judgment API takes these exact images: image support within every {@link nativeJudgmentImageBounds}. */ export declare function nativeJudgmentAcceptsImages(model: Model, images: readonly ImageContent[]): boolean; /** Whether `images` fall within every cap and floor of `bounds`. */ export declare function judgmentImagesWithin(images: readonly ImageContent[], bounds: JudgmentImageInput): boolean; /** * Reject images that `model`'s native judgment API cannot take — no image support, an unsupported or * unreferenced asset, or a transport or catalog bound exceeded — before any credential or upstream work. * @throws {AIError.ValidationError} naming the reason. */ export declare function checkNativeJudgmentImages(model: Model, request: JudgmentRequest, imageAssets?: JudgmentImageAssets): void; /** * Reject box questions whose `image` is not an index into `request.images`: nothing would say which * image their edges measure. * @throws {AIError.ValidationError} naming the question. */ export declare function checkBoxQuestions(request: JudgmentRequest): void; /** `TYPESAFE_BASE_URL` when set, else the public API root; trailing slashes stripped. */ export declare function typesafeBaseUrl(): string; /** `TYPESAFE_DEFAULT_MODEL` when set, else {@link TYPESAFE_DEFAULT_MODEL}. */ export declare function typesafeModel(): string; /** Credential and transport overrides for a judge; see {@link createNativeJudge}. */ export interface NativeJudgeConnection { apiKey: ApiKey; /** Static headers attached to judgment requests (e.g. proxy routing, gateway auth). */ headers?: Record; fetch?: FetchImpl; } export interface NativeJudgeOptions extends NativeJudgeConnection { /** Wire dialect; defaults to TypeSafe's own API. */ api?: JudgmentApi; /** Catalog provider reported on results; defaults to {@link TYPESAFE_PROVIDER}. */ provider?: string; /** Defaults to {@link typesafeBaseUrl}. */ baseUrl?: string; /** Wire model id; defaults to {@link typesafeModel}. */ model?: string; /** Per-attempt timeout; defaults to {@link DEFAULT_TIMEOUT_MS}. */ timeoutMs?: number; /** * Most questions per request the endpoint accepts, a positive integer; larger * requests are split. Unset: no cap. */ maxQuestions?: number; /** * Whether images are enabled for this judge. `false` disables image input; `true` enables * dialects that require explicit opt-in but cannot enable a wire without image support. */ supportsImages?: boolean; /** Catalog-selected image bounds, applied in addition to the wire's transport constraints. */ imageInput?: JudgmentImageInput; /** Fields merged over every encoded request body (e.g. OpenRouter `provider` routing preferences). */ extraBody?: Record; } /** Per-call options for {@link NativeJudge.judge}. */ export interface NativeJudgeCallOptions extends JudgeOptions { /** Assets keyed by their existing references; wires without asset transport reject them. */ imageAssets?: JudgmentImageAssets; /** * Called before a split judgment rejects, with the summed usage of the chunks that had already * succeeded: billed upstream, but their answers are discarded with the failure. Not called when * no chunk succeeded or the request was not split. */ onPartialUsage?: (usage: Usage) => void; } /** Non-2xx response from a native judgment API. */ export declare class JudgmentApiError extends AIError.ProviderHttpError { readonly name = "JudgmentApiError"; } export declare class NativeJudge implements Judge { #private; readonly label: string; /** True when the selected native wire and model or direct-call option permit image input. */ readonly supportsImages?: boolean; readonly api: JudgmentApi; readonly provider: string; /** Wire model id sent with every request. */ readonly model: string; readonly baseUrl: string; constructor(options: NativeJudgeOptions); judge(request: JudgmentRequest, options?: NativeJudgeCallOptions): Promise>; /** Effective image detail for cache identity after applying this wire's forwarding behavior. */ effectiveImageDetail(detail: ImageContent["detail"]): ImageContent["detail"]; } /** * The {@link NativeJudge} for a catalog judge model: its API's dialect, wire id * (`requestModelId ?? id`), base URL, catalog question cap * (`judgment-questions-max`), and, for OpenRouter Decisions, the compat * `openRouterRouting` (sent as `provider`) and `extraBody` request controls. * Shared by the coding agent's judge chain and the auth-gateway System One * route so both address a model the same way. * * @throws ConfigurationError when the model's API is not a judgment API. */ export declare function createNativeJudge(model: Model, connection: NativeJudgeConnection): NativeJudge;