/**
 * LLM Provider Adapter SDK -- public interface surface
 *
 * Defines the abstract interface that every LLM provider adapter must
 * implement. This is the contract between the governance runtime (which
 * is provider-agnostic) and the provider-specific transport layers.
 *
 * The governance runtime dispatches PreTool / PostTool hooks, approval-
 * queue routing, audit-chain emission, and circuit-breaker state through
 * this interface. No provider-specific branching is permitted in the
 * runtime layer -- all provider logic lives here.
 *
 * Spec: P3-SUB-01 (LLM Provider Adapter SDK)
 * AC:   1-3, 22-27 (interface, base, error hierarchy, version pinning)
 *
 * @connexum/ai-governance
 */
export type LlmSovereignty = 'us' | 'eu' | 'multi' | 'local' | 'cn' | 'other' | 'unknown';
export type LlmModelFamily = 'claude' | 'gpt' | 'gemini' | 'gemma' | 'titan' | 'llama' | 'mistral' | 'phi' | 'unknown';
/**
 * Multimodal content part types (F-NEW-GEMMA-VISION 2026-05-09).
 *
 * Adapters that support multimodal input (vision, audio, etc.) accept
 * `LlmMessage.content` as either a plain string OR an array of typed
 * parts. Adapters that DO NOT support multimodal MUST reject array
 * content with `LlmProviderError` (UNSUPPORTED_MULTIMODAL) — silently
 * dropping image parts is a governance violation.
 *
 * The `image_url.url` field is governance-relevant data: pack
 * classifiers see it through the same pre-call check as text content.
 * Both `data:` URIs (base64-inline) and `gs://` URIs (Google Cloud
 * Storage) are valid; adapter implementations decide how to map the
 * URI to the provider's wire format (e.g. inlineData vs fileData for
 * Google Gen AI).
 */
export interface LlmTextPart {
    type: 'text';
    text: string;
}
export interface LlmImageUrlPart {
    type: 'image_url';
    image_url: {
        /** Required. http(s) URL, data: URI, or gs:// URI. */
        url: string;
        /** Optional MIME type hint (image/png, image/jpeg, image/webp, image/heic, image/heif). */
        mimeType?: string;
        /**
         * Optional detail level pass-through. Currently advisory; OpenAI
         * uses 'low'/'high'/'auto'. Adapters may ignore.
         */
        detail?: 'low' | 'high' | 'auto';
    };
}
export type LlmContentPart = LlmTextPart | LlmImageUrlPart;
export interface LlmMessage {
    role: 'system' | 'user' | 'assistant' | 'tool';
    /**
     * Either plain text (legacy / text-only) or an ordered array of
     * typed content parts (multimodal). Arrays are only accepted by
     * adapters whose getCapabilities() reports `multimodal: true`.
     */
    content: string | LlmContentPart[];
    /** Tool call ID (present on role=tool responses) */
    toolCallId?: string;
}
export interface LlmChatRequest {
    /** Model identifier or deployment name */
    modelId: string;
    messages: LlmMessage[];
    /** Optional system prompt override */
    systemPrompt?: string;
    /** Maximum tokens to generate */
    maxTokens?: number;
    /** Temperature (0-2) */
    temperature?: number;
    /** Tools / function definitions available to the model */
    tools?: LlmToolDefinition[];
    /** Provider-specific pass-through options */
    providerOptions?: Record<string, unknown>;
}
export interface LlmChatResponse {
    /** Actual model name returned by provider (may differ from requested) */
    modelId: string;
    content: string;
    finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'unknown';
    toolCalls?: LlmToolCallResult[];
    usage?: LlmTokenAccounting;
    /** Raw provider response for adapter-level debugging only */
    _raw?: unknown;
}
export interface LlmStreamChunk {
    /** Delta content for this chunk */
    delta: string;
    finishReason?: LlmChatResponse['finishReason'];
    /** Partial tool call accumulation */
    toolCallDelta?: Partial<LlmToolCallResult>;
    /** Usage stats (only on final chunk, if provider sends them) */
    usage?: LlmTokenAccounting;
}
export interface LlmToolDefinition {
    name: string;
    description: string;
    parameters: Record<string, unknown>;
}
export interface LlmToolUseRequest {
    modelId: string;
    messages: LlmMessage[];
    tools: LlmToolDefinition[];
    systemPrompt?: string;
    maxTokens?: number;
    temperature?: number;
    providerOptions?: Record<string, unknown>;
}
export interface LlmToolCallResult {
    id: string;
    name: string;
    arguments: Record<string, unknown>;
}
export interface LlmToolUseResponse {
    modelId: string;
    toolCalls: LlmToolCallResult[];
    content?: string;
    finishReason: LlmChatResponse['finishReason'];
    usage?: LlmTokenAccounting;
    _raw?: unknown;
}
export interface LlmTokenAccounting {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
    /** Cost in USD, if determinable */
    estimatedCostUsd?: number;
}
export interface LlmModelDescriptor {
    modelId: string;
    family: LlmModelFamily;
    /** Provider-side display name */
    displayName?: string;
    /** Approx context window in tokens */
    contextWindow?: number;
    deprecated?: boolean;
}
export interface LlmSafetySignal {
    category: string;
    blocked: boolean;
    probability?: 'NEGLIGIBLE' | 'LOW' | 'MEDIUM' | 'HIGH';
    severity?: string;
}
export interface LlmAdapterCapabilities {
    /** Supports multi-turn chat */
    chat: boolean;
    /** Supports streaming (AsyncIterable chunks) */
    streaming: boolean;
    /** Supports function / tool calling */
    toolUse: boolean;
    /** Supports listing available models */
    modelEnumeration: boolean;
    /** Provider has a HIPAA BAA available */
    baa: boolean;
    /** BAA modality scope (null means full coverage) */
    baaScope?: string;
    /**
     * Supports multimodal content (image_url parts, etc.). When false,
     * the adapter MUST reject array-shaped LlmMessage.content with
     * UNSUPPORTED_MULTIMODAL. (F-NEW-GEMMA-VISION 2026-05-09.)
     */
    multimodal?: boolean;
}
export interface LlmAdapterConfig {
    /** API key or bearer token (provider-specific) */
    apiKey?: string;
    /** Base URL override (useful for proxies and Ollama) */
    baseUrl?: string;
    /** Default model to use when none is specified in the request */
    defaultModelId?: string;
    /** Request timeout in milliseconds (default: 30000) */
    timeoutMs?: number;
    /** Maximum retry attempts on transient failures (default: 3) */
    maxRetries?: number;
    /** Azure-specific: resource name (part of base URL) */
    resourceName?: string;
    /** Azure-specific: deployment name (required for AzureOpenAIAdapter) */
    deploymentName?: string;
    /** Bedrock-specific: AWS region (required -- no env fallback) */
    region?: string;
    /** Bedrock-specific: AWS access key ID */
    awsAccessKeyId?: string;
    /** Bedrock-specific: AWS secret access key */
    awsSecretAccessKey?: string;
    /** Bedrock-specific: session token for temporary credentials */
    awsSessionToken?: string;
    /** Ollama-specific: offline BAA reference document ID */
    offlineBaaReference?: string;
    /**
     * Active compliance packs for this customer install. When set, the
     * adapter's initialize() consults ProviderCompliance.check() and refuses
     * to initialize if the providerId is blocked by any active pack.
     * F-NEW-CRIT-32: closes the gap where pack.providerPolicy.blockedProviders
     * was dead data because no LLM adapter consulted it.
     */
    activePacks?: string[];
    /**
     * Optional strict-mode flag passed through to ProviderCompliance.
     * Defaults to true (fail-closed). Customers should not flip this off
     * outside dev/test.
     */
    providerComplianceStrictMode?: boolean;
    /** Additional provider-specific config */
    options?: Record<string, unknown>;
}
export type ReviewCadence = '30d' | '90d' | '180d' | '365d';
export interface ProviderComplianceRegistration {
    providerId: string;
    /** Provider has a HIPAA BAA */
    baa: boolean;
    /** If BAA is modality-restricted, describe the scope */
    baaScope?: string;
    /** Public URL where the BAA / DPA claim is verifiable */
    attestationUrl?: string;
    /** ISO-8601 date when the claim was last human-verified */
    attestationDate?: string;
    /** How often governance team must re-verify */
    reviewCadence?: ReviewCadence;
    /** Provider has a GDPR DPA */
    gdprDpa: boolean;
    /** Provider has SOC 2 Type II */
    soc2Type2: boolean;
    /** Data sovereignty scope */
    sovereignty: LlmSovereignty;
    /** BAA limited to Vertex AI path only (Google) */
    baaPath?: string;
    /** Human-readable note on BAA limitations */
    baaNote?: string;
}
/**
 * Every LLM provider adapter must implement this interface.
 *
 * No method is optional. Adapters that genuinely cannot support a method
 * (e.g. a provider with no model enumeration API) must throw
 * `LlmToolUseError` or `LlmProviderError` with an explicit not-supported
 * reason rather than returning null / undefined silently.
 */
export interface LlmProviderAdapter {
    /** Unique adapter identifier (e.g. 'azure-openai', 'claude-code') */
    readonly adapterId: string;
    /** Canonical provider ID (e.g. 'microsoft', 'anthropic') */
    readonly providerId: string;
    /**
     * Initialize the adapter with provider-specific config.
     * Must throw `LlmAuthError` synchronously if credentials are missing
     * or structurally invalid (no network call required at this point).
     */
    initialize(config: LlmAdapterConfig): void;
    /** Single-turn and multi-turn chat completion */
    chat(request: LlmChatRequest): Promise<LlmChatResponse>;
    /** Streaming chat -- yields chunks as the provider streams them */
    chatStream(request: LlmChatRequest): AsyncIterable<LlmStreamChunk>;
    /** Tool-use round-trip (function calling) */
    invokeToolUse(request: LlmToolUseRequest): Promise<LlmToolUseResponse>;
    /** List models available on this adapter / deployment */
    enumerateModels(): Promise<LlmModelDescriptor[]>;
    /**
     * Translate a raw provider error (HTTP response body, thrown object,
     * etc.) into a typed `LlmProviderError` subclass.
     * Every adapter must implement this -- it is called in the base retry
     * loop to ensure typed errors bubble up regardless of the call site.
     */
    translateError(raw: unknown): LlmProviderError;
    /** Normalise token usage from a response into the common accounting type */
    accountTokens(response: LlmChatResponse | LlmToolUseResponse): LlmTokenAccounting;
    /** Returns true if this adapter's provider has a HIPAA BAA */
    claimsBaa(): boolean;
    /** Report capabilities for this adapter instance */
    getCapabilities(): LlmAdapterCapabilities;
}
/**
 * Base error for all LLM provider errors.
 * Every error path in every adapter throws a typed subclass.
 * No adapter swallows an error and returns a fallback value.
 */
export declare class LlmProviderError extends Error {
    readonly code: string;
    readonly providerId: string;
    readonly adapterId: string;
    readonly httpStatus?: number;
    /** When the caller may retry (milliseconds) */
    readonly retryAfterMs?: number;
    /** Raw provider response (first 500 chars max) */
    readonly raw?: unknown;
    constructor(opts: {
        message: string;
        code: string;
        providerId: string;
        adapterId: string;
        httpStatus?: number;
        retryAfterMs?: number;
        raw?: unknown;
    });
}
/** Authentication / credential failure */
export declare class LlmAuthError extends LlmProviderError {
    constructor(opts: Omit<ConstructorParameters<typeof LlmProviderError>[0], 'code'>);
}
/** Rate limit exceeded -- retryAfterMs is required */
export declare class LlmRateLimitError extends LlmProviderError {
    constructor(opts: Omit<ConstructorParameters<typeof LlmProviderError>[0], 'code'> & {
        retryAfterMs: number;
    });
}
/** Content blocked by provider content filter */
export declare class LlmContentFilterError extends LlmProviderError {
    readonly filterCategory?: string;
    constructor(opts: Omit<ConstructorParameters<typeof LlmProviderError>[0], 'code'> & {
        filterCategory?: string;
    });
}
/** Requested model not found or not available on this adapter */
export declare class LlmModelNotFoundError extends LlmProviderError {
    readonly requestedModelId: string;
    constructor(opts: Omit<ConstructorParameters<typeof LlmProviderError>[0], 'code'> & {
        requestedModelId: string;
    });
}
/** Tool / function calling failure or unsupported operation */
export declare class LlmToolUseError extends LlmProviderError {
    readonly toolName?: string;
    constructor(opts: Omit<ConstructorParameters<typeof LlmProviderError>[0], 'code'> & {
        toolName?: string;
    });
}
//# sourceMappingURL=index.d.ts.map