/**
 * GAIA Dataset Loader — ADR-133-PR1
 *
 * Authenticates to Hugging Face, downloads the `gaia-benchmark/GAIA`
 * validation split, caches it under ~/.cache/ruflo/gaia/, and exposes
 * a typed `loadGaia()` API consumed by the capability-gaia subcommand.
 *
 * Token resolution order (mirrors performance-capability.ts ANTHROPIC_API_KEY pattern):
 *   1. $HF_TOKEN env var
 *   2. gcloud secrets versions access latest --secret=huggingface-token
 *   3. Fail with a clear error message
 *
 * This file is deliberately a skeleton / PR-1 checkpoint.  The full
 * dataset download is gated behind a real HF_TOKEN; a 5-question smoke
 * fixture is provided for offline / CI-without-HF testing.
 *
 * Refs: ADR-133, #2156
 */
export type GaiaLevel = 1 | 2 | 3;
export interface GaiaQuestion {
    /** Unique identifier from the HF dataset. */
    task_id: string;
    /** Difficulty level: 1 (easiest) → 3 (hardest). */
    level: GaiaLevel;
    /** The question text sent to the agent. */
    question: string;
    /** Ground-truth final answer (string normalised, no surrounding whitespace). */
    final_answer: string;
    /** Optional file attachment filename; resolved to an absolute path by the loader. */
    file_name: string | null;
    /** Absolute path to the cached attachment, or null if no attachment. */
    file_path: string | null;
    /** Steps annotation (meta-data, not used by agent). */
    annotator_metadata?: Record<string, unknown>;
}
export interface LoadGaiaOptions {
    /** Level filter (default: 1). */
    level?: GaiaLevel;
    /** Maximum questions to return (default: all). */
    limit?: number;
    /** Skip HF download; use the built-in 5-question smoke fixture instead. */
    smokeOnly?: boolean;
    /** Override the cache directory (default: ~/.cache/ruflo/gaia). */
    cacheDir?: string;
}
/**
 * Resolve a Hugging Face API token using two fallbacks:
 *   1. $HF_TOKEN env var
 *   2. `gcloud secrets versions access latest --secret=huggingface-token`
 *
 * Throws with a clear error if neither is available.
 */
export declare function resolveHfToken(): string;
/**
 * Export the default cache directory path (no side effects).
 */
export declare function getDefaultCacheDir(): string;
/**
 * Minimal offline fixture for smoke tests and CI environments without HF_TOKEN.
 * Answers are verified by hand against publicly known facts.
 * All questions are Level 1 (no file attachments, no multi-hop tool use required).
 *
 * IMPORTANT: Verify every answer key with `node -e 'console.log(…)'` before
 * adding entries to this list — three answer-key bugs were caught in session #2156.
 */
export declare const SMOKE_FIXTURE: GaiaQuestion[];
/**
 * Download all attachment files referenced by the questions list.
 * Mutates each question's `file_path` field in place.
 * Skips questions without a file_name.
 */
export declare function resolveAttachments(questions: GaiaQuestion[], token: string, cacheDir: string): Promise<void>;
/**
 * Load GAIA validation questions.
 *
 * - With `smokeOnly: true` (or when HF_TOKEN is unavailable): returns the 5-question
 *   smoke fixture — no network call, no token required.
 * - Otherwise: authenticates to HF, downloads level N questions, caches locally.
 *
 * @throws if HF_TOKEN is missing and smokeOnly is false
 */
export declare function loadGaia(options?: LoadGaiaOptions): Promise<GaiaQuestion[]>;
/**
 * Returns the cache directory path (does not create it).
 */
export declare function getGaiaCacheDir(override?: string): string;
//# sourceMappingURL=gaia-loader.d.ts.map