@dcdr/contracts 1.9.6

package/dist/prompts.contract.d.ts

@@ -0,0 +1,97 @@
+import { Message } from "./messages.contract";
+import { PromptParameters } from "./policies.contract";
+export declare enum PromptTemplateInterpolationType {
+    /** {{var}} — Mustache style (RECOMMENDED) */
+    MUSTACHE = "MUSTACHE",
+    /** ${var} — JavaScript template literal style */
+    JS_TEMPLATE = "JS_TEMPLATE",
+    /** #var# — Simple legacy style */
+    HASH = "HASH",
+    /** <<var>> — XML / chatbot legacy style */
+    ANGLE = "ANGLE"
+}
+export declare enum PromptVariableType {
+    INTEGER = "integer",
+    FLOAT = "float",
+    STRING = "string",
+    BOOLEAN = "boolean",
+    JSON = "json",
+    ANY = "any",
+    ARRAY = "array",
+    OBJECT = "object",
+    ENUM = "enum"
+}
+export declare class PromptVariable {
+    type: PromptVariableType;
+    required?: boolean;
+    description?: string;
+    itemsType?: PromptVariableType;
+    properties?: Record<string, PromptVariable>;
+    values?: string[];
+    /**
+     * Optional constraints:
+     * - For integer/float: min/max numeric value
+     * - For string: min/max length
+     */
+    min?: number;
+    max?: number;
+    constructor(type: PromptVariableType, required?: boolean, description?: string, itemsType?: PromptVariableType, properties?: Record<string, PromptVariable>, values?: string[], // NEW
+    min?: number, max?: number);
+}
+/**
+ * A versioned prompt template.
+ * This should be stable and reproducible:
+ * - `id`, `version`, and `sha256` MUST uniquely identify the prompt content.
+ * - `semanticHash` MUST represent the semantic meaning (stable normalization).
+ * - `messages` is the canonical representation (avoid raw string prompts).
+ */
+export interface PromptTemplate {
+    /** Unique prompt identifier (e.g., UUID). */
+    id: string;
+    /** Human-friendly version label (e.g., "2026-02-17.1" or "v20260217.3"). */
+    version: string;
+    /** Human-readable name (e.g., "openai-format-parser"). */
+    name: string;
+    /** Human-readable description for diagnostics. */
+    description?: string;
+    /**
+     * SHA256 hash of the canonical prompt payload (e.g., stable JSON serialization).
+     * Useful as an immutable fingerprint / audit trail.
+     */
+    sha256: string;
+    /**
+     * Precomputed semantic hash (stable across irrelevant formatting changes).
+     * This MUST be exported from backend and used for:
+     * - problemHash (dataset dedupe)
+     * - runHash (execution dedupe)
+     */
+    semanticHash: string;
+    /**
+     * Provider-agnostic prompt messages (with optional placeholders).
+     * This is the canonical representation.
+     */
+    messages: Message[];
+    /**
+     * Declared variables contract (not values).
+     * Used for validation / preflight checks, not interpolation.
+     */
+    /**
+     * Interpolation style to render placeholders in messages.
+     * Default MUST be MUSTACHE.
+     */
+    variablesInterpolationType?: PromptTemplateInterpolationType;
+    /**
+   * Default runtime params (temperature, max_tokens, etc.).
+   * Can be overridden per request.
+   *
+   * NOTE:
+   * - AISemantics.buildRuntimeParamsKey can include these as another layer if you want:
+   *   impl.runtimeConfig -> prompt.params -> model.params -> request.override
+   */
+    params?: PromptParameters;
+    /** Optional tags for routing/diagnostics (e.g., "strict_json", "qc", "beta"). */
+    tags?: string[];
+    /** Optional metadata for audits/diagnostics. */
+    meta?: Record<string, any>;
+}
+//# sourceMappingURL=prompts.contract.d.ts.map

package/dist/prompts.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.contract.d.ts","sourceRoot":"","sources":["../src/prompts.contract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAIvD,oBAAY,+BAA+B;IAEvC,6CAA6C;IAC7C,QAAQ,aAAa;IAErB,iDAAiD;IACjD,WAAW,gBAAgB;IAE3B,kCAAkC;IAClC,IAAI,SAAS;IAEb,2CAA2C;IAC3C,KAAK,UAAU;CAClB;AAGD,oBAAY,kBAAkB;IAC1B,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,IAAI,SAAS;CAChB;AAKD,qBAAa,cAAc;IAEvB,IAAI,EAAE,kBAAkB,CAAC;IAIzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAGnB,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAG/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAM5C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;;;OAIG;IAGH,GAAG,CAAC,EAAE,MAAM,CAAC;IAIb,GAAG,CAAC,EAAE,MAAM,CAAC;gBAGT,IAAI,EAAE,kBAAkB,EACxB,QAAQ,GAAE,OAAe,EACzB,WAAW,CAAC,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,kBAAkB,EAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAC3C,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM;IACzB,GAAG,CAAC,EAAE,MAAM,EACZ,GAAG,CAAC,EAAE,MAAM;CAWnB;AAKD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAE3B,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IAEX,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAEhB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,QAAQ,EAAE,OAAO,EAAE,CAAC;IAEpB;;;OAGG;IAGH;;;OAGG;IACH,0BAA0B,CAAC,EAAE,+BAA+B,CAAC;IAE7D;;;;;;;KAOC;IACD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAE1B,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B"}

package/dist/prompts.contract.js

@@ -0,0 +1,87 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptVariable = exports.PromptVariableType = exports.PromptTemplateInterpolationType = void 0;
+const class_validator_1 = require("class-validator");
+var PromptTemplateInterpolationType;
+(function (PromptTemplateInterpolationType) {
+    /** {{var}} — Mustache style (RECOMMENDED) */
+    PromptTemplateInterpolationType["MUSTACHE"] = "MUSTACHE";
+    /** ${var} — JavaScript template literal style */
+    PromptTemplateInterpolationType["JS_TEMPLATE"] = "JS_TEMPLATE";
+    /** #var# — Simple legacy style */
+    PromptTemplateInterpolationType["HASH"] = "HASH";
+    /** <<var>> — XML / chatbot legacy style */
+    PromptTemplateInterpolationType["ANGLE"] = "ANGLE";
+})(PromptTemplateInterpolationType || (exports.PromptTemplateInterpolationType = PromptTemplateInterpolationType = {}));
+var PromptVariableType;
+(function (PromptVariableType) {
+    PromptVariableType["INTEGER"] = "integer";
+    PromptVariableType["FLOAT"] = "float";
+    PromptVariableType["STRING"] = "string";
+    PromptVariableType["BOOLEAN"] = "boolean";
+    PromptVariableType["JSON"] = "json";
+    PromptVariableType["ANY"] = "any";
+    PromptVariableType["ARRAY"] = "array";
+    PromptVariableType["OBJECT"] = "object";
+    PromptVariableType["ENUM"] = "enum";
+})(PromptVariableType || (exports.PromptVariableType = PromptVariableType = {}));
+class PromptVariable {
+    type;
+    required;
+    description;
+    itemsType;
+    properties; // NEW
+    // Enum values (only meaningful when type === "enum")
+    values;
+    /**
+     * Optional constraints:
+     * - For integer/float: min/max numeric value
+     * - For string: min/max length
+     */
+    min;
+    max;
+    constructor(type, required = false, description, itemsType, properties, values, // NEW
+    min, max) {
+        this.type = type;
+        this.required = required;
+        this.description = description;
+        this.itemsType = itemsType;
+        this.properties = properties;
+        this.values = values;
+        this.min = min;
+        this.max = max;
+    }
+}
+exports.PromptVariable = PromptVariable;
+__decorate([
+    (0, class_validator_1.IsBoolean)(),
+    (0, class_validator_1.IsOptional)()
+], PromptVariable.prototype, "required", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)()
+], PromptVariable.prototype, "description", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)()
+], PromptVariable.prototype, "itemsType", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)()
+], PromptVariable.prototype, "properties", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.IsString)({ each: true })
+], PromptVariable.prototype, "values", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsNumber)()
+], PromptVariable.prototype, "min", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsNumber)()
+], PromptVariable.prototype, "max", void 0);

package/dist/provider.contract.d.ts

@@ -0,0 +1,477 @@
+import { ImplementationContract } from "./implementations.contract";
+import { Message } from "./messages.contract";
+import { Intent, IntentContract, IntentType } from "./intent.contract";
+import { PromptParameters } from "./policies.contract";
+import { PromptTemplate } from "./prompts.contract";
+import { CredentialsContract } from "./credentials.contract";
+/**
+ * Supported provider backends capable of executing an intent.
+ *
+ * These represent the underlying execution engines used by the runtime.
+ * A provider may represent:
+ *
+ * - A hosted LLM service (OpenAI, Gemini, Grok, etc.)
+ * - A local inference runtime (OFFICE, OLLAMA, VLLM)
+ * - A specialized processing engine (OCR, CLIP)
+ * - An internal execution system (RULES, HTTP_TOOL)
+ */
+export declare enum IntentProvider {
+    /**
+     * Virtual provider managed by DCDR.
+     *
+     * Notes
+     * - Cloud-only concept: the registry/runtime can resolve the underlying real provider (OpenAI/Anthropic/Gemini/Office).
+     * - Model IDs are namespaced as `provider/model` (e.g. `openai/gpt-4o-mini`) for deterministic resolution.
+     */
+    DCDR = "DCDR",
+    /** OpenAI hosted models (GPT family, embeddings, etc.) */
+    OPEN_AI = "OPEN_AI",
+    /** Google Gemini models */
+    GEMINI = "GEMINI",
+    /** xAI Grok models */
+    GROK = "GROK",
+    /** Anthropic Claude models */
+    ANTHROPIC = "ANTHROPIC",
+    /** Mistral hosted models */
+    MISTRAL = "MISTRAL",
+    /** Cohere models (chat + embeddings) */
+    COHERE = "COHERE",
+    /**
+     * Local inference runtime hosted internally (runtime-managed).
+     *
+     * Notes
+     * - Use this when the runtime/operator controls the endpoint (e.g. office GPU cluster running vLLM).
+     * - If a customer wants to plug in their own OpenAI-compatible endpoint, use OPEN_AI_COMPATIBLE.
+     */
+    OFFICE = "OFFICE",
+    /**
+     * Ollama local inference runtime.
+     * Useful for developer setups and local deployments.
+     */
+    OLLAMA = "OLLAMA",
+    /**
+     * Generic OpenAI-compatible endpoint (bring-your-own).
+     *
+     * Goal
+     * - Allow customers to plug in internal systems that expose an OpenAI-style API.
+     *
+     * Examples
+     * - vLLM, TGI, LM Studio, or custom gateways that mimic the OpenAI schema.
+     */
+    OPEN_AI_COMPATIBLE = "OPEN_AI_COMPATIBLE",
+    /**
+     * Optical character recognition engine.
+     */
+    OCR = "OCR",
+    /**
+     * CLIP-like models for multimodal embedding.
+     */
+    CLIP = "CLIP",
+    /**
+     * Generic HTTP tool provider.
+     * Used to call external APIs or services.
+     */
+    HTTP_TOOL = "HTTP_TOOL",
+    /**
+     * Internal rule-based execution engine.
+     * Used for deterministic logic instead of LLMs.
+     */
+    RULES = "RULES"
+}
+export type ProviderExecuteArgs = {
+    intent: Intent;
+    implementation: ImplementationContract;
+    credentials: CredentialsContract | null;
+    prompt: PromptTemplate;
+    renderedMessages: Message[];
+    vars: Record<string, unknown>;
+    /**
+     * If provided, this is what will be sent to the provider.
+     */
+    runtimeConfig?: PromptParameters;
+    /**
+     * ✅ Attempt timeout controlled by run policy.
+     */
+    attemptTimeoutMs?: number;
+    /**
+     * ✅ Optional model contract for schemas, tool configs, etc.
+     * If you don't want to pass the whole model, pass outputSchema only.
+     */
+    model?: IntentContract | null;
+    /** The hash of the problem associated with this execution. */
+    problemHash: string | null;
+    /** The hash of the run associated with this execution. */
+    runHash: string | null;
+    /**
+     * Optional tenant/customer id to scope runtime-side caches and circuit breakers.
+     *
+     * Notes
+     * - When omitted, the runtime will treat it as internal/default scope.
+     */
+    tenantCid?: string;
+};
+/**
+ * The result of executing a provider call.
+ * This is what ProviderExecutor returns to ExecutionService, which later writes it to AICallLog.
+ */
+export type ProviderExecuteResult = {
+    output: unknown;
+    cached: boolean;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+};
+/**
+ * Pricing metadata shared across different pricing components.
+ */
+export interface ProviderPricingMeta {
+    currency: "USD" | "EURO" | "GBP" | string;
+    /** Optional URL to the provider pricing page used as the source. */
+    sourceUrl?: string;
+    /** Timestamp (ms) indicating when this pricing snapshot was last updated. */
+    updatedAt: number;
+    /** How confident this data is (design-time friendly). */
+    confidence?: "official" | "approx" | "unknown";
+    notes?: string;
+}
+export type ProviderPricingComponent = {
+    kind: "tokens";
+    unit: "per_million_tokens";
+    input: number;
+    outputUsd: number;
+    cachedInput?: number;
+    cachedOutput?: number;
+    /** Optional tiered pricing (e.g. different rates by modality or prompt size). */
+    tiers?: Array<{
+        name: string;
+        condition?: string;
+        input: number;
+        output: number;
+        cachedInput?: number;
+        cachedOutput?: number;
+    }>;
+    notes?: string;
+} | {
+    kind: "characters";
+    unit: "per_million_characters";
+    input: number;
+    notes?: string;
+} | {
+    kind: "audio_minutes";
+    unit: "per_minute";
+    input: number;
+    output?: number;
+    notes?: string;
+} | {
+    kind: "images";
+    unit: "per_image";
+    input?: number;
+    output?: number;
+    notes?: string;
+} | {
+    kind: "video_seconds";
+    unit: "per_second";
+    input?: number;
+    output?: number;
+    notes?: string;
+} | {
+    kind: "pages";
+    unit: "per_1000_pages";
+    input: number;
+    notes?: string;
+};
+/** Unified pricing for a model: composed of 1..N pricing components. */
+export interface ProviderModelPricing extends ProviderPricingMeta {
+    components: ProviderPricingComponent[];
+}
+/** Runtime-level support status for a (provider, modelId) pair. */
+export declare enum ProviderModelRuntimeSupportStatus {
+    /** Supported by this runtime (intended to work). */
+    SUPPORTED = "SUPPORTED",
+    /** Explicitly not supported by this runtime (do not attempt provider calls). */
+    NOT_SUPPORTED = "NOT_SUPPORTED",
+    /** Known failing in current runtime; keep visible but treat as unstable. */
+    FAILING = "FAILING",
+    /** Under active work; may be partially implemented. */
+    IN_PROGRESS = "IN_PROGRESS"
+}
+/** Preferred upstream API surface for this model (when provider offers multiple). */
+export declare enum ProviderModelPreferredApi {
+    CHAT_COMPLETIONS = "CHAT_COMPLETIONS",
+    RESPONSES = "RESPONSES"
+}
+/** Generic prompt/runtime parameter keys that can be exposed to users (UI) and adapters. */
+export declare enum PromptParameterKey {
+    TEMPERATURE = "temperature",
+    TOP_P = "top_p",
+    TOP_K = "top_k",
+    MAX_TOKENS = "max_tokens",
+    SEED = "seed",
+    ENABLE_THINKING = "enable_thinking",
+    RESPONSE_FORMAT = "response_format",
+    PRESENCE_PENALTY = "presence_penalty",
+    FREQUENCY_PENALTY = "frequency_penalty"
+}
+/** Runtime-level parameter support status for a specific model. */
+export declare enum ProviderModelParameterSupportStatus {
+    /** Parameter is supported and may be used. */
+    SUPPORTED = "SUPPORTED",
+    /** Parameter is not supported and should not be sent. */
+    NOT_SUPPORTED = "NOT_SUPPORTED",
+    /** Only provider default is supported; runtime should avoid sending custom values. */
+    DEFAULT_ONLY = "DEFAULT_ONLY"
+}
+/** Optional parameter support metadata attached to a model definition (for UI and adapter normalization). */
+export interface ProviderModelParameterSupportInfo {
+    /** Per-parameter support mapping. Omitted keys mean "unknown" (use adapter defaults). */
+    parameters?: Partial<Record<PromptParameterKey, ProviderModelParameterSupportStatus>>;
+    /** Optional recommendations to avoid common misconfiguration. */
+    recommended?: {
+        /** Recommended minimum `max_tokens` to avoid empty/reasoning-only outputs on some models. */
+        minMaxTokens?: number;
+    };
+    /** Human-readable notes (safe for UI/logs). */
+    notes?: string;
+    /** ISO date string of last verification (e.g. from E2E/probes). */
+    updatedAt?: string;
+}
+/** Optional runtime support metadata attached to a model definition. */
+export interface ProviderModelRuntimeSupportInfo {
+    status: ProviderModelRuntimeSupportStatus;
+    preferredApi?: ProviderModelPreferredApi;
+    /** Human-readable notes (safe for logs/CI). */
+    reason?: string;
+    /** ISO date string of last verification (e.g. from E2E/probes). */
+    updatedAt?: string;
+}
+/**
+ * Product-level managed categories for public customer models.
+ *
+ * Purpose
+ * - Provide a stable grouping/filtering abstraction for customer-facing UIs.
+ * - Avoid exposing a flat provider/model list by default.
+ */
+export declare enum DcdrPublicModelCategory {
+    /** Maximum quality / strongest reasoning; typically expensive. */
+    BEST = "BEST",
+    /** Best balance between quality and cost; recommended default for production chat. */
+    SMART = "SMART",
+    /** Low latency; good for interactive chat/support. */
+    FAST = "FAST",
+    /** Lowest cost; good for high-volume simple tasks. */
+    ECONOMY = "ECONOMY",
+    /** Internal/local/company-managed models (self-hosted, Office, etc.). */
+    PRIVATE = "PRIVATE"
+}
+/**
+ * Canonical (de-duplicated) model definition.
+ *
+ * A single model can support multiple IntentType(s). Keeping the model metadata in one place
+ * avoids duplicating fields like cost/capabilities across multiple per-type listings.
+ */
+export interface ProviderModelDefinition {
+    id: string;
+    types: IntentType[];
+    /**
+     * If true, this model is eligible for customer-facing UIs.
+     *
+     * Notes
+     * - Fail-closed: missing/undefined is treated as false by the catalog normalizer.
+     * - This does not affect runtime execution support; it is a UI curation flag.
+     */
+    publicForCustomers: boolean;
+    /** Stable customer-facing family name for managed public models (should not expose provider/model IDs). */
+    publicName?: string;
+    /** Small variant label displayed next to `publicName` (e.g. "OpenAI", "Fast", "Lowest cost"). */
+    badge?: string;
+    /** Primary managed category used for default grouping in simple UI mode. */
+    primaryCategory?: DcdrPublicModelCategory;
+    /** Additional managed categories/tags for badges and advanced filtering. */
+    categories?: DcdrPublicModelCategory[];
+    /** Quality tier (1..5), where 5 is best. */
+    qualityTier?: number;
+    /** Speed tier (1..5), where 5 is best. */
+    speedTier?: number;
+    /** Cost tier (1..5), where 5 is best (lowest cost). */
+    costTier?: number;
+    /** Optional suggested use cases (safe for UI). */
+    recommendedUseCases?: string[];
+    /** Model is generally recommended to customers. */
+    isRecommended?: boolean;
+    /** Global default model when the user has not chosen any model/category. Exactly one public model should be true. */
+    isGlobalDefault?: boolean;
+    /** Default model within its primaryCategory when a category is chosen but no specific model is selected. */
+    isCategoryDefault?: boolean;
+    /**
+     * When true, this model has been verified (via E2E) to return token usage (`promptTokens`/`completionTokens`/`totalTokens`)
+     * in the runtime execution report.
+     *
+     * Notes
+     * - This is a billing invariant: public customer models must have token usage tracking.
+     * - Missing/undefined is treated as false (fail-closed).
+     */
+    tokenUsageCovered?: boolean;
+    pricing?: ProviderModelPricing;
+    runtimeSupport?: ProviderModelRuntimeSupportInfo;
+    parameterSupport?: ProviderModelParameterSupportInfo;
+}
+/**
+ * Stricter shape for public customer models.
+ *
+ * Notes
+ * - This is an additive (non-breaking) interface.
+ * - The catalog normalizer enforces these fields at runtime for models where `publicForCustomers === true`.
+ */
+export interface ProviderPublicCustomerModelDefinition extends ProviderModelDefinition {
+    publicForCustomers: true;
+    publicName: string;
+    badge?: string;
+    tokenUsageCovered: boolean;
+    primaryCategory: DcdrPublicModelCategory;
+    categories: DcdrPublicModelCategory[];
+    qualityTier: number;
+    speedTier: number;
+    costTier: number;
+    recommendedUseCases: string[];
+    isRecommended: boolean;
+    isGlobalDefault: boolean;
+    isCategoryDefault: boolean;
+}
+/** Options for ProviderModelRegistry.listProviderModels(...). */
+export interface ProviderModelListProviderModelsOptions {
+    /** When true, only returns models explicitly curated for customer-facing UIs. */
+    onlyPublicForCustomers?: boolean;
+}
+/** Provider + model pairing for public customer model listing helpers. */
+export interface ProviderPublicCustomerModelRef {
+    provider: IntentProvider;
+    modelId: string;
+    model: ProviderPublicCustomerModelDefinition;
+}
+/** Options for ProviderModelRegistry.listPublicCustomerModels(...). */
+export interface ProviderModelListPublicCustomerModelsOptions {
+    /** Optional filter: only include models whose primaryCategory matches this value. */
+    primaryCategory?: DcdrPublicModelCategory;
+    /** Optional filter: only include models that contain at least one of these categories. */
+    includeCategories?: DcdrPublicModelCategory[];
+}
+export interface DcdrVirtualModelResolution {
+    provider: IntentProvider;
+    modelId: string;
+    prefixedModelId: string;
+}
+/**
+ * Formats a DCDR virtual provider model id as `provider/model`.
+ *
+ * Returns an empty string for unsupported provider prefixes.
+ */
+export declare function formatDcdrVirtualModelId(provider: IntentProvider, modelId: string): string;
+/**
+ * Parses a DCDR virtual provider model id of the form `provider/model`.
+ *
+ * Returns null when the id is not a valid DCDR virtual model id.
+ */
+export declare function parseDcdrVirtualModelId(prefixedModelId: string): DcdrVirtualModelResolution | null;
+/**
+ * Canonical provider model catalog (after enrichment passes).
+ */
+export declare const PROVIDER_MODEL_DEFINITIONS_BY_PROVIDER: Record<IntentProvider, ProviderModelDefinition[]>;
+/**
+ * Canonical lookup: provider -> modelId -> model definition.
+ */
+export declare const PROVIDER_MODEL_CATALOG: Record<IntentProvider, Record<string, ProviderModelDefinition>>;
+/**
+ * Primary listing structure (no duplicated metadata): provider -> intent type -> model IDs.
+ */
+export declare const PROVIDER_MODEL_IDS_BY_PROVIDER_AND_TYPE: Record<IntentProvider, Record<IntentType, string[]>>;
+/**
+ * E2E model status used by provider test suites.
+ *
+ * Notes
+ * - This is an opt-in testing mechanism; it does not affect runtime behavior.
+ * - Use `LEGACY` to explicitly skip obsolete/retired model IDs while still keeping them
+ *   discoverable in the catalog for historical compatibility.
+ */
+export declare enum ProviderModelE2EStatus {
+    /** Model should be exercised by E2E suites (when provider is implemented and credentials exist). */
+    ACTIVE = "ACTIVE",
+    /** Model is considered legacy/obsolete and may be skipped by E2E suites. */
+    LEGACY = "LEGACY"
+}
+/**
+ * Per-model E2E override metadata.
+ */
+export interface ProviderModelE2EOverride {
+    status: ProviderModelE2EStatus;
+    /** Human-readable skip rationale (keep short; safe for CI logs). */
+    reason: string;
+}
+/**
+ * Optional provider-model overrides consumed by the provider E2E matrix tests.
+ *
+ * How to use
+ * - When a model ID becomes obsolete/retired, mark it as `LEGACY` with a reason.
+ * - The E2E suite will still enumerate it (catalog stays complete) but will skip execution.
+ */
+export declare const PROVIDER_MODEL_E2E_OVERRIDES: Record<IntentProvider, Record<string, ProviderModelE2EOverride>>;
+/**
+ * Static utility class for querying the provider model catalog.
+ *
+ * Designed for client consumption: `ProviderModelRegistry.listProvidersSupportingType(...)`.
+ */
+export declare class ProviderModelRegistry {
+    /** Canonical catalog view: provider -> modelId -> definition. */
+    static readonly catalog: Record<IntentProvider, Record<string, ProviderModelDefinition>>;
+    /** Primary listing view: provider -> intent type -> model IDs. */
+    static readonly idsByProviderAndType: Record<IntentProvider, Record<IntentType, string[]>>;
+    /** Source-of-truth definitions in declared order (useful for UI display). */
+    static readonly definitionsByProvider: Record<IntentProvider, ProviderModelDefinition[]>;
+    /** Returns the model definition if present; otherwise null. */
+    static getModelDefinition(provider: IntentProvider, modelId: string): ProviderModelDefinition | null;
+    /** Lists all model IDs for a provider (stable order as declared in the catalog). */
+    static listProviderModelIds(provider: IntentProvider): string[];
+    /** Lists all model definitions for a provider (stable order as declared in the catalog). */
+    static listProviderModels(provider: IntentProvider, options?: ProviderModelListProviderModelsOptions): ProviderModelDefinition[];
+    /**
+     * Lists all public customer models across all providers.
+     *
+     * Notes
+     * - Uses the catalog declared order (provider order, then per-provider declaration order).
+     * - This is a UI/helper surface only; execution still uses provider+modelId.
+     */
+    static listPublicCustomerModels(options?: ProviderModelListPublicCustomerModelsOptions): ProviderPublicCustomerModelRef[];
+    /**
+     * Groups all public customer models by their primaryCategory.
+     *
+     * Intended for the "simple UI" mode where the UI shows high-level DCDR groups.
+     */
+    static listPublicCustomerModelsByPrimaryCategory(): Record<DcdrPublicModelCategory, ProviderPublicCustomerModelRef[]>;
+    /** Lists model IDs for a provider that support a given IntentType. */
+    static listProviderModelIdsForType(provider: IntentProvider, type: IntentType): string[];
+    /** Lists model definitions for a provider that support a given IntentType. */
+    static listProviderModelsForType(provider: IntentProvider, type: IntentType): ProviderModelDefinition[];
+    /** Returns true if the provider has at least one model for the given IntentType. */
+    static providerSupportsType(provider: IntentProvider, type: IntentType): boolean;
+    /** Returns true if the model supports the given IntentType (based on the catalog). */
+    static modelSupportsType(provider: IntentProvider, modelId: string, type: IntentType): boolean;
+    /** Lists all providers that have at least one model supporting the given IntentType. */
+    static listProvidersSupportingType(type: IntentType): IntentProvider[];
+    /** Returns all model IDs across all providers for a given type. */
+    static listAllModelIdsForType(type: IntentType): Array<{
+        provider: IntentProvider;
+        modelId: string;
+    }>;
+    /** Convenience: get unified pricing if present (or null if not set/unknown). */
+    static getModelPricing(provider: IntentProvider, modelId: string): ProviderModelPricing | null;
+    /** Get a specific pricing component from a model by kind (or null if absent). */
+    static getPricingComponent<TKind extends ProviderPricingComponent["kind"]>(provider: IntentProvider, modelId: string, kind: TKind): Extract<ProviderPricingComponent, {
+        kind: TKind;
+    }> | null;
+    /** Convenience: token pricing (per MTok) if present. */
+    static getTokenPricing(provider: IntentProvider, modelId: string): Extract<ProviderPricingComponent, {
+        kind: "tokens";
+    }> | null;
+}
+//# sourceMappingURL=provider.contract.d.ts.map