opencandle 0.4.0 → 0.6.0

package/src/routing/slot-resolver.ts

@@ -1,11 +1,11 @@
+import { OPTIONS_SCREENER_DEFAULTS, PORTFOLIO_DEFAULTS } from "./defaults.js";
 import type {
   ExtractedEntities,
-  PortfolioSlots,
   OptionsScreenerSlots,
+  PortfolioSlots,
   SlotResolution,
   SlotSource,
 } from "./types.js";
-import { PORTFOLIO_DEFAULTS, OPTIONS_SCREENER_DEFAULTS } from "./defaults.js";
 
 interface Preferences {
   riskProfile?: string;
@@ -20,9 +20,34 @@ interface Preferences {
 }
 
 function mapDteHintToTarget(dteHint: string | undefined): string | undefined {
-  switch (dteHint) {
+  const normalized = dteHint?.toLowerCase().trim();
+  if (!normalized) return undefined;
+
+  if (/\bleaps?\b/.test(normalized) || /\blong[\s-]*dated\b/.test(normalized)) {
+    return "180_plus_days";
+  }
+  if (/\b(?:1|one)\s*(?:-|to|or)\s*(?:2|two)\s*weeks?\b/.test(normalized)) {
+    return "7_to_14_days";
+  }
+  if (/\bevent[_\s-]?week\b/.test(normalized)) {
+    return "0_to_7_days";
+  }
+  const explicitDays = normalized.match(/\b(\d+)\s*(?:-|to|or)\s*(\d+)\s*(?:days?|dte)\b/);
+  if (explicitDays) {
+    return `${explicitDays[1]}_to_${explicitDays[2]}_days`;
+  }
+  if (/\b(?:week|weekly|weeks?)\b/.test(normalized)) {
+    return "7_to_14_days";
+  }
+  if (/\b(?:month|monthly|months?)\b/.test(normalized)) {
+    return "25_to_45_days";
+  }
+
+  switch (normalized) {
     case "week":
       return "7_to_14_days";
+    case "event_week":
+      return "0_to_7_days";
     case "month":
       return "25_to_45_days";
     case "leaps":
@@ -60,15 +85,23 @@ export function resolvePortfolioSlots(
     sources.budget = "default";
   }
 
-  const risk = resolve(entities.riskProfile, preferences.riskProfile, PORTFOLIO_DEFAULTS.riskProfile);
+  const risk = resolve(
+    entities.riskProfile,
+    preferences.riskProfile,
+    PORTFOLIO_DEFAULTS.riskProfile,
+  );
   sources.riskProfile = risk.source;
   if (risk.source === "default") defaultsUsed.push("riskProfile");
 
-  const horizon = resolve(entities.timeHorizon, preferences.timeHorizon, PORTFOLIO_DEFAULTS.timeHorizon);
+  const horizon = resolve(
+    entities.timeHorizon,
+    preferences.timeHorizon,
+    PORTFOLIO_DEFAULTS.timeHorizon,
+  );
   sources.timeHorizon = horizon.source;
   if (horizon.source === "default") defaultsUsed.push("timeHorizon");
 
-  const scope = resolve(undefined, preferences.assetScope, PORTFOLIO_DEFAULTS.assetScope);
+  const scope = resolve(entities.assetScope, preferences.assetScope, PORTFOLIO_DEFAULTS.assetScope);
   sources.assetScope = scope.source;
   if (scope.source === "default") defaultsUsed.push("assetScope");
 
@@ -76,7 +109,11 @@ export function resolvePortfolioSlots(
   sources.positionCount = count.source;
   if (count.source === "default") defaultsUsed.push("positionCount");
 
-  const maxPct = resolve(undefined, preferences.maxSinglePositionPct, PORTFOLIO_DEFAULTS.maxSinglePositionPct);
+  const maxPct = resolve(
+    undefined,
+    preferences.maxSinglePositionPct,
+    PORTFOLIO_DEFAULTS.maxSinglePositionPct,
+  );
   sources.maxSinglePositionPct = maxPct.source;
   if (maxPct.source === "default") defaultsUsed.push("maxSinglePositionPct");
 
@@ -105,20 +142,27 @@ export function resolveOptionsScreenerSlots(
 
   // Symbol: required, no default
   let symbol = "";
-  if (entities.symbols.length > 0) {
-    symbol = entities.symbols[0];
+  const requestedUnderlying = entities.heldSymbol ?? entities.symbols[0];
+  if (requestedUnderlying) {
+    symbol = requestedUnderlying;
     sources.symbol = "user";
   } else {
     missingRequired.push("symbol");
     sources.symbol = "default";
   }
 
-  // Direction: default to bullish
-  const dir = resolve(entities.direction, undefined, "bullish" as const);
+  // Direction: default to bullish unless the user specified a protective put hedge.
+  const inferredDirection =
+    entities.optionStrategy === "protective_put" ? "bearish" : entities.direction;
+  const dir = resolve(inferredDirection, undefined, "bullish" as const);
   sources.direction = dir.source;
   if (dir.source === "default") defaultsUsed.push("direction");
 
-  const dte = resolve(mapDteHintToTarget(entities.dteHint), preferences.dteTarget, OPTIONS_SCREENER_DEFAULTS.dteTarget);
+  const dte = resolve(
+    mapDteHintToTarget(entities.dteHint),
+    preferences.dteTarget,
+    OPTIONS_SCREENER_DEFAULTS.dteTarget,
+  );
   sources.dteTarget = dte.source;
   if (dte.source === "default") defaultsUsed.push("dteTarget");
 
@@ -126,14 +170,27 @@ export function resolveOptionsScreenerSlots(
   sources.objective = obj.source;
   if (obj.source === "default") defaultsUsed.push("objective");
 
-  const moneyness = resolve(undefined, preferences.moneynessPreference, OPTIONS_SCREENER_DEFAULTS.moneynessPreference);
+  const moneyness = resolve(
+    undefined,
+    preferences.moneynessPreference,
+    OPTIONS_SCREENER_DEFAULTS.moneynessPreference,
+  );
   sources.moneynessPreference = moneyness.source;
   if (moneyness.source === "default") defaultsUsed.push("moneynessPreference");
 
-  const liquidity = resolve(undefined, preferences.liquidityMinimum, OPTIONS_SCREENER_DEFAULTS.liquidityMinimum);
+  const liquidity = resolve(
+    undefined,
+    preferences.liquidityMinimum,
+    OPTIONS_SCREENER_DEFAULTS.liquidityMinimum,
+  );
   sources.liquidityMinimum = liquidity.source;
   if (liquidity.source === "default") defaultsUsed.push("liquidityMinimum");
 
+  if (entities.optionStrategy) sources.optionStrategy = "user";
+  if (entities.costBasis !== undefined) sources.costBasis = "user";
+  if (entities.shareQuantity !== undefined) sources.shareQuantity = "user";
+  if (entities.catalystSymbols !== undefined) sources.catalystSymbols = "user";
+
   return {
     resolved: {
       symbol,
@@ -144,6 +201,10 @@ export function resolveOptionsScreenerSlots(
       liquidityMinimum: liquidity.value,
       budget: entities.budget,
       maxPremium: entities.maxPremium,
+      optionStrategy: entities.optionStrategy,
+      costBasis: entities.costBasis,
+      shareQuantity: entities.shareQuantity,
+      catalystSymbols: entities.catalystSymbols,
     },
     sources,
     defaultsUsed,

package/src/routing/symbol-disambiguator.ts

@@ -0,0 +1,72 @@
+export const FINANCE_ACRONYM_DICTIONARY = new Set([
+  "IV",
+  "HV",
+  "ITM",
+  "OTM",
+  "ATM",
+  "IPO",
+  "SEC",
+  "FED",
+  "FOMC",
+  "IRS",
+  "ECB",
+  "BOE",
+  "BOJ",
+  "GDP",
+  "CPI",
+  "PPI",
+  "FX",
+  "NDA",
+]);
+
+export interface DroppedSymbol {
+  token: string;
+  reason: string;
+  signalsChecked: string[];
+}
+
+export interface SymbolDisambiguation {
+  kept: string[];
+  dropped: DroppedSymbol[];
+}
+
+export function disambiguateSymbols(candidates: string[], rawInput: string): SymbolDisambiguation {
+  const kept: string[] = [];
+  const dropped: DroppedSymbol[] = [];
+
+  for (const candidate of candidates) {
+    const token = candidate.toUpperCase();
+    if (!FINANCE_ACRONYM_DICTIONARY.has(token) || hasPositiveTickerSignal(token, rawInput)) {
+      if (!kept.includes(token)) kept.push(token);
+      continue;
+    }
+
+    dropped.push({
+      token,
+      reason: "no positive ticker signal",
+      signalsChecked: ["cashtag", "local ticker phrase"],
+    });
+  }
+
+  return { kept, dropped };
+}
+
+function hasPositiveTickerSignal(token: string, rawInput: string): boolean {
+  return hasCashtag(token, rawInput) || hasLocalTickerPhrase(token, rawInput);
+}
+
+function hasCashtag(token: string, rawInput: string): boolean {
+  return new RegExp(`\\$${escapeRegExp(token)}\\b`, "i").test(rawInput);
+}
+
+function hasLocalTickerPhrase(token: string, rawInput: string): boolean {
+  const escaped = escapeRegExp(token);
+  return new RegExp(
+    `\\b${escaped}\\s+(?:ticker|stock|symbol)\\b|\\b(?:ticker|stock|symbol)\\s+${escaped}\\b`,
+    "i",
+  ).test(rawInput);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/routing/turn-context.ts

@@ -0,0 +1,108 @@
+import type { MemoryCategory, MemoryEntry } from "../memory/types.js";
+import {
+  buildPlanningEnvelope,
+  type PlanningBuildOptions,
+  type PlanningEnvelope,
+} from "./planning.js";
+import { activeToolsForBundles, memoryScopesForRoute } from "./route-manifest.js";
+import type {
+  RouterDiagnostic,
+  RouterInputContext,
+  RouterOutput,
+  RouterRoute,
+  RouterRouteKind,
+  RouterSlot,
+  ToolBundleName,
+} from "./router-types.js";
+import type { ExtractedEntities, WorkflowType } from "./types.js";
+
+export interface MemoryQueryPlan {
+  routeKind: RouterRouteKind;
+  workflow?: Exclude<WorkflowType, "unclassified">;
+  categories: MemoryCategory[];
+  symbols: string[];
+  slotKeys: string[];
+}
+
+export interface MemoryProvenance {
+  category: MemoryCategory;
+  key: string;
+  source?: string;
+  recordedAt: string;
+  confidence?: string;
+  filtered?: boolean;
+  filterReason?: string;
+}
+
+export interface ResolvedTurnContext {
+  userInput: string;
+  priorTurns: RouterInputContext["priorTurns"];
+  routeKind: RouterRouteKind;
+  legacyRoute: RouterRoute;
+  workflow?: Exclude<WorkflowType, "unclassified">;
+  entities: ExtractedEntities;
+  slots: Record<string, RouterSlot>;
+  missingRequired: string[];
+  toolBundles: ToolBundleName[];
+  activeToolNames: string[];
+  memoryQueryPlan: MemoryQueryPlan;
+  memoryProvenance: MemoryProvenance[];
+  promptPlaybook: RouterRouteKind;
+  diagnostics: RouterDiagnostic[];
+  planning: PlanningEnvelope;
+}
+
+export function buildResolvedTurnContext(
+  input: RouterInputContext,
+  output: RouterOutput,
+  options: {
+    availableToolNames?: readonly string[];
+    memoryEntries?: readonly MemoryEntry[];
+    filteredMemory?: readonly MemoryProvenance[];
+    planning?: PlanningBuildOptions;
+  } = {},
+): ResolvedTurnContext {
+  const memoryQueryPlan = buildMemoryQueryPlan(output);
+  const memoryProvenance = [
+    ...(options.memoryEntries ?? []).map(memoryEntryToProvenance),
+    ...(options.filteredMemory ?? []),
+  ];
+
+  return {
+    userInput: input.text,
+    priorTurns: input.priorTurns,
+    routeKind: output.routeKind,
+    legacyRoute: output.route,
+    workflow: output.workflow,
+    entities: output.entities,
+    slots: output.slots,
+    missingRequired: output.missing_required,
+    toolBundles: output.tool_bundles,
+    activeToolNames: activeToolsForBundles(output.tool_bundles, options.availableToolNames),
+    memoryQueryPlan,
+    memoryProvenance,
+    promptPlaybook: output.routeKind,
+    diagnostics: output.diagnostics,
+    planning: buildPlanningEnvelope(input, output, options.planning),
+  };
+}
+
+export function buildMemoryQueryPlan(output: RouterOutput): MemoryQueryPlan {
+  return {
+    routeKind: output.routeKind,
+    workflow: output.workflow,
+    categories: memoryScopesForRoute(output.routeKind, output.workflow),
+    symbols: output.entities.symbols,
+    slotKeys: Object.keys(output.slots),
+  };
+}
+
+function memoryEntryToProvenance(entry: MemoryEntry): MemoryProvenance {
+  return {
+    category: entry.category,
+    key: entry.key,
+    source: entry.source,
+    recordedAt: entry.recordedAt,
+    confidence: entry.confidence,
+  };
+}

package/src/routing/types.ts

@@ -12,9 +12,16 @@ export interface ExtractedEntities {
   budget?: number;
   maxPremium?: number;
   timeHorizon?: string;
+  assetScope?: string;
   riskProfile?: string;
   direction?: "bullish" | "bearish";
   dteHint?: string;
+  optionStrategy?: "covered_call" | "protective_put";
+  heldSymbol?: string;
+  catalystSymbols?: string[];
+  costBasis?: number;
+  shareQuantity?: number;
+  compareMetrics?: string[];
 }
 
 export interface ClassificationResult {
@@ -45,15 +52,22 @@ export interface OptionsScreenerSlots {
   liquidityMinimum: string;
   budget?: number;
   maxPremium?: number;
+  optionStrategy?: "covered_call" | "protective_put";
+  costBasis?: number;
+  shareQuantity?: number;
+  catalystSymbols?: string[];
   ivPreference?: string;
 }
 
 export interface CompareAssetsSlots {
   symbols: string[];
+  timeHorizon?: string;
   metrics?: string[];
+  budget?: number;
+  assetScope?: string;
 }
 
-export type SlotSource = "user" | "preference" | "default";
+export type SlotSource = "user" | "preference" | "default" | "prior_context" | "memory";
 
 export interface SlotResolution<T> {
   resolved: T;