@graphorin/agent 0.5.0

package/dist/evaluator-optimizer/index.d.ts

@@ -0,0 +1,91 @@
+import { AgentEvent } from "@graphorin/core";
+
+//#region src/evaluator-optimizer/index.d.ts
+
+/**
+ * Rubric discriminator. Pick the variant that matches your
+ * Evaluator's contract.
+ *
+ * @stable
+ */
+type Rubric = {
+  readonly kind: 'free-form';
+  readonly instructions: string;
+} | {
+  readonly kind: 'zod';
+  readonly instructions: string;
+} | {
+  readonly kind: 'llm-judge';
+  readonly promptTemplate: string;
+};
+/**
+ * Per-iteration evaluation outcome returned by the Evaluator.
+ *
+ * @stable
+ */
+interface EvaluatorOutcome {
+  readonly score: number;
+  readonly pass: boolean;
+  readonly critique: string;
+}
+/**
+ * Generator callable shape. Receives the original user input plus
+ * the previous iteration's critique (or `undefined` on the first
+ * iteration) and returns the new candidate output.
+ *
+ * @stable
+ */
+type GeneratorCallable<TOutput> = (input: string, priorCritique: string | undefined, iteration: number) => Promise<TOutput>;
+/**
+ * Evaluator callable shape. Receives the original user input + the
+ * candidate output and returns the structured outcome.
+ *
+ * @stable
+ */
+type EvaluatorCallable<TOutput> = (input: string, candidate: TOutput, rubric: Rubric, iteration: number) => Promise<EvaluatorOutcome>;
+/**
+ * Options accepted by {@link evaluatorOptimizer}. `maxIterations`
+ * is REQUIRED — the helper asserts `>= 1` at construction time.
+ *
+ * @stable
+ */
+interface EvaluatorOptimizerOptions<TOutput> {
+  readonly generator: GeneratorCallable<TOutput>;
+  readonly evaluator: EvaluatorCallable<TOutput>;
+  readonly maxIterations: number;
+  readonly rubric: Rubric;
+  readonly mergeStrategy?: 'last-iteration' | 'best-score';
+  readonly signal?: AbortSignal;
+  /** Optional event emitter for `agent.evaluator.iteration / converged`. */
+  readonly emit?: (event: AgentEvent) => void;
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+}
+/**
+ * Aggregate outcome of an `evaluatorOptimizer({...})` run.
+ *
+ * @stable
+ */
+interface EvaluatorOptimizerOutcome<TOutput> {
+  readonly output: TOutput;
+  readonly iterations: ReadonlyArray<{
+    readonly iteration: number;
+    readonly candidate: TOutput;
+    readonly score: number;
+    readonly pass: boolean;
+    readonly critique: string;
+    readonly durationMs: number;
+  }>;
+  readonly terminationReason: 'pass' | 'maxIterations' | 'generator-exhausted' | 'cancelled';
+  readonly finalScore: number;
+}
+/**
+ * Run the Generator → Evaluator iteration loop.
+ *
+ * @stable
+ */
+declare function evaluatorOptimizer<TOutput>(input: string, options: EvaluatorOptimizerOptions<TOutput>): Promise<EvaluatorOptimizerOutcome<TOutput>>;
+//#endregion
+export { EvaluatorCallable, EvaluatorOptimizerOptions, EvaluatorOptimizerOutcome, EvaluatorOutcome, GeneratorCallable, Rubric, evaluatorOptimizer };
+//# sourceMappingURL=index.d.ts.map

package/dist/evaluator-optimizer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/evaluator-optimizer/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AA+EoC,KAxDxB,MAAA,GAwDwB;EAWnB,SAAA,IAAA,EAAA,WAAA;EACE,SAAA,YAAA,EAAA,MAAA;CAGK,GAAA;EAFD,SAAA,IAAA,EAAA,KAAA;EAAa,SAAA,YAAA,EAAA,MAAA;AAiBpC,CAAA,GAAsB;EAEe,SAAA,IAAA,EAAA,WAAA;EAA1B,SAAA,cAAA,EAAA,MAAA;CAC0B;;;;;;UA/EpB,gBAAA;;;;;;;;;;;;KAaL,sGAIP,QAAQ;;;;;;;KAQD,wDAEC,iBACH,8BAEL,QAAQ;;;;;;;UAQI;sBACK,kBAAkB;sBAClB,kBAAkB;;mBAErB;;oBAEC;;0BAEM;;;;;;;;;;UAWT;mBACE;uBACI;;wBAEC;;;;;;;;;;;;;;iBAeF,oDAEX,0BAA0B,WAClC,QAAQ,0BAA0B"}

package/dist/evaluator-optimizer/index.js

@@ -0,0 +1,85 @@
+import { EvaluatorOptimizerConfigError } from "../errors/index.js";
+
+//#region src/evaluator-optimizer/index.ts
+/**
+* Run the Generator → Evaluator iteration loop.
+*
+* @stable
+*/
+async function evaluatorOptimizer(input, options) {
+	if (!Number.isFinite(options.maxIterations) || options.maxIterations < 1) throw new EvaluatorOptimizerConfigError(`'maxIterations' must be >= 1 (got ${String(options.maxIterations)})`);
+	const mergeStrategy = options.mergeStrategy ?? "last-iteration";
+	const iterations = [];
+	let priorCritique;
+	let terminationReason = "maxIterations";
+	for (let i = 1; i <= options.maxIterations; i++) {
+		if (options.signal?.aborted) {
+			terminationReason = "cancelled";
+			break;
+		}
+		const iterStart = Date.now();
+		let candidate;
+		try {
+			candidate = await options.generator(input, priorCritique, i);
+		} catch {
+			terminationReason = "generator-exhausted";
+			break;
+		}
+		const outcome = await options.evaluator(input, candidate, options.rubric, i);
+		const iterDuration = Date.now() - iterStart;
+		iterations.push({
+			iteration: i,
+			candidate,
+			score: outcome.score,
+			pass: outcome.pass,
+			critique: outcome.critique,
+			durationMs: iterDuration
+		});
+		options.emit?.({
+			type: "agent.evaluator.iteration",
+			runId: options.runId,
+			sessionId: options.sessionId,
+			agentId: options.agentId,
+			iteration: i,
+			score: outcome.score,
+			pass: outcome.pass,
+			critique: outcome.critique,
+			durationMs: iterDuration
+		});
+		if (outcome.pass) {
+			terminationReason = "pass";
+			break;
+		}
+		priorCritique = outcome.critique;
+	}
+	let finalEntry;
+	if (iterations.length === 0) finalEntry = {
+		iteration: 0,
+		candidate: "",
+		score: 0,
+		pass: false,
+		critique: "",
+		durationMs: 0
+	};
+	else if (mergeStrategy === "best-score") finalEntry = iterations.reduce((best, current) => current.score > best.score ? current : best);
+	else finalEntry = iterations[iterations.length - 1];
+	options.emit?.({
+		type: "agent.evaluator.converged",
+		runId: options.runId,
+		sessionId: options.sessionId,
+		agentId: options.agentId,
+		totalIterations: iterations.length,
+		finalScore: finalEntry.score,
+		terminationReason
+	});
+	return {
+		output: finalEntry.candidate,
+		iterations,
+		terminationReason,
+		finalScore: finalEntry.score
+	};
+}
+
+//#endregion
+export { evaluatorOptimizer };
+//# sourceMappingURL=index.js.map

package/dist/evaluator-optimizer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["iterations: Array<{\n    iteration: number;\n    candidate: TOutput;\n    score: number;\n    pass: boolean;\n    critique: string;\n    durationMs: number;\n  }>","priorCritique: string | undefined","terminationReason: EvaluatorOptimizerOutcome<TOutput>['terminationReason']","candidate: TOutput","finalEntry: (typeof iterations)[number]"],"sources":["../../src/evaluator-optimizer/index.ts"],"sourcesContent":["/**\n * `evaluatorOptimizer({...})` — Generator → Evaluator iteration\n * loop with three rubric kinds and a REQUIRED iteration cap.\n *\n * Iteration boundary discipline: each iteration is a fresh\n * agent.run-equivalent boundary. Intra-loop reasoning per RB-42 /\n * suggested DEC-158 applies WITHIN one iteration, not ACROSS\n * iterations. The Generator's iteration-N input is the original\n * user input + the Evaluator's iteration-(N-1) critique (NOT the\n * Generator's iteration-(N-1) internal message history).\n *\n * @packageDocumentation\n */\n\nimport type { AgentEvent } from '@graphorin/core';\nimport { EvaluatorOptimizerConfigError } from '../errors/index.js';\n\n/**\n * Rubric discriminator. Pick the variant that matches your\n * Evaluator's contract.\n *\n * @stable\n */\nexport type Rubric =\n  | { readonly kind: 'free-form'; readonly instructions: string }\n  | { readonly kind: 'zod'; readonly instructions: string }\n  | { readonly kind: 'llm-judge'; readonly promptTemplate: string };\n\n/**\n * Per-iteration evaluation outcome returned by the Evaluator.\n *\n * @stable\n */\nexport interface EvaluatorOutcome {\n  readonly score: number;\n  readonly pass: boolean;\n  readonly critique: string;\n}\n\n/**\n * Generator callable shape. Receives the original user input plus\n * the previous iteration's critique (or `undefined` on the first\n * iteration) and returns the new candidate output.\n *\n * @stable\n */\nexport type GeneratorCallable<TOutput> = (\n  input: string,\n  priorCritique: string | undefined,\n  iteration: number,\n) => Promise<TOutput>;\n\n/**\n * Evaluator callable shape. Receives the original user input + the\n * candidate output and returns the structured outcome.\n *\n * @stable\n */\nexport type EvaluatorCallable<TOutput> = (\n  input: string,\n  candidate: TOutput,\n  rubric: Rubric,\n  iteration: number,\n) => Promise<EvaluatorOutcome>;\n\n/**\n * Options accepted by {@link evaluatorOptimizer}. `maxIterations`\n * is REQUIRED — the helper asserts `>= 1` at construction time.\n *\n * @stable\n */\nexport interface EvaluatorOptimizerOptions<TOutput> {\n  readonly generator: GeneratorCallable<TOutput>;\n  readonly evaluator: EvaluatorCallable<TOutput>;\n  readonly maxIterations: number;\n  readonly rubric: Rubric;\n  readonly mergeStrategy?: 'last-iteration' | 'best-score';\n  readonly signal?: AbortSignal;\n  /** Optional event emitter for `agent.evaluator.iteration / converged`. */\n  readonly emit?: (event: AgentEvent) => void;\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly agentId: string;\n}\n\n/**\n * Aggregate outcome of an `evaluatorOptimizer({...})` run.\n *\n * @stable\n */\nexport interface EvaluatorOptimizerOutcome<TOutput> {\n  readonly output: TOutput;\n  readonly iterations: ReadonlyArray<{\n    readonly iteration: number;\n    readonly candidate: TOutput;\n    readonly score: number;\n    readonly pass: boolean;\n    readonly critique: string;\n    readonly durationMs: number;\n  }>;\n  readonly terminationReason: 'pass' | 'maxIterations' | 'generator-exhausted' | 'cancelled';\n  readonly finalScore: number;\n}\n\n/**\n * Run the Generator → Evaluator iteration loop.\n *\n * @stable\n */\nexport async function evaluatorOptimizer<TOutput>(\n  input: string,\n  options: EvaluatorOptimizerOptions<TOutput>,\n): Promise<EvaluatorOptimizerOutcome<TOutput>> {\n  if (!Number.isFinite(options.maxIterations) || options.maxIterations < 1) {\n    throw new EvaluatorOptimizerConfigError(\n      `'maxIterations' must be >= 1 (got ${String(options.maxIterations)})`,\n    );\n  }\n  const mergeStrategy = options.mergeStrategy ?? 'last-iteration';\n  const iterations: Array<{\n    iteration: number;\n    candidate: TOutput;\n    score: number;\n    pass: boolean;\n    critique: string;\n    durationMs: number;\n  }> = [];\n\n  let priorCritique: string | undefined;\n  let terminationReason: EvaluatorOptimizerOutcome<TOutput>['terminationReason'] = 'maxIterations';\n\n  for (let i = 1; i <= options.maxIterations; i++) {\n    if (options.signal?.aborted) {\n      terminationReason = 'cancelled';\n      break;\n    }\n    const iterStart = Date.now();\n    let candidate: TOutput;\n    try {\n      candidate = await options.generator(input, priorCritique, i);\n    } catch {\n      terminationReason = 'generator-exhausted';\n      break;\n    }\n    const outcome = await options.evaluator(input, candidate, options.rubric, i);\n    const iterDuration = Date.now() - iterStart;\n\n    iterations.push({\n      iteration: i,\n      candidate,\n      score: outcome.score,\n      pass: outcome.pass,\n      critique: outcome.critique,\n      durationMs: iterDuration,\n    });\n\n    options.emit?.({\n      type: 'agent.evaluator.iteration',\n      runId: options.runId,\n      sessionId: options.sessionId,\n      agentId: options.agentId,\n      iteration: i,\n      score: outcome.score,\n      pass: outcome.pass,\n      critique: outcome.critique,\n      durationMs: iterDuration,\n    });\n\n    if (outcome.pass) {\n      terminationReason = 'pass';\n      break;\n    }\n    priorCritique = outcome.critique;\n  }\n\n  let finalEntry: (typeof iterations)[number];\n  if (iterations.length === 0) {\n    // Should only happen on `cancelled` before the first iteration —\n    // synthesize a no-op final entry.\n    finalEntry = {\n      iteration: 0,\n      candidate: '' as unknown as TOutput,\n      score: 0,\n      pass: false,\n      critique: '',\n      durationMs: 0,\n    };\n  } else if (mergeStrategy === 'best-score') {\n    finalEntry = iterations.reduce((best, current) =>\n      current.score > best.score ? current : best,\n    );\n  } else {\n    finalEntry = iterations[iterations.length - 1] as (typeof iterations)[number];\n  }\n\n  options.emit?.({\n    type: 'agent.evaluator.converged',\n    runId: options.runId,\n    sessionId: options.sessionId,\n    agentId: options.agentId,\n    totalIterations: iterations.length,\n    finalScore: finalEntry.score,\n    terminationReason,\n  });\n\n  return {\n    output: finalEntry.candidate,\n    iterations,\n    terminationReason,\n    finalScore: finalEntry.score,\n  };\n}\n"],"mappings":";;;;;;;;AA6GA,eAAsB,mBACpB,OACA,SAC6C;AAC7C,KAAI,CAAC,OAAO,SAAS,QAAQ,cAAc,IAAI,QAAQ,gBAAgB,EACrE,OAAM,IAAI,8BACR,qCAAqC,OAAO,QAAQ,cAAc,CAAC,GACpE;CAEH,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,MAAMA,aAOD,EAAE;CAEP,IAAIC;CACJ,IAAIC,oBAA6E;AAEjF,MAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,eAAe,KAAK;AAC/C,MAAI,QAAQ,QAAQ,SAAS;AAC3B,uBAAoB;AACpB;;EAEF,MAAM,YAAY,KAAK,KAAK;EAC5B,IAAIC;AACJ,MAAI;AACF,eAAY,MAAM,QAAQ,UAAU,OAAO,eAAe,EAAE;UACtD;AACN,uBAAoB;AACpB;;EAEF,MAAM,UAAU,MAAM,QAAQ,UAAU,OAAO,WAAW,QAAQ,QAAQ,EAAE;EAC5E,MAAM,eAAe,KAAK,KAAK,GAAG;AAElC,aAAW,KAAK;GACd,WAAW;GACX;GACA,OAAO,QAAQ;GACf,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,YAAY;GACb,CAAC;AAEF,UAAQ,OAAO;GACb,MAAM;GACN,OAAO,QAAQ;GACf,WAAW,QAAQ;GACnB,SAAS,QAAQ;GACjB,WAAW;GACX,OAAO,QAAQ;GACf,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,YAAY;GACb,CAAC;AAEF,MAAI,QAAQ,MAAM;AAChB,uBAAoB;AACpB;;AAEF,kBAAgB,QAAQ;;CAG1B,IAAIC;AACJ,KAAI,WAAW,WAAW,EAGxB,cAAa;EACX,WAAW;EACX,WAAW;EACX,OAAO;EACP,MAAM;EACN,UAAU;EACV,YAAY;EACb;UACQ,kBAAkB,aAC3B,cAAa,WAAW,QAAQ,MAAM,YACpC,QAAQ,QAAQ,KAAK,QAAQ,UAAU,KACxC;KAED,cAAa,WAAW,WAAW,SAAS;AAG9C,SAAQ,OAAO;EACb,MAAM;EACN,OAAO,QAAQ;EACf,WAAW,QAAQ;EACnB,SAAS,QAAQ;EACjB,iBAAiB,WAAW;EAC5B,YAAY,WAAW;EACvB;EACD,CAAC;AAEF,QAAO;EACL,QAAQ,WAAW;EACnB;EACA;EACA,YAAY,WAAW;EACxB"}

package/dist/factory.d.ts

@@ -0,0 +1,13 @@
+import { Agent, AgentConfig } from "./types.js";
+
+//#region src/factory.d.ts
+
+/**
+ * Build a fresh {@link Agent} from the supplied configuration.
+ *
+ * @stable
+ */
+declare function createAgent<TDeps = unknown, TOutput = string>(config: AgentConfig<TDeps, TOutput>): Agent<TDeps, TOutput>;
+//#endregion
+export { createAgent };
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","names":[],"sources":["../src/factory.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAovBgB,uDACN,YAAY,OAAO,WAC1B,MAAM,OAAO"}