/**
 * LLMProviderPort — BYOM (Bring Your Own Model) abstraction.
 *
 * BYOM axiom (Brain entry 4fa36aad): the SDK ships ZERO default provider.
 * Callers inject the concrete adapter at boot. No model name is hardcoded
 * in this port file or any file that re-exports it.
 *
 * Plan v6 §3.2 — canonical interface.
 *
 * OTel instrumentation: import { createTracedLLMProviderPort } to wrap any
 * LLMProviderPort implementation with OpenTelemetry spans per completion.
 * Gracefully degrades to noop spans when no OTel SDK is installed.
 *
 * @public
 */
export interface ChatMessage {
    role: "system" | "user" | "assistant";
    content: string;
}
export interface ChatRequest {
    messages: ChatMessage[];
    model?: string;
    temperature?: number;
    maxTokens?: number;
    abortSignal?: AbortSignal;
    metadata?: {
        tenantId?: string;
        agentId?: string;
        correlationId?: string;
    };
}
export interface ChatUsage {
    inputTokens: number;
    outputTokens: number;
    /** Cost in USD. Optional — adapters that cannot compute it omit this field. */
    costUsd?: number;
    /** Tokens written to the prompt cache (Anthropic cache_creation_input_tokens). @since 1.13.0 */
    readonly cacheCreationTokens?: number;
    /** Tokens read from the prompt cache (Anthropic cache_read_input_tokens). @since 1.13.0 */
    readonly cacheReadTokens?: number;
}
export interface ChatResponse {
    content: string;
    usage: ChatUsage;
    model: string;
    finishReason: "stop" | "length" | "tool" | "error";
}
export interface StreamDelta {
    delta: string;
    usage?: ChatUsage;
}
export interface LLMProviderPort {
    /**
     * Blocking completion — resolves when the full response is available.
     * Never rejects on model error: return `finishReason: "error"` instead.
     */
    complete(req: ChatRequest): Promise<ChatResponse>;
    /**
     * Optional streaming completion.
     * Each yielded chunk carries at minimum `delta`; final chunk may carry `usage`.
     */
    stream?(req: ChatRequest): AsyncIterable<StreamDelta>;
    /**
     * Optional cost estimation before a real call.
     * Must be monotonically non-decreasing with token count.
     */
    estimateCost?(req: ChatRequest): {
        usd: number;
    };
}
/**
 * Base class for all LLM provider errors.
 * Concrete implementations throw subclasses so callers can switch on error type.
 */
export declare class LLMProviderError extends Error {
    readonly cause?: unknown | undefined;
    /** The provider identifier (e.g. "groq", "litellm", "anthropic"). */
    readonly provider: string;
    /** The model that was being called (e.g. "llama-3.3-70b"). */
    readonly model: string;
    constructor(message: string, provider: string, model: string, cause?: unknown | undefined);
}
/**
 * Thrown when the LLM provider returns 429 (rate limit exceeded).
 * Callers should retry after the delay indicated in `retryAfterMs`
 * or switch to a fallback provider.
 */
export declare class LLMRateLimitError extends LLMProviderError {
    /** Retry-After delay in milliseconds. */
    readonly retryAfterMs: number;
    constructor(message: string, provider: string, model: string, retryAfterMs: number, cause?: unknown);
}
/**
 * Wrap any LLMProviderPort implementation with OTel spans per complete() call.
 * The span captures the model, provider, and token usage on success.
 * Gracefully degrades to noop spans when no OTel SDK is installed.
 *
 * Usage:
 *   const raw: LLMProviderPort = buildAnthropicAdapter(...);
 *   const traced = createTracedLLMProviderPort(raw);
 *   const resp = await traced.complete(req) // emits "llm-provider.complete" span
 */
export declare function createTracedLLMProviderPort(impl: LLMProviderPort): LLMProviderPort;
//# sourceMappingURL=llm-provider.d.ts.map