/** * GoalEngineer - the core Goal Engineering entry point. * * Python parity: praisonaiagents/goal/engineer.py. Goal Engineering is the * systematic practice of turning a vague objective into a structured, * measurable {@link Goal} (statement + weighted success criteria + * constraints), then verifying an output against it. * * @example * const engineer = new GoalEngineer({ autoDecompose: false }); * const goal = await engineer.engineer('Summarise the report in under 100 words'); * goal.addCriterion('Summary is under 100 words'); * const result = await engineer.verify(goal, 'A concise summary...'); * console.log(result.score, result.achieved); * * Zero performance impact: the LLM client and the Judge are created lazily. */ import { Judge } from '../eval/judge'; import { GoalConfig, GoalConfigOptions } from './config'; import { Goal, GoalVerificationResult } from './models'; /** * Minimal LLM surface the engineer needs. {@link BaseLLM} from `src/llm` * satisfies it structurally; tests can pass a stub. */ export interface GoalLLM { generate(prompt: string): Promise; } /** Constructor options for {@link GoalEngineer} (goal/engineer.py:58-66). */ export interface GoalEngineerOptions { /** LLM model for decomposition/verification (overrides config) (default null). */ model?: string | null; /** Max number of success criteria to generate (default null -> config). */ maxCriteria?: number | null; /** Score (0-10) at/above which a goal is achieved (default null -> config). */ threshold?: number | null; /** Auto-generate criteria via the LLM when engineering (default null -> config). */ autoDecompose?: boolean | null; /** A full {@link GoalConfig} (takes precedence over kwargs) (default null). */ config?: GoalConfig | GoalConfigOptions | null; /** Enable verbose logging (default false). */ verbose?: boolean; /** * TypeScript-only: injectable LLM used for both decomposition and * verification. Defaults to `BaseLLM({ model: config.model })` for * decomposition and the eval {@link Judge} (which resolves its own provider * from `config.model`) for verification. */ llm?: GoalLLM; } /** * Engineers structured, measurable goals and verifies outputs against them. * * Python parity: goal/engineer.py:45 `GoalEngineer`. */ export declare class GoalEngineer { config: GoalConfig; private readonly llm; private defaultLLM; constructor(options?: GoalEngineerOptions); /** * Build a structured {@link Goal} from a plain statement. * * If `criteria` are provided they are used directly. Otherwise, when * `autoDecompose` is enabled, the LLM proposes measurable criteria. * * Python parity: goal/engineer.py:79 `engineer(statement, criteria=None, constraints=None)`. */ engineer(statement: string, criteria?: string[] | null, constraints?: string[] | null): Promise; /** * Use the LLM to decompose a statement into success criteria. * * Python parity: goal/engineer.py:108 `_decompose`. */ protected decompose(statement: string): Promise; /** * Parse an LLM response into a list of criterion strings. * * Python parity: goal/engineer.py:129 `_parse_criteria`. A JSON array * anywhere in the reply wins; otherwise lines/bullets are split. */ static parseCriteria(response: unknown): string[]; /** * Verify an `output` against a `goal` using LLM-as-judge. * * Reuses the unified eval {@link Judge} (DRY). Falls back to a neutral * result if the judge is unavailable: criteria stay `pending` and * `achieved` is false, without mutating the goal into an `unmet` state. * * Python parity: goal/engineer.py:147 `verify(goal, output)`. */ verify(goal: Goal, output: unknown): Promise; /** The decomposition LLM: the injected one, else a lazily built `BaseLLM`. */ protected getLLM(): Promise; /** The verification judge: routed through the injected LLM when one was given. */ protected createJudge(criteria: string): Judge; }