/**
 * Analyst-kind factory — the typed way to define trace analysts.
 *
 * A "kind" is a specialized analyst whose actor prompt, tool subset,
 * and Ax recursion config target one failure-mode lens (failure-mode
 * classification, knowledge gap discovery, knowledge poisoning, recursive
 * self-improvement, ...). Kinds emit findings in the typed `RawAnalystFinding`
 * shape via a JSON-array Ax output; the factory validates each row with
 * Zod and lifts it into `AnalystFinding[]` with no shape guessing.
 *
 * Composition rules:
 *   - Each kind owns its actor description. No generic "answer this
 *     question" prompt — the prompt names the failure lens.
 *   - Each kind picks a narrow tool subset from `ANALYST_TOOL_GROUPS`.
 *     A kind that never needs full-trace dumps can drop `viewTrace` /
 *     `viewSpans` and stay cheap.
 *   - Each kind declares its recursion + parallelism budget. Discovery-
 *     heavy kinds (failure-mode) get higher `maxDepth`; lens kinds
 *     (poisoning) usually stay at 0 since they have a tighter brief.
 *
 * Optimizer hook: kinds may declare `goldens` — labeled examples used
 * by `AxMiPRO` / `AxBootstrapFewShot` / `AxGEPA` to fit the actor
 * description programmatically. Stored on the kind, not the registry,
 * because the right metric is kind-specific.
 */
import type { AxAIService, AxFunction } from '@ax-llm/ax';
import type { TraceAnalysisStore } from '../trace-analyst/store';
import { type RawAnalystFinding } from './finding-signature';
import type { Analyst, AnalystContext, AnalystCost } from './types';
/**
 * Per-kind specification. The factory turns this into a regular
 * `Analyst<TraceAnalysisStore>` ready for `AnalystRegistry.register()`.
 */
export interface TraceAnalystKindSpec {
    /** Stable id. Appears in finding_id, telemetry, and registry exclusions. */
    id: string;
    /** One-sentence description shown in `registry.list()`. */
    description: string;
    /** Coarse classification stamped on every emitted finding (`failure-mode`, `knowledge-gap`, ...). */
    area: string;
    /** Bump on any breaking change to the actor prompt or output schema. */
    version: string;
    /** Actor system prompt. Must instruct the LLM to emit `findings` per the schema. */
    actorDescription: string;
    /** Responder system prompt; falls back to a minimal "format the findings" instruction. */
    responderDescription?: string;
    /** Tool functions the actor may call. Pick narrow subsets via `ANALYST_TOOL_GROUPS`. */
    buildTools: (store: TraceAnalysisStore) => AxFunction[];
    /** Recursion budget. `maxDepth: 0` disables subagents. */
    recursion?: {
        maxDepth: number;
        maxParallelSubagents?: number;
    };
    /** Actor turn cap. Default 12. */
    maxTurns?: number;
    /** Runtime char cap. Default 6000. */
    maxRuntimeChars?: number;
    /** Cost classification surfaced in `registry.list()` and budget enforcement. */
    cost: AnalystCost;
    /** Per-finding-row hook — kinds may reject / rewrite before lifting. */
    postProcess?: (row: RawAnalystFinding, ctx: AnalystContext) => RawAnalystFinding | null;
    /** Optional optimizer hook — populated when a kind wants to fit its prompt against labeled examples. */
    goldens?: TraceAnalystGolden[];
}
/**
 * One labeled example consumed by Ax optimizers (MIPRO / GEPA / Bootstrap).
 * Each input is the same `{question}` an analyst would receive; `expected`
 * is the ground-truth finding set a fitted prompt should produce on this
 * input. Metric: kind-specific (default: F1 on `finding_id` overlap).
 */
export interface TraceAnalystGolden {
    question: string;
    expected: ReadonlyArray<Omit<RawAnalystFinding, 'confidence'>>;
}
export interface CreateTraceAnalystKindOpts {
    /** AxAIService bound at registration time. */
    ai: AxAIService;
    /** Optional model override; falls back to the AI service's default. */
    model?: string;
    /** Override the spec's `version` (e.g. when an optimizer has fitted a new prompt). */
    versionSuffix?: string;
    /**
     * Optional two-phase recovery: when the agentic harvest is empty but the
     * actor produced a substantive free-form `report`, extract findings from that
     * prose via a tolerant chat-completions pass (`structureFindings`) — no
     * strict-emission contract, so it works on weak models. Omit to leave the
     * actor's harvest as-is (the report is still surfaced fail-loud either way).
     */
    recovery?: {
        baseUrl: string;
        apiKey?: string;
        model?: string;
        fetchImpl?: typeof fetch;
    };
}
/**
 * Build an `Analyst<TraceAnalysisStore>` from a kind spec.
 *
 * Lifts the Ax pipeline once at registration time so the registry
 * gets a stateless analyst. The Ax agent is freshly constructed per
 * `analyze()` call (the agent carries chat-log + usage state we don't
 * want shared across analyst runs).
 */
export declare function createTraceAnalystKind(spec: TraceAnalystKindSpec, opts: CreateTraceAnalystKindOpts): Analyst<TraceAnalysisStore>;
/**
 * Render a compact prior-findings block the actor reads alongside its
 * brief. Each row is one line so the actor can scan dozens cheaply.
 * The kind's prompt instructs the actor to (a) check whether a new
 * cluster matches a prior `finding_id` (carry the id forward via
 * `id_basis` to keep diffs stable) and (b) raise severity / confidence
 * when a prior finding has reappeared without remediation.
 *
 * Returns the empty string when there are no prior findings — most
 * runs are "first-of-its-kind" and the prompt stays unchanged.
 *
 * Exported for tests + for consumers that build their own actor
 * prompts (e.g. specialized analysts living outside the default kinds).
 */
export declare function renderPriorFindings(prior: AnalystContext['priorFindings']): string;
//# sourceMappingURL=kind-factory.d.ts.map