/**
 * Port: LLM access for non-grader features.
 *
 * Adapters wrap a vendor REST API and centralize retry, rate-limit handling,
 * cost calculation, and observability. Features call this port instead of
 * importing the grader's internals or a vendor SDK directly.
 *
 * The grader path (`packages/eval/src/pipeline/grader-api.ts`) is intentionally
 * NOT migrated here — D0051 defers grader migration as a follow-up.
 *
 * @see docs/decisions/D0051-llm-client-port.md
 */
import type { ZodType } from "zod";
import { type Brand, type IdValidationError, type Result } from "../types/branded-ids.js";
/**
 * A canonical LLM model identifier.
 *
 * Grammar: `<provider>:<segment>...:<modelName>` (e.g.
 * `"openai:chat:gpt-5.2"`, `"anthropic:messages:claude-opus-4-6"`,
 * `"anthropic:claude-sonnet-4-6"`). Branded so adapters can trust the
 * grammar and consumers can't accidentally pass an arbitrary string.
 */
export type ModelId = Brand<string, "ModelId">;
/** The supported provider prefixes for `ModelId`. */
export type ModelProvider = "anthropic" | "openai";
/** Result of parsing a `ModelId` — provider plus the bare model name. */
export interface ParsedModelId {
    readonly id: ModelId;
    readonly provider: ModelProvider;
    /** Bare vendor model name with provider segments stripped. */
    readonly modelName: string;
}
/**
 * Parse a raw string into a `ParsedModelId`. Returns `Result` — never throws.
 *
 * Recognized prefixes:
 * - `openai:<modelName>` or `openai:<sub>:<modelName>` (e.g. `"openai:chat:gpt-5"`)
 * - `anthropic:<modelName>` or `anthropic:messages:<modelName>`
 */
export declare function parseModelId(raw: string): Result<ParsedModelId, IdValidationError>;
/**
 * Throwing constructor — convenient for known-good inputs (config files,
 * tests). Throws if the id is malformed; use `parseModelId` for untrusted
 * input.
 */
export declare function modelId(raw: string): ModelId;
/**
 * Extract `provider` + `modelName` from an already-branded `ModelId`. Assumes
 * the id was produced by `parseModelId` / `modelId` and is therefore valid;
 * if it isn't, the caller's bug surfaces as a thrown `Error`.
 */
export declare function splitModelId(id: ModelId): ParsedModelId;
/**
 * Per-call telemetry tag. Carried through usage / cost records so billing can
 * roll up by feature, run, or card.
 */
export interface LLMCallContext {
    /** Logical feature name (e.g. "diagnosis", "meta-eval"). */
    feature: string;
    /** Optional pipeline run id when the call happens inside a run. */
    runId?: string;
    /** Optional originating card id (for diagnosis-style features). */
    cardId?: string;
}
/** Token usage reported by the vendor for a single call. */
export interface LLMUsage {
    promptTokens: number;
    completionTokens: number;
}
/** Result of a free-text completion. */
export interface LLMCompletion {
    text: string;
    usage: LLMUsage;
    /** End-to-end USD cost for the call. */
    cost: number;
    /** Echo of the canonical model id used. */
    model: ModelId;
}
/** Result of a structured-output completion. `value` is parsed via the supplied schema. */
export interface LLMStructuredCompletion<T> {
    value: T;
    usage: LLMUsage;
    cost: number;
    model: ModelId;
}
export interface LLMCompleteArgs {
    /** Canonical model id — produced by `modelId` / `parseModelId`. */
    model: ModelId;
    /** Raw prompt text — adapters wrap it in the vendor message envelope. */
    prompt: string;
    temperature?: number;
    maxTokens?: number;
    stop?: string[];
    context?: LLMCallContext;
}
export interface LLMCompleteStructuredArgs<T> {
    model: ModelId;
    prompt: string;
    /** Runtime contract — the adapter parses the model's response through this. */
    schema: ZodType<T>;
    temperature?: number;
    maxTokens?: number;
    context?: LLMCallContext;
}
/**
 * Synthesis-side LLM port. v0 is single-call only — streaming and batching are
 * deferred per D0051 until a consumer needs them.
 */
export interface LLMClient {
    complete(args: LLMCompleteArgs): Promise<LLMCompletion>;
    completeStructured<T>(args: LLMCompleteStructuredArgs<T>): Promise<LLMStructuredCompletion<T>>;
}
