opencandle 0.3.0 → 0.4.0

package/src/analysts/orchestrator.ts

@@ -0,0 +1,300 @@
+export type AnalystRole =
+  | "valuation"
+  | "momentum"
+  | "options"
+  | "contrarian"
+  | "risk";
+
+const SYMBOL_CAPTURE = "(\\$?[A-Za-z]{1,5}(?:[./-][A-Za-z]{1,2})?)";
+const NORMALIZED_SYMBOL_PATTERN = /^[A-Z]{1,5}(?:[./-][A-Z]{1,2})?$/;
+
+const VOTING_INSTRUCTION = `
+
+End your analysis with this exact format:
+SIGNAL: BUY | HOLD | SELL
+CONVICTION: [1-10]
+THESIS: [one sentence summary of your position]`;
+
+const EXECUTION_GUARDRAILS = `
+Execution rules:
+- Reuse tool outputs that were already fetched earlier in the session. Do not call the same tool again for the same symbol unless you need a missing field.
+- If a required provider returns unavailable or missing data, stop that leg quickly, label the missing metrics as unavailable, and continue with the remaining evidence.
+- Do not retry the same failing fundamentals call multiple times.`;
+
+const ANALYST_PROMPTS: Record<AnalystRole, (symbol: string) => string> = {
+  valuation: (symbol) =>
+    `**[Valuation Analyst]** You are a Damodaran-style valuation analyst. Your approach: connect the company's narrative to numbers, then compute intrinsic value. Analyze ${symbol}:
+1. Start with get_company_overview for P/E, forward P/E, EPS, profit margin, and market cap.
+2. If overview data is available, use get_financials for revenue, income, and free cash flow trends across years.
+3. If financial statements are available, use get_earnings for EPS surprise patterns and growth trajectory.
+4. Only use compute_dcf once you have the inputs needed to estimate intrinsic value.
+Assess: What growth rate is the market implicitly pricing in? Is the current price above or below your intrinsic value range? Cite specific numbers with their source tool. Keep reasoning data-driven — every claim must reference a fetched number.${EXECUTION_GUARDRAILS}${VOTING_INSTRUCTION}`,
+
+  momentum: (symbol) =>
+    `**[Momentum Analyst]** You are a CAN SLIM-style momentum analyst. Price action and volume are your primary evidence. Analyze ${symbol}:
+1. Use get_stock_history with 1y range, then get_technical_indicators.
+2. Focus on: Is price making new highs or breaking down from a base? Is OBV rising (volume confirming) or diverging? Where is price relative to VWAP?
+3. Check RSI (overbought >70 / oversold <30) and MACD histogram direction.
+4. Identify key support/resistance from Bollinger Bands and SMA(20)/SMA(50).
+5. Use get_earnings to check if earnings are accelerating quarter over quarter.
+State specific price levels. A breakout on rising volume is bullish; a breakdown on high volume is bearish. No vague language — cite the numbers.${EXECUTION_GUARDRAILS}${VOTING_INSTRUCTION}`,
+
+  options: (symbol) =>
+    `**[Options Analyst]** You analyze what the derivatives market is pricing in. Analyze ${symbol}:
+1. Use get_option_chain to review the full chain with strikes, volume, open interest, IV, and Greeks.
+2. Compute the put/call ratio from volume data — above 1.0 is bearish bias, below 0.7 is bullish.
+3. Look for unusually high volume contracts (>3x average OI) that signal institutional positioning.
+4. Note the overall IV level — is it elevated (expecting a move) or compressed (quiet period)?
+5. Check if smart money is positioning via deep ITM or OTM options with high volume.
+What is the options market pricing in that the stock price alone doesn't show?${EXECUTION_GUARDRAILS}${VOTING_INSTRUCTION}`,
+
+  contrarian: (symbol) =>
+    `**[Contrarian Analyst]** You are a Burry-style contrarian. Your job is to find what the crowd is missing. Be terse and data-driven — cite concrete numbers like "FCF yield 14.7%" or "P/E 8.3x vs sector 22x." Analyze ${symbol}:
+1. Use get_fear_greed for overall market mood — extreme readings signal opportunity.
+2. Use get_reddit_sentiment on wallstreetbets and stocks — check the sentiment score. Extreme bullishness from retail is a warning; extreme bearishness may be opportunity.
+3. Cross-reference: Is sentiment overly bullish while fundamentals (revenue, margins, FCF) are deteriorating? Is everyone bearish while the numbers quietly improve?
+5. Reuse get_company_overview or other fundamentals already fetched earlier in the session if available. If fundamentals are unavailable, say so and base the contrarian view on sentiment and price only.
+Where is the consensus wrong? What is the market over-pricing or under-pricing?${EXECUTION_GUARDRAILS}${VOTING_INSTRUCTION}`,
+
+  risk: (symbol) =>
+    `**[Risk Manager]** You are the final check before capital is deployed. Your job is to quantify downside, not to have an opinion on direction. Analyze ${symbol}:
+1. Use analyze_risk to compute annualized volatility, Sharpe ratio, max drawdown, and VaR(95%).
+2. Position sizing: Using the 2% portfolio risk rule, compute max position size. Formula: position_size = (0.02 * portfolio_value) / (entry_price * stop_loss_pct). Assume $100K portfolio.
+3. Risk/reward: Is potential upside at least 2x the max drawdown? If not, the trade is unfavorable regardless of thesis.
+4. Correlation: If this is in a portfolio, would it add diversification or concentration risk?
+5. Scenario analysis: What is the max realistic downside in a 1-sigma and 2-sigma move?
+Be quantitative. Every assessment must include a number.${EXECUTION_GUARDRAILS}${VOTING_INSTRUCTION}`,
+};
+
+export function buildBullPrompt(symbol: string): string {
+  return `**[Bull Researcher]** You have received five analyst perspectives above for ${symbol}.
+Build the strongest possible case FOR this position.
+
+Rules:
+- Cite analyst outputs and underlying tool evidence where available.
+- Address any bearish signals (SELL votes, high VaR, negative sentiment) and explain why they are less concerning than they appear.
+- You may call up to 2 tools if you identify a specific gap in the existing evidence. State the gap before calling the tool.
+- Reuse data already fetched in the session.
+${EXECUTION_GUARDRAILS}
+
+End with this exact format:
+BULL THESIS: [2-3 sentences building the case for the position]
+KEY RISK TO THIS THESIS: [one sentence — the single thing that would invalidate your case]`;
+}
+
+export function buildBearPrompt(symbol: string): string {
+  return `**[Bear Researcher]** You have received five analyst perspectives and a bull case above for ${symbol}. Your job is to dismantle the bull thesis.
+
+Rules:
+- Attack the weakest assumptions in the bull case above.
+- Cite analyst outputs and underlying tool evidence where available.
+- If the bull case ignored negative data points, surface them.
+- You may call up to 2 tools if you identify a specific gap in the existing evidence. State the gap before calling the tool.
+- Reuse data already fetched in the session.
+${EXECUTION_GUARDRAILS}
+
+End with this exact format:
+BEAR THESIS: [2-3 sentences arguing against the position]
+WHAT WOULD CHANGE MY MIND: [one sentence — what data would make you concede to the bull]`;
+}
+
+export function buildRebuttalPrompt(symbol: string): string {
+  return `**[Bull Rebuttal]** First, check the five analyst SIGNAL: lines above for ${symbol} (each analyst ended with "SIGNAL: BUY", "SIGNAL: HOLD", or "SIGNAL: SELL").
+If there is NO case where at least one analyst said SIGNAL: BUY and at least one said SIGNAL: SELL, respond with ONLY:
+REBUTTAL SKIPPED — consensus reached.
+
+Otherwise, the bear raised specific concerns above. Address each one directly.
+
+Rules:
+- Concede any point where the bear is factually correct.
+- For points you rebut, cite specific data from the analysts above.
+- Do not repeat your original thesis — respond to the bear's NEW arguments.
+- No tool calls in the rebuttal. Work with existing evidence only.
+${EXECUTION_GUARDRAILS}
+
+End with this exact format:
+CONCESSIONS: [bullet list of points you concede]
+REMAINING CONVICTION: [1-10, where 10 = fully confident despite bear case]`;
+}
+
+export function buildSynthesisPrompt(symbol: string): string {
+  return `**[Synthesis]** You have received five analyst signals with conviction scores for ${symbol}, a bull case arguing FOR the position, and a bear case arguing AGAINST.
+If a bull rebuttal with concessions appears above (not a line starting with "REBUTTAL SKIPPED"), treat the concessions as validated risks that must be addressed.
+
+Your job is NOT to average opinions. Your job is to RESOLVE THE DEBATE.
+
+1. **Vote Tally**: X BUY, Y HOLD, Z SELL — weighted average conviction
+2. **Verdict**: BUY, HOLD, or SELL
+3. **Debate winner**: Which side had the stronger argument, and why
+4. **Strongest counterpoint**: Address the losing side's best argument directly — explain why it's outweighed, or acknowledge it as a real risk
+5. **Reversal condition**: State the SPECIFIC, TESTABLE condition under which your verdict would reverse (the bear's "what would change my mind" or the bull's "key risk")
+6. **Key levels**: Entry, stop-loss, and target prices
+7. **Position sizing**: Based on risk manager's analysis
+
+Be direct and actionable. This is your final word on ${symbol}.
+
+End with this exact format:
+VERDICT: [BUY|HOLD|SELL]
+CONFIDENCE: [1-10]
+DEBATE WINNER: [BULL|BEAR]
+REVERSAL CONDITION: [specific, testable condition]`;
+}
+
+const VALIDATION_PROMPT_DEBATE = (symbol: string) =>
+  `**[Validation Check]** Review the complete analysis of ${symbol} above, including the debate. For each specific number cited by any analyst, bull, or bear researcher, verify it matches tool output data received in the session. Flag any inconsistencies. If a number was stated without being fetched first, call it out as UNVERIFIED.
+
+Additionally check:
+1. Did the bull/bear cite real numbers from analyst outputs (not hallucinated)?
+2. If a rebuttal occurred (not a line starting with "REBUTTAL SKIPPED"), are the concessions genuine (did the bull actually give ground on the bear's specific points)?
+3. Is the reversal condition specific and testable (not vague like "if macro deteriorates")?
+
+Output: VALIDATED if all checks pass, or list specific corrections needed.`;
+
+const SYNTHESIS_PROMPT_NO_DEBATE = (symbol: string) =>
+  `**[Synthesis]** You have received five analyst signals above for ${symbol}. Tally the SIGNAL votes (BUY/HOLD/SELL) and weight them by CONVICTION scores. Then provide:
+1. **Vote Tally**: X BUY, Y HOLD, Z SELL — weighted average conviction
+2. **Verdict**: Buy, Hold, or Sell — based on the signal consensus
+3. **Key thesis** in 2-3 sentences
+4. **Bull case** — what could go right
+5. **Bear case** — what could go wrong
+6. **Key levels** — entry, stop-loss, and target prices
+7. **Position sizing recommendation** based on risk profile
+
+Be direct and actionable. This is your final word on ${symbol}.`;
+
+const VALIDATION_PROMPT_NO_DEBATE = (symbol: string) =>
+  `**[Validation Check]** Review your complete analysis of ${symbol} above. For each specific number you cited (price, P/E, revenue, RSI, intrinsic value, etc.), verify it matches the tool output data you received. Flag any inconsistencies. If you stated a number without fetching it first, call that out as UNVERIFIED. Output: VALIDATED if all numbers check out, or list specific corrections needed.`;
+
+export function getInitialAnalysisPrompt(symbol: string): string {
+  return `Begin comprehensive analysis of ${symbol}. Start by getting the current stock quote.`;
+}
+
+export interface ComprehensiveAnalysisOptions {
+  debate?: boolean;
+}
+
+export function getComprehensiveAnalysisPrompts(symbol: string, options?: ComprehensiveAnalysisOptions): string[] {
+  const debate = options?.debate ?? true;
+  const roles: AnalystRole[] = ["valuation", "momentum", "options", "contrarian", "risk"];
+  const prompts = [getInitialAnalysisPrompt(symbol)];
+
+  for (const role of roles) {
+    prompts.push(ANALYST_PROMPTS[role](symbol));
+  }
+
+  if (debate) {
+    prompts.push(buildBullPrompt(symbol));
+    prompts.push(buildBearPrompt(symbol));
+    prompts.push(buildRebuttalPrompt(symbol));
+    prompts.push(buildSynthesisPrompt(symbol));
+    prompts.push(VALIDATION_PROMPT_DEBATE(symbol));
+  } else {
+    prompts.push(SYNTHESIS_PROMPT_NO_DEBATE(symbol));
+    prompts.push(VALIDATION_PROMPT_NO_DEBATE(symbol));
+  }
+
+  return prompts;
+}
+
+import type { WorkflowDefinition } from "../runtime/prompt-step.js";
+import { promptStep } from "../runtime/prompt-step.js";
+
+export function buildComprehensiveAnalysisDefinition(symbol: string, options?: ComprehensiveAnalysisOptions): WorkflowDefinition {
+  const debate = options?.debate ?? true;
+  const roles: AnalystRole[] = ["valuation", "momentum", "options", "contrarian", "risk"];
+
+  const analystOutputs = roles.map((r) => `${r}_signal`);
+
+  const analystSteps = [
+    promptStep("initial_fetch", "Fetch initial quote data", getInitialAnalysisPrompt(symbol), {
+      expectedOutputs: ["quote"],
+    }),
+    ...roles.map((role) =>
+      promptStep(`analyst_${role}`, `${role} analysis`, ANALYST_PROMPTS[role](symbol), {
+        skippable: true,
+        requiredInputs: ["quote"],
+        expectedOutputs: [`${role}_signal`],
+      }),
+    ),
+  ];
+
+  if (debate) {
+    return {
+      workflowType: "comprehensive_analysis",
+      steps: [
+        ...analystSteps,
+        promptStep("debate_bull", "Bull researcher case", buildBullPrompt(symbol), {
+          requiredInputs: analystOutputs,
+          expectedOutputs: ["bull_thesis"],
+        }),
+        promptStep("debate_bear", "Bear researcher case", buildBearPrompt(symbol), {
+          requiredInputs: [...analystOutputs, "bull_thesis"],
+          expectedOutputs: ["bear_thesis"],
+        }),
+        promptStep("debate_rebuttal", "Bull rebuttal (self-gating)", buildRebuttalPrompt(symbol), {
+          requiredInputs: [...analystOutputs, "bull_thesis", "bear_thesis"],
+          expectedOutputs: ["rebuttal"],
+        }),
+        promptStep("synthesis", "Resolve the debate", buildSynthesisPrompt(symbol), {
+          requiredInputs: [...analystOutputs, "bull_thesis", "bear_thesis", "rebuttal"],
+          expectedOutputs: ["verdict"],
+        }),
+        promptStep("validation", "Validate cited numbers", VALIDATION_PROMPT_DEBATE(symbol), {
+          skippable: true,
+          requiredInputs: ["verdict"],
+          expectedOutputs: ["validation_result"],
+        }),
+      ],
+    };
+  }
+
+  return {
+    workflowType: "comprehensive_analysis",
+    steps: [
+      ...analystSteps,
+      promptStep("synthesis", "Synthesize analyst signals", SYNTHESIS_PROMPT_NO_DEBATE(symbol), {
+        requiredInputs: analystOutputs,
+        expectedOutputs: ["verdict"],
+      }),
+      promptStep("validation", "Validate cited numbers", VALIDATION_PROMPT_NO_DEBATE(symbol), {
+        skippable: true,
+        requiredInputs: ["verdict"],
+        expectedOutputs: ["validation_result"],
+      }),
+    ],
+  };
+}
+
+export function runComprehensiveAnalysis(
+  enqueueFollowUp: (prompt: string) => void,
+  symbol: string,
+  options?: ComprehensiveAnalysisOptions,
+): void {
+  for (const prompt of getComprehensiveAnalysisPrompts(symbol, options).slice(1)) {
+    enqueueFollowUp(prompt);
+  }
+}
+
+export function isAnalysisRequest(input: string): { match: boolean; symbol?: string } {
+  const patterns = [
+    new RegExp(`^analyze\\s+${SYMBOL_CAPTURE}\\s*$`, "i"),
+    new RegExp(`^full\\s+analysis\\s+(?:of\\s+)?${SYMBOL_CAPTURE}\\s*$`, "i"),
+    new RegExp(`^deep\\s+dive\\s+(?:on\\s+)?${SYMBOL_CAPTURE}\\s*$`, "i"),
+  ];
+
+  for (const pattern of patterns) {
+    const match = input.match(pattern);
+    if (match) {
+      return { match: true, symbol: match[1].replace(/\$/g, "").toUpperCase() };
+    }
+  }
+
+  return { match: false };
+}
+
+export function normalizeSymbol(input: string): string | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) return undefined;
+  const candidate = trimmed.replace(/\$/g, "").toUpperCase();
+  return NORMALIZED_SYMBOL_PATTERN.test(candidate) ? candidate : undefined;
+}

package/src/cli.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import "./infra/node-version.js";
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import {
+  AuthStorage,
+  DefaultPackageManager,
+  InteractiveMode,
+  ModelRegistry,
+  SettingsManager,
+  createAgentSessionRuntime,
+  createAgentSessionServices,
+  getAgentDir,
+  initTheme,
+} from "@earendil-works/pi-coding-agent";
+import { createOpenCandleSession } from "./pi/session.js";
+import { continueOpenCandleSession } from "./pi/session-storage.js";
+import { loadEnv } from "./config.js";
+
+const require = createRequire(import.meta.url);
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+async function handlePackageCommand(
+  args: string[],
+  cwd: string,
+  agentDir: string,
+): Promise<boolean> {
+  const [command, ...rest] = args;
+  if (
+    !command ||
+    !["install", "remove", "uninstall", "list", "update"].includes(command)
+  ) {
+    return false;
+  }
+
+  const settingsManager = SettingsManager.create(cwd, agentDir);
+  const packageManager = new DefaultPackageManager({
+    cwd,
+    agentDir,
+    settingsManager,
+  });
+  packageManager.setProgressCallback((event) => {
+    if (event.type === "start" || event.type === "progress") {
+      process.stdout.write(`${event.message}\n`);
+    }
+  });
+
+  const source = rest.find((a) => !a.startsWith("-"));
+  const local = rest.includes("-l") || rest.includes("--local");
+
+  switch (command === "uninstall" ? "remove" : command) {
+    case "install": {
+      if (!source) {
+        console.error("Usage: opencandle install <source> [-l]");
+        process.exitCode = 1;
+        return true;
+      }
+      await packageManager.install(source, { local });
+      packageManager.addSourceToSettings(source, { local });
+      console.log(`Installed ${source}`);
+      return true;
+    }
+    case "remove": {
+      if (!source) {
+        console.error("Usage: opencandle remove <source> [-l]");
+        process.exitCode = 1;
+        return true;
+      }
+      await packageManager.remove(source, { local });
+      const removed = packageManager.removeSourceFromSettings(source, {
+        local,
+      });
+      if (!removed) {
+        console.error(`No matching package found for ${source}`);
+        process.exitCode = 1;
+      } else {
+        console.log(`Removed ${source}`);
+      }
+      return true;
+    }
+    case "list": {
+      const globalPkgs = settingsManager.getGlobalSettings().packages ?? [];
+      const projectPkgs = settingsManager.getProjectSettings().packages ?? [];
+      if (globalPkgs.length === 0 && projectPkgs.length === 0) {
+        console.log("No packages installed.");
+        return true;
+      }
+      if (globalPkgs.length > 0) {
+        console.log("User packages:");
+        for (const pkg of globalPkgs) {
+          const s = typeof pkg === "string" ? pkg : pkg.source;
+          const path = packageManager.getInstalledPath(s, "user");
+          console.log(`  ${s}${path ? `\n    ${path}` : ""}`);
+        }
+      }
+      if (projectPkgs.length > 0) {
+        console.log("Project packages:");
+        for (const pkg of projectPkgs) {
+          const s = typeof pkg === "string" ? pkg : pkg.source;
+          const path = packageManager.getInstalledPath(s, "project");
+          console.log(`  ${s}${path ? `\n    ${path}` : ""}`);
+        }
+      }
+      return true;
+    }
+    case "update": {
+      await packageManager.update(source);
+      console.log(source ? `Updated ${source}` : "All packages updated.");
+      return true;
+    }
+  }
+  return false;
+}
+
+async function handleGuiCommand(args: string[], cwd: string): Promise<boolean> {
+  if (args[0] !== "gui") return false;
+
+  const tsxCli = require.resolve("tsx/cli");
+  const serverPath = resolve(packageRoot, "gui/server/server.ts");
+  const child = spawn(process.execPath, [tsxCli, serverPath, ...args.slice(1)], {
+    cwd,
+    env: process.env,
+    stdio: "inherit",
+  });
+
+  const exitCode = await new Promise<number>((resolveExit) => {
+    child.on("close", (code, signal) => {
+      if (signal) {
+        resolveExit(1);
+      } else {
+        resolveExit(code ?? 0);
+      }
+    });
+  });
+  process.exitCode = exitCode;
+  return true;
+}
+
+async function main(): Promise<void> {
+  const { positionals } = parseArgs({ allowPositionals: true, strict: false });
+  const cwd = process.cwd();
+  const agentDir = getAgentDir();
+
+  if (await handleGuiCommand(positionals, cwd)) {
+    return;
+  }
+
+  if (await handlePackageCommand(positionals, cwd, agentDir)) {
+    return;
+  }
+
+  // Default: start the OpenCandle interactive agent
+  loadEnv();
+  const settingsManager = SettingsManager.create(cwd, agentDir);
+  const authStorage = AuthStorage.create();
+  const modelRegistry = ModelRegistry.create(authStorage);
+  const shouldSuppressFallbackMessage = modelRegistry.getAvailable().length === 0;
+
+  initTheme(settingsManager.getTheme(), true);
+
+  const sessionManager = continueOpenCandleSession(cwd);
+
+  const runtime = await createAgentSessionRuntime(
+    async (opts) => {
+      const services = await createAgentSessionServices({
+        cwd: opts.cwd,
+        agentDir: opts.agentDir,
+        authStorage,
+        settingsManager,
+        modelRegistry,
+      });
+      const result = await createOpenCandleSession({
+        cwd: opts.cwd,
+        agentDir: opts.agentDir,
+        settingsManager,
+        authStorage,
+        modelRegistry,
+        sessionManager: opts.sessionManager,
+        bindExtensions: false,
+      });
+      return {
+        ...result,
+        services,
+        diagnostics: services.diagnostics,
+      };
+    },
+    { cwd, agentDir, sessionManager },
+  );
+
+  try {
+    const interactiveMode = new InteractiveMode(runtime, {
+      modelFallbackMessage: shouldSuppressFallbackMessage
+        ? undefined
+        : runtime.modelFallbackMessage,
+    });
+    await interactiveMode.run();
+  } finally {
+    await runtime.dispose();
+  }
+}
+
+await main();

package/src/config.ts

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureParentDir, getConfigPath } from "./infra/opencandle-paths.js";
+
+export interface SentimentConfig {
+  retentionDays: number;
+  defaultSubreddits: string[];
+  commentsPerPost: number;
+  divergenceThreshold: number;
+}
+
+export type RouterMode = "rules" | "llm";
+
+export interface Config {
+  alphaVantageApiKey?: string;
+  fredApiKey?: string;
+  braveApiKey?: string;
+  exaApiKey?: string;
+  finnhubApiKey?: string;
+  /** Enable adversarial bull/bear debate in comprehensive analysis. Default: true. */
+  debate?: boolean;
+  /**
+   * Intent-router rollout flag. `"rules"` (default) runs the legacy regex
+   * `classifyIntent` + `extractPreferences` path. `"llm"` runs the LLM router
+   * ahead of prompt assembly. Controlled by `OPENCANDLE_ROUTER_MODE`.
+   */
+  routerMode: RouterMode;
+  sentiment?: SentimentConfig;
+}
+
+export interface OpenCandleFileConfig {
+  providers?: {
+    alphaVantage?: {
+      apiKey?: string;
+    };
+    fred?: {
+      apiKey?: string;
+    };
+    brave?: {
+      apiKey?: string;
+    };
+    exa?: {
+      apiKey?: string;
+    };
+    finnhub?: {
+      apiKey?: string;
+    };
+  };
+  /** Enable adversarial bull/bear debate in comprehensive analysis. Default: true. */
+  debate?: boolean;
+  sentiment?: {
+    retentionDays?: number;
+    defaultSubreddits?: string[];
+    commentsPerPost?: number;
+    divergenceThreshold?: number;
+  };
+}
+
+export function loadEnv(path = ".env"): void {
+  let content: string;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch {
+    return;
+  }
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    const value = trimmed.slice(eqIndex + 1).trim();
+    if (key && value) {
+      process.env[key] = value;
+    }
+  }
+}
+
+let cachedConfig: Config | null = null;
+
+const SENTIMENT_DEFAULTS: SentimentConfig = {
+  retentionDays: 30,
+  defaultSubreddits: ["wallstreetbets", "stocks", "investing", "options"],
+  commentsPerPost: 5,
+  divergenceThreshold: 0.4,
+};
+
+function resolveRouterMode(): RouterMode {
+  const raw = process.env.OPENCANDLE_ROUTER_MODE;
+  if (raw === undefined || raw === "") return "rules";
+  if (raw === "rules" || raw === "llm") return raw;
+  throw new Error(
+    `Invalid OPENCANDLE_ROUTER_MODE="${raw}". Allowed values: "rules" (default) or "llm".`,
+  );
+}
+
+function resolveConfig(fileConfig: OpenCandleFileConfig): Config {
+  const debateEnv = process.env.OPENCANDLE_DEBATE;
+  const fileSentiment = fileConfig.sentiment;
+  return {
+    alphaVantageApiKey:
+      process.env.ALPHA_VANTAGE_API_KEY ?? fileConfig.providers?.alphaVantage?.apiKey,
+    fredApiKey: process.env.FRED_API_KEY ?? fileConfig.providers?.fred?.apiKey,
+    braveApiKey: process.env.BRAVE_API_KEY ?? fileConfig.providers?.brave?.apiKey,
+    exaApiKey: process.env.EXA_API_KEY ?? fileConfig.providers?.exa?.apiKey,
+    finnhubApiKey: process.env.FINNHUB_API_KEY ?? fileConfig.providers?.finnhub?.apiKey,
+    debate: debateEnv !== undefined ? debateEnv !== "false" && debateEnv !== "0" : fileConfig.debate ?? true,
+    routerMode: resolveRouterMode(),
+    sentiment: {
+      retentionDays: fileSentiment?.retentionDays ?? SENTIMENT_DEFAULTS.retentionDays,
+      defaultSubreddits: fileSentiment?.defaultSubreddits ?? SENTIMENT_DEFAULTS.defaultSubreddits,
+      commentsPerPost: fileSentiment?.commentsPerPost ?? SENTIMENT_DEFAULTS.commentsPerPost,
+      divergenceThreshold: fileSentiment?.divergenceThreshold ?? SENTIMENT_DEFAULTS.divergenceThreshold,
+    },
+  };
+}
+
+export function loadFileConfig(path = getConfigPath()): OpenCandleFileConfig {
+  if (!existsSync(path)) {
+    return {};
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Unable to read OpenCandle config at ${path}: ${message}`);
+  }
+
+  try {
+    const parsed = JSON.parse(content) as OpenCandleFileConfig;
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid OpenCandle config at ${path}: ${message}`);
+  }
+}
+
+export function saveFileConfig(config: OpenCandleFileConfig, path = getConfigPath()): void {
+  ensureParentDir(path);
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+
+export function loadConfig(): Config {
+  loadEnv();
+  cachedConfig = resolveConfig(loadFileConfig());
+
+  return cachedConfig;
+}
+
+export function getConfig(): Config {
+  if (!cachedConfig) {
+    return loadConfig();
+  }
+  return cachedConfig;
+}
+
+/** Test-only: clear the memoized config so the next `getConfig()` re-reads env. */
+export function resetConfigCache(): void {
+  cachedConfig = null;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { createOpenCandleSession, type CreateOpenCandleSessionOptions } from "./pi/session.js";
+export { default as openCandleExtension } from "./pi/opencandle-extension.js";
+export { agentToolToPiTool, getOpenCandleToolDefinitions } from "./pi/tool-adapter.js";
+export { registerTools } from "./tool-kit.js";
+export { getAllTools } from "./tools/index.js";