agent-ablation 0.1.0 → 0.2.0

package/README.md

@@ -59,6 +59,43 @@ console.log(summary.averageLoadBearingRatio);
 console.log(summary.perAgentInfluence); // { transaction_pattern: 0.17, identity_signal: 0.83, ... }
 ```
 
+## Using with LangGraph
+
+If you are orchestrating multi-agent systems with LangGraph, `fromLangGraphMessages` provides a zero-dependency convenience mapper for common LangGraph message shapes (this is a structural mapper, not an official LangGraph integration). It extracts named agent messages from `state.messages` and converts them into `Finding[]`:
+
+```typescript
+import { runAblation, fromLangGraphMessages, type Finding } from "agent-ablation";
+
+// In your LangGraph supervisor node / decision step:
+function evaluateState(state: { messages: any[] }) {
+  // Maps named specialist messages to Finding[]
+  const findings = fromLangGraphMessages(state.messages, {
+    scoreOf: (msg) => (msg.content as any).score,
+    confidenceOf: (msg) => (msg.content as any).confidence,
+  });
+
+  const decide = (fs: Finding[]) => {
+    const risk = 1 - fs.reduce((p, f) => p * (1 - f.score / 100), 1);
+    return risk >= 0.7 ? "decline" : "approve";
+  };
+
+  const result = runAblation(findings, decide);
+  return result;
+}
+```
+
+For arbitrary custom structures or telemetry traces, `fromRecords()` is also available to map any record array with custom extraction callbacks:
+
+```typescript
+import { fromRecords } from "agent-ablation";
+
+const findings = fromRecords(customAuditRecords, {
+  agentId: (r) => r.specialistId,
+  scoreOf: (r) => r.riskScore,
+  confidenceOf: (r) => r.confidenceLevel, // optional
+});
+```
+
 ## Worked example: reproducing SentryMesh's 33% multi-signal-share finding
 
 [SentryMesh](https://github.com/AyushCipher/Sentry-Mesh) is a four-specialist
@@ -166,6 +203,31 @@ function batchAblation<TVerdict>(
   decide: DecisionFn<TVerdict>,
   equals?: (a: TVerdict, b: TVerdict) => boolean
 ): { results: AblationResult<TVerdict>[]; summary: BatchAblationSummary };
+
+interface LangGraphAgentMessage {
+  name?: string | null;
+  content?: unknown;
+  [key: string]: unknown;
+}
+
+interface LangGraphAdapterOptions<TMessage extends LangGraphAgentMessage = LangGraphAgentMessage> {
+  scoreOf: (message: TMessage) => number;
+  confidenceOf?: (message: TMessage) => number | undefined;
+}
+
+function fromLangGraphMessages<TMessage extends LangGraphAgentMessage = LangGraphAgentMessage>(
+  messages: readonly TMessage[] | TMessage[],
+  options: LangGraphAdapterOptions<TMessage>
+): Finding[];
+
+function fromRecords<T>(
+  records: readonly T[] | T[],
+  options: {
+    agentId: (record: T, index: number) => string;
+    scoreOf: (record: T, index: number) => number;
+    confidenceOf?: (record: T, index: number) => number | undefined;
+  }
+): Finding[];
 ```
 
 `equals` defaults to `===`. If `TVerdict` is an object (or anything else compared

package/dist/index.cjs

@@ -21,9 +21,66 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   batchAblation: () => batchAblation,
+  fromLangGraphMessages: () => fromLangGraphMessages,
+  fromRecords: () => fromRecords,
   runAblation: () => runAblation
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/adapters/langgraph.ts
+function fromLangGraphMessages(messages, options) {
+  const findings = [];
+  for (const message of messages) {
+    if (!message || typeof message !== "object") {
+      continue;
+    }
+    if (typeof message.name !== "string" || message.name.trim().length === 0) {
+      continue;
+    }
+    const agentId = message.name;
+    const score = options.scoreOf(message);
+    const confidence = options.confidenceOf ? options.confidenceOf(message) : void 0;
+    let metadata;
+    if (typeof message.content === "string") {
+      metadata = { raw: message.content };
+    } else if (typeof message.content === "object" && message.content !== null && !Array.isArray(message.content)) {
+      metadata = { ...message.content };
+    } else if (message.content !== void 0 && message.content !== null) {
+      metadata = { raw: message.content };
+    }
+    const finding = {
+      agentId,
+      score
+    };
+    if (confidence !== void 0) {
+      finding.confidence = confidence;
+    }
+    if (metadata !== void 0) {
+      finding.metadata = metadata;
+    }
+    findings.push(finding);
+  }
+  return findings;
+}
+function fromRecords(records, options) {
+  return records.map((record, index) => {
+    const agentId = options.agentId(record, index);
+    const score = options.scoreOf(record, index);
+    const confidence = options.confidenceOf ? options.confidenceOf(record, index) : void 0;
+    const metadata = typeof record === "object" && record !== null && !Array.isArray(record) ? { ...record } : { raw: record };
+    const finding = {
+      agentId,
+      score,
+      metadata
+    };
+    if (confidence !== void 0) {
+      finding.confidence = confidence;
+    }
+    return finding;
+  });
+}
+
+// src/index.ts
 function defaultEquals(a, b) {
   return a === b;
 }
@@ -77,5 +134,7 @@ function batchAblation(cases, decide, equals = defaultEquals) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   batchAblation,
+  fromLangGraphMessages,
+  fromRecords,
   runAblation
 });

package/dist/index.d.cts

@@ -1,3 +1,66 @@
+/**
+ * Structural representation of a message produced by a LangGraph / LangChain agent.
+ *
+ * Convenience mapper type designed without importing any LangChain / LangGraph packages.
+ */
+interface LangGraphAgentMessage {
+    /**
+     * The name of the agent or node that produced the message.
+     * Messages without a valid name are skipped during conversion.
+     */
+    name?: string | null;
+    /**
+     * The message content. Can be a string, a structured object (e.g. parsed JSON),
+     * or any arbitrary payload.
+     */
+    content?: unknown;
+    /**
+     * Arbitrary additional properties from the message structure.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Options for mapping LangGraph messages into findings.
+ */
+interface LangGraphAdapterOptions<TMessage extends LangGraphAgentMessage = LangGraphAgentMessage> {
+    /**
+     * Required mapping function to extract the numerical score from each message.
+     */
+    scoreOf: (message: TMessage) => number;
+    /**
+     * Optional mapping function to extract a numerical confidence from each message.
+     */
+    confidenceOf?: (message: TMessage) => number | undefined;
+}
+/**
+ * Converts an array of LangGraph-style agent messages into `Finding` objects for ablation.
+ *
+ * Rules:
+ * - Entries without a valid string `name` are ignored.
+ * - `scoreOf(message)` is invoked for each named message to extract its score.
+ * - `confidenceOf(message)` is invoked if provided.
+ * - Object `content` is stored directly as `metadata`.
+ * - String `content` is wrapped inside `{ raw: content }` as `metadata`.
+ *
+ * @param messages Array of message-like objects (e.g. `state.messages`).
+ * @param options Mapping options requiring `scoreOf` and optional `confidenceOf`.
+ * @returns Array of `Finding` objects ready for `runAblation`.
+ */
+declare function fromLangGraphMessages<TMessage extends LangGraphAgentMessage = LangGraphAgentMessage>(messages: readonly TMessage[] | TMessage[], options: LangGraphAdapterOptions<TMessage>): Finding[];
+/**
+ * Converts an arbitrary array of records into `Finding` objects using user-supplied mapping functions.
+ * Preserves the original record in `metadata`.
+ *
+ * @param records Array of arbitrary records.
+ * @param options Mapping configuration providing `agentId`, `scoreOf`, and optional `confidenceOf`.
+ * @returns Array of `Finding` objects ready for `runAblation`.
+ */
+declare function fromRecords<T>(records: readonly T[] | T[], options: {
+    agentId: (record: T, index: number) => string;
+    scoreOf: (record: T, index: number) => number;
+    confidenceOf?: (record: T, index: number) => number | undefined;
+}): Finding[];
+
 interface Finding {
     agentId: string;
     score: number;
@@ -44,4 +107,4 @@ declare function batchAblation<TVerdict>(cases: Finding[][], decide: DecisionFn<
     summary: BatchAblationSummary;
 };
 
-export { type AblationResult, type BatchAblationSummary, type DecisionFn, type Finding, type PerAgentAblation, batchAblation, runAblation };
+export { type AblationResult, type BatchAblationSummary, type DecisionFn, type Finding, type LangGraphAdapterOptions, type LangGraphAgentMessage, type PerAgentAblation, batchAblation, fromLangGraphMessages, fromRecords, runAblation };

package/dist/index.d.ts

@@ -1,3 +1,66 @@
+/**
+ * Structural representation of a message produced by a LangGraph / LangChain agent.
+ *
+ * Convenience mapper type designed without importing any LangChain / LangGraph packages.
+ */
+interface LangGraphAgentMessage {
+    /**
+     * The name of the agent or node that produced the message.
+     * Messages without a valid name are skipped during conversion.
+     */
+    name?: string | null;
+    /**
+     * The message content. Can be a string, a structured object (e.g. parsed JSON),
+     * or any arbitrary payload.
+     */
+    content?: unknown;
+    /**
+     * Arbitrary additional properties from the message structure.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Options for mapping LangGraph messages into findings.
+ */
+interface LangGraphAdapterOptions<TMessage extends LangGraphAgentMessage = LangGraphAgentMessage> {
+    /**
+     * Required mapping function to extract the numerical score from each message.
+     */
+    scoreOf: (message: TMessage) => number;
+    /**
+     * Optional mapping function to extract a numerical confidence from each message.
+     */
+    confidenceOf?: (message: TMessage) => number | undefined;
+}
+/**
+ * Converts an array of LangGraph-style agent messages into `Finding` objects for ablation.
+ *
+ * Rules:
+ * - Entries without a valid string `name` are ignored.
+ * - `scoreOf(message)` is invoked for each named message to extract its score.
+ * - `confidenceOf(message)` is invoked if provided.
+ * - Object `content` is stored directly as `metadata`.
+ * - String `content` is wrapped inside `{ raw: content }` as `metadata`.
+ *
+ * @param messages Array of message-like objects (e.g. `state.messages`).
+ * @param options Mapping options requiring `scoreOf` and optional `confidenceOf`.
+ * @returns Array of `Finding` objects ready for `runAblation`.
+ */
+declare function fromLangGraphMessages<TMessage extends LangGraphAgentMessage = LangGraphAgentMessage>(messages: readonly TMessage[] | TMessage[], options: LangGraphAdapterOptions<TMessage>): Finding[];
+/**
+ * Converts an arbitrary array of records into `Finding` objects using user-supplied mapping functions.
+ * Preserves the original record in `metadata`.
+ *
+ * @param records Array of arbitrary records.
+ * @param options Mapping configuration providing `agentId`, `scoreOf`, and optional `confidenceOf`.
+ * @returns Array of `Finding` objects ready for `runAblation`.
+ */
+declare function fromRecords<T>(records: readonly T[] | T[], options: {
+    agentId: (record: T, index: number) => string;
+    scoreOf: (record: T, index: number) => number;
+    confidenceOf?: (record: T, index: number) => number | undefined;
+}): Finding[];
+
 interface Finding {
     agentId: string;
     score: number;
@@ -44,4 +107,4 @@ declare function batchAblation<TVerdict>(cases: Finding[][], decide: DecisionFn<
     summary: BatchAblationSummary;
 };
 
-export { type AblationResult, type BatchAblationSummary, type DecisionFn, type Finding, type PerAgentAblation, batchAblation, runAblation };
+export { type AblationResult, type BatchAblationSummary, type DecisionFn, type Finding, type LangGraphAdapterOptions, type LangGraphAgentMessage, type PerAgentAblation, batchAblation, fromLangGraphMessages, fromRecords, runAblation };

package/dist/index.js

@@ -1,3 +1,56 @@
+// src/adapters/langgraph.ts
+function fromLangGraphMessages(messages, options) {
+  const findings = [];
+  for (const message of messages) {
+    if (!message || typeof message !== "object") {
+      continue;
+    }
+    if (typeof message.name !== "string" || message.name.trim().length === 0) {
+      continue;
+    }
+    const agentId = message.name;
+    const score = options.scoreOf(message);
+    const confidence = options.confidenceOf ? options.confidenceOf(message) : void 0;
+    let metadata;
+    if (typeof message.content === "string") {
+      metadata = { raw: message.content };
+    } else if (typeof message.content === "object" && message.content !== null && !Array.isArray(message.content)) {
+      metadata = { ...message.content };
+    } else if (message.content !== void 0 && message.content !== null) {
+      metadata = { raw: message.content };
+    }
+    const finding = {
+      agentId,
+      score
+    };
+    if (confidence !== void 0) {
+      finding.confidence = confidence;
+    }
+    if (metadata !== void 0) {
+      finding.metadata = metadata;
+    }
+    findings.push(finding);
+  }
+  return findings;
+}
+function fromRecords(records, options) {
+  return records.map((record, index) => {
+    const agentId = options.agentId(record, index);
+    const score = options.scoreOf(record, index);
+    const confidence = options.confidenceOf ? options.confidenceOf(record, index) : void 0;
+    const metadata = typeof record === "object" && record !== null && !Array.isArray(record) ? { ...record } : { raw: record };
+    const finding = {
+      agentId,
+      score,
+      metadata
+    };
+    if (confidence !== void 0) {
+      finding.confidence = confidence;
+    }
+    return finding;
+  });
+}
+
 // src/index.ts
 function defaultEquals(a, b) {
   return a === b;
@@ -51,5 +104,7 @@ function batchAblation(cases, decide, equals = defaultEquals) {
 }
 export {
   batchAblation,
+  fromLangGraphMessages,
+  fromRecords,
   runAblation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-ablation",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Leave-one-out ablation testing for multi-agent decision systems — find out which agents' findings actually change the outcome.",
   "type": "module",
   "main": "./dist/index.cjs",