@tangle-network/agent-eval 0.123.0 → 0.123.1

package/CHANGELOG.md

@@ -18,6 +18,10 @@ All notable changes to `@tangle-network/agent-eval` and its sibling `agent-eval-
 - Pass track identity, operation, vision, ancestry, and proposer choice to candidate generation so independent tracks can pursue distinct strategies.
 - Route named tracks to caller-supplied proposers, with the default proposer as fallback, and make heuristic branches inherit their parent track's proposer.
 
+### Fixed
+
+- Compute contextual-bandit doubly robust estimates with separate logged-action and target-policy value terms, expose how many rows use DR versus IPS or the deprecated scalar path, and carry both values through belief-state records.
+
 ## [0.122.2] — 2026-07-17 — premeasured optimization continuation
 
 ### Added

package/dist/belief-state/index.d.ts

@@ -281,9 +281,10 @@ interface CalibrationReport {
  *   - For LLM agents, propensity scores must be supplied by the caller
  *     (logged in the trace, recovered from token log-probs, or estimated
  *     via a learned propensity model). We do NOT estimate propensity here.
- *   - Doubly-robust requires a Q-function (model-based reward predictor).
- *     We accept any callable; consumers pass either a tabular average,
- *     a regression fit, or a learned reward model.
+ *   - Doubly-robust requires two outputs from a Q-function: its prediction
+ *     for the logged action and its expectation under the target policy.
+ *     Consumers compute these with a tabular estimate, regression fit, or
+ *     learned reward model before constructing the trajectories.
  *
  * Bias / variance tradeoffs:
  *   - IPS: unbiased; high variance for small overlap, infinite variance
@@ -316,11 +317,33 @@ interface OffPolicyTrajectory {
      */
     targetProb: number;
     /**
-     * Optional model-based reward prediction at the same context. Used by
-     * `doublyRobust`. Set to `null` for IPS-only evaluation.
+     * Model-based reward prediction for the action selected by the behavior
+     * policy: `Q_hat(context, loggedAction)`. Supply this together with
+     * `vHatTarget` for contextual-bandit doubly-robust estimation.
+     */
+    qHatChosen?: number | null;
+    /**
+     * Expected model-based reward under the target policy:
+     * `sum_action targetPolicy(action | context) * Q_hat(context, action)`.
+     * Supply this together with `qHatChosen`. For an honest evaluation, both
+     * values must come from a model cross-fitted or trained outside this row.
+     */
+    vHatTarget?: number | null;
+    /**
+     * @deprecated Use `qHatChosen` and `vHatTarget` together. When the new pair
+     * is absent, this scalar is used as both terms to preserve existing results.
+     * When the new pair is present, this field is ignored.
      */
     qHat?: number | null;
 }
+interface OffPolicyContributionCounts {
+    /** Contributions using the contextual-bandit doubly-robust formula. */
+    dr: number;
+    /** Contributions using exact IPS because no reward-model estimate was supplied. */
+    ipsFallback: number;
+    /** Contributions using the deprecated single-scalar formula. */
+    legacyScalar: number;
+}
 interface OffPolicyEstimate {
     /** Estimated value of the target policy. */
     value: number;
@@ -335,6 +358,8 @@ interface OffPolicyEstimate {
      * mean) are a red flag — variance is dominated by a few outliers.
      */
     maxImportanceWeight: number;
+    /** Populated by `doublyRobust` to expose which formula each row used. */
+    contributionCounts?: OffPolicyContributionCounts;
 }
 interface OffPolicyOptions {
     /**
@@ -446,6 +471,9 @@ interface BeliefDecisionPoint {
     confidence?: number;
     behaviorProb?: number;
     targetProb?: number;
+    qHatChosen?: number | null;
+    vHatTarget?: number | null;
+    /** @deprecated Use `qHatChosen` and `vHatTarget` together. */
     qHat?: number | null;
     costUsd?: number;
     evidence: BeliefEvidenceRef[];
@@ -468,6 +496,9 @@ interface BeliefPolicyDecision {
     action: BeliefPolicyAction;
     confidence?: number;
     targetProb?: number;
+    qHatChosen?: number | null;
+    vHatTarget?: number | null;
+    /** @deprecated Use `qHatChosen` and `vHatTarget` together. */
     qHat?: number | null;
     reason?: string;
     reasons?: BeliefDecisionReason[];
@@ -479,6 +510,9 @@ interface BeliefSelectivePolicy {
 interface BeliefOpeTargetPolicy {
     id: string;
     targetProbOf(point: BeliefDecisionPoint): number | null | undefined;
+    qHatChosenOf?(point: BeliefDecisionPoint): number | null | undefined;
+    vHatTargetOf?(point: BeliefDecisionPoint): number | null | undefined;
+    /** @deprecated Use `qHatChosenOf` and `vHatTargetOf` together. */
     qHatOf?(point: BeliefDecisionPoint): number | null | undefined;
 }
 interface BeliefUtilityOptions {
@@ -1189,6 +1223,9 @@ interface RuntimeBeliefDecisionPointOptions {
     confidence?: number;
     behaviorProb?: number;
     targetProb?: number;
+    qHatChosen?: number | null;
+    vHatTarget?: number | null;
+    /** @deprecated Use `qHatChosen` and `vHatTarget` together. */
     qHat?: number | null;
     costUsd?: number;
     outcome?: BeliefDecisionOutcome;
@@ -1230,6 +1267,9 @@ interface RuntimeBeliefDecisionLabel {
     confidence?: number;
     behaviorProb?: number;
     targetProb?: number;
+    qHatChosen?: number | null;
+    vHatTarget?: number | null;
+    /** @deprecated Use `qHatChosen` and `vHatTarget` together. */
     qHat?: number | null;
     costUsd?: number;
     splitTag?: RunSplitTag;

package/dist/belief-state/index.js

@@ -14,7 +14,7 @@ import {
 } from "../chunk-T4SQEITX.js";
 import {
   offPolicyEstimateAll
-} from "../chunk-DTJ6QUQB.js";
+} from "../chunk-VGRCHJON.js";
 import {
   confidenceInterval
 } from "../chunk-PJQFMIOX.js";
@@ -68,6 +68,12 @@ function embeddedBeliefOpeTargetPolicy(id = "embedded-target-prob") {
     targetProbOf(point) {
       return point.targetProb;
     },
+    qHatChosenOf(point) {
+      return point.qHatChosen;
+    },
+    vHatTargetOf(point) {
+      return point.vHatTarget;
+    },
     qHatOf(point) {
       return point.qHat;
     }
@@ -86,9 +92,13 @@ function beliefDecisionsToOffPolicyTrajectories(points, targetPolicy, options =
       continue;
     }
     let targetProb;
+    let qHatChosen;
+    let vHatTarget;
     let qHat;
     try {
       targetProb = targetPolicy.targetProbOf(point);
+      qHatChosen = targetPolicy.qHatChosenOf?.(point);
+      vHatTarget = targetPolicy.vHatTargetOf?.(point);
       qHat = targetPolicy.qHatOf?.(point);
     } catch (error) {
       diagnostics.push(
@@ -100,7 +110,19 @@ function beliefDecisionsToOffPolicyTrajectories(points, targetPolicy, options =
       diagnostics.push(`${point.id}: invalid targetProb ${formatProbability(targetProb)}`);
       continue;
     }
-    if (qHat !== null && qHat !== void 0 && !isTargetProbability(qHat)) {
+    const hasQHatChosen = qHatChosen !== null && qHatChosen !== void 0;
+    const hasVHatTarget = vHatTarget !== null && vHatTarget !== void 0;
+    if (hasQHatChosen !== hasVHatTarget) {
+      diagnostics.push(`${point.id}: qHatChosen and vHatTarget must be supplied together`);
+      continue;
+    }
+    if (hasQHatChosen && hasVHatTarget && (!isTargetProbability(qHatChosen) || !isTargetProbability(vHatTarget))) {
+      diagnostics.push(
+        `${point.id}: invalid contextual Q pair qHatChosen=${formatProbability(qHatChosen)} vHatTarget=${formatProbability(vHatTarget)}`
+      );
+      continue;
+    }
+    if (!hasQHatChosen && !hasVHatTarget && qHat !== null && qHat !== void 0 && !isTargetProbability(qHat)) {
       diagnostics.push(`${point.id}: invalid qHat ${formatProbability(qHat)}; ignoring qHat`);
       qHat = null;
     }
@@ -109,6 +131,8 @@ function beliefDecisionsToOffPolicyTrajectories(points, targetPolicy, options =
       reward: rewardOf(point),
       behaviorProb: point.behaviorProb,
       targetProb,
+      ...qHatChosen !== void 0 ? { qHatChosen } : {},
+      ...vHatTarget !== void 0 ? { vHatTarget } : {},
       qHat
     });
   }
@@ -127,7 +151,8 @@ function evaluateBeliefOffPolicy(points, targetPolicy, options = {}) {
     minEffectiveSampleSize: options.minEffectiveSampleSize ?? 30,
     minEffectiveSampleRatio: options.minEffectiveSampleRatio ?? 0.25,
     dropped: trajectoryReport.dropped,
-    diagnostics: trajectoryReport.diagnostics
+    diagnostics: trajectoryReport.diagnostics,
+    legacyScalarContributions: estimates.dr.contributionCounts?.legacyScalar ?? 0
   });
   return { targetPolicyId: targetPolicy.id, ...estimates, support };
 }
@@ -140,6 +165,11 @@ function supportDiagnostics(estimate, options) {
   if (options.dropped > 0) {
     reasons.push(`dropped ${options.dropped} unsupported decision(s)`);
   }
+  if (options.legacyScalarContributions > 0) {
+    reasons.push(
+      `${options.legacyScalarContributions} decision(s) used deprecated scalar qHat; supply qHatChosen and vHatTarget for contextual doubly robust estimation`
+    );
+  }
   if (estimate.effectiveSampleSize < options.minEffectiveSampleSize) {
     reasons.push(
       `effective sample size ${estimate.effectiveSampleSize.toFixed(2)} below ${options.minEffectiveSampleSize}`
@@ -216,6 +246,8 @@ function thresholdSelectivePolicy(options) {
         action: confidence >= threshold ? "accept" : belowThresholdAction,
         confidence,
         targetProb: point.targetProb,
+        qHatChosen: point.qHatChosen,
+        vHatTarget: point.vHatTarget,
         qHat: point.qHat,
         reason: confidence >= threshold ? "confidence threshold passed" : "confidence threshold failed"
       };
@@ -1041,6 +1073,8 @@ function parseDecisionEvent(event, context) {
       confidence: finiteUnitField(payload, "confidence"),
       behaviorProb: numberField(payload, "behaviorProb"),
       targetProb: numberField(payload, "targetProb"),
+      qHatChosen: finiteUnitField(payload, "qHatChosen"),
+      vHatTarget: finiteUnitField(payload, "vHatTarget"),
       qHat: finiteUnitField(payload, "qHat"),
       costUsd: nonNegativeNumberField(payload, "costUsd"),
       evidence,
@@ -1155,6 +1189,8 @@ function runtimeDecisionPointToBeliefDecisionPoint(point, options) {
       confidence: unitProbabilityOrUndefined(options.confidence),
       behaviorProb: finiteNumberOrUndefined(options.behaviorProb),
       targetProb: finiteNumberOrUndefined(options.targetProb),
+      qHatChosen: options.qHatChosen === null ? null : unitProbabilityOrUndefined(options.qHatChosen),
+      vHatTarget: options.vHatTarget === null ? null : unitProbabilityOrUndefined(options.vHatTarget),
       qHat: options.qHat === null ? null : unitProbabilityOrUndefined(options.qHat),
       costUsd: nonNegativeNumberOrUndefined(options.costUsd),
       evidence: evidence.map((ref) => runtimeEvidenceToBeliefEvidence(ref, point)),
@@ -1384,6 +1420,8 @@ function buildRuntimeBeliefPhase0Measurement(options) {
         confidence: label.confidence,
         behaviorProb: label.behaviorProb,
         targetProb: label.targetProb,
+        qHatChosen: label.qHatChosen,
+        vHatTarget: label.vHatTarget,
         qHat: label.qHat,
         costUsd: label.costUsd,
         outcome: label.outcome,