/**
 * FAPO (Fully Autonomous Prompt Optimization) is an orchestration policy, not
 * a new prompt mutation primitive. The paper's loop evaluates an inspectable
 * workflow, attributes failures to an edit level, proposes ONE scoped change,
 * reviews it, measures it, and escalates from prompt -> parameters -> structure
 * only when prompt-level search is exhausted and attribution supports the
 * higher-cost edit.
 *
 * This substrate proposer encodes that policy while keeping the edit generators
 * pluggable:
 *   - prompt: usually `gepaProposer`, `skillOptProposer`, or a runtime reflective proposer
 *   - parameter: `parameterSweepProposer` or a caller-supplied config proposer
 *   - structural: a caller-supplied code/worktree proposer from agent-runtime
 *
 * It deliberately does not import Claude Code, LangGraph, or Cisco's tenant
 * runtime. agent-eval owns measurement and proposer contracts; runtime-shaped
 * code generation stays downstream.
 *
 * Grounded sources:
 *   - Kassianik et al., "FAPO: Fully Autonomous Prompt Optimization of
 *     Multi-Step LLM Pipelines", arXiv:2606.19605v1.
 *   - cisco-foundation-ai/fully-automated-prompt-optimization at
 *     376b50c57d5e2423e5a5de46e0d315a761d272d8.
 */
import type { ProposeContext, ProposedCandidate, SurfaceProposer } from '../types';
export type FapoOptimizationLevel = 'prompt' | 'parameter' | 'structural';
export interface FapoScopeContract {
    /** Levels the tenant/playbook allows. Defaults to the levels with proposers. */
    allowedLevels?: readonly FapoOptimizationLevel[];
    /** Explicitly forbidden levels; wins over `allowedLevels`. */
    forbiddenLevels?: readonly FapoOptimizationLevel[];
}
export interface FapoFailureCluster {
    label: string;
    level: FapoOptimizationLevel;
    count: number;
    confidence?: 'high' | 'medium' | 'low';
    suggestedFix?: string;
    caseIds?: string[];
}
export interface FapoAttributionSignals {
    counts: Record<FapoOptimizationLevel, number>;
    clusters: FapoFailureCluster[];
}
export interface FapoReviewIssue {
    checkName: string;
    severity: 'block' | 'warn';
    description: string;
    location?: string;
}
export interface FapoReviewResult {
    verdict: 'pass' | 'warn' | 'fail';
    issues?: FapoReviewIssue[];
    suggestions?: string[];
}
export interface FapoReviewInput<TFindings = unknown> {
    level: FapoOptimizationLevel;
    candidate: ProposedCandidate;
    context: ProposeContext<TFindings>;
    reason: string;
}
export interface FapoProposerOptions<TFindings = unknown> {
    /** Level-specific candidate proposers. At least one is required. */
    proposers?: Partial<Record<FapoOptimizationLevel, SurfaceProposer<TFindings>>>;
    /** Convenience aliases for `proposers.<level>`. */
    promptProposer?: SurfaceProposer<TFindings>;
    parameterProposer?: SurfaceProposer<TFindings>;
    structuralProposer?: SurfaceProposer<TFindings>;
    /** Tenant/playbook-derived allowed and forbidden edit levels. */
    scope?: FapoScopeContract;
    /**
     * Independent reviewer hook. Return `fail` to block a candidate before eval,
     * mirroring FAPO's variant-reviewer phase.
     */
    reviewCandidate?: (input: FapoReviewInput<TFindings>) => Promise<FapoReviewResult>;
    /**
     * FAPO proposes one scoped change per cycle. Keep this at 1 unless you are
     * intentionally relaxing the paper loop for a batch experiment.
     */
    proposalsPerCycle?: number;
    /** Consecutive non-improving variants required before a level is exhausted. Default 3. */
    plateauWindow?: number;
    /** Distinct strategies required before declaring a plateau. Default 3. */
    minDistinctStrategies?: number;
    /** Candidate score delta needed to count as an improvement. Default 0. */
    minImprovement?: number;
    /** Paper-faithful default: try prompt edits before escalating. */
    promptFirst?: boolean;
    /** Paper-faithful default: try parameter/config edits before structural code edits. */
    parameterBeforeStructural?: boolean;
}
/** Build a FAPO policy proposer from level-specific candidate generators. */
export declare function fapoProposer<TFindings = unknown>(opts: FapoProposerOptions<TFindings>): SurfaceProposer<TFindings>;
export declare function extractFapoAttributionSignals(findings: readonly unknown[]): FapoAttributionSignals;
export type JsonPrimitive = string | number | boolean | null;
export type JsonValue = JsonPrimitive | JsonValue[] | {
    [key: string]: JsonValue;
};
export interface ParameterChange {
    path: string | readonly string[];
    value: JsonValue;
}
export interface ParameterCandidate {
    label: string;
    rationale: string;
    /** Deep-merged into the current JSON surface. */
    patch?: Record<string, JsonValue>;
    /** Dot-path writes, e.g. `{ path: 'retrieval.k', value: 10 }`. */
    changes?: readonly ParameterChange[];
}
export interface ParameterSweepProposerOptions {
    candidates: readonly ParameterCandidate[];
    /** Optional parser for non-JSON config surface strings. */
    parse?: (surface: string) => Record<string, JsonValue>;
    /** Optional serializer for non-JSON config surface strings. */
    stringify?: (config: Record<string, JsonValue>) => string;
}
/** Config/parameter-level proposer for FAPO's middle escalation level. */
export declare function parameterSweepProposer(opts: ParameterSweepProposerOptions): SurfaceProposer;
//# sourceMappingURL=fapo.d.ts.map