agentfootprint 6.40.0 → 6.41.0

package/dist/types/observability/contextError/finders/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Context-error finders — the plain, pluggable public surface for context-bug
+ * localization. A `Finder` answers one question: "which piece of context made the
+ * agent's answer wrong?" Each finder is a thin, named adapter over the engines in
+ * `src/lib/context-bisect` + `src/lib/influence-core`; the academic method + citation
+ * live in `meta`, never in the import name.
+ *
+ * Taxonomy (area / category / thing): observability / contextError / finders.
+ * Tree-shakeable: one finder = one file = one named export; import only what you use.
+ */
+import type { Embedder } from '../../../lib/influence-core/index.js';
+/** How sure the finder is. `guessed` = ranked by a similarity proxy only;
+ *  `proven` = a removal/re-run actually flipped the outcome (counterfactual). */
+export type Evidence = 'guessed' | 'proven';
+/** What the finder points at. `piece` = a context element; `step` = an agent step. */
+export type Granularity = 'piece' | 'step';
+/** A removable piece of context the finder can suspect. */
+export interface ContextPiece {
+    readonly id: string;
+    readonly text: string;
+}
+/** One agent step (a tool-call), for finders that work at step granularity. */
+export interface StepInput {
+    readonly id: string;
+    /** Human-readable label, e.g. `get_promo@L1`. */
+    readonly label: string;
+    readonly text: string;
+}
+/** Everything a finder may need. Light finders use `embedder`; counterfactual
+ *  finders use `rerun`; step finders use `steps`. A finder throws if a field it
+ *  needs is missing. */
+export interface FindInput {
+    /** The removable context pieces to consider. */
+    readonly suspects: readonly ContextPiece[];
+    /** The wrong answer to explain. */
+    readonly wrongOutput: string;
+    /** Embedder for similarity-ranking finders. */
+    readonly embedder?: Embedder;
+    /** Re-run with the given pieces removed; `recovered` = the outcome flipped back. */
+    readonly rerun?: (removedIds: readonly string[]) => Promise<{
+        recovered: boolean;
+        outcome?: string;
+    }>;
+    /** The agent's steps, for step-granularity finders. */
+    readonly steps?: readonly StepInput[];
+    /** For testManyCombos: how many on/off combinations to sample (default ~4×#suspects). */
+    readonly samples?: number;
+}
+/** One suspect in the finder's ranked output. */
+export interface ScoredSuspect {
+    readonly id: string;
+    /** Higher = more suspicious. Absent for finders that don't score. */
+    readonly score?: number;
+}
+/** What a finder returns. Plain fields, namespace-independent. */
+export interface FindResult {
+    /** Which finder produced this. */
+    readonly finder: string;
+    /** Suspects, most-to-least suspicious. */
+    readonly suspects: readonly ScoredSuspect[];
+    /** The single top suspect, if any. */
+    readonly lead?: string;
+    /** The small set worth confirming when there is no clear single winner. */
+    readonly shortlist: readonly string[];
+    /** `guessed` (proxy) vs `proven` (counterfactual). */
+    readonly evidence: Evidence;
+    /** `piece` vs `step`. */
+    readonly granularity: Granularity;
+    /** How many times the finder re-ran the agent (the honest cost). 0 = free. */
+    readonly checks: number;
+    /** A self-explaining narrative of how the finder reached its answer. */
+    readonly explanation: string;
+}
+/** Attribution — kept off the import name, surfaced in docs / leaderboards. */
+export interface FinderMeta {
+    /** Plain one-liner for a leaderboard row. */
+    readonly label: string;
+    /** The precise technique, for experts. */
+    readonly method: string;
+    /** Citation, if the finder reimplements a published method. */
+    readonly paper?: string;
+}
+/** A pluggable context-error finder. */
+export interface Finder {
+    readonly name: string;
+    readonly meta: FinderMeta;
+    find(input: FindInput): Promise<FindResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/observability/contextError/finders/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/observability/contextError/finders/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAErE;iFACiF;AACjF,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5C,sFAAsF;AACtF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;wBAEwB;AACxB,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,CACf,UAAU,EAAE,SAAS,MAAM,EAAE,KAC1B,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,sCAAsC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wCAAwC;AACxC,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC7C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "6.40.0",
+  "version": "6.41.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -122,6 +122,11 @@
       "import": "./dist/esm/observe.js",
       "require": "./dist/observe.js"
     },
+    "./observability/contextError/finders": {
+      "types": "./dist/types/observability/contextError/finders/index.d.ts",
+      "import": "./dist/esm/observability/contextError/finders/index.js",
+      "require": "./dist/observability/contextError/finders/index.js"
+    },
     "./resilience": {
       "types": "./dist/types/resilience/index.d.ts",
       "import": "./dist/esm/resilience/index.js",