/**
 * Darwin — Reflective Text Feedback (Phase 2 A2, S1185 follow-up).
 *
 * GEPA's signature insight: instead of guiding mutation by a single
 * scalar reward, give the optimizer rich TEXT feedback ("what went
 * wrong, what to fix, what NOT to change") and let it synthesise the
 * mutation from that feedback.
 *
 * This module is a pure TS port of the GEPA-style reflector — no
 * Python sidecar, no hard dep on `@gepa-ai/gepa`. The reflector takes
 * a current prompt + a set of (variant, score, trace) feedbacks and
 * asks an injected LLM to write a SMALLEST-POSSIBLE-EDIT mutation of
 * the current prompt that addresses the failure modes.
 *
 * Reference snippet from GEPA docs:
 *
 *   "Make the smallest possible targeted edit to fix the identified
 *    failure mode. Preserve all existing correct behavior. Do not
 *    rewrite from scratch."
 *
 * The module is composable with the existing `PromptOptimizer` —
 * `GepaOptimizer` (next file) coordinates Reflector + paretoSelect into
 * a generation loop. The reflector itself is single-shot.
 *
 * **Inspired by, not lifted from** the official `gepa-ai/gepa` Python
 * library. This is a pure TS port of GEPA's core ideas (Pareto-front +
 * reflective mutation) — see `optimizer-gepa.ts` for the deliberate
 * deviations from Algorithm 1/2 of the GEPA paper (arxiv 2507.19457).
 * For a feature-complete GEPA experience use the upstream Python tool.
 *
 * **Stronger reflection LM (V0.5.1, S1235):** GEPA's official guidance
 * is to use a STRONGER LM for reflection than for task execution
 * (their `reflection_lm` parameter). Direct support shipped in V0.5.1
 * via `GepaOptimizerOptions.reflectionRunPrompt` on `GepaOptimizer`'s
 * constructor — the override is wired into the internal Reflector so
 * `reflect()` calls route through the stronger LM. The `Reflector`
 * class itself remains single-LM by design (the override lives one
 * layer up in `GepaOptimizer`).
 */
import type { ExecutionTrace } from "../types.js";
import type { RunPromptFn } from "./run-prompt-fn.js";
export type { RunPromptFn };
/** One variant's evaluation feedback, fed into the reflector. */
export interface ReflectiveFeedback {
    /** Identifier of the variant this feedback refers to (e.g. "v3"). */
    variantId: string;
    /** Scalar score for at-a-glance ranking. */
    score: number;
    /**
     * Rich text feedback describing what went well, what failed, and
     * (ideally) WHY. The richer this is, the better the mutation. GEPA
     * docs recommend including: expected vs. actual, specific issue
     * analysis, and any provider-side error class.
     */
    textFeedback: string;
    /** Optional execution trace (A1 trajectory) for tool-level context. */
    trace?: ExecutionTrace;
    /** Optional: the variant's prompt text itself (helps the reflector compare). */
    variantPrompt?: string;
}
/**
 * Options accepted by {@link Reflector#reflect}.
 */
export interface ReflectOptions {
    /**
     * Override the reflection prompt template. Default is GEPA's
     * "smallest possible targeted edit" template. Use a custom template
     * when you want different mutation pressure (e.g. exploratory vs.
     * conservative).
     */
    reflectionPromptTemplate?: string;
    /**
     * Max characters of `textFeedback` included per variant. Default
     * 2000 — keeps the meta-prompt under typical context windows even
     * with N=5 variants.
     */
    feedbackCap?: number;
    /**
     * Hard upper bound on the returned mutated-prompt length. Default
     * `Math.max(currentPrompt.length * 1.3, 3500)` — same growth ceiling
     * as `PromptOptimizer.generateVariant` for symmetry.
     */
    maxMutationLength?: number;
}
/**
 * Single-shot reflector. Wraps one LLM call that takes the current
 * prompt + per-variant feedback and returns a mutated prompt.
 */
export declare class Reflector {
    private readonly runPrompt;
    constructor(runPrompt: RunPromptFn);
    /**
     * Build a reflection meta-prompt and ask the injected LLM for a
     * mutated prompt. Returns the mutated prompt text (cleaned + capped).
     *
     * Throws `TypeError` if `currentPrompt` is empty or `feedbacks` is
     * empty — meaningless inputs are a programmer bug, not a runtime
     * edge.
     */
    reflect(currentPrompt: string, feedbacks: ReadonlyArray<ReflectiveFeedback>, opts?: ReflectOptions): Promise<string>;
    /** Single-feedback formatter. */
    private formatFeedback;
    /** Strip markdown fences and leading/trailing whitespace. */
    private cleanOutput;
    /** Truncate at the last sentence/newline boundary within `maxLength`. */
    private truncateAtSentenceBoundary;
}
//# sourceMappingURL=reflector.d.ts.map