tradeblocks-mcp 4.2.0 → 4.4.0

package/src/tools/shared/field-analysis.ts

@@ -4,35 +4,63 @@ import { sweepThresholds } from "../../utils/threshold-sweep.ts";
 import { computeSliceStats } from "../../utils/analysis-stats.ts";
 import { createToolOutput } from "../../utils/output-formatter.ts";
 import { datasetAgeOutput } from "../../db/dataset-schemas.ts";
+import {
+  suggestionEvidence,
+  rankSuggestions,
+  objectiveOutput,
+  type FilterObjective,
+  type SuggestionEvidence,
+} from "./filter-objective.ts";
 
 export async function suggestFieldFilters(
   baseDir: string,
   blockId: string,
   trades: Trade[],
   fields: string[],
-  minImprovementPct: number,
+  minImprovementPct: number | undefined,
+  objective: FilterObjective,
+  maxMissedSessions?: number,
 ) {
-  const { catalog, values, datasetAge } = await resolveAnalysisFields(baseDir, trades);
-  const suggestions: {
+  const { catalog, values, datasetAge } = await resolveAnalysisFields(
+    baseDir,
+    trades,
+    maxMissedSessions,
+  );
+  const suggestions: (SuggestionEvidence & {
     filter: string;
     condition: { field: string; operator: string; value: number | string; lagged: boolean };
-    tradesRemoved: number;
     winnersRemoved: number;
     losersRemoved: number;
     newWinRate: number;
     newTotalPl: number;
     winRateDelta: number;
     plDelta: number;
-    confidence: string;
-  }[] = [];
+  })[] = [];
   const coverage: Record<string, { covered: number; uncovered: number }> = {};
+  const fieldBaselines: Record<
+    string,
+    {
+      count: number;
+      totalPl: number;
+      uncoveredCount: number;
+      uncoveredTotalPl: number;
+    }
+  > = {};
   for (const field of fields) {
-    requireCoveredField(field, catalog, values);
+    requireCoveredField(field, catalog, values, datasetAge);
     const pool = trades
       .map((trade, i) => ({ trade, value: values[i][field] }))
       .filter((item) => item.value !== undefined);
     coverage[field] = { covered: pool.length, uncovered: trades.length - pool.length };
     const baseline = computeSliceStats(pool.map(({ trade }) => trade.pl));
+    fieldBaselines[field] = {
+      count: pool.length,
+      totalPl: baseline.totalPl,
+      uncoveredCount: trades.length - pool.length,
+      uncoveredTotalPl: computeSliceStats(
+        trades.filter((_, i) => values[i][field] === undefined).map((trade) => trade.pl),
+      ).totalPl,
+    };
     const entry = catalog.find((entry) => entry.field === field)!;
     const candidates =
       entry.type === "numeric"
@@ -53,7 +81,15 @@ export async function suggestFieldFilters(
       if (!kept.length || !excluded.size) continue;
       const stats = computeSliceStats(kept.map(({ trade }) => trade.pl));
       const improvement = stats.winRate - baseline.winRate;
-      if (improvement < minImprovementPct) continue;
+      const evidence = suggestionEvidence(
+        objective,
+        improvement,
+        stats.totalPl - baseline.totalPl,
+        kept.length,
+        excluded.size,
+        minImprovementPct ?? 3,
+      );
+      if (!evidence) continue;
       const winnersRemoved = candidate.excluded.filter(({ trade }) => trade.pl > 0).length;
       suggestions.push({
         filter: `Skip when ${field} ${candidate.operator} ${candidate.value}`,
@@ -63,27 +99,29 @@ export async function suggestFieldFilters(
           value: candidate.value,
           lagged: entry.timing === "close",
         },
-        tradesRemoved: excluded.size,
+        ...evidence,
         winnersRemoved,
         losersRemoved: excluded.size - winnersRemoved,
         newWinRate: stats.winRate,
         newTotalPl: stats.totalPl,
         winRateDelta: improvement,
         plDelta: stats.totalPl - baseline.totalPl,
-        confidence: kept.length >= 100 ? "high" : kept.length >= 30 ? "medium" : "low",
       });
     }
   }
-  suggestions.sort((a, b) => b.winRateDelta - a.winRateDelta || b.plDelta - a.plDelta);
+  suggestions.sort((a, b) => rankSuggestions(objective, a, b));
   return createToolOutput(`Field filter analysis: ${blockId} | ${suggestions.length} suggestions`, {
     blockId,
     fields,
+    ...objectiveOutput(objective, minImprovementPct),
     currentStats: computeSliceStats(trades.map((trade) => trade.pl)),
     suggestedFilters: suggestions,
     compositeSuggestions: [],
     coverage,
+    fieldBaselines,
+    comparisonPopulation: "fieldBaselines",
     ...datasetAgeOutput(datasetAge, fields),
-    minImprovementThreshold: minImprovementPct,
+    minImprovementThreshold: objective === "winRate" ? (minImprovementPct ?? 3) : null,
   });
 }
 
@@ -93,9 +131,14 @@ export async function analyzeFieldRegimes(
   trades: Trade[],
   field: string,
   bins?: number[],
+  maxMissedSessions?: number,
 ) {
-  const { catalog, values, datasetAge } = await resolveAnalysisFields(baseDir, trades);
-  requireCoveredField(field, catalog, values);
+  const { catalog, values, datasetAge } = await resolveAnalysisFields(
+    baseDir,
+    trades,
+    maxMissedSessions,
+  );
+  requireCoveredField(field, catalog, values, datasetAge);
   const entry = catalog.find((entry) => entry.field === field)!;
   if (bins && entry.type !== "numeric") throw new Error(`Bins require a numeric field: ${field}`);
   if (bins?.some((value, i) => !Number.isFinite(value) || (i > 0 && value <= bins[i - 1])))

package/src/tools/shared/filter-objective.ts

@@ -0,0 +1,73 @@
+export type FilterObjective = "totalPl" | "winRate";
+
+export interface SuggestionEvidence {
+  objective: FilterObjective;
+  tradesKept: number;
+  keptFraction: number;
+  tradesRemoved: number;
+  confidence: "high" | "medium" | "low";
+  warnings: string[];
+}
+
+/** Both suggestion paths use the same admission and sample-size support rule. */
+export function suggestionEvidence(
+  objective: FilterObjective,
+  winRateDelta: number,
+  plDelta: number,
+  kept: number,
+  removed: number,
+  minImprovementPct: number,
+): SuggestionEvidence | null {
+  if (
+    !kept ||
+    !removed ||
+    (objective === "totalPl" ? plDelta <= 0 : winRateDelta < minImprovementPct)
+  )
+    return null;
+  const keptFraction = kept / (kept + removed);
+  const lowRetention = keptFraction < 0.2;
+  return {
+    objective,
+    tradesKept: kept,
+    keptFraction,
+    tradesRemoved: removed,
+    confidence: lowRetention
+      ? "low"
+      : removed >= 10 && kept >= 20
+        ? "high"
+        : removed >= 5 && kept >= 10
+          ? "medium"
+          : "low",
+    warnings: lowRetention
+      ? ["Low retention: fewer than 20% of covered trades kept; sample-size support capped at low."]
+      : [],
+  };
+}
+
+export function rankSuggestions(
+  objective: FilterObjective,
+  a: { winRateDelta: number; plDelta: number },
+  b: { winRateDelta: number; plDelta: number },
+): number {
+  return objective === "totalPl"
+    ? b.plDelta - a.plDelta || b.winRateDelta - a.winRateDelta
+    : b.winRateDelta - a.winRateDelta || b.plDelta - a.plDelta;
+}
+
+export function objectiveOutput(objective: FilterObjective, minImprovementPct?: number) {
+  return {
+    objective,
+    rankingRule:
+      objective === "totalPl"
+        ? "Positive P&L improvement, ranked by P&L improvement then win-rate gain"
+        : "Win-rate gain >= minImprovementPct, ranked by win-rate gain then P&L improvement",
+    supportNote:
+      "confidence is sample-size support, not statistical confidence; keptFraction < 0.2 caps it at low",
+    ...(objective === "totalPl" && minImprovementPct !== undefined
+      ? {
+          objectiveNote:
+            "minImprovementPct is ignored under totalPl; only positive P&L improvement is admitted.",
+        }
+      : {}),
+  };
+}

package/src/utils/filter-curve.ts

@@ -0,0 +1,257 @@
+import { sweepThresholds } from "./threshold-sweep.ts";
+import { rankSuggestions, type FilterObjective } from "../tools/shared/filter-objective.ts";
+
+interface CurveTrade {
+  pl: number;
+  dateOpened: Date;
+}
+interface Options {
+  mode: "lt" | "gt" | "both";
+  thresholds?: number[];
+  percentileSteps?: number[];
+  objective?: FilterObjective;
+  permutation?: { iterations: number; block: "month"; seed: number };
+}
+
+function population(trades: Array<{ pl: number }>) {
+  const totalPl = trades.reduce((sum, trade) => sum + trade.pl, 0);
+  return {
+    count: trades.length,
+    totalPl,
+    winRate: trades.length ? trades.filter((trade) => trade.pl > 0).length / trades.length : 0,
+  };
+}
+
+/** The same sweep and objective ranking are used for observed and permuted outcomes. */
+export function analyzeFilterCurve<T extends CurveTrade>(
+  trades: T[],
+  valueOf: (trade: T) => number | null,
+  options: Options,
+) {
+  const covered = trades.filter((trade) => valueOf(trade) !== null);
+  const base = population(covered);
+  const uncovered = population(trades.filter((trade) => valueOf(trade) === null));
+  const baseline = {
+    count: base.count,
+    winRate: Math.round(base.winRate * 10000) / 10000,
+    avgPl: Math.round((base.totalPl / base.count) * 100) / 100,
+    totalPl: Math.round(base.totalPl * 100) / 100,
+    uncoveredCount: uncovered.count,
+    uncoveredTotalPl: Math.round(uncovered.totalPl * 100) / 100,
+  };
+  function metrics(items: T[]) {
+    const stats = population(items);
+    const avgPl = stats.count ? stats.totalPl / stats.count : 0;
+    return {
+      count: stats.count,
+      percentOfTrades: Math.round((stats.count / base.count) * 10000) / 100,
+      winRate: Math.round(stats.winRate * 10000) / 10000,
+      avgPl: Math.round(avgPl * 100) / 100,
+      totalPl: Math.round(stats.totalPl * 100) / 100,
+      winRateDelta: stats.count
+        ? Math.round((stats.winRate - baseline.winRate) * 10000) / 10000
+        : -baseline.winRate,
+      avgPlDelta: stats.count ? Math.round((avgPl - baseline.avgPl) * 100) / 100 : -baseline.avgPl,
+      ...(stats.count > 0 && stats.count < 30
+        ? {
+            lowSampleWarning: `${stats.count} trades may be insufficient for reliable statistics (recommend >= 30)`,
+          }
+        : {}),
+    };
+  }
+  const sweeps = sweepThresholds(covered, valueOf, options.thresholds, options.percentileSteps);
+  const thresholds = sweeps.map((sweep) => ({
+    threshold: sweep.threshold,
+    ...(options.mode !== "gt" ? { lt: metrics(sweep.lt) } : {}),
+    ...(options.mode !== "lt" ? { gt: metrics(sweep.gt) } : {}),
+  }));
+  const sweetSpots = thresholds
+    .flatMap((row) =>
+      (["lt", "gt"] as const).flatMap((direction) => {
+        const stats = row[direction];
+        if (
+          !stats ||
+          stats.winRateDelta <= 0 ||
+          stats.avgPlDelta <= 0 ||
+          stats.percentOfTrades < 20
+        )
+          return [];
+        return [
+          {
+            threshold: row.threshold,
+            direction,
+            winRateDelta: stats.winRateDelta,
+            avgPlDelta: stats.avgPlDelta,
+            percentOfTrades: stats.percentOfTrades,
+            score: Math.round(stats.winRateDelta * stats.avgPlDelta * 10000) / 10000,
+          },
+        ];
+      }),
+    )
+    .sort((a, b) => b.score - a.score);
+  const legacy = {
+    tradesAnalyzed: covered.length,
+    baseline,
+    thresholds,
+    sweetSpots,
+    sweetSpotCriteria: {
+      winRateDelta: "> 0 (win rate improves)",
+      avgPlDelta: "> 0 (average P/L improves)",
+      percentOfTrades: ">= 20% (retains meaningful sample)",
+      scoreFormula: "winRateDelta * avgPlDelta (higher = better)",
+    },
+  };
+  if (!options.objective && !options.permutation) return { ...legacy, analysis: undefined };
+  const objective = options.objective ?? "totalPl";
+  const pairs = covered.map((trade) => ({ value: valueOf(trade)!, pl: trade.pl }));
+  function best(items: Array<{ value: number; pl: number }>) {
+    const candidates = sweepThresholds(
+      items,
+      (item) => item.value,
+      options.thresholds,
+      options.percentileSteps,
+    ).flatMap((sweep) =>
+      (["lt", "gt"] as const).flatMap((direction) => {
+        const kept = sweep[direction];
+        if (
+          (options.mode !== "both" && options.mode !== direction) ||
+          !kept.length ||
+          kept.length === items.length
+        )
+          return [];
+        const stats = population(kept);
+        return [
+          {
+            threshold: sweep.threshold,
+            direction,
+            kept,
+            plDelta: stats.totalPl - base.totalPl,
+            winRateDelta: (stats.winRate - base.winRate) * 100,
+          },
+        ];
+      }),
+    );
+    candidates.sort((a, b) => rankSuggestions(objective, a, b));
+    return candidates[0] ?? null;
+  }
+  const chosen = best(pairs);
+  const bestThreshold = chosen
+    ? {
+        threshold: chosen.threshold,
+        direction: chosen.direction,
+        kept: population(chosen.kept),
+        removed: population(
+          pairs.filter((pair) =>
+            chosen.direction === "lt"
+              ? pair.value >= chosen.threshold
+              : pair.value <= chosen.threshold,
+          ),
+        ),
+        objectiveDelta: objective === "totalPl" ? chosen.plDelta : chosen.winRateDelta,
+      }
+    : null;
+  const years = [...new Set(trades.map((trade) => trade.dateOpened.getFullYear()))].sort();
+  const perYear = chosen
+    ? years.map((year) => {
+        const annual = covered.filter((trade) => trade.dateOpened.getFullYear() === year);
+        const uncovered = population(
+          trades.filter(
+            (trade) => trade.dateOpened.getFullYear() === year && valueOf(trade) === null,
+          ),
+        );
+        const kept = annual.filter((trade) =>
+          chosen.direction === "lt"
+            ? valueOf(trade)! < chosen.threshold
+            : valueOf(trade)! > chosen.threshold,
+        );
+        const removed = annual.filter((trade) =>
+          chosen.direction === "lt"
+            ? valueOf(trade)! >= chosen.threshold
+            : valueOf(trade)! <= chosen.threshold,
+        );
+        const baseline = population(annual);
+        const stats = population(kept);
+        return {
+          year,
+          baseline: {
+            ...baseline,
+            uncoveredCount: uncovered.count,
+            uncoveredTotalPl: uncovered.totalPl,
+          },
+          kept: stats,
+          removed: population(removed),
+          objectiveDelta:
+            objective === "totalPl"
+              ? stats.totalPl - baseline.totalPl
+              : (stats.winRate - baseline.winRate) * 100,
+          ...(annual.length < 30 || kept.length < 30 || removed.length < 30
+            ? { lowSampleWarning: "Fewer than 30 covered, kept or removed entries" }
+            : {}),
+        };
+      })
+    : [];
+  let permutation:
+    | {
+        iterations: number;
+        block: "month";
+        seed: number;
+        blockCount: number;
+        status: string;
+        reason?: string;
+        pValue?: number;
+        exceedances?: number;
+        correction?: string;
+      }
+    | undefined;
+  if (options.permutation) {
+    const ordered = [...covered].sort((a, b) => a.dateOpened.getTime() - b.dateOpened.getTime());
+    const blocks = new Map<string, number[]>();
+    for (const trade of ordered) {
+      const key = `${trade.dateOpened.getFullYear()}-${trade.dateOpened.getMonth()}`;
+      if (!blocks.has(key)) blocks.set(key, []);
+      blocks.get(key)!.push(trade.pl);
+    }
+    permutation = { ...options.permutation, blockCount: blocks.size, status: "refused" };
+    if (covered.length < 30) permutation.reason = "too_few_covered_trades";
+    else if (blocks.size < 8) permutation.reason = "too_few_blocks";
+    else if (!chosen) permutation.reason = "no_eligible_threshold";
+    else {
+      let state = options.permutation.seed >>> 0;
+      const rng = () => {
+        state = (Math.imul(1664525, state) + 1013904223) >>> 0;
+        return state / 4294967296;
+      };
+      const original = [...blocks.values()];
+      let exceedances = 0;
+      const observed = objective === "totalPl" ? chosen.plDelta : chosen.winRateDelta;
+      const orderedValues = ordered.map((trade) => valueOf(trade)!);
+      for (let iteration = 0; iteration < options.permutation.iterations; iteration++) {
+        const shuffled = [...original];
+        for (let i = shuffled.length - 1; i > 0; i--) {
+          const j = Math.floor(rng() * (i + 1));
+          [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+        }
+        const outcomes = shuffled.flat();
+        const permuted = outcomes.map((pl, index) => ({ value: orderedValues[index], pl }));
+        const winner = best(permuted);
+        const score = winner
+          ? objective === "totalPl"
+            ? winner.plDelta
+            : winner.winRateDelta
+          : -Infinity;
+        if (score >= observed) exceedances++;
+      }
+      permutation = {
+        ...permutation,
+        status: "ok",
+        exceedances,
+        pValue: (exceedances + 1) / (options.permutation.iterations + 1),
+        correction: "add-one: (exceedances + 1) / (iterations + 1)",
+      };
+    }
+  }
+  return {
+    ...legacy,
+    analysis: { objective, bestThreshold, perYear, ...(permutation ? { permutation } : {}) },
+  };
+}

package/src/utils/trade-analysis-fields.ts

@@ -5,15 +5,22 @@ import {
   resolveTradeDatasets,
   runtimeFieldCatalog,
   summarizeDatasetAge,
+  type DatasetFieldAge,
 } from "../db/dataset-schemas.ts";
 import { buildLookaheadFreeQuery, CLOSE_KNOWN_FIELDS } from "./field-timing.ts";
 import { marketTickerDateKey, resolveTradeTicker } from "./ticker.ts";
 
-export async function resolveAnalysisFields(baseDir: string, trades: Trade[]) {
+export async function resolveAnalysisFields(
+  baseDir: string,
+  trades: Trade[],
+  maxMissedSessions?: number,
+) {
   const conn = await getConnection(baseDir);
   const datasets = await listDatasets(conn);
   const catalog = await runtimeFieldCatalog(conn);
-  const datasetMatches = trades.map((trade) => resolveTradeDatasets(datasets, trade));
+  const datasetMatches = trades.map((trade) =>
+    resolveTradeDatasets(datasets, trade, maxMissedSessions),
+  );
   const keys = trades.map((trade) => {
     const date = new Date(trade.dateOpened);
     const midnightUtc = date.getUTCHours() === 0 && date.getUTCMinutes() === 0;
@@ -64,9 +71,17 @@ export function requireCoveredField(
   field: string,
   catalog: { field: string }[],
   values: Record<string, number | string>[],
+  ages?: Record<string, DatasetFieldAge>,
 ) {
   if (!catalog.some((entry) => entry.field === field))
     throw new Error(`Unknown analysis field: ${field}`);
-  if (!values.some((row) => row[field] !== undefined))
-    throw new Error(`Uncovered analysis field: ${field}; no value available at trade entry`);
+  if (!values.some((row) => row[field] !== undefined)) {
+    const age = ages?.[field];
+    const reason = age?.rejectedAttachments
+      ? `; ${age.rejectedAttachments} refused by maxMissedSessions; ${age.unsupportedSessionAge} session ages unsupported`
+      : "";
+    throw new Error(
+      `Uncovered analysis field: ${field}; no value available at trade entry${reason}`,
+    );
+  }
 }