/**
 * `gepaProposer` — a reflective `SurfaceProposer` for prompt-tier surfaces.
 * Each generation it reflects on the prior best candidate's per-scenario
 * scores + weakest dimensions, asks an LLM to propose targeted rewrites of
 * the current surface, and returns them as the next population.
 *
 * Maps onto the GEPA paper (Agrawal et al., arXiv:2507.19457):
 *   - *Reflection*: each generation reflects on the best parent's weakest
 *     dimensions + per-scenario top/bottom scores to propose targeted rewrites.
 *   - *Pareto frontier*: `runOptimization` maintains the non-dominated set of
 *     surfaces across generations (per-scenario objective vectors) and supplies
 *     it as `ctx.paretoParents`. A surface uniquely best on one hard scenario
 *     survives even when its mean composite is lower.
 *   - *Combine complementary lessons*: when the frontier has >1 member, the
 *     first population slot is a merge of those parents' strengths (one LLM
 *     call citing each parent's winning scenarios). Toggle via `combineParents`.
 * Dominance is computed by the package-canonical `paretoFrontier` (`pareto.ts`).
 *
 * Optional `constraints` move structured-doc guards into the proposer
 * (preserve H2 section headings, cap sentence-level edits) — useful when
 * the surface IS a structured procedure like a SKILL.md / runbook /
 * judge rubric. When `constraints` is omitted, behavior is unchanged.
 *
 * The proposer is surface-agnostic — any string surface in any consumer opts
 * in by selecting it. Reuses the generic reflection primitive
 * (`buildReflectionPrompt` / `parseReflectionResponse`) and the router client.
 *
 * Earns its keep where there is real per-instance signal (which the
 * dimensional + per-scenario evidence + the `LabeledScenarioStore` flywheel
 * now provide). For thin-signal surfaces it degrades to plain reflection.
 * On generation 0 (no history) it reflects on the current surface against
 * the mutation primitives alone.
 */
import { type LlmClientOptions } from '../../llm-client';
import type { SurfaceProposer } from '../types';
export interface GepaProposerConstraints {
    /** H2 section headings that MUST appear unchanged in every candidate.
     *  When set, the proposer auto-detects current H2s if this is empty AND
     *  rejects any candidate that drops or renames a preserved heading.
     *  Use when the surface is a structured doc (SKILL.md, runbook,
     *  sectioned system prompt, judge rubric). */
    preserveSections?: string[];
    /** Maximum sentence-level edits per candidate vs the parent surface.
     *  Rejection threshold = maxSentenceEdits × 2 (counts adds + removes).
     *  Inspired by SkillOpt's edit-budget as a "textual learning rate."
     *  Cap prevents an LLM rewrite from overwriting useful prior rules. */
    maxSentenceEdits?: number;
}
export interface GepaProposerOptions {
    /** Router transport (apiKey/baseUrl). */
    llm: LlmClientOptions;
    /** Model that performs the reflection. */
    model: string;
    /** What is being optimized — appears in the reflection prompt for orientation. */
    target: string;
    /** Surface-specific mutation levers offered to the model. */
    mutationPrimitives?: string[];
    /** Top/bottom scenarios surfaced as evidence each generation. Default 3. */
    evidenceK?: number;
    /** Reflection sampling temperature. Default 0.7. */
    temperature?: number;
    /** Reflection max tokens. Default 6000. */
    maxTokens?: number;
    /** Structured-doc constraints. Candidates violating any are rejected
     *  post-parse and dropped from the returned population. */
    constraints?: GepaProposerConstraints;
    /** GEPA combine-complementary-lessons: when the loop supplies a Pareto
     *  frontier of >1 non-dominated parents (`ctx.paretoParents`), spend one
     *  slot of the population on a merge of their strengths. Default `true` —
     *  this is the GEPA-faithful behavior; the merge only fires once the
     *  frontier has more than one member (generation ≥ 1). Set `false` for
     *  pure single-parent reflection. */
    combineParents?: boolean;
    /** Cap on how many frontier parents feed one combine prompt (highest
     *  composite first), to bound prompt size. Default 4. */
    combineMaxParents?: number;
}
export declare function gepaProposer(opts: GepaProposerOptions): SurfaceProposer;
/** Extract H2 headings (`## Foo`) from a markdown surface. Exported for
 *  consumers building custom mutators that share the same invariant. */
export declare function extractH2Sections(text: string): string[];
/** Sentence-level edit distance — count distinct add/remove ops between
 *  two surfaces via a normalised line-by-line set diff. Treats trivial
 *  whitespace as identical. Exported for tests + consumer-side validators. */
export declare function countSentenceEdits(baseline: string, candidate: string): number;
//# sourceMappingURL=gepa.d.ts.map