import { type LlmRole } from './registry.js';
import { type LlmUsage } from './provider-base.js';
export interface IntrospectionInput {
    /** Role name to look up in the registry. */
    role: LlmRole;
    /** The user prompt. Required. */
    prompt: string;
    /** Optional system prompt prepended as a system message. */
    system?: string;
    /** Hard deadline. Default 30s — short enough that a stuck provider
     *  trips fallback fast, long enough that legitimate JSON extraction
     *  on a free-tier model completes. */
    timeoutMs?: number;
    /** Caller may pass through an AbortSignal (e.g. distill's queue is
     *  draining); we merge it with timeoutMs. */
    signal?: AbortSignal;
    /** Per-call temperature override (cheap callers usually want 0.2; the
     *  provider default is already low so this is rarely needed). */
    temperature?: number;
    /** Per-call model override; falls back to the provider's default. */
    model?: string;
    /** Ask the provider for JSON Output when supported (DeepSeek / OpenAI). */
    jsonMode?: boolean;
}
export interface IntrospectionResult {
    /** Plain text body. Empty string means "model returned nothing useful";
     *  the caller decides whether that's a failure. */
    text: string;
    /** Aggregate usage from the provider. */
    usage: LlmUsage;
    /** Backend name that handled the request; useful for audit rows. */
    backendName: string;
    /** Provider type label (e.g. "deepseek" / "openai-compat") for the
     *  cost dashboard. */
    providerType: string;
    /** Elapsed wall-clock time. */
    durationMs: number;
}
/**
 * Try to satisfy the introspection request via the configured backend
 * for `role`. Returns null when:
 *   - no provider is wired for this role, OR
 *   - the provider call failed (errors are logged + classified, never
 *     re-thrown — the caller's fallback path takes over).
 *
 * The "return null on failure" contract is exactly what distill /
 * consolidate / intent want: they then fall back to spawning their
 * CLI agent and the user notices nothing.
 */
export declare function tryIntrospect(input: IntrospectionInput): Promise<IntrospectionResult | null>;
/**
 * Stage 5 — try a CHAIN of roles in order until one returns a non-null
 * result. The chain is operator-configurable per call (typically
 * ['cheap', 'native-chat', 'evaluator'] for low-stakes introspection
 * that should escalate to a smarter / different vendor on failure).
 *
 * Returns the first successful IntrospectionResult, augmented with
 * `triedRoles` so the caller can audit which roles got skipped. When
 * every role in the chain returns null, returns null — the caller's
 * existing CLI-fallback path takes over (same contract as
 * tryIntrospect).
 */
export interface IntrospectionChainInput extends Omit<IntrospectionInput, 'role'> {
    /** Roles to try in order. Empty array returns null immediately. */
    roles: LlmRole[];
    /** Per-role wall-clock cap (default 30s). */
    perRoleTimeoutMs?: number;
}
export interface IntrospectionChainResult extends IntrospectionResult {
    /** Roles attempted in order, including the one that succeeded
     *  (always last). Lets the caller log "we fell back twice". */
    triedRoles: LlmRole[];
}
export declare function tryIntrospectChain(input: IntrospectionChainInput): Promise<IntrospectionChainResult | null>;
//# sourceMappingURL=introspection.d.ts.map