@textopt/langchain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charlie Duong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @textopt/langchain
+
+LangChain adapter for [textopt](https://github.com/ctdio/textopt#readme).
+
+The adapter rebuilds a LangChain runnable, chain, agent, or LangGraph graph for each candidate. Candidate components can supply prompts, tool descriptions, routing instructions, or other text read by the runnable.
+
+`@langchain/core` is a peer dependency (`>=0.3.0 <2`).
+
+## Usage
+
+```ts
+import { GepaOptimizer } from "textopt/gepa";
+import { createLangChainAdapter } from "@textopt/langchain";
+import { ChatPromptTemplate } from "@langchain/core/prompts";
+import { StringOutputParser } from "@langchain/core/output_parsers";
+
+const adapter = createLangChainAdapter<Ticket, string>({
+  buildRunnable: (candidate) =>
+    ChatPromptTemplate.fromMessages([
+      ["system", candidate.system ?? ""],
+      ["human", "{text}"],
+    ])
+      .pipe(model)
+      .pipe(new StringOutputParser()),
+
+  toInput: (datum) => ({ text: datum.text }),
+
+  score: ({ datum, output }) =>
+    output === datum.label
+      ? { score: 1, feedback: `Correct: ${datum.label}.` }
+      : {
+          score: 0,
+          feedback: `Predicted "${output}", expected "${datum.label}".`,
+        },
+});
+
+const result = await new GepaOptimizer().optimize({
+  seedCandidate: { system: "Classify the support ticket." },
+  trainingSet,
+  adapter,
+  reflect,
+  maxMetricCalls: 150,
+});
+```
+
+`score` returns a `ScoreResult`. GEPA uses its optional `feedback` field during reflection, so include a description of the failure when possible.
+
+## Options
+
+| Option              | Default                   | Effect                                                                                     |
+| ------------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
+| `buildRunnable`     | required                  | Rebuilds the chain with the candidate's text injected into its prompts.                    |
+| `score`             | required                  | Scores one rollout, given the `datum`, `output`, and `trace`.                              |
+| `toInput`           | the row itself            | Maps a dataset row to the chain's input.                                                   |
+| `concurrency`       | `8`                       | In-flight rollouts.                                                                        |
+| `includeChainSteps` | `false`                   | Includes per-runnable chain spans in traces.                                               |
+| `componentRunNames` | none                      | Maps component names to run names and filters each component's evidence to matching steps. |
+| `isTransient`       | `false` for all errors    | Identifies infrastructure errors whose fallback scores must not be cached.                 |
+| `buildRecord`       | default reflective record | Builds a custom reflective record.                                                         |
+
+## Tracing
+
+Each rollout includes `textopt_iteration`, `textopt_phase`, `textopt_split`, and `textopt_candidate_id` in its LangChain metadata. With a tracer configured, these fields can filter and group runs in LangSmith.
+
+Traces include LLM, tool, and retriever spans with run IDs, parent run IDs, inputs, outputs, and errors. Set `includeChainSteps` to include chain spans.
+
+Tracing callbacks are attached only when the optimizer requests traces, typically for reflection minibatches. During validation sweeps, `score` receives a trace with no steps and should score the output directly.
+
+Types: `LangChainAdapterOptions`, `LangChainTrace`, `LangChainTraceStep`, `LangChainStepType`, `LangChainEvidence`, `LangChainScore`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,311 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let textopt = require("textopt");
+//#region src/adapter.ts
+const DEFAULT_CONCURRENCY = 8;
+/**
+* Runs a LangChain runnable (chain, agent, or LangGraph graph) as the system
+* under optimization. The candidate is injected by rebuilding the runnable, so
+* anything that reads candidate text — prompts, tool descriptions, routing
+* instructions — is optimizable.
+*/
+function createLangChainAdapter(options) {
+	const { buildRunnable, score, toInput = (datum) => datum, concurrency = DEFAULT_CONCURRENCY, includeChainSteps = false, pricing, componentRunNames, isTransient = () => false, buildRecord } = options;
+	return {
+		evaluate: async ({ batch, candidate, captureTraces, run, signal }) => {
+			const runnable = buildRunnable(candidate);
+			const metadata = {
+				textopt_iteration: run.iteration,
+				textopt_phase: run.phase,
+				textopt_split: run.split,
+				textopt_candidate_id: run.candidateId
+			};
+			const results = await (0, textopt.mapWithConcurrency)({
+				items: batch,
+				limit: concurrency,
+				task: async (datum) => {
+					const collector = createTraceCollector({ includeChainSteps });
+					const startedAt = Date.now();
+					let output = null;
+					let failure;
+					let transient = false;
+					try {
+						output = await runnable.invoke(toInput(datum), {
+							callbacks: [collector.handler],
+							metadata,
+							signal
+						});
+					} catch (err) {
+						signal?.throwIfAborted();
+						failure = err instanceof Error ? err.message : String(err);
+						transient = isTransient(err);
+					}
+					const steps = collector.finish();
+					const usage = (0, textopt.priceUsage)({
+						usage: collector.usage(),
+						...pricing === void 0 ? {} : { pricing }
+					});
+					const trace = {
+						steps: captureTraces ? steps : [],
+						durationMs: Date.now() - startedAt,
+						...failure === void 0 ? {} : { error: failure }
+					};
+					if (failure !== void 0) return {
+						output: null,
+						trace,
+						usage,
+						scored: {
+							score: 0,
+							feedback: `Run failed: ${failure}`,
+							transient
+						}
+					};
+					try {
+						return {
+							output,
+							trace,
+							usage,
+							scored: await score({
+								datum,
+								output,
+								trace
+							})
+						};
+					} catch (err) {
+						signal?.throwIfAborted();
+						const message = err instanceof Error ? err.message : String(err);
+						return {
+							output,
+							trace,
+							usage,
+							scored: {
+								score: 0,
+								feedback: `Scoring failed: ${message}`,
+								transient: isTransient(err)
+							}
+						};
+					}
+				},
+				signal
+			});
+			const evaluation = {
+				outputs: results.map((result) => result.output),
+				scores: results.map((result) => result.scored.score),
+				feedback: results.map((result) => result.scored.feedback ?? "")
+			};
+			if (results.some((result) => result.scored.usage !== void 0 || Object.keys(result.usage).length > 0)) evaluation.usage = results.map((result) => result.scored.usage ?? result.usage);
+			if (captureTraces) evaluation.trajectories = results.map((result) => result.trace);
+			if (results.some((result) => result.scored.objectiveScores !== void 0)) evaluation.objectiveScores = results.map((result) => result.scored.objectiveScores ?? {});
+			if (results.some((result) => result.scored.transient === true)) evaluation.transient = results.map((result) => result.scored.transient === true);
+			return evaluation;
+		},
+		makeReflectiveDataset: ({ batch, evaluation, componentsToUpdate }) => {
+			const dataset = {};
+			for (const component of componentsToUpdate) dataset[component] = batch.map((datum, index) => {
+				const trace = evaluation.trajectories?.[index] ?? {
+					steps: [],
+					durationMs: 0
+				};
+				const output = evaluation.outputs[index] ?? null;
+				const scoreValue = evaluation.scores[index] ?? 0;
+				const feedback = evaluation.feedback?.[index] ?? "";
+				if (buildRecord !== void 0) return buildRecord({
+					datum,
+					output,
+					trace,
+					score: scoreValue,
+					feedback,
+					component
+				});
+				const componentSteps = selectComponentSteps({
+					trace,
+					runName: componentRunNames?.[component]
+				});
+				return {
+					inputs: toInput(datum),
+					generatedOutputs: output,
+					feedback,
+					score: scoreValue,
+					...componentSteps.length > 0 ? { evidence: { trace: componentSteps } } : {}
+				};
+			});
+			return dataset;
+		}
+	};
+}
+function selectComponentSteps(args) {
+	const { trace, runName } = args;
+	if (runName === void 0) return trace.steps;
+	return trace.steps.filter((step) => step.name === runName);
+}
+/**
+* LangChain accepts plain handler objects, so trace capture needs no subclass
+* and no LangSmith account — the same events LangSmith records land here.
+*/
+function createTraceCollector(args) {
+	const { includeChainSteps } = args;
+	const steps = [];
+	const openSteps = /* @__PURE__ */ new Map();
+	const tokens = {
+		inputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0
+	};
+	let counted = false;
+	function open(step) {
+		openSteps.set(step.runId, step);
+		steps.push(step);
+	}
+	/**
+	* Any span still open when the run ends never got its end callback — the
+	* chain was torn down first. Left alone it is indistinguishable in the trace
+	* from a step that legitimately produced nothing, which quietly misleads the
+	* reflection model.
+	*/
+	function finish() {
+		for (const step of openSteps.values()) step.error = "Step did not complete before the run ended";
+		openSteps.clear();
+		return steps;
+	}
+	function close(args) {
+		const step = openSteps.get(args.runId);
+		if (step === void 0) return;
+		step.outputs = args.outputs;
+		if (args.error !== void 0) step.error = args.error;
+		openSteps.delete(args.runId);
+	}
+	const handler = {
+		handleLLMStart: (llm, prompts, runId, parentRunId, _extra, _tags, _meta, runName) => {
+			open({
+				type: "llm",
+				name: runName ?? nameOf(llm),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs: prompts
+			});
+		},
+		handleChatModelStart: (llm, messages, runId, parentRunId, _extra, _tags, _meta, runName) => {
+			open({
+				type: "llm",
+				name: runName ?? nameOf(llm),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs: messages.flat().map((message) => ({
+					role: message.getType(),
+					content: message.content
+				}))
+			});
+		},
+		handleLLMEnd: (output, runId) => {
+			countTokens(output);
+			close({
+				runId,
+				outputs: output.generations.flat().map((generation) => generation.text)
+			});
+		},
+		handleLLMError: (err, runId) => {
+			close({
+				runId,
+				outputs: null,
+				error: messageOf(err)
+			});
+		},
+		handleToolStart: (tool, input, runId, parentRunId, _tags, _meta, runName) => {
+			open({
+				type: "tool",
+				name: runName ?? nameOf(tool),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs: input
+			});
+		},
+		handleToolEnd: (output, runId) => {
+			close({
+				runId,
+				outputs: output
+			});
+		},
+		handleToolError: (err, runId) => {
+			close({
+				runId,
+				outputs: null,
+				error: messageOf(err)
+			});
+		},
+		handleRetrieverStart: (retriever, query, runId, parentRunId, _tags, _meta, runName) => {
+			open({
+				type: "retriever",
+				name: runName ?? nameOf(retriever),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs: query
+			});
+		},
+		handleRetrieverEnd: (documents, runId) => {
+			close({
+				runId,
+				outputs: documents.map((document) => document.pageContent)
+			});
+		}
+	};
+	if (includeChainSteps) {
+		handler.handleChainStart = (chain, inputs, runId, parentRunId, _tags, _meta, _runType, runName) => {
+			open({
+				type: "chain",
+				name: runName ?? nameOf(chain),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs
+			});
+		};
+		handler.handleChainEnd = (outputs, runId) => {
+			close({
+				runId,
+				outputs
+			});
+		};
+	}
+	/**
+	* LangChain reports tokens in two shapes depending on the integration: the
+	* legacy `llmOutput.tokenUsage` and the message-level `usage_metadata` newer
+	* chat models attach. Reading both is what makes this work across providers;
+	* an integration that fills both describes one call twice, so a message-level
+	* shape that carries a count wins and the legacy total is only a fallback.
+	*/
+	function countTokens(output) {
+		let fromMetadata = false;
+		for (const generation of output.generations?.flat() ?? []) {
+			const metadata = generation.message?.usage_metadata;
+			if (metadata === void 0) continue;
+			const inputTokens = metadata.input_tokens ?? 0;
+			const outputTokens = metadata.output_tokens ?? 0;
+			const totalTokens = metadata.total_tokens ?? inputTokens + outputTokens;
+			if (inputTokens === 0 && outputTokens === 0 && totalTokens === 0) continue;
+			fromMetadata = true;
+			counted = true;
+			tokens.inputTokens += inputTokens;
+			tokens.outputTokens += outputTokens;
+			tokens.totalTokens += totalTokens;
+		}
+		if (fromMetadata) return;
+		const legacy = output.llmOutput?.tokenUsage;
+		if (legacy !== void 0) {
+			counted = true;
+			tokens.inputTokens += legacy.promptTokens ?? 0;
+			tokens.outputTokens += legacy.completionTokens ?? 0;
+			tokens.totalTokens += legacy.totalTokens ?? (legacy.promptTokens ?? 0) + (legacy.completionTokens ?? 0);
+		}
+	}
+	return {
+		handler,
+		finish,
+		usage: () => counted ? { ...tokens } : {}
+	};
+}
+function nameOf(serialized) {
+	return serialized?.id?.at(-1) ?? "unknown";
+}
+function messageOf(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+exports.createLangChainAdapter = createLangChainAdapter;

package/dist/index.d.cts

@@ -0,0 +1,74 @@
+import { Candidate, ScoreResult, TokenPricing } from "textopt";
+import { GepaAdapter, ReflectiveRecord } from "textopt/gepa";
+import { Runnable } from "@langchain/core/runnables";
+//#region src/adapter.d.ts
+type LangChainStepType = "llm" | "chain" | "tool" | "retriever";
+interface LangChainTraceStep {
+  type: LangChainStepType;
+  name: string;
+  runId: string;
+  parentRunId?: string;
+  inputs?: unknown;
+  outputs?: unknown;
+  error?: string;
+}
+interface LangChainTrace {
+  steps: LangChainTraceStep[];
+  durationMs: number;
+  error?: string;
+}
+type LangChainScore = ScoreResult;
+/** What the reflection model sees beyond the score and feedback of a run. */
+interface LangChainEvidence {
+  trace: LangChainTraceStep[];
+}
+interface LangChainAdapterOptions<Datum, Output> {
+  /** Rebuild the chain with the candidate's text injected into its prompts. */
+  buildRunnable: (candidate: Candidate) => Runnable<never, Output>;
+  /**
+   * Per-instance score plus the textual feedback the reflection model reads.
+   * Feedback is what separates GEPA from blind search — say what went wrong,
+   * not just how wrong it was.
+   */
+  score: (args: {
+    datum: Datum;
+    output: Output | null;
+    trace: LangChainTrace;
+  }) => LangChainScore | Promise<LangChainScore>;
+  /** Map a dataset row to the chain's input. Defaults to the row itself. */
+  toInput?: (datum: Datum) => unknown;
+  concurrency?: number;
+  /** Include LangChain's per-runnable chain spans in the trace. Noisy. */
+  includeChainSteps?: boolean;
+  /**
+   * Converts the tokens the chain's model spans reported into dollars. Without
+   * it usage is still reported in tokens; with it a run can be given a spend
+   * ceiling.
+   */
+  pricing?: TokenPricing;
+  /** Component name -> LangChain run name, used to highlight per-component IO. */
+  componentRunNames?: Record<string, string>;
+  /**
+   * Classify a thrown error as infrastructure (rate limit, 5xx, network) so
+   * its zero is not cached against the candidate. Defaults to treating every
+   * failure as the candidate's, which is the safe assumption.
+   */
+  isTransient?: (err: unknown) => boolean;
+  buildRecord?: (args: {
+    datum: Datum;
+    output: Output | null;
+    trace: LangChainTrace;
+    score: number;
+    feedback: string;
+    component: string;
+  }) => ReflectiveRecord;
+}
+/**
+ * Runs a LangChain runnable (chain, agent, or LangGraph graph) as the system
+ * under optimization. The candidate is injected by rebuilding the runnable, so
+ * anything that reads candidate text — prompts, tool descriptions, routing
+ * instructions — is optimizable.
+ */
+declare function createLangChainAdapter<Datum, Output>(options: LangChainAdapterOptions<Datum, Output>): GepaAdapter<Datum, LangChainTrace, Output | null>;
+//#endregion
+export { LangChainAdapterOptions, LangChainEvidence, LangChainScore, LangChainStepType, LangChainTrace, LangChainTraceStep, createLangChainAdapter };

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+import { Candidate, ScoreResult, TokenPricing } from "textopt";
+import { GepaAdapter, ReflectiveRecord } from "textopt/gepa";
+import { Runnable } from "@langchain/core/runnables";
+//#region src/adapter.d.ts
+type LangChainStepType = "llm" | "chain" | "tool" | "retriever";
+interface LangChainTraceStep {
+  type: LangChainStepType;
+  name: string;
+  runId: string;
+  parentRunId?: string;
+  inputs?: unknown;
+  outputs?: unknown;
+  error?: string;
+}
+interface LangChainTrace {
+  steps: LangChainTraceStep[];
+  durationMs: number;
+  error?: string;
+}
+type LangChainScore = ScoreResult;
+/** What the reflection model sees beyond the score and feedback of a run. */
+interface LangChainEvidence {
+  trace: LangChainTraceStep[];
+}
+interface LangChainAdapterOptions<Datum, Output> {
+  /** Rebuild the chain with the candidate's text injected into its prompts. */
+  buildRunnable: (candidate: Candidate) => Runnable<never, Output>;
+  /**
+   * Per-instance score plus the textual feedback the reflection model reads.
+   * Feedback is what separates GEPA from blind search — say what went wrong,
+   * not just how wrong it was.
+   */
+  score: (args: {
+    datum: Datum;
+    output: Output | null;
+    trace: LangChainTrace;
+  }) => LangChainScore | Promise<LangChainScore>;
+  /** Map a dataset row to the chain's input. Defaults to the row itself. */
+  toInput?: (datum: Datum) => unknown;
+  concurrency?: number;
+  /** Include LangChain's per-runnable chain spans in the trace. Noisy. */
+  includeChainSteps?: boolean;
+  /**
+   * Converts the tokens the chain's model spans reported into dollars. Without
+   * it usage is still reported in tokens; with it a run can be given a spend
+   * ceiling.
+   */
+  pricing?: TokenPricing;
+  /** Component name -> LangChain run name, used to highlight per-component IO. */
+  componentRunNames?: Record<string, string>;
+  /**
+   * Classify a thrown error as infrastructure (rate limit, 5xx, network) so
+   * its zero is not cached against the candidate. Defaults to treating every
+   * failure as the candidate's, which is the safe assumption.
+   */
+  isTransient?: (err: unknown) => boolean;
+  buildRecord?: (args: {
+    datum: Datum;
+    output: Output | null;
+    trace: LangChainTrace;
+    score: number;
+    feedback: string;
+    component: string;
+  }) => ReflectiveRecord;
+}
+/**
+ * Runs a LangChain runnable (chain, agent, or LangGraph graph) as the system
+ * under optimization. The candidate is injected by rebuilding the runnable, so
+ * anything that reads candidate text — prompts, tool descriptions, routing
+ * instructions — is optimizable.
+ */
+declare function createLangChainAdapter<Datum, Output>(options: LangChainAdapterOptions<Datum, Output>): GepaAdapter<Datum, LangChainTrace, Output | null>;
+//#endregion
+export { LangChainAdapterOptions, LangChainEvidence, LangChainScore, LangChainStepType, LangChainTrace, LangChainTraceStep, createLangChainAdapter };

package/dist/index.mjs

@@ -0,0 +1,310 @@
+import { mapWithConcurrency, priceUsage } from "textopt";
+//#region src/adapter.ts
+const DEFAULT_CONCURRENCY = 8;
+/**
+* Runs a LangChain runnable (chain, agent, or LangGraph graph) as the system
+* under optimization. The candidate is injected by rebuilding the runnable, so
+* anything that reads candidate text — prompts, tool descriptions, routing
+* instructions — is optimizable.
+*/
+function createLangChainAdapter(options) {
+	const { buildRunnable, score, toInput = (datum) => datum, concurrency = DEFAULT_CONCURRENCY, includeChainSteps = false, pricing, componentRunNames, isTransient = () => false, buildRecord } = options;
+	return {
+		evaluate: async ({ batch, candidate, captureTraces, run, signal }) => {
+			const runnable = buildRunnable(candidate);
+			const metadata = {
+				textopt_iteration: run.iteration,
+				textopt_phase: run.phase,
+				textopt_split: run.split,
+				textopt_candidate_id: run.candidateId
+			};
+			const results = await mapWithConcurrency({
+				items: batch,
+				limit: concurrency,
+				task: async (datum) => {
+					const collector = createTraceCollector({ includeChainSteps });
+					const startedAt = Date.now();
+					let output = null;
+					let failure;
+					let transient = false;
+					try {
+						output = await runnable.invoke(toInput(datum), {
+							callbacks: [collector.handler],
+							metadata,
+							signal
+						});
+					} catch (err) {
+						signal?.throwIfAborted();
+						failure = err instanceof Error ? err.message : String(err);
+						transient = isTransient(err);
+					}
+					const steps = collector.finish();
+					const usage = priceUsage({
+						usage: collector.usage(),
+						...pricing === void 0 ? {} : { pricing }
+					});
+					const trace = {
+						steps: captureTraces ? steps : [],
+						durationMs: Date.now() - startedAt,
+						...failure === void 0 ? {} : { error: failure }
+					};
+					if (failure !== void 0) return {
+						output: null,
+						trace,
+						usage,
+						scored: {
+							score: 0,
+							feedback: `Run failed: ${failure}`,
+							transient
+						}
+					};
+					try {
+						return {
+							output,
+							trace,
+							usage,
+							scored: await score({
+								datum,
+								output,
+								trace
+							})
+						};
+					} catch (err) {
+						signal?.throwIfAborted();
+						const message = err instanceof Error ? err.message : String(err);
+						return {
+							output,
+							trace,
+							usage,
+							scored: {
+								score: 0,
+								feedback: `Scoring failed: ${message}`,
+								transient: isTransient(err)
+							}
+						};
+					}
+				},
+				signal
+			});
+			const evaluation = {
+				outputs: results.map((result) => result.output),
+				scores: results.map((result) => result.scored.score),
+				feedback: results.map((result) => result.scored.feedback ?? "")
+			};
+			if (results.some((result) => result.scored.usage !== void 0 || Object.keys(result.usage).length > 0)) evaluation.usage = results.map((result) => result.scored.usage ?? result.usage);
+			if (captureTraces) evaluation.trajectories = results.map((result) => result.trace);
+			if (results.some((result) => result.scored.objectiveScores !== void 0)) evaluation.objectiveScores = results.map((result) => result.scored.objectiveScores ?? {});
+			if (results.some((result) => result.scored.transient === true)) evaluation.transient = results.map((result) => result.scored.transient === true);
+			return evaluation;
+		},
+		makeReflectiveDataset: ({ batch, evaluation, componentsToUpdate }) => {
+			const dataset = {};
+			for (const component of componentsToUpdate) dataset[component] = batch.map((datum, index) => {
+				const trace = evaluation.trajectories?.[index] ?? {
+					steps: [],
+					durationMs: 0
+				};
+				const output = evaluation.outputs[index] ?? null;
+				const scoreValue = evaluation.scores[index] ?? 0;
+				const feedback = evaluation.feedback?.[index] ?? "";
+				if (buildRecord !== void 0) return buildRecord({
+					datum,
+					output,
+					trace,
+					score: scoreValue,
+					feedback,
+					component
+				});
+				const componentSteps = selectComponentSteps({
+					trace,
+					runName: componentRunNames?.[component]
+				});
+				return {
+					inputs: toInput(datum),
+					generatedOutputs: output,
+					feedback,
+					score: scoreValue,
+					...componentSteps.length > 0 ? { evidence: { trace: componentSteps } } : {}
+				};
+			});
+			return dataset;
+		}
+	};
+}
+function selectComponentSteps(args) {
+	const { trace, runName } = args;
+	if (runName === void 0) return trace.steps;
+	return trace.steps.filter((step) => step.name === runName);
+}
+/**
+* LangChain accepts plain handler objects, so trace capture needs no subclass
+* and no LangSmith account — the same events LangSmith records land here.
+*/
+function createTraceCollector(args) {
+	const { includeChainSteps } = args;
+	const steps = [];
+	const openSteps = /* @__PURE__ */ new Map();
+	const tokens = {
+		inputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0
+	};
+	let counted = false;
+	function open(step) {
+		openSteps.set(step.runId, step);
+		steps.push(step);
+	}
+	/**
+	* Any span still open when the run ends never got its end callback — the
+	* chain was torn down first. Left alone it is indistinguishable in the trace
+	* from a step that legitimately produced nothing, which quietly misleads the
+	* reflection model.
+	*/
+	function finish() {
+		for (const step of openSteps.values()) step.error = "Step did not complete before the run ended";
+		openSteps.clear();
+		return steps;
+	}
+	function close(args) {
+		const step = openSteps.get(args.runId);
+		if (step === void 0) return;
+		step.outputs = args.outputs;
+		if (args.error !== void 0) step.error = args.error;
+		openSteps.delete(args.runId);
+	}
+	const handler = {
+		handleLLMStart: (llm, prompts, runId, parentRunId, _extra, _tags, _meta, runName) => {
+			open({
+				type: "llm",
+				name: runName ?? nameOf(llm),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs: prompts
+			});
+		},
+		handleChatModelStart: (llm, messages, runId, parentRunId, _extra, _tags, _meta, runName) => {
+			open({
+				type: "llm",
+				name: runName ?? nameOf(llm),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs: messages.flat().map((message) => ({
+					role: message.getType(),
+					content: message.content
+				}))
+			});
+		},
+		handleLLMEnd: (output, runId) => {
+			countTokens(output);
+			close({
+				runId,
+				outputs: output.generations.flat().map((generation) => generation.text)
+			});
+		},
+		handleLLMError: (err, runId) => {
+			close({
+				runId,
+				outputs: null,
+				error: messageOf(err)
+			});
+		},
+		handleToolStart: (tool, input, runId, parentRunId, _tags, _meta, runName) => {
+			open({
+				type: "tool",
+				name: runName ?? nameOf(tool),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs: input
+			});
+		},
+		handleToolEnd: (output, runId) => {
+			close({
+				runId,
+				outputs: output
+			});
+		},
+		handleToolError: (err, runId) => {
+			close({
+				runId,
+				outputs: null,
+				error: messageOf(err)
+			});
+		},
+		handleRetrieverStart: (retriever, query, runId, parentRunId, _tags, _meta, runName) => {
+			open({
+				type: "retriever",
+				name: runName ?? nameOf(retriever),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs: query
+			});
+		},
+		handleRetrieverEnd: (documents, runId) => {
+			close({
+				runId,
+				outputs: documents.map((document) => document.pageContent)
+			});
+		}
+	};
+	if (includeChainSteps) {
+		handler.handleChainStart = (chain, inputs, runId, parentRunId, _tags, _meta, _runType, runName) => {
+			open({
+				type: "chain",
+				name: runName ?? nameOf(chain),
+				runId,
+				...parentRunId === void 0 ? {} : { parentRunId },
+				inputs
+			});
+		};
+		handler.handleChainEnd = (outputs, runId) => {
+			close({
+				runId,
+				outputs
+			});
+		};
+	}
+	/**
+	* LangChain reports tokens in two shapes depending on the integration: the
+	* legacy `llmOutput.tokenUsage` and the message-level `usage_metadata` newer
+	* chat models attach. Reading both is what makes this work across providers;
+	* an integration that fills both describes one call twice, so a message-level
+	* shape that carries a count wins and the legacy total is only a fallback.
+	*/
+	function countTokens(output) {
+		let fromMetadata = false;
+		for (const generation of output.generations?.flat() ?? []) {
+			const metadata = generation.message?.usage_metadata;
+			if (metadata === void 0) continue;
+			const inputTokens = metadata.input_tokens ?? 0;
+			const outputTokens = metadata.output_tokens ?? 0;
+			const totalTokens = metadata.total_tokens ?? inputTokens + outputTokens;
+			if (inputTokens === 0 && outputTokens === 0 && totalTokens === 0) continue;
+			fromMetadata = true;
+			counted = true;
+			tokens.inputTokens += inputTokens;
+			tokens.outputTokens += outputTokens;
+			tokens.totalTokens += totalTokens;
+		}
+		if (fromMetadata) return;
+		const legacy = output.llmOutput?.tokenUsage;
+		if (legacy !== void 0) {
+			counted = true;
+			tokens.inputTokens += legacy.promptTokens ?? 0;
+			tokens.outputTokens += legacy.completionTokens ?? 0;
+			tokens.totalTokens += legacy.totalTokens ?? (legacy.promptTokens ?? 0) + (legacy.completionTokens ?? 0);
+		}
+	}
+	return {
+		handler,
+		finish,
+		usage: () => counted ? { ...tokens } : {}
+	};
+}
+function nameOf(serialized) {
+	return serialized?.id?.at(-1) ?? "unknown";
+}
+function messageOf(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+export { createLangChainAdapter };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@textopt/langchain",
+  "version": "0.1.0",
+  "description": "LangChain adapter for textopt",
+  "keywords": [
+    "prompt-optimization",
+    "gepa",
+    "langchain",
+    "langgraph",
+    "llm"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/ctdio/textopt#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ctdio/textopt.git",
+    "directory": "packages/langchain"
+  },
+  "bugs": {
+    "url": "https://github.com/ctdio/textopt/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "textopt": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3.0 <2"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.2.8"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}