/**
 * LLM provider abstraction layer for Iranti.
 *
 * Provides a unified interface over multiple LLM backends (OpenAI, Gemini,
 * Claude, Groq, Mistral, Ollama, and a mock for tests). Provider selection is
 * controlled by LLM_PROVIDER and LLM_PROVIDER_FALLBACK env vars. All requests
 * flow through completeWithFallback() which walks the fallback chain and emits
 * a staff event on fallback or total failure.
 *
 * Budget enforcement: every LLM call within a request context increments a
 * counter tracked via AsyncLocalStorage. Calls beyond MAX_LLM_CALLS_PER_REQUEST
 * throw immediately to prevent runaway LLM spend.
 *
 * Providers are lazily loaded on first use and cached in-process. The mock
 * provider is always appended to the fallback chain as a last-resort safety net.
 *
 * Key exports:
 *   - completeWithFallback()         — call LLM with fallback chain + budget enforcement
 *   - completeRouted()               — call a specific provider/model directly
 *   - complete()                     — shorthand for completeWithFallback with default options
 *   - initProvider()                 — warm up a named provider
 *   - getSupportedProviders()        — list of all known provider names
 *   - normalizeProviderApiError()    — standardize HTTP API error messages
 *   - normalizeProviderCaughtError() — standardize caught provider errors
 *   - LLMProvider / LLMMessage / LLMResponse — core provider interface types
 */
type SessionLedgerEmitContext = {
    source?: string;
    host?: string | null;
    agentId?: string;
    operation?: string;
};
export interface LLMMessage {
    role: 'user' | 'assistant';
    content: string;
}
export interface LLMResponse {
    text: string;
    model: string;
    provider: string;
}
export type CompleteOptions = {
    model?: string;
    maxTokens?: number;
    timeoutMs?: number;
};
export interface LLMProvider {
    complete(messages: LLMMessage[], options?: CompleteOptions): Promise<LLMResponse>;
}
export declare function normalizeProviderApiError(provider: string, status: number | undefined, statusText: string | undefined, rawBody?: string): Error;
export declare function normalizeProviderCaughtError(provider: string, error: unknown): Error;
export declare function getSupportedProviders(): string[];
export declare function getLLM(): LLMProvider;
export declare function initProvider(name: string): Promise<LLMProvider>;
export declare function completeWithFallback(messages: LLMMessage[], options?: {
    preferredProvider?: string;
    model?: string;
    maxTokens?: number;
    timeoutMs?: number;
    ledgerContext?: SessionLedgerEmitContext;
}): Promise<LLMResponse & {
    providerUsed: string;
}>;
export declare function completeRouted(messages: LLMMessage[], route: {
    provider: string;
    model?: string;
    maxTokens?: number;
}): Promise<LLMResponse>;
export declare function complete(messages: LLMMessage[], maxTokens?: number): Promise<LLMResponse>;
export {};
//# sourceMappingURL=llm.d.ts.map