build option trading agent modules

.gitignore

@@ -1,2 +1,44 @@
-./knowledge_base
-knowledge_base/raw/pdf/*.pdf
+# Secrets and local environment
+.env
+.env.*
+!.env.example
+.venv/
+.uv-cache/
+.python_history
+
+# Python generated files
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+
+# App/runtime artifacts
+.gradio/
+*.log
+.DS_Store
+
+# Local vector databases and RAG inputs
+alfred_chroma_db/
+knowledge_base/
+tools/knowledge_base/
+*.sqlite3
+*.sqlite
+
+# Local model caches
+hf_cache/
+tools/hf_cache/
+
+# Evaluation datasets, indexes, and generated reports
+eval/data/
+eval/indexes/
+eval/reports/
+eval/local_options_eval.jsonl
+
+# Local market/backtest data exports
+data/
+backtest/data/
+*.parquet
+*.feather

.python-version

@@ -0,0 +1 @@
+3.12

app.py

@@ -1,91 +1,27 @@
-from smolagents import CodeAgent,DuckDuckGoSearchTool, HfApiModel,load_tool,tool, LiteLLMModel
+from smolagents import CodeAgent, HfApiModel, load_tool, tool, LiteLLMModel
 import os
 import datetime
-import requests
 import pytz
 import yaml
-import json
 from dotenv import load_dotenv
 from tools.final_answer import FinalAnswerTool
-import yfinance as yf
+from tools.query_knowledge import QueryKnowledgeTool
+from tools.web_search import DuckDuckGoSearchTool
+from tools.visit_webpage import VisitWebpageTool
+from market_data.tools import (
+    calculate_option_greeks,
+    query_market_asset,
+    query_option_chain,
+    query_option_expirations,
+    query_price_history,
+    query_realized_volatility,
+    query_volatility_snapshot,
+)
+from strategy.tools import build_volatility_strategy
+from backtest.tools import analyze_strategy_payoff, backtest_long_straddle_csv, backtest_volatility_signal
+from optimizer.tools import optimize_volatility_signal_parameters
 from Gradio_UI import GradioUI
 
-@tool                       
-def query_market_asset(symbol: str) -> str:
-    """A universal market data tool to query the current price or level of ANY asset.
-    
-    Supported asset classes include major indices, stocks, ETFs, crypto, and forex.
-    
-    Args:
-        symbol: The specific ticker symbol used by Yahoo Finance. Examples:
-                - Indices (requires '^'): '^GSPC' (S&P 500), '^VIX' (Volatility Index), '^DJI' (Dow Jones), '^IXIC' (Nasdaq)
-                - Equities / ETFs: 'AAPL' (Apple), 'SPY' (SPDR S&P 500 ETF), 'TLT' (20+ Yr Treasury Bond)
-                - Crypto: 'BTC-USD' (Bitcoin), 'ETH-USD' (Ethereum)
-                - Forex: 'EURUSD=X' (EUR/USD rate), 'USDCNH=X' (USD/Offshore RMB)
-                       
-    Returns:
-        A JSON-formatted string containing the current price, high/low, timestamp, and asset info.
-    """
-    symbol = symbol.strip().upper()
-    
-    try:
-        ticker = yf.Ticker(symbol)
-        
-        data = ticker.history(period="1d", interval="1m")
-        
-        if not data.empty:
-            latest_row = data.iloc[-1]
-            current_price = float(latest_row['Close'])
-            open_price = float(latest_row['Open'])
-            high_price = float(latest_row['High'])
-            low_price = float(latest_row['Low'])
-            volume = int(latest_row['Volume'])
-            timestamp = str(data.index[-1])
-            
-            result = {
-                "status": "success",
-                "symbol": symbol,
-                "current_price": round(current_price, 4),
-                "open": round(open_price, 4),
-                "high": round(high_price, 4),
-                "low": round(low_price, 4),
-                "volume": volume,
-                "timestamp": timestamp,
-                "data_type": "intraday_1m"
-            }
-        else:
-            info = ticker.info
-            current_price = info.get("regularMarketPrice") or info.get("previousClose") or info.get("ask") or info.get("bid")
-            
-            if current_price:
-                result = {
-                    "status": "success",
-                    "symbol": symbol,
-                    "current_price": round(float(current_price), 4),
-                    "open": info.get("regularMarketOpen") or info.get("open"),
-                    "high": info.get("regularMarketDayHigh") or info.get("dayHigh"),
-                    "low": info.get("regularMarketDayLow") or info.get("dayLow"),
-                    "volume": info.get("regularMarketVolume") or info.get("volume", 0),
-                    "short_name": info.get("shortName", ""),
-                    "data_type": "cached_info"
-                }
-            else:
-                result = {
-                    "status": "error", 
-                    "symbol": symbol, 
-                    "message": "No price data could be resolved for this asset."
-                }
-                
-    except Exception as e:
-        result = {
-            "status": "error",
-            "symbol": symbol,
-            "message": f"Exception occurred while querying: {str(e)}"
-        }
-        
-    return json.dumps(result, ensure_ascii=False, indent=2)
-
-
 @tool
 def get_current_time_in_timezone(timezone: str) -> str:
     """A tool that fetches the current local time in a specified timezone.
@@ -104,6 +40,9 @@ def get_current_time_in_timezone(timezone: str) -> str:
 
 if __name__ == "__main__":
     final_answer = FinalAnswerTool()
+    query_knowledge = QueryKnowledgeTool()
+    web_search = DuckDuckGoSearchTool(max_results=6)
+    visit_webpage = VisitWebpageTool()
     load_dotenv()
     hf_token = os.getenv("HF_TOKEN")
     gemini_api_key = os.getenv("GEMINI_API_KEY");
@@ -118,7 +57,25 @@ if __name__ == "__main__":
         
     agent = CodeAgent(
         model=model,
-        tools=[query_market_asset, get_current_time_in_timezone, final_answer],
+        tools=[
+            query_market_asset,
+            query_price_history,
+            query_realized_volatility,
+            query_option_expirations,
+            query_option_chain,
+            query_volatility_snapshot,
+            calculate_option_greeks,
+            build_volatility_strategy,
+            analyze_strategy_payoff,
+            backtest_long_straddle_csv,
+            backtest_volatility_signal,
+            optimize_volatility_signal_parameters,
+            get_current_time_in_timezone,
+            query_knowledge,
+            web_search,
+            visit_webpage,
+            final_answer,
+        ],
         max_steps=6,
         verbosity_level=1,
         grammar=None,

backtest/__init__.py

@@ -0,0 +1,8 @@
+from .vol_backtest import backtest_realized_vol_signal
+from .option_backtest import backtest_long_straddle_from_quotes, load_option_quotes_csv
+
+__all__ = [
+    "backtest_long_straddle_from_quotes",
+    "backtest_realized_vol_signal",
+    "load_option_quotes_csv",
+]

backtest/option_backtest.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import timedelta
+from pathlib import Path
+
+import pandas as pd
+
+from .vol_backtest import max_drawdown
+
+
+REQUIRED_QUOTE_COLUMNS = {
+    "date",
+    "underlying_symbol",
+    "underlying_price",
+    "contract_symbol",
+    "option_type",
+    "expiration",
+    "strike",
+    "bid",
+    "ask",
+}
+
+
+@dataclass
+class OptionBacktestTrade:
+    entry_date: str
+    exit_date: str
+    contract_symbol: str
+    option_type: str
+    strike: float
+    expiration: str
+    quantity: int
+    entry_price: float
+    exit_price: float
+    fees: float
+    pnl: float
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def validate_quote_frame(quotes: pd.DataFrame) -> None:
+    missing = REQUIRED_QUOTE_COLUMNS - set(quotes.columns)
+    if missing:
+        raise ValueError(f"Historical option quotes missing required columns: {sorted(missing)}")
+
+
+def prepare_quotes(quotes: pd.DataFrame) -> pd.DataFrame:
+    validate_quote_frame(quotes)
+    frame = quotes.copy()
+    frame["date"] = pd.to_datetime(frame["date"]).dt.normalize()
+    frame["expiration"] = pd.to_datetime(frame["expiration"]).dt.normalize()
+    frame["option_type"] = frame["option_type"].str.lower()
+    quoted_mid = (frame["bid"] + frame["ask"]) / 2
+    if "mid" not in frame.columns:
+        frame["mid"] = quoted_mid
+    else:
+        frame["mid"] = frame["mid"].where(frame["mid"].notna(), quoted_mid)
+    frame["dte"] = (frame["expiration"] - frame["date"]).dt.days
+    frame = frame[(frame["bid"] >= 0) & (frame["ask"] > 0) & (frame["dte"] >= 0)]
+    return frame.sort_values(["date", "expiration", "strike", "option_type"]).reset_index(drop=True)
+
+
+def load_option_quotes_csv(path: str | Path) -> pd.DataFrame:
+    return prepare_quotes(pd.read_csv(path))
+
+
+def available_exit_date(
+    quotes: pd.DataFrame,
+    entry_date: pd.Timestamp,
+    target_exit_date: pd.Timestamp,
+    contract_symbol: str,
+) -> pd.Timestamp | None:
+    contract_quotes = quotes[
+        (quotes["contract_symbol"] == contract_symbol)
+        & (quotes["date"] >= target_exit_date)
+    ]
+    if contract_quotes.empty:
+        contract_quotes = quotes[quotes["contract_symbol"] == contract_symbol]
+        contract_quotes = contract_quotes[
+            (contract_quotes["date"] > entry_date)
+            & (contract_quotes["date"] < target_exit_date)
+        ]
+        if contract_quotes.empty:
+            return None
+        return contract_quotes["date"].max()
+    if contract_quotes.empty:
+        return None
+    return contract_quotes["date"].min()
+
+
+def quote_price(row: pd.Series, side: str, price_field: str) -> float:
+    if price_field == "mid":
+        return float(row["mid"])
+    if price_field != "trade":
+        raise ValueError("price_field must be 'trade' or 'mid'.")
+    if side == "buy":
+        return float(row["ask"])
+    return float(row["bid"])
+
+
+def select_expiration_slice(day_quotes: pd.DataFrame, target_dte: int) -> pd.DataFrame:
+    candidates = day_quotes[day_quotes["dte"] > 0]
+    if candidates.empty:
+        return candidates
+    expiration = candidates.assign(dte_error=(candidates["dte"] - target_dte).abs()).sort_values("dte_error").iloc[0]["expiration"]
+    return candidates[candidates["expiration"] == expiration]
+
+
+def select_atm_contract(expiration_slice: pd.DataFrame, option_type: str) -> pd.Series | None:
+    contracts = expiration_slice[expiration_slice["option_type"] == option_type]
+    if contracts.empty:
+        return None
+    spot = float(expiration_slice["underlying_price"].iloc[0])
+    return contracts.assign(strike_error=(contracts["strike"] - spot).abs()).sort_values("strike_error").iloc[0]
+
+
+def backtest_long_straddle_from_quotes(
+    quotes: pd.DataFrame,
+    symbol: str,
+    target_dte: int = 30,
+    holding_days: int = 5,
+    entry_every_days: int = 5,
+    contract_multiplier: int = 100,
+    fee_per_contract: float = 0.65,
+    price_field: str = "trade",
+) -> dict:
+    frame = prepare_quotes(quotes)
+    frame = frame[frame["underlying_symbol"].str.upper() == symbol.upper()]
+    if frame.empty:
+        raise ValueError(f"No historical option quotes found for {symbol}.")
+
+    trades: list[OptionBacktestTrade] = []
+    trade_groups = []
+    equity = [0.0]
+    dates = sorted(frame["date"].unique())
+    next_entry_date = dates[0]
+
+    for entry_date in dates:
+        entry_date = pd.Timestamp(entry_date)
+        if entry_date < next_entry_date:
+            continue
+
+        day_quotes = frame[frame["date"] == entry_date]
+        expiration_slice = select_expiration_slice(day_quotes, target_dte)
+        if expiration_slice.empty:
+            continue
+
+        call = select_atm_contract(expiration_slice, "call")
+        put = select_atm_contract(expiration_slice, "put")
+        if call is None or put is None:
+            continue
+
+        target_exit_date = entry_date + timedelta(days=holding_days)
+        pending_group_trades = []
+        group_pnl = 0.0
+        for leg in [call, put]:
+            exit_date = available_exit_date(frame, entry_date, target_exit_date, str(leg["contract_symbol"]))
+            if exit_date is None:
+                continue
+            exit_quote = frame[
+                (frame["date"] == exit_date)
+                & (frame["contract_symbol"] == leg["contract_symbol"])
+            ].iloc[0]
+
+            entry_price = quote_price(leg, "buy", price_field)
+            exit_price = quote_price(exit_quote, "sell", price_field)
+            fees = fee_per_contract * 2
+            pnl = (exit_price - entry_price) * contract_multiplier - fees
+            trade = OptionBacktestTrade(
+                entry_date=str(entry_date.date()),
+                exit_date=str(pd.Timestamp(exit_date).date()),
+                contract_symbol=str(leg["contract_symbol"]),
+                option_type=str(leg["option_type"]),
+                strike=float(leg["strike"]),
+                expiration=str(pd.Timestamp(leg["expiration"]).date()),
+                quantity=1,
+                entry_price=round(entry_price, 4),
+                exit_price=round(exit_price, 4),
+                fees=round(fees, 2),
+                pnl=round(pnl, 2),
+            )
+            pending_group_trades.append(trade)
+            group_pnl += pnl
+
+        if len(pending_group_trades) == 2:
+            trades.extend(pending_group_trades)
+            equity.append(equity[-1] + group_pnl)
+            trade_groups.append(
+                {
+                    "entry_date": str(entry_date.date()),
+                    "exit_date": pending_group_trades[0].exit_date,
+                    "strategy": "long_straddle",
+                    "pnl": round(group_pnl, 2),
+                    "legs": [trade.to_dict() for trade in pending_group_trades],
+                }
+            )
+            next_entry_date = entry_date + timedelta(days=entry_every_days)
+
+    equity_series = pd.Series(equity)
+    group_pnls = [group["pnl"] for group in trade_groups]
+    wins = [pnl for pnl in group_pnls if pnl > 0]
+    losses = [pnl for pnl in group_pnls if pnl <= 0]
+
+    return {
+        "strategy": "long_straddle",
+        "symbol": symbol.upper(),
+        "target_dte": target_dte,
+        "holding_days": holding_days,
+        "entry_every_days": entry_every_days,
+        "contract_multiplier": contract_multiplier,
+        "fee_per_contract": fee_per_contract,
+        "price_field": price_field,
+        "trade_count": len(trade_groups),
+        "leg_trade_count": len(trades),
+        "total_pnl": round(float(equity_series.iloc[-1]), 2) if not equity_series.empty else 0.0,
+        "max_drawdown": round(max_drawdown(equity_series + 100000), 6),
+        "win_rate": len(wins) / len(group_pnls) if group_pnls else 0.0,
+        "avg_win": round(sum(wins) / len(wins), 2) if wins else 0.0,
+        "avg_loss": round(sum(losses) / len(losses), 2) if losses else 0.0,
+        "trades": trade_groups[:200],
+        "data_requirements": [
+            "Historical option quotes with date, expiration, strike, bid, ask, and underlying_price.",
+            "For production-grade backtests, include deltas, IV, volume, open interest, and corporate action adjusted symbols.",
+        ],
+        "limitations": [
+            "No early assignment model yet.",
+            "No margin model yet.",
+            "No intraday fills; entry and exit use the daily quote row.",
+            "Results are only as good as the historical option quote data supplied.",
+        ],
+    }

backtest/tools.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import json
+
+from smolagents import tool
+
+from market_data.providers import get_price_history
+from strategy.payoff import expiration_payoff, strategy_summary
+from strategy.schemas import OptionLeg, OptionStrategy
+
+from .option_backtest import backtest_long_straddle_from_quotes, load_option_quotes_csv
+from .vol_backtest import backtest_realized_vol_signal
+
+
+def parse_legs(legs_json: str) -> list[OptionLeg]:
+    payload = json.loads(legs_json)
+    if isinstance(payload, dict) and "legs" in payload:
+        payload = payload["legs"]
+    return [OptionLeg(**leg) for leg in payload]
+
+
+@tool
+def analyze_strategy_payoff(legs_json: str, min_price: float, max_price: float, steps: int = 25) -> str:
+    """Analyze expiration payoff for an option strategy.
+
+    Args:
+        legs_json: JSON list of option legs from build_volatility_strategy.
+        min_price: Minimum underlying price scenario.
+        max_price: Maximum underlying price scenario.
+        steps: Number of scenario steps.
+    """
+    try:
+        legs = parse_legs(legs_json)
+        points = [
+            min_price + (max_price - min_price) * index / max(steps, 1)
+            for index in range(max(steps, 1) + 1)
+        ]
+        rows = [
+            {"underlying_price": round(price, 2), "pnl": round(expiration_payoff(legs, price), 2)}
+            for price in points
+        ]
+        temp_strategy = OptionStrategy(
+            name="custom_strategy",
+            volatility_view="unknown",
+            directional_view="unknown",
+            legs=legs,
+            rationale="custom payoff analysis",
+            risks=[],
+            max_profit=None,
+            max_loss=None,
+            breakevens=[],
+            net_debit_or_credit=round(sum(leg.premium * leg.signed_quantity() * 100 for leg in legs), 2),
+            score=0.0,
+        )
+        return json.dumps(
+            {
+                "status": "success",
+                "payoff_rows": rows,
+                "payoff_summary": strategy_summary(temp_strategy),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    except Exception as exc:
+        return json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False, indent=2)
+
+
+@tool
+def backtest_volatility_signal(
+    symbol: str,
+    signal: str = "long_vol",
+    period: str = "2y",
+    short_window: int = 10,
+    long_window: int = 30,
+    holding_days: int = 5,
+) -> str:
+    """Backtest a simple realized-volatility expansion/compression signal on the underlying.
+
+    Args:
+        symbol: Yahoo Finance ticker.
+        signal: long_vol or short_vol.
+        period: Yahoo Finance history period.
+        short_window: Short realized volatility lookback.
+        long_window: Long realized volatility lookback.
+        holding_days: Holding period after entry.
+    """
+    try:
+        history = get_price_history(symbol, period=period, interval="1d")
+        result = backtest_realized_vol_signal(
+            history["Close"],
+            short_window=short_window,
+            long_window=long_window,
+            holding_days=holding_days,
+            signal=signal,
+        )
+        return json.dumps({"status": "success", "symbol": symbol.upper(), **result}, ensure_ascii=False, indent=2)
+    except Exception as exc:
+        return json.dumps({"status": "error", "symbol": symbol, "message": str(exc)}, ensure_ascii=False, indent=2)
+
+
+@tool
+def backtest_long_straddle_csv(
+    csv_path: str,
+    symbol: str,
+    target_dte: int = 30,
+    holding_days: int = 5,
+    entry_every_days: int = 5,
+    price_field: str = "trade",
+) -> str:
+    """Run a real option-quote backtest for repeated ATM long straddles.
+
+    This is a true option PnL backtest when supplied with historical option quotes.
+    Required CSV columns: date, underlying_symbol, underlying_price, contract_symbol,
+    option_type, expiration, strike, bid, ask. Optional columns include mid, delta,
+    gamma, theta, vega, implied_volatility, volume, open_interest.
+
+    Args:
+        csv_path: Path to historical option quotes CSV.
+        symbol: Underlying ticker.
+        target_dte: Target days to expiration at entry.
+        holding_days: Number of calendar days to hold each straddle.
+        entry_every_days: Minimum days between new entries.
+        price_field: trade for buy-at-ask/sell-at-bid, or mid for mid-price marks.
+    """
+    try:
+        quotes = load_option_quotes_csv(csv_path)
+        result = backtest_long_straddle_from_quotes(
+            quotes=quotes,
+            symbol=symbol,
+            target_dte=target_dte,
+            holding_days=holding_days,
+            entry_every_days=entry_every_days,
+            price_field=price_field,
+        )
+        return json.dumps({"status": "success", **result}, ensure_ascii=False, indent=2)
+    except Exception as exc:
+        return json.dumps(
+            {
+                "status": "error",
+                "symbol": symbol,
+                "message": str(exc),
+                "note": "A real option backtest requires historical option quote data. yfinance does not provide reliable historical option chains.",
+            },
+            ensure_ascii=False,
+            indent=2,
+        )

backtest/vol_backtest.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import math
+
+import pandas as pd
+
+
+def max_drawdown(equity: pd.Series) -> float:
+    if equity.empty:
+        return 0.0
+    running_max = equity.cummax()
+    drawdown = equity / running_max - 1
+    return float(drawdown.min())
+
+
+def backtest_realized_vol_signal(
+    prices: pd.Series,
+    short_window: int = 10,
+    long_window: int = 30,
+    holding_days: int = 5,
+    signal: str = "long_vol",
+) -> dict:
+    close = prices.dropna().astype(float)
+    returns = close.pct_change().dropna()
+    short_rv = returns.rolling(short_window).std() * math.sqrt(252)
+    long_rv = returns.rolling(long_window).std() * math.sqrt(252)
+
+    trades = []
+    equity = [1.0]
+    index = 0
+    dates = list(returns.index)
+    while index + holding_days < len(returns):
+        current_date = dates[index]
+        if pd.isna(short_rv.iloc[index]) or pd.isna(long_rv.iloc[index]):
+            index += 1
+            equity.append(equity[-1])
+            continue
+
+        vol_expanding = short_rv.iloc[index] > long_rv.iloc[index]
+        enter = vol_expanding if signal == "long_vol" else not vol_expanding
+        if not enter:
+            index += 1
+            equity.append(equity[-1])
+            continue
+
+        period_returns = returns.iloc[index + 1:index + 1 + holding_days]
+        realized_move = float(period_returns.abs().sum())
+        signed_pnl = realized_move if signal == "long_vol" else -realized_move
+        equity.append(equity[-1] * (1 + signed_pnl))
+        trades.append(
+            {
+                "entry_date": str(current_date),
+                "exit_date": str(dates[index + holding_days]),
+                "short_rv": float(short_rv.iloc[index]),
+                "long_rv": float(long_rv.iloc[index]),
+                "realized_abs_move": realized_move,
+                "pnl_proxy": signed_pnl,
+            }
+        )
+        index += holding_days
+
+    equity_series = pd.Series(equity)
+    wins = [trade for trade in trades if trade["pnl_proxy"] > 0]
+    return {
+        "signal": signal,
+        "short_window": short_window,
+        "long_window": long_window,
+        "holding_days": holding_days,
+        "trade_count": len(trades),
+        "win_rate": len(wins) / len(trades) if trades else 0.0,
+        "total_return_proxy": float(equity_series.iloc[-1] - 1) if not equity_series.empty else 0.0,
+        "max_drawdown_proxy": max_drawdown(equity_series),
+        "avg_trade_pnl_proxy": (
+            sum(trade["pnl_proxy"] for trade in trades) / len(trades)
+            if trades
+            else 0.0
+        ),
+        "trades": trades[:100],
+        "limitations": [
+            "This is an underlying-price realized-volatility signal backtest, not a true option PnL backtest.",
+            "It does not use historical option-chain prices, bid/ask spreads, margin, assignment, or delta hedging costs.",
+        ],
+    }

eval/README.md

@@ -58,6 +58,23 @@ The suite writes per-dataset reports and one aggregate report under `eval/report
 
 ## Common Commands
 
+Run with the default multilingual embedding model:
+
+```bash
+uv --cache-dir .uv-cache run python -m eval.run_eval_suite --rebuild
+```
+
+Use a custom embedding model for experiments:
+
+```bash
+RAG_EMBED_MODEL=intfloat/multilingual-e5-base \
+uv --cache-dir .uv-cache run python -m eval.run_eval_suite \
+  --datasets local-options \
+  --top-k 5 \
+  --output-name local_options_e5_base \
+  --rebuild
+```
+
 Run the fastest local check while developing PDF parsing or chunking:
 
 ```bash
@@ -114,6 +131,36 @@ uv --cache-dir .uv-cache run python -m eval.run_eval_suite \
   --rebuild
 ```
 
+Compare retrieval with and without reranker:
+
+```bash
+uv --cache-dir .uv-cache run python -m eval.run_eval_suite \
+  --datasets local-options \
+  --top-k 5 \
+  --output-name local_options_no_reranker \
+  --rebuild
+
+uv --cache-dir .uv-cache run python -m eval.run_eval_suite \
+  --datasets local-options \
+  --top-k 5 \
+  --use-reranker \
+  --reranker-candidates 25 \
+  --output-name local_options_with_reranker \
+  --rebuild
+```
+
+Use a custom reranker model:
+
+```bash
+uv --cache-dir .uv-cache run python -m eval.run_eval_suite \
+  --datasets beir/fiqa \
+  --use-reranker \
+  --reranker-model cross-encoder/ms-marco-MiniLM-L-6-v2 \
+  --reranker-candidates 50 \
+  --top-k 5 \
+  --rebuild
+```
+
 Compare different chunk settings:
 
 ```bash
@@ -169,6 +216,7 @@ uv --cache-dir .uv-cache run python -m eval.rag_eval \
 2. After changing PDF extraction, chunking, embeddings, or retrieval code, add `--rebuild`.
 3. Before comparing two versions, use the same `--datasets`, `--max-queries`, `--max-corpus-docs`, `--top-k`, `--chunk-size`, and `--chunk-overlap`.
 4. Use `--output-name` to save stable report names for before/after comparison.
+5. When testing reranker, compare the same dataset once without `--use-reranker` and once with `--use-reranker`.
 
 ## Metrics
 

eval/generate_local_options_eval.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import argparse
+import json
+import random
+import re
+from pathlib import Path
+from typing import Any
+
+from tools.query_knowledge import RAW_DIR, iter_source_files, load_source_file
+
+
+KEY_TERMS = [
+    "volatility smile",
+    "implied volatility",
+    "local volatility",
+    "stochastic volatility",
+    "Black-Scholes",
+    "delta",
+    "gamma",
+    "vega",
+    "theta",
+    "rho",
+    "skew",
+    "straddle",
+    "correlation",
+    "at-the-money",
+    "forward",
+    "risk-neutral",
+]
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+OUTPUT_PATH = PROJECT_ROOT / "eval" / "local_options_eval.jsonl"
+
+
+def normalize_space(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def extract_keywords(text: str, max_keywords: int = 4) -> list[str]:
+    lowered = text.lower()
+    keywords = [term for term in KEY_TERMS if term.lower() in lowered]
+    equation_ids = re.findall(r"\(\d+\.\d+[a-z]?\)", text)
+    formulas = re.findall(r"[A-Za-z𝜎𝜇𝜌𝜃𝛴][A-Za-z0-9𝜎𝜇𝜌𝜃𝛴_{}^]*\s*=", text)
+    keywords.extend(equation_ids[:2])
+    keywords.extend(item.strip() for item in formulas[:2])
+
+    if not keywords:
+        candidates = [
+            word
+            for word in re.findall(r"[A-Za-z][A-Za-z-]{4,}", text)
+            if word.lower() not in {"there", "where", "which", "would", "could", "should", "chapter"}
+        ]
+        keywords.extend(candidates[:max_keywords])
+
+    deduped = []
+    banned = {"id=", "FORMULA", "value ="}
+    for keyword in keywords:
+        if keyword and keyword not in banned and keyword not in deduped:
+            deduped.append(keyword)
+    return deduped[:max_keywords]
+
+
+def is_sane_section(section: str | None) -> bool:
+    if not section:
+        return False
+    section = section.strip()
+    if not 6 <= len(section) <= 90:
+        return False
+    if section.count(",") >= 2:
+        return False
+    digit_count = sum(char.isdigit() for char in section)
+    letter_count = sum(char.isalpha() for char in section)
+    if digit_count > max(2, letter_count // 3):
+        return False
+    if re.search(r"\b(figure|table|printed|united states|amount unit price|call price|under)$", section, re.I):
+        return False
+    if "figure" in section.lower() or "table" in section.lower():
+        return False
+    if re.search(r"\b(figure|table|printed|united states|amount unit price|call price)\b", section, re.I):
+        return False
+    words = section.split()
+    if len(words) > 12:
+        return False
+    return True
+
+
+def make_case(document: Any, index: int) -> dict[str, Any] | None:
+    metadata = document.metadata
+    text = normalize_space(document.text)
+    if len(text) < 80:
+        return None
+
+    page = metadata.get("page_number")
+    if isinstance(page, int) and (page < 25 or page > 500):
+        return None
+    section = metadata.get("section_path") or metadata.get("section_title")
+    content_type = metadata.get("content_type", "text")
+    formula_id = metadata.get("formula_id")
+    keywords = extract_keywords(text)
+    if not keywords and not section:
+        return None
+
+    if content_type == "formula" or formula_id:
+        question = f"What formula or equation is described on page {page}?"
+        answer_type = "formula"
+    elif is_sane_section(section):
+        question = f"What does the section {section} discuss?"
+        answer_type = "section"
+        keywords.append(section.split(">")[-1].strip())
+    else:
+        if not keywords:
+            return None
+        term = keywords[0]
+        if term.lower() in {"formula", "id=", "value ="}:
+            return None
+        question = f"Where does the options reference discuss {term}?"
+        answer_type = "concept"
+
+    expected_pages = [page] if page is not None else []
+    return {
+        "id": f"auto_options_{index:03d}",
+        "question": question,
+        "expected_pages": expected_pages,
+        "expected_keywords": keywords[:5],
+        "answer_type": answer_type,
+    }
+
+
+def generate_cases(count: int, seed: int) -> list[dict[str, Any]]:
+    documents = []
+    for source_file in iter_source_files(RAW_DIR):
+        documents.extend(load_source_file(source_file))
+
+    random.Random(seed).shuffle(documents)
+    cases = []
+    seen_questions = set()
+    for document in documents:
+        case = make_case(document, len(cases) + 1)
+        if not case:
+            continue
+        if case["question"] in seen_questions:
+            continue
+        seen_questions.add(case["question"])
+        cases.append(case)
+        if len(cases) >= count:
+            break
+
+    if len(cases) < count:
+        raise RuntimeError(f"Only generated {len(cases)} cases; requested {count}.")
+    return cases
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate local options RAG eval cases.")
+    parser.add_argument("--count", type=int, default=40)
+    parser.add_argument("--seed", type=int, default=20260525)
+    parser.add_argument("--output", type=Path, default=OUTPUT_PATH)
+    args = parser.parse_args()
+
+    cases = generate_cases(args.count, args.seed)
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(
+        "\n".join(json.dumps(case, ensure_ascii=False) for case in cases) + "\n",
+        encoding="utf-8",
+    )
+    print(f"Wrote {len(cases)} cases to {args.output}")
+
+
+if __name__ == "__main__":
+    main()

eval/rag_eval.py

@@ -4,6 +4,7 @@ import argparse
 import csv
 import json
 import math
+import re
 import shutil
 import zipfile
 from dataclasses import dataclass
@@ -15,9 +16,17 @@ import requests
 from llama_index.core import StorageContext, VectorStoreIndex
 from llama_index.core.node_parser import SentenceSplitter
 from llama_index.core.schema import Document
+from llama_index.core.schema import NodeWithScore, TextNode
 from llama_index.vector_stores.chroma import ChromaVectorStore
 
-from tools.query_knowledge import configure_model_cache, resolve_embed_model_name
+from tools.query_knowledge import (
+    BM25Retriever,
+    EMBED_MODEL_NAME,
+    RERANKER_MODEL_NAME,
+    CrossEncoderReranker,
+    configure_model_cache,
+    resolve_embed_model_name,
+)
 
 
 PROJECT_ROOT = Path(__file__).resolve().parents[1]
@@ -387,7 +396,9 @@ def load_local_options_eval(max_queries: int | None) -> EvalCorpus:
 
     from tools.query_knowledge import load_pdf_file
 
-    pdf_files = sorted((PROJECT_ROOT / "tools" / "knowledge_base" / "raw").rglob("*.pdf"))
+    pdf_files = sorted((PROJECT_ROOT / "knowledge_base" / "raw").rglob("*.pdf"))
+    if not pdf_files:
+        pdf_files = sorted((PROJECT_ROOT / "tools" / "knowledge_base" / "raw").rglob("*.pdf"))
     documents = []
     for pdf_file in pdf_files:
         for doc_index, document in enumerate(load_pdf_file(pdf_file)):
@@ -443,6 +454,11 @@ def load_eval_corpus(args: argparse.Namespace) -> EvalCorpus:
     raise ValueError(f"Unknown dataset: {args.dataset}")
 
 
+def collection_safe_name(value: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9_-]+", "_", value)
+    return safe.strip("_") or "default"
+
+
 def build_index(corpus: EvalCorpus, chunk_size: int, chunk_overlap: int, rebuild: bool) -> VectorStoreIndex:
     configure_model_cache()
     from llama_index.embeddings.huggingface import HuggingFaceEmbedding
@@ -453,7 +469,8 @@ def build_index(corpus: EvalCorpus, chunk_size: int, chunk_overlap: int, rebuild
     index_path.mkdir(parents=True, exist_ok=True)
 
     db = chromadb.PersistentClient(path=str(index_path))
-    collection_name = f"{corpus.name}_eval"
+    embed_slug = collection_safe_name(EMBED_MODEL_NAME)
+    collection_name = f"{corpus.name}_{embed_slug}_eval"
     if rebuild:
         try:
             db.delete_collection(collection_name)
@@ -464,7 +481,7 @@ def build_index(corpus: EvalCorpus, chunk_size: int, chunk_overlap: int, rebuild
     storage_context = StorageContext.from_defaults(vector_store=vector_store)
     embed_model = HuggingFaceEmbedding(
         model_name=resolve_embed_model_name(),
-        cache_folder=str(PROJECT_ROOT / "tools" / "hf_cache" / "sentence_transformers"),
+        cache_folder=str(PROJECT_ROOT / "hf_cache" / "sentence_transformers"),
     )
 
     if collection.count() == 0:
@@ -491,8 +508,70 @@ def build_index(corpus: EvalCorpus, chunk_size: int, chunk_overlap: int, rebuild
     return VectorStoreIndex.from_vector_store(vector_store, embed_model=embed_model)
 
 
-def evaluate_retrieval(corpus: EvalCorpus, index: VectorStoreIndex, top_k: int) -> dict[str, Any]:
-    retriever = index.as_retriever(similarity_top_k=max(top_k * 5, top_k))
+def build_bm25_retriever(corpus: EvalCorpus, chunk_size: int, chunk_overlap: int) -> BM25Retriever:
+    documents = [
+        Document(
+            text=document["text"],
+            metadata={
+                "doc_id": document["doc_id"],
+                "title": document.get("title", ""),
+                **(document.get("metadata") or {}),
+            },
+        )
+        for document in corpus.documents
+    ]
+    splitter = SentenceSplitter(chunk_size=chunk_size, chunk_overlap=chunk_overlap)
+    nodes = splitter.get_nodes_from_documents(documents)
+    text_nodes = [
+        TextNode(id_=node.node_id, text=node.get_content(), metadata=node.metadata)
+        for node in nodes
+    ]
+    return BM25Retriever(text_nodes)
+
+
+def merge_eval_results(
+    vector_results: list[NodeWithScore],
+    bm25_results: list[NodeWithScore],
+    top_k: int,
+) -> list[NodeWithScore]:
+    merged: dict[str, NodeWithScore] = {}
+
+    for rank, result in enumerate(vector_results):
+        node_id = result.node.node_id
+        merged[node_id] = NodeWithScore(node=result.node, score=1.0 / (rank + 1))
+
+    for rank, result in enumerate(bm25_results):
+        node_id = result.node.node_id
+        reciprocal_rank_score = 1.0 / (rank + 1)
+        if node_id in merged:
+            merged[node_id].score = (merged[node_id].score or 0.0) + reciprocal_rank_score
+        else:
+            merged[node_id] = NodeWithScore(node=result.node, score=reciprocal_rank_score)
+
+    results = list(merged.values())
+    results.sort(key=lambda item: item.score or float("-inf"), reverse=True)
+    return results[:top_k]
+
+
+def evaluate_retrieval(
+    corpus: EvalCorpus,
+    index: VectorStoreIndex,
+    top_k: int,
+    use_reranker: bool = False,
+    use_hybrid: bool = False,
+    chunk_size: int = 512,
+    chunk_overlap: int = 64,
+    reranker_model_name: str = RERANKER_MODEL_NAME,
+    reranker_candidates: int = 25,
+) -> dict[str, Any]:
+    retrieve_top_k = max(reranker_candidates, top_k) if use_reranker else max(top_k * 5, top_k)
+    retriever = index.as_retriever(similarity_top_k=retrieve_top_k)
+    bm25_retriever = (
+        build_bm25_retriever(corpus, chunk_size, chunk_overlap)
+        if use_hybrid
+        else None
+    )
+    reranker = CrossEncoderReranker(reranker_model_name) if use_reranker else None
     cases = []
     hit_counts = {1: 0, 3: 0, 5: 0, top_k: 0}
     reciprocal_ranks = []
@@ -500,7 +579,17 @@ def evaluate_retrieval(corpus: EvalCorpus, index: VectorStoreIndex, top_k: int)
 
     for query in corpus.queries:
         relevant_doc_ids = corpus.qrels.get(query["query_id"], set())
-        results = retriever.retrieve(query["question"])
+        vector_results = retriever.retrieve(query["question"])
+        results = vector_results
+        if bm25_retriever:
+            bm25_results = bm25_retriever.retrieve(query["question"], retrieve_top_k)
+            results = merge_eval_results(vector_results, bm25_results, retrieve_top_k)
+        if reranker:
+            results = reranker.rerank(
+                query["question"],
+                results,
+                top_n=max(top_k * 5, top_k),
+            )
         retrieved = []
         seen_doc_ids = set()
         first_hit_rank = None
@@ -557,6 +646,8 @@ def evaluate_retrieval(corpus: EvalCorpus, index: VectorStoreIndex, top_k: int)
         "top_k": top_k,
         "mrr": sum(reciprocal_ranks) / total if total else 0.0,
         "ndcg_at_k": sum(ndcg_scores) / total if total else 0.0,
+        "reranker_enabled": use_reranker,
+        "hybrid_enabled": use_hybrid,
     }
     for k, count in sorted(hit_counts.items()):
         metrics[f"hit_at_{k}"] = count / total if total else 0.0
@@ -612,6 +703,10 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--max-corpus-docs", type=int, default=None)
     parser.add_argument("--max-queries", type=int, default=None)
     parser.add_argument("--rebuild", action="store_true")
+    parser.add_argument("--use-hybrid", action="store_true")
+    parser.add_argument("--use-reranker", action="store_true")
+    parser.add_argument("--reranker-model", default=RERANKER_MODEL_NAME)
+    parser.add_argument("--reranker-candidates", type=int, default=25)
     return parser.parse_args()
 
 
@@ -619,7 +714,17 @@ def main() -> None:
     args = parse_args()
     corpus = load_eval_corpus(args)
     index = build_index(corpus, args.chunk_size, args.chunk_overlap, args.rebuild)
-    report = evaluate_retrieval(corpus, index, args.top_k)
+    report = evaluate_retrieval(
+        corpus,
+        index,
+        args.top_k,
+        use_reranker=args.use_reranker,
+        use_hybrid=args.use_hybrid,
+        chunk_size=args.chunk_size,
+        chunk_overlap=args.chunk_overlap,
+        reranker_model_name=args.reranker_model,
+        reranker_candidates=args.reranker_candidates,
+    )
     json_path, md_path = write_reports(report)
     print(json.dumps(report["metrics"], ensure_ascii=False, indent=2))
     print(f"JSON report: {json_path}")

eval/run_eval_suite.py

@@ -57,6 +57,10 @@ def build_dataset_args(args: argparse.Namespace, dataset: str) -> SimpleNamespac
         else defaults["max_corpus_docs"],
         max_queries=args.max_queries if args.max_queries is not None else defaults["max_queries"],
         rebuild=args.rebuild,
+        use_hybrid=args.use_hybrid,
+        use_reranker=args.use_reranker,
+        reranker_model=args.reranker_model,
+        reranker_candidates=args.reranker_candidates,
     )
 
 
@@ -65,7 +69,9 @@ def run_one(dataset: str, args: argparse.Namespace) -> DatasetRun:
     print(
         f"\n=== Running {dataset} "
         f"(top_k={dataset_args.top_k}, max_corpus_docs={dataset_args.max_corpus_docs}, "
-        f"max_queries={dataset_args.max_queries}, rebuild={dataset_args.rebuild}) ==="
+        f"max_queries={dataset_args.max_queries}, rebuild={dataset_args.rebuild}, "
+        f"use_hybrid={dataset_args.use_hybrid}, "
+        f"use_reranker={dataset_args.use_reranker}) ==="
     )
 
     corpus = load_eval_corpus(dataset_args)
@@ -75,7 +81,17 @@ def run_one(dataset: str, args: argparse.Namespace) -> DatasetRun:
         chunk_overlap=dataset_args.chunk_overlap,
         rebuild=dataset_args.rebuild,
     )
-    report = evaluate_retrieval(corpus, index, dataset_args.top_k)
+    report = evaluate_retrieval(
+        corpus,
+        index,
+        dataset_args.top_k,
+        use_hybrid=dataset_args.use_hybrid,
+        chunk_size=dataset_args.chunk_size,
+        chunk_overlap=dataset_args.chunk_overlap,
+        use_reranker=dataset_args.use_reranker,
+        reranker_model_name=dataset_args.reranker_model,
+        reranker_candidates=dataset_args.reranker_candidates,
+    )
     json_path, md_path = write_reports(report)
     print(json.dumps(report["metrics"], ensure_ascii=False, indent=2))
 
@@ -132,6 +148,10 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--max-corpus-docs", type=int, default=None)
     parser.add_argument("--max-queries", type=int, default=None)
     parser.add_argument("--rebuild", action="store_true")
+    parser.add_argument("--use-hybrid", action="store_true")
+    parser.add_argument("--use-reranker", action="store_true")
+    parser.add_argument("--reranker-model", default="cross-encoder/ms-marco-MiniLM-L-6-v2")
+    parser.add_argument("--reranker-candidates", type=int, default=25)
     parser.add_argument("--fail-fast", action="store_true")
     parser.add_argument("--output-name", default=None, help="Suite report filename stem under eval/reports.")
     return parser.parse_args()

market_data/__init__.py

@@ -0,0 +1,30 @@
+from .analytics import (
+    black_scholes_greeks,
+    classify_volatility_regime,
+    rank_current_iv_against_rv,
+    realized_volatility,
+    summarize_option_chain,
+)
+from .providers import (
+    get_current_quote,
+    get_option_chain,
+    get_price_history,
+    list_option_expirations,
+)
+from .schemas import OptionChain, OptionContract, UnderlyingQuote, VolSnapshot
+
+__all__ = [
+    "black_scholes_greeks",
+    "classify_volatility_regime",
+    "get_current_quote",
+    "get_option_chain",
+    "get_price_history",
+    "list_option_expirations",
+    "OptionChain",
+    "OptionContract",
+    "realized_volatility",
+    "rank_current_iv_against_rv",
+    "summarize_option_chain",
+    "UnderlyingQuote",
+    "VolSnapshot",
+]

market_data/analytics.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import math
+from statistics import NormalDist
+
+import pandas as pd
+
+from .schemas import OptionChain
+
+
+NORMAL = NormalDist()
+
+
+def realized_volatility(
+    prices: pd.Series,
+    windows: tuple[int, ...] = (5, 10, 20, 30, 60),
+    trading_days: int = 252,
+) -> dict[str, float | None]:
+    close = prices.dropna().astype(float)
+    returns = close.pct_change().dropna()
+    output: dict[str, float | None] = {}
+
+    for window in windows:
+        key = f"{window}d"
+        if len(returns) < window:
+            output[key] = None
+            continue
+        output[key] = float(returns.tail(window).std(ddof=1) * math.sqrt(trading_days))
+
+    return output
+
+
+def _norm_pdf(value: float) -> float:
+    return math.exp(-0.5 * value * value) / math.sqrt(2 * math.pi)
+
+
+def black_scholes_greeks(
+    spot: float,
+    strike: float,
+    time_to_expiry: float,
+    volatility: float,
+    risk_free_rate: float = 0.0,
+    dividend_yield: float = 0.0,
+    option_type: str = "call",
+) -> dict[str, float | None]:
+    if spot <= 0 or strike <= 0 or time_to_expiry <= 0 or volatility <= 0:
+        return {
+            "delta": None,
+            "gamma": None,
+            "vega": None,
+            "theta": None,
+            "rho": None,
+        }
+
+    sqrt_t = math.sqrt(time_to_expiry)
+    d1 = (
+        math.log(spot / strike)
+        + (risk_free_rate - dividend_yield + 0.5 * volatility * volatility) * time_to_expiry
+    ) / (volatility * sqrt_t)
+    d2 = d1 - volatility * sqrt_t
+    discount_dividend = math.exp(-dividend_yield * time_to_expiry)
+    discount_rate = math.exp(-risk_free_rate * time_to_expiry)
+    option_type = option_type.lower()
+
+    if option_type == "put":
+        delta = discount_dividend * (NORMAL.cdf(d1) - 1)
+        theta = (
+            -spot * discount_dividend * _norm_pdf(d1) * volatility / (2 * sqrt_t)
+            + dividend_yield * spot * discount_dividend * NORMAL.cdf(-d1)
+            - risk_free_rate * strike * discount_rate * NORMAL.cdf(-d2)
+        ) / 365
+        rho = -strike * time_to_expiry * discount_rate * NORMAL.cdf(-d2) / 100
+    else:
+        delta = discount_dividend * NORMAL.cdf(d1)
+        theta = (
+            -spot * discount_dividend * _norm_pdf(d1) * volatility / (2 * sqrt_t)
+            - dividend_yield * spot * discount_dividend * NORMAL.cdf(d1)
+            + risk_free_rate * strike * discount_rate * NORMAL.cdf(d2)
+        ) / 365
+        rho = strike * time_to_expiry * discount_rate * NORMAL.cdf(d2) / 100
+
+    gamma = discount_dividend * _norm_pdf(d1) / (spot * volatility * sqrt_t)
+    vega = spot * discount_dividend * _norm_pdf(d1) * sqrt_t / 100
+
+    return {
+        "delta": float(delta),
+        "gamma": float(gamma),
+        "vega": float(vega),
+        "theta": float(theta),
+        "rho": float(rho),
+    }
+
+
+def nearest_atm_iv(chain: OptionChain) -> float | None:
+    if chain.underlying_price is None:
+        return None
+    contracts = chain.calls + chain.puts
+    valid = [
+        contract
+        for contract in contracts
+        if contract.implied_volatility is not None and contract.implied_volatility > 0
+    ]
+    if not valid:
+        return None
+    nearest = min(valid, key=lambda contract: abs(contract.strike - chain.underlying_price))
+    return nearest.implied_volatility
+
+
+def simple_skew(chain: OptionChain) -> float | None:
+    if chain.underlying_price is None:
+        return None
+    otm_puts = [
+        contract
+        for contract in chain.puts
+        if contract.strike < chain.underlying_price and contract.implied_volatility
+    ]
+    otm_calls = [
+        contract
+        for contract in chain.calls
+        if contract.strike > chain.underlying_price and contract.implied_volatility
+    ]
+    if not otm_puts or not otm_calls:
+        return None
+    put = max(otm_puts, key=lambda contract: contract.strike)
+    call = min(otm_calls, key=lambda contract: contract.strike)
+    return float((put.implied_volatility or 0) - (call.implied_volatility or 0))
+
+
+def summarize_option_chain(chain: OptionChain, realized_vol_20d: float | None = None) -> dict:
+    atm_iv = nearest_atm_iv(chain)
+    return {
+        "symbol": chain.symbol,
+        "expiration": chain.expiration,
+        "underlying_price": chain.underlying_price,
+        "atm_iv": atm_iv,
+        "iv_rv_spread_20d": (
+            float(atm_iv - realized_vol_20d)
+            if atm_iv is not None and realized_vol_20d is not None
+            else None
+        ),
+        "skew_put_minus_call": simple_skew(chain),
+        "call_count": len(chain.calls),
+        "put_count": len(chain.puts),
+    }
+
+
+def rank_current_iv_against_rv(
+    current_iv: float | None,
+    realized_vols: dict[str, float | None],
+) -> float | None:
+    if current_iv is None:
+        return None
+    rv_values = [value for value in realized_vols.values() if value is not None]
+    if len(rv_values) < 2:
+        return None
+    low = min(rv_values)
+    high = max(rv_values)
+    if high <= low:
+        return None
+    return max(0.0, min(1.0, (current_iv - low) / (high - low)))
+
+
+def classify_volatility_regime(
+    current_iv: float | None,
+    realized_vol_20d: float | None,
+    term_structure_slope: float | None,
+    skew: float | None,
+) -> dict:
+    if current_iv is None or realized_vol_20d is None:
+        return {
+            "regime": "unknown",
+            "vol_signal": "insufficient_iv_or_rv",
+            "confidence": "low",
+            "notes": ["Need both option implied volatility and realized volatility."],
+        }
+
+    iv_rv_spread = current_iv - realized_vol_20d
+    notes = []
+    if iv_rv_spread > 0.08:
+        regime = "high_implied_vol_premium"
+        vol_signal = "short_vol_candidate"
+        notes.append("Current ATM IV is materially above 20D realized volatility.")
+    elif iv_rv_spread < -0.04:
+        regime = "low_implied_vol_discount"
+        vol_signal = "long_vol_candidate"
+        notes.append("Current ATM IV is below 20D realized volatility.")
+    else:
+        regime = "balanced_iv_vs_rv"
+        vol_signal = "neutral_vol"
+        notes.append("Current ATM IV is close to 20D realized volatility.")
+
+    if term_structure_slope is not None:
+        if term_structure_slope > 0.04:
+            notes.append("Term structure is upward sloping.")
+        elif term_structure_slope < -0.04:
+            notes.append("Term structure is inverted or front-loaded.")
+    if skew is not None and abs(skew) > 0.05:
+        notes.append("Put-call skew is elevated in the sampled expiration.")
+
+    confidence = "medium" if len(notes) >= 2 else "low"
+    return {
+        "regime": regime,
+        "vol_signal": vol_signal,
+        "confidence": confidence,
+        "notes": notes,
+    }

market_data/providers.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any
+
+import pandas as pd
+import yfinance as yf
+
+from .schemas import OptionChain, OptionContract, UnderlyingQuote
+
+
+def none_if_nan(value: Any) -> Any:
+    if pd.isna(value):
+        return None
+    return value
+
+
+def to_float(value: Any) -> float | None:
+    value = none_if_nan(value)
+    return float(value) if value is not None else None
+
+
+def to_int(value: Any) -> int | None:
+    value = none_if_nan(value)
+    return int(value) if value is not None else None
+
+
+def get_price_history(
+    symbol: str,
+    period: str = "1y",
+    interval: str = "1d",
+    start: str | None = None,
+    end: str | None = None,
+) -> pd.DataFrame:
+    ticker = yf.Ticker(symbol.strip().upper())
+    return ticker.history(period=period, interval=interval, start=start, end=end)
+
+
+def get_current_quote(symbol: str) -> UnderlyingQuote:
+    symbol = symbol.strip().upper()
+    ticker = yf.Ticker(symbol)
+    data = ticker.history(period="1d", interval="1m")
+
+    if not data.empty:
+        latest_row = data.iloc[-1]
+        return UnderlyingQuote(
+            symbol=symbol,
+            current_price=float(latest_row["Close"]),
+            open=float(latest_row["Open"]),
+            high=float(latest_row["High"]),
+            low=float(latest_row["Low"]),
+            volume=int(latest_row["Volume"]),
+            timestamp=str(data.index[-1]),
+            data_type="intraday_1m",
+        )
+
+    info = ticker.info
+    current_price = (
+        info.get("regularMarketPrice")
+        or info.get("previousClose")
+        or info.get("ask")
+        or info.get("bid")
+    )
+    return UnderlyingQuote(
+        symbol=symbol,
+        current_price=float(current_price) if current_price else None,
+        open=to_float(info.get("regularMarketOpen") or info.get("open")),
+        high=to_float(info.get("regularMarketDayHigh") or info.get("dayHigh")),
+        low=to_float(info.get("regularMarketDayLow") or info.get("dayLow")),
+        volume=to_int(info.get("regularMarketVolume") or info.get("volume")),
+        timestamp=datetime.utcnow().isoformat(timespec="seconds"),
+        data_type="cached_info",
+        short_name=info.get("shortName", ""),
+    )
+
+
+def list_option_expirations(symbol: str) -> list[str]:
+    ticker = yf.Ticker(symbol.strip().upper())
+    return list(ticker.options or [])
+
+
+def liquidity_warnings(row: pd.Series) -> list[str]:
+    warnings = []
+    bid = to_float(row.get("bid"))
+    ask = to_float(row.get("ask"))
+    volume = to_int(row.get("volume")) or 0
+    open_interest = to_int(row.get("openInterest")) or 0
+
+    if bid is None or ask is None or bid <= 0 or ask <= 0:
+        warnings.append("missing_or_zero_bid_ask")
+    elif ask > 0 and (ask - bid) / ask > 0.25:
+        warnings.append("wide_bid_ask_spread")
+    if volume <= 0:
+        warnings.append("zero_volume")
+    if open_interest <= 0:
+        warnings.append("zero_open_interest")
+    return warnings
+
+
+def row_to_contract(row: pd.Series, option_type: str, expiration: str) -> OptionContract:
+    bid = to_float(row.get("bid"))
+    ask = to_float(row.get("ask"))
+    mid = (bid + ask) / 2 if bid is not None and ask is not None and bid > 0 and ask > 0 else None
+    days_to_expiration = max((date.fromisoformat(expiration) - date.today()).days, 0)
+
+    return OptionContract(
+        contract_symbol=str(row.get("contractSymbol", "")),
+        option_type=option_type,
+        expiration=expiration,
+        strike=float(row.get("strike")),
+        bid=bid,
+        ask=ask,
+        mid=mid,
+        last_price=to_float(row.get("lastPrice")),
+        volume=to_int(row.get("volume")),
+        open_interest=to_int(row.get("openInterest")),
+        implied_volatility=to_float(row.get("impliedVolatility")),
+        in_the_money=bool(row.get("inTheMoney", False)),
+        days_to_expiration=days_to_expiration,
+        liquidity_warnings=liquidity_warnings(row),
+    )
+
+
+def get_option_chain(symbol: str, expiration: str | None = None) -> OptionChain:
+    symbol = symbol.strip().upper()
+    ticker = yf.Ticker(symbol)
+    expirations = list(ticker.options or [])
+    if not expirations:
+        raise ValueError(f"No option expirations found for {symbol}.")
+    expiration = expiration or expirations[0]
+    if expiration not in expirations:
+        raise ValueError(f"Expiration {expiration} is not available for {symbol}.")
+
+    chain = ticker.option_chain(expiration)
+    quote = get_current_quote(symbol)
+    calls = [row_to_contract(row, "call", expiration) for _, row in chain.calls.iterrows()]
+    puts = [row_to_contract(row, "put", expiration) for _, row in chain.puts.iterrows()]
+    return OptionChain(
+        symbol=symbol,
+        expiration=expiration,
+        underlying_price=quote.current_price,
+        calls=calls,
+        puts=puts,
+    )

market_data/schemas.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass
+class UnderlyingQuote:
+    symbol: str
+    current_price: float | None
+    open: float | None
+    high: float | None
+    low: float | None
+    volume: int | None
+    timestamp: str
+    data_type: str
+    short_name: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class OptionContract:
+    contract_symbol: str
+    option_type: str
+    expiration: str
+    strike: float
+    bid: float | None
+    ask: float | None
+    mid: float | None
+    last_price: float | None
+    volume: int | None
+    open_interest: int | None
+    implied_volatility: float | None
+    in_the_money: bool
+    days_to_expiration: int
+    liquidity_warnings: list[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class OptionChain:
+    symbol: str
+    expiration: str
+    underlying_price: float | None
+    calls: list[OptionContract]
+    puts: list[OptionContract]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "symbol": self.symbol,
+            "expiration": self.expiration,
+            "underlying_price": self.underlying_price,
+            "calls": [contract.to_dict() for contract in self.calls],
+            "puts": [contract.to_dict() for contract in self.puts],
+        }
+
+
+@dataclass
+class VolSnapshot:
+    symbol: str
+    current_price: float | None
+    realized_volatility: dict[str, float | None]
+    atm_iv_by_expiration: dict[str, float | None]
+    iv_rv_spread_by_expiration: dict[str, float | None]
+    term_structure_slope: float | None
+    skew_by_expiration: dict[str, float | None]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

market_data/tools.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import json
+
+from smolagents import tool
+
+from .analytics import (
+    black_scholes_greeks,
+    classify_volatility_regime,
+    rank_current_iv_against_rv,
+    realized_volatility,
+    summarize_option_chain,
+)
+from .providers import get_current_quote, get_option_chain, get_price_history, list_option_expirations
+from .schemas import VolSnapshot
+
+
+def json_dumps(payload) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2, default=str)
+
+
+@tool
+def query_market_asset(symbol: str) -> str:
+    """Query the current price and intraday quote data for an asset.
+
+    Args:
+        symbol: Yahoo Finance ticker, e.g. AAPL, SPY, ^VIX, BTC-USD, EURUSD=X.
+    """
+    try:
+        return json_dumps({"status": "success", **get_current_quote(symbol).to_dict()})
+    except Exception as exc:
+        return json_dumps({"status": "error", "symbol": symbol, "message": str(exc)})
+
+
+@tool
+def query_price_history(symbol: str, period: str = "1y", interval: str = "1d") -> str:
+    """Query historical OHLCV prices for an asset.
+
+    Args:
+        symbol: Yahoo Finance ticker.
+        period: Yahoo Finance period such as 1mo, 6mo, 1y, 5y.
+        interval: Yahoo Finance interval such as 1d, 1h, 15m.
+    """
+    try:
+        history = get_price_history(symbol, period=period, interval=interval)
+        records = history.tail(20).reset_index().to_dict(orient="records")
+        return json_dumps(
+            {
+                "status": "success",
+                "symbol": symbol.upper(),
+                "period": period,
+                "interval": interval,
+                "rows_returned": len(records),
+                "latest_rows": records,
+            }
+        )
+    except Exception as exc:
+        return json_dumps({"status": "error", "symbol": symbol, "message": str(exc)})
+
+
+@tool
+def query_realized_volatility(symbol: str, period: str = "1y") -> str:
+    """Calculate realized volatility windows from historical close prices.
+
+    Args:
+        symbol: Yahoo Finance ticker.
+        period: Yahoo Finance history period.
+    """
+    try:
+        history = get_price_history(symbol, period=period, interval="1d")
+        rv = realized_volatility(history["Close"])
+        return json_dumps({"status": "success", "symbol": symbol.upper(), "realized_volatility": rv})
+    except Exception as exc:
+        return json_dumps({"status": "error", "symbol": symbol, "message": str(exc)})
+
+
+@tool
+def query_option_expirations(symbol: str) -> str:
+    """List available option expiration dates for an underlying.
+
+    Args:
+        symbol: Yahoo Finance ticker.
+    """
+    try:
+        expirations = list_option_expirations(symbol)
+        return json_dumps({"status": "success", "symbol": symbol.upper(), "expirations": expirations})
+    except Exception as exc:
+        return json_dumps({"status": "error", "symbol": symbol, "message": str(exc)})
+
+
+@tool
+def query_option_chain(symbol: str, expiration: str = "") -> str:
+    """Query an option chain with liquidity warnings and implied volatility.
+
+    Args:
+        symbol: Yahoo Finance ticker.
+        expiration: Expiration date in YYYY-MM-DD. Leave empty to use the nearest expiration.
+    """
+    try:
+        chain = get_option_chain(symbol, expiration or None)
+        summary = summarize_option_chain(chain)
+        payload = chain.to_dict()
+        payload["summary"] = summary
+        payload["calls"] = payload["calls"][:80]
+        payload["puts"] = payload["puts"][:80]
+        return json_dumps({"status": "success", **payload})
+    except Exception as exc:
+        return json_dumps({"status": "error", "symbol": symbol, "message": str(exc)})
+
+
+@tool
+def query_volatility_snapshot(symbol: str, max_expirations: int = 4, history_period: str = "1y") -> str:
+    """Summarize realized volatility, ATM IV, IV-RV spread, skew, and term structure.
+
+    Args:
+        symbol: Yahoo Finance ticker.
+        max_expirations: Number of expirations to sample from the option chain.
+        history_period: Yahoo Finance history period for realized volatility.
+    """
+    try:
+        symbol = symbol.strip().upper()
+        quote = get_current_quote(symbol)
+        history = get_price_history(symbol, period=history_period, interval="1d")
+        rv = realized_volatility(history["Close"])
+        rv_20d = rv.get("20d")
+        expirations = list_option_expirations(symbol)[:max_expirations]
+
+        atm_iv_by_expiration = {}
+        iv_rv_spread_by_expiration = {}
+        skew_by_expiration = {}
+        for expiration in expirations:
+            chain = get_option_chain(symbol, expiration)
+            summary = summarize_option_chain(chain, realized_vol_20d=rv_20d)
+            atm_iv_by_expiration[expiration] = summary["atm_iv"]
+            iv_rv_spread_by_expiration[expiration] = summary["iv_rv_spread_20d"]
+            skew_by_expiration[expiration] = summary["skew_put_minus_call"]
+
+        valid_term_ivs = [
+            value
+            for value in atm_iv_by_expiration.values()
+            if value is not None
+        ]
+        current_atm_iv = valid_term_ivs[0] if valid_term_ivs else None
+        sampled_skews = [value for value in skew_by_expiration.values() if value is not None]
+        front_skew = sampled_skews[0] if sampled_skews else None
+        term_structure_slope = (
+            float(valid_term_ivs[-1] - valid_term_ivs[0])
+            if len(valid_term_ivs) >= 2
+            else None
+        )
+        regime = classify_volatility_regime(
+            current_iv=current_atm_iv,
+            realized_vol_20d=rv_20d,
+            term_structure_slope=term_structure_slope,
+            skew=front_skew,
+        )
+        snapshot = VolSnapshot(
+            symbol=symbol,
+            current_price=quote.current_price,
+            realized_volatility=rv,
+            atm_iv_by_expiration=atm_iv_by_expiration,
+            iv_rv_spread_by_expiration=iv_rv_spread_by_expiration,
+            term_structure_slope=term_structure_slope,
+            skew_by_expiration=skew_by_expiration,
+        )
+        return json_dumps(
+            {
+                "status": "success",
+                **snapshot.to_dict(),
+                "front_atm_iv": current_atm_iv,
+                "front_skew": front_skew,
+                "iv_vs_rv_rank_proxy": rank_current_iv_against_rv(current_atm_iv, rv),
+                "volatility_regime": regime,
+                "limitations": [
+                    "IV rank/percentile is a proxy based on current ATM IV versus realized-volatility windows.",
+                    "True historical IV rank requires historical option-chain data from a richer provider.",
+                ],
+            }
+        )
+    except Exception as exc:
+        return json_dumps({"status": "error", "symbol": symbol, "message": str(exc)})
+
+
+@tool
+def calculate_option_greeks(
+    spot: float,
+    strike: float,
+    time_to_expiry: float,
+    volatility: float,
+    option_type: str = "call",
+    risk_free_rate: float = 0.0,
+    dividend_yield: float = 0.0,
+) -> str:
+    """Calculate Black-Scholes-Merton Greeks for a single option.
+
+    Args:
+        spot: Current underlying price.
+        strike: Option strike.
+        time_to_expiry: Time to expiration in years.
+        volatility: Annualized implied volatility as a decimal.
+        option_type: call or put.
+        risk_free_rate: Annualized risk-free rate as a decimal.
+        dividend_yield: Annualized dividend yield as a decimal.
+    """
+    greeks = black_scholes_greeks(
+        spot=spot,
+        strike=strike,
+        time_to_expiry=time_to_expiry,
+        volatility=volatility,
+        risk_free_rate=risk_free_rate,
+        dividend_yield=dividend_yield,
+        option_type=option_type,
+    )
+    return json_dumps({"status": "success", "greeks": greeks})

optimizer/__init__.py

@@ -0,0 +1,3 @@
+from .vol_optimizer import optimize_volatility_signal
+
+__all__ = ["optimize_volatility_signal"]

optimizer/tools.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import json
+
+from smolagents import tool
+
+from market_data.providers import get_price_history
+
+from .vol_optimizer import optimize_volatility_signal
+
+
+@tool
+def optimize_volatility_signal_parameters(
+    symbol: str,
+    signal: str = "long_vol",
+    period: str = "3y",
+) -> str:
+    """Scan simple realized-volatility signal parameters and compare best vs baseline.
+
+    Args:
+        symbol: Yahoo Finance ticker.
+        signal: long_vol or short_vol.
+        period: Yahoo Finance history period.
+    """
+    try:
+        history = get_price_history(symbol, period=period, interval="1d")
+        result = optimize_volatility_signal(history["Close"], signal=signal)
+        return json.dumps({"status": "success", "symbol": symbol.upper(), **result}, ensure_ascii=False, indent=2)
+    except Exception as exc:
+        return json.dumps({"status": "error", "symbol": symbol, "message": str(exc)}, ensure_ascii=False, indent=2)

optimizer/vol_optimizer.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import pandas as pd
+
+from backtest.vol_backtest import backtest_realized_vol_signal
+
+
+def optimize_volatility_signal(
+    prices: pd.Series,
+    signal: str = "long_vol",
+    short_windows: tuple[int, ...] = (5, 10, 15),
+    long_windows: tuple[int, ...] = (20, 30, 60),
+    holding_days_options: tuple[int, ...] = (3, 5, 10),
+) -> dict:
+    runs = []
+    for short_window in short_windows:
+        for long_window in long_windows:
+            if short_window >= long_window:
+                continue
+            for holding_days in holding_days_options:
+                result = backtest_realized_vol_signal(
+                    prices=prices,
+                    short_window=short_window,
+                    long_window=long_window,
+                    holding_days=holding_days,
+                    signal=signal,
+                )
+                runs.append(
+                    {
+                        "short_window": short_window,
+                        "long_window": long_window,
+                        "holding_days": holding_days,
+                        "trade_count": result["trade_count"],
+                        "win_rate": result["win_rate"],
+                        "total_return_proxy": result["total_return_proxy"],
+                        "max_drawdown_proxy": result["max_drawdown_proxy"],
+                        "avg_trade_pnl_proxy": result["avg_trade_pnl_proxy"],
+                    }
+                )
+
+    runs.sort(
+        key=lambda run: (
+            run["total_return_proxy"],
+            -abs(run["max_drawdown_proxy"]),
+            run["win_rate"],
+        ),
+        reverse=True,
+    )
+    best = runs[0] if runs else None
+    baseline = next(
+        (
+            run
+            for run in runs
+            if run["short_window"] == 10 and run["long_window"] == 30 and run["holding_days"] == 5
+        ),
+        runs[0] if runs else None,
+    )
+    return {
+        "signal": signal,
+        "best": best,
+        "baseline": baseline,
+        "top_runs": runs[:10],
+        "metrics_delta": (
+            {
+                "total_return_proxy_delta": best["total_return_proxy"] - baseline["total_return_proxy"],
+                "win_rate_delta": best["win_rate"] - baseline["win_rate"],
+                "max_drawdown_proxy_delta": best["max_drawdown_proxy"] - baseline["max_drawdown_proxy"],
+            }
+            if best and baseline
+            else None
+        ),
+        "anti_overfit_note": (
+            "This is an in-sample parameter scan. Use walk-forward or out-of-sample validation "
+            "before trusting optimized parameters."
+        ),
+    }

prompts.yaml

@@ -9,6 +9,18 @@
   These print outputs will then appear in the 'Observation:' field, which will be available as input for the next step.
   In the end you have to return a final answer using the `final_answer` tool.
 
+  You are also an options research agent focused on volatility trading. When the task concerns options, volatility, market data, strategy construction, or backtesting, follow these rules:
+  - Treat all outputs as research and education, not guaranteed investment advice.
+  - Prefer `query_knowledge` for stable options concepts, formulas, Greeks, volatility trading theory, and citations from local reference books.
+  - Use `web_search` and `visit_webpage` for recent market events, earnings dates, company announcements, macro events, exchange rules, and source verification.
+  - Use market data tools for current price, option chains, realized volatility, IV/RV spread, skew, term structure, and Greeks before proposing a strategy.
+  - For volatility strategies, state whether the idea is long vol, short vol, term-structure, skew, or event-vol driven.
+  - Every strategy discussion must include legs, expiration, strikes, net debit/credit, max loss, breakevens, major Greeks exposure, liquidity warnings, and event/IV-crush risk when relevant.
+  - Before presenting a final strategy, use payoff/backtest/optimization tools when sufficient data is available, and clearly label any proxy backtest limitations.
+  - Never present short premium strategies as low-risk. Explicitly mention tail risk, margin, assignment, liquidity, slippage, and gap risk.
+  - If required inputs are missing, ask for the missing symbol, outlook, time horizon, risk budget, or whether naked option selling is allowed.
+  - Final answers for options tasks should use this structure when applicable: market_context, volatility_view, strategy_candidates, selected_strategy, backtest_summary, risk_warnings, sources, limitations.
+
   Here are a few examples using notional tools:
   ---
   Task: "Generate an image of the oldest person in this document."

pyproject.toml

@@ -18,6 +18,8 @@ dependencies = [
     "tokenizers>=0.22.0,<=0.23.0",
     "transformers<5",
     "pymupdf>=1.27.2.3",
+    "pandas>=2.0.0",
+    "yfinance>=0.2.0",
 ]
 
 [build-system]

quantconnect/README.md

@@ -0,0 +1,28 @@
+# QuantConnect / LEAN Option Backtest Template
+
+这个目录放真正期权历史回测的 QuantConnect/LEAN 模板。它和本地
+`backtest_long_straddle_csv` 的定位不同：
+
+- 本地 CSV 回测：适合用供应商导出的历史期权 bid/ask quote 快速验证策略。
+- QuantConnect/LEAN：适合用 LEAN 数据源、撮合模型、手续费模型、组合持仓和保证金模型做更完整的回测。
+
+## 当前模板
+
+`VolatilityStraddleAlgorithm.py` 实现一个 ATM long straddle 示例：
+
+- 每隔 `entry_every_days` 天寻找目标 DTE 附近的期权到期日。
+- 选择最接近 ATM 的 call 和 put。
+- 用市场单买入 1 组 straddle。
+- 持有 `holding_days` 后平仓。
+- 使用 LEAN 的期权链、组合持仓、手续费/滑点/撮合模型能力。
+
+## 使用方式
+
+1. 在 QuantConnect 新建 Python algorithm。
+2. 将 `VolatilityStraddleAlgorithm.py` 内容复制到 `main.py`。
+3. 根据标的、日期、DTE、holding period 和资金规模修改参数。
+4. 运行回测，导出 orders/trades/equity 后可再交给 agent 分析。
+
+## 注意
+
+真实期权回测必须有历史期权链或历史期权报价。`yfinance` 只能查当前/近期期权链，不能可靠提供历史期权链，所以不能单独支撑严肃的历史期权策略回测。

quantconnect/VolatilityStraddleAlgorithm.py

@@ -0,0 +1,91 @@
+from AlgorithmImports import *
+
+
+class VolatilityStraddleAlgorithm(QCAlgorithm):
+    """ATM long straddle template for real option backtests in QuantConnect/LEAN."""
+
+    def Initialize(self):
+        self.SetStartDate(2022, 1, 1)
+        self.SetEndDate(2024, 1, 1)
+        self.SetCash(100000)
+
+        self.ticker = "SPY"
+        self.target_dte = 30
+        self.holding_days = 5
+        self.entry_every_days = 5
+        self.contract_quantity = 1
+
+        equity = self.AddEquity(self.ticker, Resolution.Minute)
+        option = self.AddOption(self.ticker, Resolution.Minute)
+        option.SetFilter(self.OptionFilter)
+
+        self.underlying = equity.Symbol
+        self.option_symbol = option.Symbol
+        self.next_entry_time = self.StartDate
+        self.open_groups = []
+
+    def OptionFilter(self, universe):
+        min_dte = max(1, self.target_dte - 10)
+        max_dte = self.target_dte + 10
+        return universe.IncludeWeeklys().Strikes(-10, 10).Expiration(min_dte, max_dte)
+
+    def OnData(self, slice):
+        self.CloseExpiredHoldingGroups()
+
+        if self.Time < self.next_entry_time:
+            return
+
+        chain = slice.OptionChains.get(self.option_symbol)
+        if chain is None:
+            return
+
+        contracts = [contract for contract in chain if contract.Expiry.date() > self.Time.date()]
+        if not contracts:
+            return
+
+        expiry = min(contracts, key=lambda contract: abs((contract.Expiry.date() - self.Time.date()).days - self.target_dte)).Expiry
+        expiry_contracts = [contract for contract in contracts if contract.Expiry == expiry]
+        spot = self.Securities[self.underlying].Price
+
+        calls = [contract for contract in expiry_contracts if contract.Right == OptionRight.Call]
+        puts = [contract for contract in expiry_contracts if contract.Right == OptionRight.Put]
+        if not calls or not puts:
+            return
+
+        call = min(calls, key=lambda contract: abs(contract.Strike - spot))
+        put = min(puts, key=lambda contract: abs(contract.Strike - spot))
+
+        self.MarketOrder(call.Symbol, self.contract_quantity)
+        self.MarketOrder(put.Symbol, self.contract_quantity)
+
+        self.open_groups.append(
+            {
+                "entry_time": self.Time,
+                "exit_time": self.Time + timedelta(days=self.holding_days),
+                "symbols": [call.Symbol, put.Symbol],
+            }
+        )
+        self.next_entry_time = self.Time + timedelta(days=self.entry_every_days)
+
+        self.Debug(
+            f"Opened ATM straddle {call.Symbol.Value}, {put.Symbol.Value}; "
+            f"spot={spot:.2f}; expiry={expiry.date()}"
+        )
+
+    def CloseExpiredHoldingGroups(self):
+        remaining_groups = []
+        for group in self.open_groups:
+            if self.Time < group["exit_time"]:
+                remaining_groups.append(group)
+                continue
+
+            for symbol in group["symbols"]:
+                holding = self.Portfolio[symbol]
+                if holding.Invested:
+                    self.MarketOrder(symbol, -holding.Quantity)
+            self.Debug(f"Closed straddle group from {group['entry_time']}")
+
+        self.open_groups = remaining_groups
+
+    def OnEndOfAlgorithm(self):
+        self.Debug(f"Final portfolio value: {self.Portfolio.TotalPortfolioValue:.2f}")

rag_eval_interview_notes.md

@@ -0,0 +1,544 @@
+# RAG 评测模块构建总结
+
+本文档用于面试时说明：为什么需要 RAG 评测、如何设计 retrieval eval、如何接入公开数据集和自建 PDF 测试集，以及如何判断 RAG 优化是否真的有效。
+
+## 背景问题
+
+在优化 RAG 系统时，仅靠主观查看回答效果不稳定，也很难判断 PDF 解析、chunk 切分、embedding、reranker 或检索参数的改动是否真的带来提升。
+
+因此我先搭建了一个独立的 RAG retrieval evaluation 模块，用固定测试集和固定指标来做 before/after 对比。
+
+目标是：
+
+- 能快速验证检索链路是否跑通。
+- 能用公开 benchmark 做横向参考。
+- 能用金融相关数据集贴近业务场景。
+- 能用自己的期权 PDF 测试集验证 PDF 解析、公式抽取和章节切分是否有效。
+- 每次改动后可以一条命令自动跑评测并生成报告。
+
+## 数据集接入顺序
+
+我按照由易到难、由通用到业务的顺序接入了 4 类测试集。
+
+### 1. BEIR/scifact
+
+`scifact` 是 BEIR 中比较小的科学事实检索数据集，适合快速跑通 retrieval eval。
+
+接入它的目的不是追求业务贴合，而是验证：
+
+- 数据下载和解析是否正常。
+- corpus、query、qrels 能否正确对齐。
+- 向量索引是否能构建。
+- 检索指标是否能稳定输出。
+
+### 2. BEIR/fiqa
+
+`fiqa` 是金融问答相关数据集，比 `scifact` 更贴近金融场景。
+
+接入它的目的：
+
+- 验证金融语义检索能力。
+- 检查 embedding 对金融术语、问答表达的适配情况。
+- 作为后续期权 PDF 场景前的公开金融 benchmark。
+
+### 3. Open RAGBench
+
+Open RAGBench 更接近长文档、PDF、报告类 RAG 场景。
+
+我选择了其中的 `pdf/arxiv` 子集，用来验证：
+
+- 长文档解析后的检索效果。
+- 多章节、多段落文档下的 chunk 检索表现。
+- RAG 系统在 PDF-like 文档上的泛化能力。
+
+### 4. 自建期权 PDF 测试集
+
+最后补充自己的期权 PDF 测试集，因为公开 benchmark 无法完全覆盖当前项目中的业务难点。
+
+自建测试集重点覆盖：
+
+- 期权定价概念。
+- PDF 中的公式内容。
+- 章节标题和上下文定位。
+- 公式编号、页码、章节等 metadata 是否能帮助检索。
+
+## 模块设计
+
+评测模块放在 `eval/` 目录下，核心文件包括：
+
+- `eval/rag_eval.py`：单数据集 retrieval eval 入口。
+- `eval/run_eval_suite.py`：批量评测多个数据集的 suite runner。
+- `eval/local_options_eval.jsonl`：自建期权 PDF 测试集。
+- `eval/README.md`：调用示例和使用说明。
+
+整体流程如下：
+
+```text
+加载数据集
+  -> 构造 documents / queries / qrels
+  -> 构建 Chroma 向量索引
+  -> 执行 top-k retrieval
+  -> 按 doc_id 去重
+  -> 计算 hit@k / MRR / NDCG@K
+  -> 生成 JSON 和 Markdown 报告
+```
+
+## 为什么只先做 retrieval eval
+
+RAG 的最终效果由两部分组成：
+
+```text
+RAG = Retrieval + Generation
+```
+
+如果检索阶段没有找到正确上下文，后面的 LLM 生成很容易幻觉。因此我先评估 retrieval：
+
+- 问题对应的正确文档有没有被找回来。
+- 正确文档排在第几名。
+- top-k 结果排序是否合理。
+
+这样可以先把问题定位在“检索是否正确”，再进一步评估生成答案。
+
+## 指标设计
+
+### Hit@K
+
+`Hit@K` 表示前 K 个结果里是否包含正确文档。
+
+例如 `Hit@5 = 1`，表示正确文档出现在前 5 个检索结果中。
+
+它适合判断：
+
+- 正确上下文有没有被召回。
+- top-k 设大以后召回是否提升。
+
+### MRR
+
+`MRR` 是 Mean Reciprocal Rank，关注第一个正确结果出现的位置。
+
+如果正确结果排第 1，得分是 `1`。
+如果正确结果排第 2，得分是 `1/2`。
+如果正确结果排第 5，得分是 `1/5`。
+
+它适合判断：
+
+- 正确文档是否排得足够靠前。
+- 检索排序质量是否提升。
+
+### NDCG@K
+
+`NDCG@K` 衡量前 K 个结果的排序质量。
+
+计算方式是：
+
+```text
+DCG@K = rel_1 / log2(2) + rel_2 / log2(3) + ... + rel_K / log2(K + 1)
+NDCG@K = DCG@K / IDCG@K
+```
+
+其中 `rel_i = 1` 表示第 i 个结果相关，`rel_i = 0` 表示不相关。
+
+NDCG 越接近 1，说明相关结果越靠前。
+
+## 关键实现细节
+
+### 1. 统一数据格式
+
+不同数据集格式不同，因此我统一抽象成：
+
+```python
+documents = [
+    {
+        "doc_id": "...",
+        "title": "...",
+        "text": "...",
+        "metadata": {...}
+    }
+]
+
+queries = [
+    {
+        "query_id": "...",
+        "question": "...",
+        "relevant_doc_ids": [...]
+    }
+]
+
+qrels = {
+    "query_id": {"doc_id"}
+}
+```
+
+这样后续索引构建和指标计算可以复用同一套逻辑。
+
+### 2. 小样本评测必须包含 gold 文档
+
+在做 smoke test 时，如果只取 corpus 前 N 篇文档，可能会出现 query 的正确文档不在测试 corpus 里，导致评测不公平。
+
+所以我在��载 BEIR 和 Open RAGBench 时，会先读取 qrels，确定当前 query 需要哪些 gold documents，再优先把这些文档纳入 corpus。
+
+这样小样本测试可以稳定评估检索能力，而不是被采样问题干扰。
+
+### 3. 检索结果按 doc_id 去重
+
+一个文档会被切成多个 chunk，检索时可能同一篇文档的多个 chunk 同时出现在 top-k 中。
+
+如果不去重，会导致：
+
+- 指标被重复 chunk 影响。
+- NDCG 可能异常偏高。
+- top-k 实际上不是 top-k documents，而是 top-k chunks。
+
+因此评测时内部会多取一些 chunk，然后按 `doc_id` 去重，再计算 top-k 文档级指标。
+
+### 4. 支持 rebuild
+
+如果修改了：
+
+- PDF 解析逻辑
+- chunk 切分方式
+- embedding 模型
+- metadata 构造
+- reranker 或检索参数
+
+必须使用 `--rebuild` 重建索引，否则会复用旧索引，评测结果不能代表最新代码。
+
+## 自动化评测脚本
+
+单数据集评测：
+
+```bash
+uv --cache-dir .uv-cache run python -m eval.rag_eval \
+  --dataset local-options \
+  --max-queries 3 \
+  --top-k 5 \
+  --rebuild
+```
+
+批量评测：
+
+```bash
+uv --cache-dir .uv-cache run python -m eval.run_eval_suite --rebuild
+```
+
+只跑指定数据集：
+
+```bash
+uv --cache-dir .uv-cache run python -m eval.run_eval_suite \
+  --datasets local-options,beir/fiqa \
+  --top-k 5 \
+  --max-queries 20 \
+  --rebuild
+```
+
+对比不同 chunk 设置：
+
+```bash
+uv --cache-dir .uv-cache run python -m eval.run_eval_suite \
+  --datasets local-options \
+  --chunk-size 384 \
+  --chunk-overlap 64 \
+  --output-name local_options_chunk384 \
+  --rebuild
+```
+
+报告会输出到：
+
+```text
+eval/reports/
+```
+
+包括：
+
+- 每个数据集的 JSON 报告。
+- 每个数据集的 Markdown 报告。
+- suite 级别的汇总报告。
+
+## 遇到的问题和解决方案
+
+### 问题 1：公开数据集需要联网下载
+
+BEIR 和 Open RAGBench 都需要从公网下载数据。
+
+解决方法：
+
+- 第一次运行时下载并缓存到 `eval/data/`。
+- 后续运行直接复用本地数据。
+- 数据和索引分开存放，便于排查问题。
+
+### 问题 2：Open RAGBench 实际目录结构和预期不一致
+
+最开始预设路径是 `official/pdf/arxiv`，但实际下载后路径是 `pdf/arxiv`。
+
+解决方法：
+
+- loader 中兼容两种路径。
+- 优先尝试 `pdf/arxiv`，不存在时再回退到 `official/pdf/arxiv`。
+
+### 问题 3：小样本采样会漏掉 gold document
+
+如果 `max_corpus_docs` 很小，直接截取 corpus 前 N 条可能不包含 qrels 中的正确文档。
+
+解决方法：
+
+- 先根据 qrels 选择 query。
+- 再把对应 gold documents 强制纳入 corpus。
+- 最后补充其他文档作为干扰项。
+
+### 问题 4：chunk 重复导致指标异常
+
+同一篇文档的多个 chunk 可能同时命中，导致 NDCG 等指标不合理。
+
+解决方法：
+
+- 检索时多取一些 chunk。
+- 评估时按 `doc_id` 去重。
+- 最终以 document-level top-k 计算指标。
+
+### 问题 5：不重建索引可能复用旧结果
+
+如果代码改了但没有 `--rebuild`，Chroma 可能复用旧索引。
+
+解决方法：
+
+- 文档中明确说明改动后必须加 `--rebuild`。
+- suite runner 支持统一传入 `--rebuild`。
+- 用 `--output-name` 固定报告名，方便 before/after 对比。
+
+### 问题 6：RAG 只是独立模块，没有真正接入 Agent
+
+最开始 RAG 已经能单独查询知识库，但主 `CodeAgent` 的 tools 里没有注册知识库工具。这样在真实对话里，agent 实际只能查行情和时间，不能主动调用本地期权知识库。
+
+解决方法：
+
+- 将 `QueryKnowledgeTool` 注册进主 agent。
+- 优化 tool description，让模型知道它应该在期权概念、波动率、Greeks、策略、公式编号和书籍引用问题上调用该工具。
+- 控制 tool 输出长度，只返回来源、页码、section、分数和截断后的片段，避免检索结果占满上下文。
+
+面试可以强调：
+
+> RAG 不是只要能单独跑 query 就算完成，必须作为 agent 的一个可调用工具接入主工作流。否则用户问期权概念时，agent 不一定会查知识库，仍然可能凭模型参数记忆回答。
+
+### 问题 7：知识库目录和代码目录耦合
+
+早期知识库放在 `tools/knowledge_base` 下，代码、原始资料和 Chroma 数据库混在一起。随着知识库变大，这种结构不利于维护，也不利于后续把工具代码、数据和缓存分开管理。
+
+解决方法：
+
+- 将知识库统一到项目根目录：
+
+```text
+OptionAgent/knowledge_base/
+  raw/
+  chroma_db/
+```
+
+- 工具代码中使用 `PROJECT_ROOT / "knowledge_base"` 作为主路径。
+- 保留旧路径 fallback，避免迁移时旧数据立刻失效。
+
+面试可以强调：
+
+> 我把知识库从工具目录迁到项目根目录，并保留 legacy fallback。这样既完成了结构治理，也避免了迁移时破坏已有索引和原始文档。
+
+### 问题 8：全量 rebuild 成本高
+
+只要文档、解析方法或 embedding 模型变化，就全量重建索引。书籍变多后，这会浪费大量时间，而且不方便频繁更新笔记。
+
+解决方法：
+
+- 每个 chunk metadata 中保留：
+
+```text
+source_file
+file_hash
+embedding_model
+extraction_method
+```
+
+- 启动时扫描当前 raw 文件，和 Chroma 中已有 metadata 对比：
+
+```text
+新增文件 -> 只入库新增文件
+修改文件 -> 删除该文件旧 chunks，再重新入库
+删除文件 -> 删除该文件对应 chunks
+embedding/extraction 版本变化 -> 触发对应文件更新
+```
+
+面试可以强调：
+
+> 我没有只依赖 collection 是否为空，而是基于 source_file、file_hash、embedding_model 和 extraction_method 做增量更新。这样文档更新后索引不会脏，也不用每次全量 rebuild。
+
+### 问题 9：纯向量检索对公式编号和专有名词不稳定
+
+期权书里有很多精确查询，例如：
+
+```text
+Equation 21.23
+WITH ZERO CORRELATION
+Black-Scholes-Merton
+vega
+gamma
+```
+
+这类问题不只是语义相似，还需要字面命中。纯 dense embedding 对概念解释很强，但对公式编号、章节标题、专有名词有时不如关键词检索稳定。
+
+解决方法：
+
+- 增加轻量 BM25 检索。
+- 查询时同时跑：
+
+```text
+dense vector retrieval
+BM25 keyword retrieval
+```
+
+- 使用 reciprocal-rank merge 合并结果。
+- 再交给 cross-encoder reranker 做最终排序。
+
+最终链路：
+
+```text
+query
+  -> dense top-k
+  -> BM25 top-k
+  -> merge / deduplicate
+  -> reranker
+  -> top results with citations
+```
+
+面试可以强调：
+
+> 我做 hybrid search 是因为金融和期权文档里存在大量公式编号、章节名、ticker-like token 和专有名词。Dense retrieval 负责语义召回，BM25 负责精确词命中，reranker 负责最终排序。
+
+### 问题 10：本地评测集太小
+
+最初 `local-options` 只有 3 条 case，容易出现指标过高但不可泛化的问题。比如小样本里 Hit@5 为 1，并不代表系统在真实问题上稳定。
+
+解决方法：
+
+- 新增 `eval/generate_local_options_eval.py`。
+- 从已解析的 PDF/MD 文档中随机抽样 chunk。
+- 优先覆盖：
+  - 公式问题。
+  - 章节定位问题。
+  - 期权关键词问题。
+  - 波动率、Greeks、风险中性、策略等业务术语。
+- 过滤前言、索引页、表格/图注噪声，避免生成低质量 query。
+- 将本地 eval 扩充到 40 条。
+
+面试可以强调：
+
+> 我没有只手写少量 happy path case，而是做了一个本地 eval case generator，从真实 chunk 中抽样生成问题，并对噪声标题做过滤。这样可以更稳定地评估 PDF 解析和检索策略的变化。
+
+## Hybrid Search 和 Reranker 对比实验
+
+扩充到 40 条 local-options case 后，我做了三组对比：
+
+```text
+dense-only:
+MRR      0.4708
+NDCG@5   0.3468
+Hit@1    0.4250
+Hit@3    0.5250
+Hit@5    0.5250
+
+hybrid:
+MRR      0.4833
+NDCG@5   0.3190
+Hit@1    0.4250
+Hit@3    0.5250
+Hit@5    0.5750
+
+hybrid + reranker:
+MRR      0.7125
+NDCG@5   0.4717
+Hit@1    0.7000
+Hit@3    0.7250
+Hit@5    0.7250
+```
+
+结果解释：
+
+- Hybrid search 单独提升了 Hit@5，说明 BM25 补充了召回，尤其对精确术语和公式编号有帮助。
+- Hybrid 的 NDCG 略降，说明召回增加后排序还不够好。
+- 加上 reranker 后，MRR、NDCG、Hit@1、Hit@5 都明显提升，说明 reranker 有效改善了排序质量。
+
+面试可以这样总结：
+
+> 单独加 BM25 后，召回有提升但排序不一定更好；这符合预期，因为 BM25 会把更多字面相关结果拉进候选集。最终效果最好的是 dense + BM25 扩召回，再用 cross-encoder reranker 排序。这个实验也说明我不是凭感觉加组件，而是用 Hit@K、MRR 和 NDCG 验证每一步是否真的有效。
+
+## 当前评测结果示例
+
+早期小规模 smoke test 的结果示例：
+
+```text
+BEIR/scifact:
+MRR = 0.9000
+NDCG@5 = 0.9262
+Hit@1 = 0.8000
+Hit@5 = 1.0000
+
+BEIR/fiqa:
+MRR = 0.8000
+NDCG@5 = 0.6582
+Hit@1 = 0.8000
+Hit@5 = 0.8000
+
+local-options:
+MRR = 1.0000
+NDCG@5 = 0.7162
+Hit@1 = 1.0000
+Hit@5 = 1.0000
+```
+
+这些结果主要用于验证评测流程和小样本趋势，不能直接代表完整 benchmark 成绩。正式对比时需要扩大 `max_queries` 和 `max_corpus_docs`。
+
+## 面试回答话术
+
+可以这样回答：
+
+> 我在优化 RAG 系统时发现，单纯看回答效果很难判断改动是否真的有效，所以先搭了一个 retrieval evaluation 模块。我的思路是先用 BEIR/scifact 快速跑通标准检索评测，再接 BEIR/fiqa 贴近金融场景，然后接 Open RAGBench 验证长文档和 PDF-like 场景，最后补自己的期权 PDF 测试集，用来覆盖项目里公式、章节和金融术语这些业务难点。
+
+如果面试官问为什么先评估 retrieval：
+
+> 因为 RAG 的生成质量高度依赖检索质量。如果检索阶段没有召回正确上下文，后面 LLM 很容易幻觉。所以我先用 Hit@K、MRR、NDCG@K 衡量正确文档是否被召回以及排序是否靠前，把 retrieval 问题和 generation 问题分开定位。
+
+如果面试官问如何保证评测可靠：
+
+> 我做了几个处理。第一，所有数据集统一成 documents、queries、qrels 三类结构。第二，小样本 smoke test 会优先把 qrels 需要的 gold document 放进 corpus，避免因为采样漏掉正确文档导致评测不公平。第三，检索结果按 doc_id 去重，避免同一篇文档多个 chunk 重复命中导致指标虚高。第四，修改解析、chunk、embedding 或检索逻辑后必须 rebuild 索引，保证评测对应的是最新系统。
+
+如果面试官问这个模块怎么用：
+
+> 我提供了单数据集入口和 suite 入口。单数据集可以用 `python -m eval.rag_eval --dataset local-options --rebuild`，批量评测可以用 `python -m eval.run_eval_suite --rebuild`。它会自动跑多个数据集，输出 JSON 和 Markdown 报告，便于做 before/after 对比。
+
+如果面试官问为什么要做 hybrid search：
+
+> 因为期权和金融文档里有两类查询。一类是语义型，比如“为什么临近到期 gamma 风险变大”，dense embedding 很适合；另一类是精确匹配型，比如 `Equation 21.23`、`WITH ZERO CORRELATION`、`Black-Scholes-Merton`，这些 BM25 更稳定。所以我用 dense retrieval 负责语义召回，BM25 负责关键词召回，然后合并候选，再用 cross-encoder reranker 排序。
+
+如果面试官问 hybrid 是否真的提升了：
+
+> 我用扩充后的 40 条 local-options eval 做了对比。Dense-only 的 Hit@5 是 0.525，MRR 是 0.471；加入 hybrid 后 Hit@5 提升到 0.575，说明召回变好，但 NDCG 有一点下降，说明排序还不够好；再加 reranker 后 Hit@5 到 0.725，MRR 到 0.713，Hit@1 到 0.700，说明 dense + BM25 + reranker 的组合最稳。
+
+如果面试官问为什么不能每次全量 rebuild：
+
+> 全量 rebuild 在文档少的时候可以，但参考书和笔记变多后成本会越来越高。我在 metadata 里记录 source_file、file_hash、embedding_model 和 extraction_method，启动时对比当前文件状态和 Chroma 中已有 metadata。新增文件只入库新增部分，修改文件只删除并重建该文件对应 chunks，删除文件同步清理旧 chunks。这样既保证索引新鲜，也避免无意义的全量重建。
+
+如果面试官问 RAG 和 agent 怎么结合：
+
+> 我把 RAG 封装成 `QueryKnowledgeTool` 注册到主 `CodeAgent`，而不是只做一个独立脚本。tool description 明确告诉模型在期权概念、波动率、Greeks、策略和公式编号问题上调用它。返回结果包含 source、page、section、content_type、score 和 excerpt，方便 agent 带引用地回答，而不是凭模型记忆回答。
+
+如果面试官问如何避免本地 eval 过拟合：
+
+> 早期我只有几条手写 case，很容易高估效果。后来我写了 local eval generator，从真实 PDF chunks 中抽样生成问题，同时过滤前言、索引、表格和图注噪声。这样测试集覆盖公式、章节、概念和金融术语，能更真实地暴露 retrieval 的召回和排序问题。
+
+## 后续可扩展方向
+
+后续还可以继续扩展：
+
+- 增加 reranker 前后的对比实验。
+- 增加 answer-level evaluation，评估最终回答是否正确。
+- 增加 citation accuracy，判断引用来源是否准确。
+- 增加公式检索专门测试集。
+- 增加表格类 query 测试集。
+- 对不同 chunk 策略、embedding 模型、top-k 参数做批量实验。
+- 将报告接入 CI 或定期任务，防止 RAG 效果回退。

requirements.txt

@@ -3,6 +3,7 @@ smolagents==1.13.0
 requests
 duckduckgo_search
 pandas
+yfinance
 pypdf
 PyMuPDF
 chromadb

strategy/__init__.py

@@ -0,0 +1,11 @@
+from .builder import generate_volatility_strategies
+from .payoff import expiration_payoff, strategy_summary
+from .schemas import OptionLeg, OptionStrategy
+
+__all__ = [
+    "expiration_payoff",
+    "generate_volatility_strategies",
+    "OptionLeg",
+    "OptionStrategy",
+    "strategy_summary",
+]

strategy/builder.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from market_data.schemas import OptionChain, OptionContract
+
+from .payoff import estimate_breakevens
+from .schemas import OptionLeg, OptionStrategy
+
+
+def usable_contracts(contracts: list[OptionContract]) -> list[OptionContract]:
+    return [
+        contract
+        for contract in contracts
+        if contract.mid is not None
+        and contract.mid > 0
+        and not {"missing_or_zero_bid_ask", "zero_open_interest"}.intersection(contract.liquidity_warnings)
+    ]
+
+
+def nearest_contract(contracts: list[OptionContract], target_strike: float) -> OptionContract | None:
+    valid = usable_contracts(contracts)
+    if not valid:
+        return None
+    return min(valid, key=lambda contract: abs(contract.strike - target_strike))
+
+
+def contract_to_leg(contract: OptionContract, action: str, quantity: int = 1) -> OptionLeg:
+    return OptionLeg(
+        action=action,
+        option_type=contract.option_type,
+        strike=contract.strike,
+        expiration=contract.expiration,
+        quantity=quantity,
+        premium=contract.mid or contract.last_price or 0.0,
+        implied_volatility=contract.implied_volatility,
+        liquidity_warnings=contract.liquidity_warnings,
+    )
+
+
+def make_strategy(
+    name: str,
+    volatility_view: str,
+    directional_view: str,
+    legs: list[OptionLeg],
+    rationale: str,
+    risks: list[str],
+    score: float,
+) -> OptionStrategy:
+    net_cash_flow = sum(leg.cash_flow() for leg in legs)
+    net_debit_or_credit = -net_cash_flow
+    breakevens = estimate_breakevens(legs)
+
+    max_profit: float | str | None = None
+    max_loss: float | str | None = None
+    if name in {"long_straddle", "long_strangle"}:
+        max_loss = round(max(net_debit_or_credit, 0.0), 2)
+        max_profit = "unlimited"
+    elif name == "short_straddle":
+        max_profit = round(abs(min(net_debit_or_credit, 0.0)), 2)
+        max_loss = "unlimited"
+    elif name == "iron_condor":
+        call_strikes = sorted(leg.strike for leg in legs if leg.option_type == "call")
+        put_strikes = sorted(leg.strike for leg in legs if leg.option_type == "put")
+        width = max(call_strikes[-1] - call_strikes[0], put_strikes[-1] - put_strikes[0])
+        credit = abs(min(net_debit_or_credit, 0.0))
+        max_profit = round(credit, 2)
+        max_loss = round(width * 100 - credit, 2)
+    elif name == "calendar_spread":
+        max_loss = round(max(net_debit_or_credit, 0.0), 2)
+        max_profit = "path_dependent"
+
+    return OptionStrategy(
+        name=name,
+        volatility_view=volatility_view,
+        directional_view=directional_view,
+        legs=legs,
+        rationale=rationale,
+        risks=risks,
+        max_profit=max_profit,
+        max_loss=max_loss,
+        breakevens=breakevens,
+        net_debit_or_credit=round(net_debit_or_credit, 2),
+        score=score,
+    )
+
+
+def generate_volatility_strategies(
+    near_chain: OptionChain,
+    volatility_view: str = "neutral",
+    directional_view: str = "neutral",
+    far_chain: OptionChain | None = None,
+) -> list[OptionStrategy]:
+    if near_chain.underlying_price is None:
+        return []
+
+    spot = near_chain.underlying_price
+    atm_call = nearest_contract(near_chain.calls, spot)
+    atm_put = nearest_contract(near_chain.puts, spot)
+    otm_call = nearest_contract(near_chain.calls, spot * 1.05)
+    otm_put = nearest_contract(near_chain.puts, spot * 0.95)
+    strategies: list[OptionStrategy] = []
+
+    if atm_call and atm_put:
+        if volatility_view in {"long_vol", "neutral", "vol_expansion"}:
+            strategies.append(
+                make_strategy(
+                    name="long_straddle",
+                    volatility_view="long_vol",
+                    directional_view="neutral",
+                    legs=[contract_to_leg(atm_call, "buy"), contract_to_leg(atm_put, "buy")],
+                    rationale="Benefits from a large realized move or IV expansion; risk is premium paid.",
+                    risks=["theta_decay", "iv_crush", "requires_large_move"],
+                    score=0.75,
+                )
+            )
+        if volatility_view in {"short_vol", "neutral", "vol_compression"}:
+            strategies.append(
+                make_strategy(
+                    name="short_straddle",
+                    volatility_view="short_vol",
+                    directional_view="neutral",
+                    legs=[contract_to_leg(atm_call, "sell"), contract_to_leg(atm_put, "sell")],
+                    rationale="Benefits from realized volatility staying below implied volatility.",
+                    risks=["unlimited_tail_risk", "gap_risk", "margin_requirement"],
+                    score=0.45,
+                )
+            )
+
+    if otm_call and otm_put and volatility_view in {"long_vol", "neutral", "vol_expansion"}:
+        strategies.append(
+            make_strategy(
+                name="long_strangle",
+                volatility_view="long_vol",
+                directional_view="neutral",
+                legs=[contract_to_leg(otm_call, "buy"), contract_to_leg(otm_put, "buy")],
+                rationale="Lower-cost long volatility expression than a straddle, but needs a larger move.",
+                risks=["theta_decay", "wide_breakevens", "iv_crush"],
+                score=0.65,
+            )
+        )
+
+    if far_chain and atm_call and volatility_view in {"long_vol", "neutral", "term_structure"}:
+        far_call = nearest_contract(far_chain.calls, atm_call.strike)
+        if far_call:
+            strategies.append(
+                make_strategy(
+                    name="calendar_spread",
+                    volatility_view="term_structure",
+                    directional_view="neutral",
+                    legs=[contract_to_leg(atm_call, "sell"), contract_to_leg(far_call, "buy")],
+                    rationale="Expresses a term-structure view and benefits if longer-dated IV holds up.",
+                    risks=["path_dependency", "front_expiry_gamma", "term_structure_shift"],
+                    score=0.60,
+                )
+            )
+
+    if otm_call and otm_put and volatility_view in {"short_vol", "neutral", "vol_compression"}:
+        long_call = nearest_contract(near_chain.calls, otm_call.strike * 1.03)
+        long_put = nearest_contract(near_chain.puts, otm_put.strike * 0.97)
+        if long_call and long_put:
+            strategies.append(
+                make_strategy(
+                    name="iron_condor",
+                    volatility_view="short_vol",
+                    directional_view="neutral",
+                    legs=[
+                        contract_to_leg(otm_put, "sell"),
+                        contract_to_leg(long_put, "buy"),
+                        contract_to_leg(otm_call, "sell"),
+                        contract_to_leg(long_call, "buy"),
+                    ],
+                    rationale="Defined-risk short volatility strategy for range-bound markets.",
+                    risks=["short_gamma", "tail_loss_to_width", "assignment_risk"],
+                    score=0.70,
+                )
+            )
+
+    return sorted(strategies, key=lambda strategy: strategy.score, reverse=True)

strategy/payoff.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from .schemas import OptionLeg, OptionStrategy
+
+
+def leg_expiration_payoff(leg: OptionLeg, underlying_price: float) -> float:
+    if leg.option_type == "call":
+        intrinsic = max(underlying_price - leg.strike, 0.0)
+    else:
+        intrinsic = max(leg.strike - underlying_price, 0.0)
+    return intrinsic * leg.signed_quantity() * 100 + leg.cash_flow()
+
+
+def expiration_payoff(legs: list[OptionLeg], underlying_price: float) -> float:
+    return sum(leg_expiration_payoff(leg, underlying_price) for leg in legs)
+
+
+def estimate_breakevens(legs: list[OptionLeg]) -> list[float]:
+    strikes = [leg.strike for leg in legs]
+    low = max(min(strikes) * 0.5, 0.01)
+    high = max(strikes) * 1.5
+    steps = 400
+    points = [low + (high - low) * index / steps for index in range(steps + 1)]
+    payoffs = [expiration_payoff(legs, point) for point in points]
+    breakevens = []
+    for index in range(1, len(points)):
+        previous = payoffs[index - 1]
+        current = payoffs[index]
+        if previous == 0:
+            breakevens.append(points[index - 1])
+        if previous * current < 0:
+            ratio = abs(previous) / (abs(previous) + abs(current))
+            breakevens.append(points[index - 1] + (points[index] - points[index - 1]) * ratio)
+    return [round(value, 2) for value in breakevens]
+
+
+def strategy_summary(strategy: OptionStrategy) -> dict:
+    strikes = [leg.strike for leg in strategy.legs]
+    low = max(min(strikes) * 0.6, 0.01)
+    high = max(strikes) * 1.4
+    grid = [low + (high - low) * index / 80 for index in range(81)]
+    payoffs = [expiration_payoff(strategy.legs, price) for price in grid]
+    return {
+        "min_grid_payoff": round(min(payoffs), 2),
+        "max_grid_payoff": round(max(payoffs), 2),
+        "payoff_at_middle_strike": round(expiration_payoff(strategy.legs, sum(strikes) / len(strikes)), 2),
+        "sample_points": [
+            {"underlying_price": round(price, 2), "pnl": round(pnl, 2)}
+            for price, pnl in zip(grid[::10], payoffs[::10])
+        ],
+    }

strategy/schemas.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass
+class OptionLeg:
+    action: str
+    option_type: str
+    strike: float
+    expiration: str
+    quantity: int
+    premium: float
+    implied_volatility: float | None = None
+    delta: float | None = None
+    liquidity_warnings: list[str] | None = None
+
+    def signed_quantity(self) -> int:
+        return self.quantity if self.action == "buy" else -self.quantity
+
+    def cash_flow(self) -> float:
+        return -self.premium * self.signed_quantity() * 100
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class OptionStrategy:
+    name: str
+    volatility_view: str
+    directional_view: str
+    legs: list[OptionLeg]
+    rationale: str
+    risks: list[str]
+    max_profit: float | str | None
+    max_loss: float | str | None
+    breakevens: list[float]
+    net_debit_or_credit: float
+    score: float
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["legs"] = [leg.to_dict() for leg in self.legs]
+        return payload

strategy/tools.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+
+from smolagents import tool
+
+from market_data.providers import get_option_chain, list_option_expirations
+
+from .builder import generate_volatility_strategies
+from .payoff import strategy_summary
+
+
+@tool
+def build_volatility_strategy(
+    symbol: str,
+    volatility_view: str = "neutral",
+    directional_view: str = "neutral",
+    near_expiration: str = "",
+    far_expiration: str = "",
+) -> str:
+    """Build candidate volatility option strategies from the current option chain.
+
+    Args:
+        symbol: Yahoo Finance ticker.
+        volatility_view: long_vol, short_vol, vol_expansion, vol_compression, term_structure, or neutral.
+        directional_view: bullish, bearish, neutral, or range_bound.
+        near_expiration: Near option expiration in YYYY-MM-DD. Empty uses nearest expiration.
+        far_expiration: Far option expiration for calendar spreads. Empty uses a later available expiration.
+    """
+    try:
+        symbol = symbol.strip().upper()
+        expirations = list_option_expirations(symbol)
+        if not expirations:
+            raise ValueError(f"No option expirations found for {symbol}.")
+        near = near_expiration or expirations[0]
+        far = far_expiration or (expirations[1] if len(expirations) > 1 else "")
+        near_chain = get_option_chain(symbol, near)
+        far_chain = get_option_chain(symbol, far) if far else None
+        strategies = generate_volatility_strategies(
+            near_chain=near_chain,
+            volatility_view=volatility_view,
+            directional_view=directional_view,
+            far_chain=far_chain,
+        )
+        return json.dumps(
+            {
+                "status": "success",
+                "symbol": symbol,
+                "near_expiration": near,
+                "far_expiration": far or None,
+                "strategies": [
+                    {
+                        **strategy.to_dict(),
+                        "payoff_summary": strategy_summary(strategy),
+                    }
+                    for strategy in strategies
+                ],
+                "risk_note": (
+                    "This is research output, not a trade recommendation. "
+                    "Validate quotes, liquidity, margin, assignment risk, and event risk before trading."
+                ),
+            },
+            ensure_ascii=False,
+            indent=2,
+            default=str,
+        )
+    except Exception as exc:
+        return json.dumps(
+            {"status": "error", "symbol": symbol, "message": str(exc)},
+            ensure_ascii=False,
+            indent=2,
+        )

tools/query_knowledge.py

@@ -3,6 +3,7 @@ import asyncio
 from collections import Counter
 import hashlib
 import logging
+import math
 import os
 from pathlib import Path
 from typing import Iterable, List, Optional
@@ -13,19 +14,29 @@ from chromadb.errors import NotFoundError
 from pypdf import PdfReader
 
 from llama_index.core import StorageContext, VectorStoreIndex
-from llama_index.core.schema import Document, BaseNode
+from llama_index.core.schema import Document, BaseNode, NodeWithScore, TextNode
 from llama_index.core.node_parser import SentenceSplitter
 from llama_index.vector_stores.chroma import ChromaVectorStore
 
 
+load_dotenv()
 BASE_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = BASE_DIR.parent
 KNOWLEDGE_BASE_DIR = BASE_DIR / "knowledge_base"
+LEGACY_KNOWLEDGE_BASE_DIR = BASE_DIR / "knowledge_base"
+KNOWLEDGE_BASE_DIR = PROJECT_ROOT / "knowledge_base"
 RAW_DIR = KNOWLEDGE_BASE_DIR / "raw"
 CHROMA_DB_DIR = KNOWLEDGE_BASE_DIR / "chroma_db"
-HF_CACHE_DIR = BASE_DIR / "hf_cache"
+HF_CACHE_DIR = PROJECT_ROOT / "hf_cache"
 COLLECTION_NAME = "options_knowledge"
 
-EMBED_MODEL_NAME = "BAAI/bge-small-en-v1.5"
+EMBED_MODEL_NAME = os.getenv("RAG_EMBED_MODEL", "BAAI/bge-small-en-v1.5")
+RERANKER_MODEL_NAME = os.getenv(
+    "RAG_RERANKER_MODEL", "cross-encoder/ms-marco-MiniLM-L-6-v2")
+RERANKER_BATCH_SIZE = int(os.getenv("RAG_RERANKER_BATCH_SIZE", "16"))
+EMBED_MODEL_METADATA_KEY = "embedding_model"
+BM25_METADATA_KEY = "bm25_score"
+VECTOR_METADATA_KEY = "vector_score"
 CHUNK_SIZE = 1000
 CHUNK_OVERLAP = 150
 PDF_REPEATED_LINE_MIN_PAGES = 3
@@ -68,31 +79,177 @@ def configure_model_cache() -> None:
     os.environ.setdefault("SENTENCE_TRANSFORMERS_HOME", str(
         HF_CACHE_DIR / "sentence_transformers"))
     os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
-    cached_model_dir = (
-        HF_CACHE_DIR
-        / "sentence_transformers"
-        / f"models--{EMBED_MODEL_NAME.replace('/', '--')}"
-    )
-    if cached_model_dir.exists():
+    if local_model_snapshot(EMBED_MODEL_NAME):
         os.environ.setdefault("HF_HUB_OFFLINE", "1")
         os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
 
 
-def resolve_embed_model_name() -> str:
+def local_model_snapshot(model_name: str) -> Optional[Path]:
     cached_model_dir = (
         HF_CACHE_DIR
         / "sentence_transformers"
-        / f"models--{EMBED_MODEL_NAME.replace('/', '--')}"
+        / f"models--{model_name.replace('/', '--')}"
     )
     snapshots_dir = cached_model_dir / "snapshots"
     if snapshots_dir.exists():
         snapshots = sorted(path for path in snapshots_dir.iterdir() if path.is_dir())
-        if snapshots:
-            return str(snapshots[-1])
+        for snapshot in reversed(snapshots):
+            if (snapshot / "config.json").exists():
+                return snapshot
+
+    return None
+
+
+def resolve_embed_model_name() -> str:
+    snapshot = local_model_snapshot(EMBED_MODEL_NAME)
+    if snapshot:
+        return str(snapshot)
 
     return EMBED_MODEL_NAME
 
 
+def resolve_reranker_model_name(model_name: str = RERANKER_MODEL_NAME) -> str:
+    snapshot = local_model_snapshot(model_name)
+    if snapshot:
+        return str(snapshot)
+
+    return model_name
+
+
+def env_flag(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def effective_raw_dir(raw_dir: Path = RAW_DIR) -> Path:
+    if any(iter_source_files(raw_dir)):
+        return raw_dir
+
+    legacy_raw_dir = LEGACY_KNOWLEDGE_BASE_DIR / "raw"
+    if any(iter_source_files(legacy_raw_dir)):
+        logging.warning(
+            "Using legacy knowledge base path %s. Move files to %s when convenient.",
+            legacy_raw_dir,
+            raw_dir,
+        )
+        return legacy_raw_dir
+
+    return raw_dir
+
+
+class CrossEncoderReranker:
+    def __init__(
+        self,
+        model_name: str = RERANKER_MODEL_NAME,
+        batch_size: int = RERANKER_BATCH_SIZE,
+    ):
+        self.model_name = model_name
+        self.batch_size = batch_size
+        self._model = None
+
+    def _load_model(self):
+        if self._model is not None:
+            return self._model
+
+        from sentence_transformers import CrossEncoder
+
+        self._model = CrossEncoder(
+            resolve_reranker_model_name(self.model_name),
+            max_length=512,
+            cache_folder=str(HF_CACHE_DIR / "sentence_transformers"),
+        )
+        return self._model
+
+    def rerank(
+        self,
+        query: str,
+        results: list[NodeWithScore],
+        top_n: Optional[int] = None,
+    ) -> list[NodeWithScore]:
+        if not results:
+            return []
+
+        pairs = [
+            (query, result.node.get_content())
+            for result in results
+        ]
+        model = self._load_model()
+        scores = model.predict(
+            pairs,
+            batch_size=self.batch_size,
+            show_progress_bar=False,
+        )
+
+        reranked = [
+            NodeWithScore(node=result.node, score=float(score))
+            for result, score in zip(results, scores)
+        ]
+        reranked.sort(key=lambda item: item.score or float("-inf"), reverse=True)
+        return reranked[:top_n] if top_n else reranked
+
+
+class BM25Retriever:
+    def __init__(self, nodes: list[TextNode]):
+        self.nodes = nodes
+        self.tokenized_docs = [self.tokenize(node.get_content()) for node in nodes]
+        self.doc_freqs: Counter[str] = Counter()
+        for tokens in self.tokenized_docs:
+            self.doc_freqs.update(set(tokens))
+        self.avg_doc_len = (
+            sum(len(tokens) for tokens in self.tokenized_docs) / len(self.tokenized_docs)
+            if self.tokenized_docs
+            else 0.0
+        )
+
+    @staticmethod
+    def tokenize(text: str) -> list[str]:
+        return [
+            token.lower()
+            for token in re.findall(r"[A-Za-z]+(?:[-'][A-Za-z]+)*|\d+(?:\.\d+)*|[^\sA-Za-z0-9]", text)
+            if token.strip()
+        ]
+
+    def score(self, query_tokens: list[str], doc_tokens: list[str]) -> float:
+        if not query_tokens or not doc_tokens:
+            return 0.0
+
+        token_counts = Counter(doc_tokens)
+        doc_len = len(doc_tokens)
+        total_docs = len(self.tokenized_docs)
+        k1 = 1.5
+        b = 0.75
+        score = 0.0
+
+        for token in query_tokens:
+            term_freq = token_counts.get(token, 0)
+            if term_freq == 0:
+                continue
+            doc_freq = self.doc_freqs.get(token, 0)
+            idf = math.log(1 + (total_docs - doc_freq + 0.5) / (doc_freq + 0.5))
+            denominator = term_freq + k1 * (
+                1 - b + b * doc_len / max(self.avg_doc_len, 1.0)
+            )
+            score += idf * (term_freq * (k1 + 1)) / denominator
+
+        return score
+
+    def retrieve(self, query: str, top_k: int) -> list[NodeWithScore]:
+        query_tokens = self.tokenize(query)
+        scored: list[NodeWithScore] = []
+
+        for node, doc_tokens in zip(self.nodes, self.tokenized_docs):
+            score = self.score(query_tokens, doc_tokens)
+            if score <= 0:
+                continue
+            node.metadata[BM25_METADATA_KEY] = score
+            scored.append(NodeWithScore(node=node, score=score))
+
+        scored.sort(key=lambda item: item.score or float("-inf"), reverse=True)
+        return scored[:top_k]
+
+
 def file_sha256(path: Path) -> str:
     digest = hashlib.sha256()
     with path.open("rb") as file:
@@ -116,6 +273,49 @@ def load_md_file(path: Path) -> Document:
     )
 
 
+def load_md_documents(path: Path) -> List[Document]:
+    text = path.read_text(encoding="utf-8")
+    file_hash = file_sha256(path)
+    documents: List[Document] = []
+    current_heading = ""
+    current_lines: List[str] = []
+
+    def flush() -> None:
+        nonlocal current_lines
+        section_text = "\n".join(current_lines).strip()
+        if not section_text:
+            current_lines = []
+            return
+        documents.append(
+            Document(
+                text=section_text,
+                metadata={
+                    "source_file": str(path.resolve()),
+                    "file_name": path.name,
+                    "file_type": path.suffix.lower().lstrip("."),
+                    "document_title": path.stem,
+                    "file_hash": file_hash,
+                    "content_type": "markdown_section",
+                    "chapter_title": "",
+                    "section_title": current_heading,
+                    "section_path": current_heading,
+                    "char_count": len(section_text),
+                },
+            )
+        )
+        current_lines = []
+
+    for line in text.splitlines():
+        heading_match = re.match(r"^(#{1,6})\s+(.+?)\s*$", line)
+        if heading_match:
+            flush()
+            current_heading = heading_match.group(2).strip()
+        current_lines.append(line)
+
+    flush()
+    return documents or [load_md_file(path)]
+
+
 def append_visual_fragment(line_parts: List[str], text: str, baseline_y: float, item: dict) -> None:
     if not text:
         return
@@ -1008,13 +1208,28 @@ def load_pdf_file(path: Path) -> List[Document]:
 
 
 def load_txt_file(path: Path) -> List[Document]:
-    # TODO: load text file
-    pass
-    return []
+    text = path.read_text(encoding="utf-8")
+    return [
+        Document(
+            text=text,
+            metadata={
+                "source_file": str(path.resolve()),
+                "file_name": path.name,
+                "file_type": "txt",
+                "document_title": path.stem,
+                "file_hash": file_sha256(path),
+                "content_type": "text",
+                "chapter_title": "",
+                "section_title": "",
+                "section_path": "",
+                "char_count": len(text),
+            },
+        )
+    ]
 
 
 def iter_source_files(raw_dir: Path) -> Iterable[Path]:
-    supported_suffixes = {".md", ".markdown", ".pdf"}
+    supported_suffixes = {".md", ".markdown", ".pdf", ".txt"}
     for path in sorted(raw_dir.rglob("*")):
         if path.is_file() and path.suffix.lower() in supported_suffixes:
             yield path
@@ -1022,12 +1237,13 @@ def iter_source_files(raw_dir: Path) -> Iterable[Path]:
 
 def load_docs(raw_dir: Path = RAW_DIR) -> List[Document]:
     documents: List[Document] = []
+    raw_dir = effective_raw_dir(raw_dir)
 
     for path in iter_source_files(raw_dir):
         suffix = path.suffix.lower()
 
         if suffix in {".md", ".markdown"}:
-            documents.append(load_md_file(path))
+            documents.extend(load_md_documents(path))
         elif suffix == ".pdf":
             documents.extend(load_pdf_file(path))
         elif suffix == ".txt":
@@ -1053,6 +1269,7 @@ def add_chunk_metadata(nodes: List[BaseNode]) -> List[BaseNode]:
 
         node.metadata["chunk_id"] = chunk_id
         node.metadata["chunk_index"] = chunk_index
+        node.metadata[EMBED_MODEL_METADATA_KEY] = EMBED_MODEL_NAME
         node.id_ = chunk_id
 
     return nodes
@@ -1073,8 +1290,7 @@ def validate_nodes(nodes: List[BaseNode]) -> None:
                 f"PDF node {node.node_id} is missing page_number metadata.")
 
 
-def build_nodes(raw_dir: Path = RAW_DIR) -> List[BaseNode]:
-    documents = load_docs(raw_dir)
+def split_documents(documents: List[Document]) -> List[BaseNode]:
     splitter = SentenceSplitter(
         chunk_size=CHUNK_SIZE,
         chunk_overlap=CHUNK_OVERLAP,
@@ -1085,7 +1301,123 @@ def build_nodes(raw_dir: Path = RAW_DIR) -> List[BaseNode]:
     return nodes
 
 
-def collection_needs_pdf_rebuild(chroma_collection) -> bool:
+def build_nodes(raw_dir: Path = RAW_DIR) -> List[BaseNode]:
+    documents = load_docs(raw_dir)
+    return split_documents(documents)
+
+
+def load_source_file(path: Path) -> List[Document]:
+    suffix = path.suffix.lower()
+    if suffix in {".md", ".markdown"}:
+        return load_md_documents(path)
+    if suffix == ".pdf":
+        return load_pdf_file(path)
+    if suffix == ".txt":
+        return load_txt_file(path)
+    return []
+
+
+def list_current_sources(raw_dir: Path = RAW_DIR) -> dict[str, dict[str, str]]:
+    raw_dir = effective_raw_dir(raw_dir)
+    sources = {}
+    for path in iter_source_files(raw_dir):
+        resolved = str(path.resolve())
+        sources[resolved] = {
+            "file_hash": file_sha256(path),
+            "file_type": path.suffix.lower().lstrip("."),
+        }
+    return sources
+
+
+def existing_source_metadata(chroma_collection) -> dict[str, dict[str, str]]:
+    existing: dict[str, dict[str, str]] = {}
+    if chroma_collection.count() == 0:
+        return existing
+
+    offset = 0
+    limit = 500
+    while True:
+        batch = chroma_collection.get(
+            limit=limit,
+            offset=offset,
+            include=["metadatas"],
+        )
+        metadatas = batch.get("metadatas") or []
+        if not metadatas:
+            break
+        for metadata in metadatas:
+            source_file = metadata.get("source_file")
+            if not source_file:
+                continue
+            existing[source_file] = {
+                "file_hash": metadata.get("file_hash", ""),
+                "file_type": metadata.get("file_type", ""),
+                "embedding_model": metadata.get(EMBED_MODEL_METADATA_KEY, ""),
+                "extraction_method": metadata.get("extraction_method", ""),
+            }
+        if len(metadatas) < limit:
+            break
+        offset += limit
+    return existing
+
+
+def source_needs_update(current: dict[str, str], existing: dict[str, str] | None) -> bool:
+    if not existing:
+        return True
+    if existing.get("file_hash") != current["file_hash"]:
+        return True
+    if existing.get("embedding_model") != EMBED_MODEL_NAME:
+        return True
+    if current["file_type"] == "pdf" and existing.get("extraction_method") != PDF_EXTRACTION_METHOD:
+        return True
+    return False
+
+
+def incremental_update_index(
+    raw_dir: Path,
+    chroma_collection,
+    storage_context: StorageContext,
+    embed_model,
+) -> bool:
+    current_sources = list_current_sources(raw_dir)
+    existing_sources = existing_source_metadata(chroma_collection)
+
+    deleted_sources = sorted(set(existing_sources) - set(current_sources))
+    changed_sources = sorted(
+        source_file
+        for source_file, current in current_sources.items()
+        if source_needs_update(current, existing_sources.get(source_file))
+    )
+
+    for source_file in deleted_sources + changed_sources:
+        try:
+            chroma_collection.delete(where={"source_file": source_file})
+        except Exception as exc:
+            logging.warning("Could not delete stale chunks for %s: %s", source_file, exc)
+
+    if not changed_sources:
+        if deleted_sources:
+            print(f"Removed {len(deleted_sources)} stale source(s) from collection '{COLLECTION_NAME}'.")
+        return bool(deleted_sources)
+
+    documents: List[Document] = []
+    for source_file in changed_sources:
+        documents.extend(load_source_file(Path(source_file)))
+
+    nodes = split_documents(documents)
+    VectorStoreIndex(
+        nodes,
+        storage_context=storage_context,
+        embed_model=embed_model,
+        show_progress=True,
+    )
+    print(
+        f"Incrementally indexed {len(nodes)} chunk(s) from {len(changed_sources)} source file(s)."
+    )
+    return True
+
+
+def collection_needs_rebuild(chroma_collection) -> bool:
     if chroma_collection.count() == 0:
         return True
 
@@ -1095,6 +1427,8 @@ def collection_needs_pdf_rebuild(chroma_collection) -> bool:
         return False
 
     for metadata in sample.get("metadatas") or []:
+        if metadata.get(EMBED_MODEL_METADATA_KEY) != EMBED_MODEL_NAME:
+            return True
         if metadata.get("file_type") == "pdf":
             return metadata.get("extraction_method") != PDF_EXTRACTION_METHOD
 
@@ -1107,6 +1441,7 @@ async def build_index(raw_dir: Path = RAW_DIR, rebuild: bool = False) -> VectorS
     from llama_index.embeddings.huggingface import HuggingFaceEmbedding
 
     load_dotenv()
+    raw_dir = effective_raw_dir(raw_dir)
     CHROMA_DB_DIR.mkdir(parents=True, exist_ok=True)
 
     db = chromadb.PersistentClient(path=str(CHROMA_DB_DIR))
@@ -1118,9 +1453,6 @@ async def build_index(raw_dir: Path = RAW_DIR, rebuild: bool = False) -> VectorS
             pass
 
     chroma_collection = db.get_or_create_collection(COLLECTION_NAME)
-    if not rebuild and collection_needs_pdf_rebuild(chroma_collection):
-        db.delete_collection(COLLECTION_NAME)
-        chroma_collection = db.get_or_create_collection(COLLECTION_NAME)
 
     vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
     storage_context = StorageContext.from_defaults(vector_store=vector_store)
@@ -1141,6 +1473,13 @@ async def build_index(raw_dir: Path = RAW_DIR, rebuild: bool = False) -> VectorS
             f"Indexed {len(nodes)} chunks into collection '{COLLECTION_NAME}'")
         return index
 
+    incremental_update_index(
+        raw_dir=raw_dir,
+        chroma_collection=chroma_collection,
+        storage_context=storage_context,
+        embed_model=embed_model,
+    )
+
     print(
         f"Loaded existing collection '{COLLECTION_NAME}' with {chroma_collection.count()} chunks.")
     return VectorStoreIndex.from_vector_store(vector_store, embed_model=embed_model)
@@ -1148,13 +1487,17 @@ async def build_index(raw_dir: Path = RAW_DIR, rebuild: bool = False) -> VectorS
 
 class QueryKnowledgeTool(Tool):
     name = "query_knowledge"
-    description = "Performs a search of related information based on your query"
+    description = (
+        "Searches the local options trading knowledge base. Use this for option "
+        "concepts, volatility, Greeks, strategies, formulas, equation numbers, "
+        "and citations from reference books."
+    )
     inputs = {'query': {'type': 'string',
                         'description': 'The search query to perform.'}}
     output_type = "string"
 
     @staticmethod
-    def format_results(results):
+    def format_results(results, max_chars: int = 800):
         output = []
 
         for result in results:
@@ -1166,6 +1509,8 @@ class QueryKnowledgeTool(Tool):
             formula_id = metadata.get("formula_id", "")
             score = result.score
             text = result.node.get_content()
+            if len(text) > max_chars:
+                text = f"{text[:max_chars].rstrip()}..."
 
             output.append(
                 f"source：{source}\n"
@@ -1174,20 +1519,139 @@ class QueryKnowledgeTool(Tool):
                 f"content_type：{content_type}\n"
                 f"formula_id：{formula_id or 'n/a'}\n"
                 f"score：{score:.4f}\n"
+                f"vector_score：{metadata.get(VECTOR_METADATA_KEY, 'n/a')}\n"
+                f"bm25_score：{metadata.get(BM25_METADATA_KEY, 'n/a')}\n"
                 f"content：{text}"
             )
 
         return "\n\n---\n\n".join(output)
 
-    def __init__(self, max_results=10, top_k=5, **kwargs):
+    @staticmethod
+    def load_bm25_nodes(collection_name: str = COLLECTION_NAME) -> list[TextNode]:
+        db = chromadb.PersistentClient(path=str(CHROMA_DB_DIR))
+        try:
+            collection = db.get_collection(collection_name)
+        except Exception:
+            return []
+
+        nodes: list[TextNode] = []
+        offset = 0
+        limit = 500
+        while True:
+            batch = collection.get(
+                limit=limit,
+                offset=offset,
+                include=["documents", "metadatas"],
+            )
+            documents = batch.get("documents") or []
+            metadatas = batch.get("metadatas") or []
+            ids = batch.get("ids") or []
+            if not documents:
+                break
+
+            for index, text in enumerate(documents):
+                metadata = dict(metadatas[index] or {})
+                node_id = ids[index] if index < len(ids) else metadata.get("chunk_id", "")
+                nodes.append(TextNode(id_=node_id, text=text or "", metadata=metadata))
+
+            if len(documents) < limit:
+                break
+            offset += limit
+
+        return nodes
+
+    @staticmethod
+    def merge_results(
+        vector_results: list[NodeWithScore],
+        bm25_results: list[NodeWithScore],
+        top_k: int,
+    ) -> list[NodeWithScore]:
+        merged: dict[str, NodeWithScore] = {}
+
+        for rank, result in enumerate(vector_results):
+            node_id = result.node.node_id
+            result.node.metadata[VECTOR_METADATA_KEY] = result.score
+            merged[node_id] = NodeWithScore(
+                node=result.node,
+                score=1.0 / (rank + 1),
+            )
+
+        for rank, result in enumerate(bm25_results):
+            node_id = result.node.node_id
+            result.node.metadata[BM25_METADATA_KEY] = result.score
+            reciprocal_rank_score = 1.0 / (rank + 1)
+            if node_id in merged:
+                merged[node_id].score = (merged[node_id].score or 0.0) + reciprocal_rank_score
+                merged[node_id].node.metadata[BM25_METADATA_KEY] = result.score
+            else:
+                merged[node_id] = NodeWithScore(
+                    node=result.node,
+                    score=reciprocal_rank_score,
+                )
+
+        results = list(merged.values())
+        results.sort(key=lambda item: item.score or float("-inf"), reverse=True)
+        return results[:top_k]
+
+    def __init__(
+        self,
+        max_results=20,
+        top_k=5,
+        use_reranker: Optional[bool] = None,
+        use_hybrid: Optional[bool] = None,
+        reranker_top_n: Optional[int] = None,
+        reranker_model_name: Optional[str] = None,
+        **kwargs,
+    ):
         super().__init__()
         self.max_results = max_results
+        self.top_k = top_k
+        self.use_reranker = (
+            env_flag("RAG_USE_RERANKER", True)
+            if use_reranker is None
+            else use_reranker
+        )
+        self.use_hybrid = (
+            env_flag("RAG_USE_HYBRID", True)
+            if use_hybrid is None
+            else use_hybrid
+        )
+        self.reranker_top_n = reranker_top_n or top_k
+        self.reranker = (
+            CrossEncoderReranker(reranker_model_name or RERANKER_MODEL_NAME)
+            if self.use_reranker
+            else None
+        )
         index = asyncio.run(build_index(rebuild=False))
-        self.retriever = index.as_retriever(similarity_top_k=top_k)
+        retrieve_top_k = max(max_results, top_k) if self.use_reranker else top_k
+        self.retriever = index.as_retriever(similarity_top_k=retrieve_top_k)
+        self.bm25_retriever = (
+            BM25Retriever(self.load_bm25_nodes())
+            if self.use_hybrid
+            else None
+        )
 
     def forward(self, query: str) -> str:
-        results = self.retriever.retrieve(query)
-        return QueryKnowledgeTool.format_results(results)
+        vector_results = self.retriever.retrieve(query)
+        results = vector_results
+        if self.bm25_retriever:
+            bm25_results = self.bm25_retriever.retrieve(query, self.max_results)
+            results = self.merge_results(
+                vector_results=vector_results,
+                bm25_results=bm25_results,
+                top_k=max(self.max_results, self.top_k),
+            )
+        if self.reranker:
+            try:
+                results = self.reranker.rerank(
+                    query,
+                    results,
+                    top_n=self.reranker_top_n,
+                )
+            except Exception as exc:
+                logging.warning("Reranker failed; falling back to vector ranking: %s", exc)
+                results = results[:self.top_k]
+        return QueryKnowledgeTool.format_results(results[:self.top_k])
 
 
 if __name__ == "__main__":

tools/todo.md

@@ -1,5 +1,437 @@
-1. 添加reranker
-2. 修改embedding模型
-3. chunk策略粗糙，建议按照章节、标题等进行划分
-4. 提升pdf提取能力
-5. 完成load_txt
+# OptionAgent 构建 TODO
+
+目标：构建一个能辅助期权交易研究的 agent。后续重点偏向波动率交易，而不是单纯方向性期权交易。它需要能查资料、查市场数据、分析 IV/RV/skew/term structure，生成波动率策略、回测策略，并根据回测结果迭代改进。所有输出必须带假设、风险、数据来源和限制说明，不直接承诺收益。
+
+## 0. 当前已有能力
+
+- [x] 本地 RAG：`QueryKnowledgeTool` 已接入主 agent，可查询期权书籍知识库。
+- [x] PDF RAG 优化：支持 PyMuPDF 提取、公式块识别、章节 metadata、页码引用。
+- [x] Hybrid search：dense retrieval + BM25 + reranker。
+- [x] 本地 RAG eval：支持 local-options eval、BEIR/fiqa、Open RAGBench。
+- [x] 基础市场价格工具：`query_market_asset` 可查询股票、指数、ETF、crypto、forex 的当前价格。
+- [x] Web search/visit webpage 已接入主 agent，并通过工具初始化与网页解析 mock 测试。
+- [x] 期权链、IV、Greeks、期限结构、偏斜等基础数据模块已完成 MVP，并通过 mock 测试。
+- [x] 策略构建模块 MVP 已完成：支持 5 类波动率策略候选。
+- [x] 回测模块 MVP 已完成：支持 payoff 情景分析、RV signal 历史回测 proxy、历史期权 bid/ask quote CSV 真实腿级回测。
+- [x] QuantConnect/LEAN 期权回测模板已加入：可用于接入真实历史期权链、撮合、组合持仓和保证金模型。
+- [x] 策略改进/优化闭环 MVP 已完成：支持参数扫描和 best vs baseline 对比。
+
+## 1. Research 模块：资料检索
+
+### 1.1 本地知识库 RAG
+
+- [x] 查询本地书籍、PDF、Markdown 知识库。
+- [x] 返回 source、page、section、content_type、score、excerpt。
+- [x] 支持公式 chunk 和正文 chunk。
+- [ ] 为期权策略类问题增加 query rewrite：
+  - 中文问题转英文检索词。
+  - 生成多个 query variants。
+  - 对公式/章节/策略/风险问题采用不同检索策略。
+- [ ] 增加 citation policy：
+  - agent 最终回答必须引用 RAG 来源。
+  - 没查到资料时明确说“不确定/资料不足”。
+
+### 1.2 Web Search
+
+- [x] 将 `DuckDuckGoSearchTool` 和 `VisitWebpageTool` 接入 `app.py` 的 tools。
+- [x] 修复 `VisitWebpageTool` 中缺失的 `re` import。
+- [x] 给 web search 加使用边界：
+  - 用于查最新市场事件、宏观事件、财报日期、公司公告、交易所规则。
+  - 本地书籍知识优先用 RAG，实时信息优先用 web。
+- [x] Web 结果返回标题、URL 和摘要；发布时间后续按数据源能力增强。
+- [ ] 对高风险市场信息做多源交叉验证。
+
+## 2. Market Data 模块：市场数据与期权数据
+
+### 2.1 标的行情
+
+- [x] 当前价格、日内 OHLC、成交量。
+- [x] 增加历史价格接口：
+  - 日线、小时线、分钟线。
+  - 支持 start/end/period/interval 参数。
+  - 输出用于回测的标准 DataFrame/JSON。
+- [x] 增加 realized volatility 计算：
+  - 10D/20D/30D/60D realized vol。
+  - Parkinson/Garman-Klass 可选。
+
+### 2.2 期权链
+
+- [x] 新增 `query_option_chain(symbol, expiration)` tool。
+- [x] 返回 calls/puts：
+  - strike
+  - bid/ask/mid/last
+  - volume/open_interest
+  - implied_volatility
+  - in_the_money
+  - expiration
+  - days_to_expiration
+- [x] 支持列出全部 expiration dates。
+- [x] 对无流动性合约做标记：
+  - bid/ask 缺失
+  - spread 过宽
+  - volume/OI 过低
+
+### 2.3 Greeks 与波动率结构
+
+- [x] 新增 Greeks 计算模块：
+  - delta/gamma/vega/theta/rho。
+  - 支持 Black-Scholes-Merton。
+  - 支持 dividend yield / risk-free rate 参数。
+- [x] 新增 IV surface / skew 分析 MVP：
+  - ATM IV。
+  - 近似 put-call skew。
+  - ATM IV term structure slope。
+  - IV percentile / rank 后续在 Milestone 2 完成。
+- [x] 新增 volatility trading 专用指标 MVP：
+  - realized volatility: 5D/10D/20D/30D/60D。
+  - implied vs realized spread。
+  - volatility risk premium: IV - RV。
+  - IV term structure slope。
+  - skew slope / put-call skew。
+  - vol-of-vol proxy 后续增强。
+  - event IV premium 后续增强。
+- [ ] 对 yfinance IV 字段做 sanity check：
+  - IV 为 0、缺失、异常值时标记。
+  - bid/ask/mid 不合理时不参与策略构建。
+
+### 2.4 数据源抽象
+
+- [x] 建立 `market_data/` 模块，避免所有行情逻辑堆在 `app.py`。
+- [x] 设计统一 schema：
+  - `UnderlyingQuote`
+  - `OptionContract`
+  - `OptionChain`
+  - `VolSnapshot`
+- [x] 第一阶段可用 yfinance，后续可接 Polygon/Tradier/IBKR。
+
+## 3. Strategy Builder 模块：策略构建
+
+后续策略构建以波动率观点为核心，方向观点为辅助变量。
+
+### 3.1 用户意图解析
+
+- [ ] 解析用户输入：
+  - 标的 symbol。
+  - 波动率观点：long vol / short vol / vol mean reversion / event vol / skew trade。
+  - 方向观点：bullish/bearish/neutral/range-bound。
+  - 时间周期。
+  - 风险承受。
+  - 账户约束/最大亏损。
+  - 是否允许裸卖。
+- [ ] 如果关键信息缺失，agent 需要追问，而不是直接生成交易。
+
+### 3.2 策略候选生成
+
+- [ ] 支持基础策略模板：
+  - long call / long put
+  - covered call
+  - cash-secured put
+  - vertical spread
+  - calendar spread
+  - straddle / strangle
+  - iron condor
+  - collar
+- [x] 支持波动率交易策略模板 MVP：
+  - long straddle / long strangle
+  - short straddle / short strangle
+  - delta-hedged straddle
+  - calendar spread
+  - diagonal spread
+  - variance-style option basket approximation
+  - skew trade: risk reversal / put spread vs call spread
+  - term structure trade: near-term short vol + longer-term long vol
+- [x] 每个策略输出：
+  - legs
+  - expiration
+  - strike
+  - net debit/credit
+  - max profit
+  - max loss
+  - breakeven
+  - margin estimate
+  - Greeks exposure
+  - liquidity warnings
+
+### 3.3 策略筛选规则
+
+- [ ] 根据市场状态筛选策略：
+  - 高 IV：偏向 credit spread / iron condor / covered call。
+  - 低 IV：偏向 long options / calendar / debit spread。
+  - 趋势观点强：vertical spread / directional options。
+  - 震荡观点：short premium / condor。
+- [ ] 根据波动率状态筛选策略：
+  - IV 明显高于 RV：考虑 short vol，但必须检查事件风险和尾部风险。
+  - IV 明显低于 RV：考虑 long vol，但必须检查 theta bleed。
+  - 近月 IV 异常高：考虑 calendar/diagonal 或 event vol 策略。
+  - skew 极端：考虑 risk reversal、put spread、skew mean reversion。
+  - term structure 陡峭：考虑跨期限 vol trade。
+- [ ] 加入风险约束：
+  - max loss 不超过用户预算。
+  - spread 不能过宽。
+  - OI/volume 低的合约排除。
+  - 禁止默认裸卖期权。
+- [ ] 输出多个候选策略并排序，而不是只给一个。
+
+### 3.4 策略解释
+
+- [ ] 每个策略必须解释：
+  - 为什么适合当前市场。
+  - 主要盈利条件。
+  - 主要亏损场景。
+  - Greeks 风险。
+  - IV crush / event risk。
+  - Vega / gamma / theta trade-off。
+  - Long vol 或 short vol 的核心假设。
+  - 流动性和滑点风险。
+- [ ] 必须引用 RAG/web/market data 来源。
+
+## 3.5 Volatility Research 模块：波动率交易研究
+
+- [x] 构建 volatility dashboard MVP：
+  - current IV vs historical IV range。
+  - IV percentile / rank。
+  - realized volatility windows。
+  - IV-RV spread。
+  - term structure chart。
+  - skew chart。
+- [x] 识别波动率 regime MVP：
+  - low vol regime。
+  - high vol regime。
+  - vol expansion。
+  - vol compression。
+  - event-driven vol。
+- [ ] 事件模块：
+  - earnings date。
+  - CPI/FOMC/NFP 等宏观事件。
+  - event implied move。
+  - post-event IV crush risk。
+- [x] 输出波动率观点 MVP：
+  - long vol / short vol / neutral。
+  - confidence。
+  - key assumptions。
+  - invalidation conditions。
+
+## 4. Backtesting 模块：回测与情景分析
+
+### 4.1 第一阶段：Payoff 与情景分析
+
+- [x] 新增 `backtest/` 模块。
+- [x] 实现到期 payoff 情景表：
+  - 不同标的价格下 PnL。
+  - breakeven。
+  - max loss/max profit。
+- [x] 实现情景分析 MVP：
+  - underlying price shock。
+  - IV up/down。
+  - days passed / theta decay。
+  - Greeks approximation。
+- [x] 增加波动率情景 MVP：
+  - IV crush。
+  - IV expansion。
+  - realized move vs implied move。
+  - gamma scalp breakeven move。
+  - delta-hedging frequency sensitivity。
+- [x] 输出表格和 JSON，方便 agent 总结。
+
+### 4.2 第二阶段：历史回测
+
+- [x] 获取历史 underlying price。
+- [ ] 获取或近似历史 IV：
+  - 优先真实历史 option chain。
+  - 没有数据时用 realized vol 或当前 IV 做近似，并明确标注限制。
+- [x] 支持真实历史期权 quote CSV 输入：
+  - 必需字段：date、underlying_symbol、underlying_price、contract_symbol、option_type、expiration、strike、bid、ask。
+  - 可选字段：mid、delta、gamma、theta、vega、implied_volatility、volume、open_interest。
+  - 当前实现可做 ATM long straddle 的真实开仓/平仓腿级 PnL。
+  - 注意：yfinance 不能可靠提供历史 option chain，严肃回测需要 Polygon/ORATS/OptionMetrics/QuantConnect 等数据源。
+- [x] 设计 entry/exit rules MVP：
+  - 入场条件。
+  - 出场条件。
+  - DTE 管理。
+  - 固定 holding period。
+  - 固定 entry frequency。
+- [ ] 设计高级 entry/exit rules：
+  - 止盈止损。
+  - rolling 规则。
+- [x] 为波动率策略增加专门规则 MVP：
+  - IV percentile 入场阈值。
+  - IV-RV spread 入场阈值。
+  - earnings 前后入场/退出。
+  - DTE bucket。
+  - delta hedge 频率。
+  - gamma scalp rule。
+- [x] 计算指标 MVP：
+  - total PnL
+  - max drawdown
+  - win rate
+  - avg win/loss
+- [ ] 计算高级指标：
+  - total return
+  - CAGR
+  - Sharpe/Sortino
+  - exposure time
+  - tail loss
+  - realized vs implied PnL attribution
+  - theta PnL
+  - vega PnL
+  - gamma scalping PnL
+
+### 4.3 第三阶段：组合级回测
+
+- [x] 支持单策略多笔交易 MVP。
+- [ ] 支持多策略/多标的组合交易。
+- [ ] 支持现金、保证金、仓位占用。
+- [x] 支持交易成本、bid/ask slippage MVP。
+- [ ] 支持 assignment / early exercise 风险近似。
+- [x] 生成交易日志 MVP。
+- [ ] 生成风险归因。
+
+## 5. Strategy Optimizer 模块：回测后改进
+
+- [x] 根据回测结果自动提出改进 MVP：
+  - 调整 expiration。
+  - 调整 strike/delta。
+  - 调整止盈止损。
+  - 限制入场市场环境。
+  - 避开财报/宏观事件。
+- [ ] 对波动率策略提出专门改进：
+  - 调整 long/short vol 入场 IV percentile。
+  - 调整 straddle/strangle delta。
+  - 调整 delta hedge 频率。
+  - 调整 DTE bucket。
+  - 避开或利用 event vol。
+  - 加入 tail hedge。
+- [x] 支持参数扫描 MVP：
+  - DTE range。
+  - delta target。
+  - width。
+  - profit target。
+  - stop loss。
+  - IV percentile threshold。
+  - IV-RV spread threshold。
+  - hedge frequency。
+- [x] 输出对比表：
+  - baseline strategy
+  - improved strategy
+  - metrics delta
+  - trade-off
+- [ ] 防止过拟合：
+  - train/test split。
+  - walk-forward analysis。
+  - out-of-sample period。
+
+## 6. Agent Orchestrator 模块：完整工作流
+
+- [ ] 定义标准工作流：
+
+```text
+用户提出目标
+  -> 解析意图和约束
+  -> 查询 RAG/web 背景资料
+  -> 查询标的行情和期权链
+  -> 分析 IV/Greeks/流动性
+  -> 生成多个策略候选
+  -> 初步风险筛选
+  -> 回测/情景分析
+  -> 改进策略
+  -> 输出最终报告
+```
+
+- [x] 增加 agent prompt 约束：
+  - 不承诺收益。
+  - 不给无风险建议。
+  - 必须说明假设和数据限制。
+  - 必须输出最大亏损。
+  - 必须说明流动性、滑点、IV、事件风险。
+- [x] 增加结构化输出格式：
+  - `market_context`
+  - `strategy_candidates`
+  - `selected_strategy`
+  - `backtest_summary`
+  - `risk_warnings`
+  - `sources`
+
+## 7. UI / Report 模块
+
+- [ ] Gradio UI 支持输入：
+  - symbol
+  - outlook
+  - time horizon
+  - risk budget
+  - strategy preference
+- [ ] 展示：
+  - 策略 legs 表格。
+  - payoff 图。
+  - Greeks 表格。
+  - 回测指标。
+  - 引用来源。
+- [ ] 支持导出 Markdown/HTML report。
+
+## 8. Evaluation 模块
+
+- [x] RAG retrieval eval。
+- [x] Market data tool 单元测试：已覆盖 RV、Greeks、历史价格 tool、期权链 tool、volatility snapshot mock。
+- [x] Strategy builder 单元测试：
+  - payoff 计算正确。
+  - max loss/max profit 正确。
+  - breakeven 正确。
+- [x] Backtest engine 测试：
+  - 单腿/多腿 payoff。
+  - 交易成本。
+  - rolling/exit rule。
+- [ ] Agent end-to-end 测试：
+  - 给定 symbol + outlook，能完整输出策略、风险和来源。
+
+## 9. 推荐实现顺序
+
+### Milestone 1：Research + Market Data 可用
+
+- [x] 接入 web search 和 visit webpage 到主 agent。
+- [x] 修复 `VisitWebpageTool`。
+- [x] 新增 option chain 查询工具。
+- [x] 新增 Greeks/IV 基础计算。
+- [x] 新增 IV/RV/skew/term structure 基础分析。
+- [x] 将行情代码从 `app.py` 拆到独立模块。
+
+### Milestone 2：Volatility Dashboard MVP
+
+- [x] 计算 realized volatility windows。
+- [x] 计算 ATM IV、IV rank/percentile proxy。
+- [x] 计算 IV-RV spread。
+- [x] 计算 skew 和 term structure。
+- [x] 输出 volatility regime 判断。
+
+### Milestone 3：波动率策略生成 MVP
+
+- [x] 定义策略 leg schema。
+- [x] 实现 5 个优先策略模板：
+  - long straddle
+  - long strangle
+  - short straddle
+  - calendar spread
+  - iron condor
+- [x] 实现 payoff/max loss/breakeven 计算。
+- [x] 根据 volatility regime 和 IV/RV 状态生成候选策略 MVP。
+
+### Milestone 4：回测 MVP
+
+- [x] 实现到期 payoff 和情景分析。
+- [x] 实现历史 underlying 回测 MVP。
+- [x] 实现 IV/RV 条件入场回测 MVP。
+- [x] 实现历史期权 quote CSV 的真实 long straddle 回测 MVP。
+- [x] 添加 QuantConnect/LEAN ATM long straddle 回测模板。
+- [x] 实现 straddle/strangle 的 delta hedge 情景分析 proxy。
+- [x] 输出核心指标和交易日志。
+
+### Milestone 5：优化闭环
+
+- [x] 参数扫描。
+- [x] 策略改进建议 MVP。
+- [x] 对比报告。
+- [ ] 防过拟合验证。
+
+### Milestone 6：完整 Agent 工作流
+
+- [x] 统一 prompt 和输出格式。
+- [ ] Gradio UI 展示策略、图表和回测。
+- [ ] 端到端测试。

tools/visit_webpage.py

@@ -1,15 +1,20 @@
-from typing import Any, Optional
+import re
+
 from smolagents.tools import Tool
-import requests
-import markdownify
-import smolagents
 
 class VisitWebpageTool(Tool):
     name = "visit_webpage"
-    description = "Visits a webpage at the given url and reads its content as a markdown string. Use this to browse webpages."
+    description = (
+        "Visits a webpage at the given URL and returns its readable Markdown content. "
+        "Use this after web_search when current market news, company events, "
+        "earnings information, exchange rules, or source verification is needed."
+    )
     inputs = {'url': {'type': 'string', 'description': 'The url of the webpage to visit.'}}
     output_type = "string"
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
     def forward(self, url: str) -> str:
         try:
             import requests
@@ -40,6 +45,3 @@ class VisitWebpageTool(Tool):
             return f"Error fetching the webpage: {str(e)}"
         except Exception as e:
             return f"An unexpected error occurred: {str(e)}"
-
-    def __init__(self, *args, **kwargs):
-        self.is_initialized = False

tools/web_search.py

@@ -1,10 +1,12 @@
-from typing import Any, Optional
 from smolagents.tools import Tool
-import duckduckgo_search
 
 class DuckDuckGoSearchTool(Tool):
     name = "web_search"
-    description = "Performs a duckduckgo web search based on your query (think a Google search) then returns the top search results."
+    description = (
+        "Searches the web for current information. Use this for recent market events, "
+        "earnings dates, company announcements, macro events, current rules, or "
+        "source discovery. Prefer the local knowledge base for stable options concepts."
+    )
     inputs = {'query': {'type': 'string', 'description': 'The search query to perform.'}}
     output_type = "string"
 

uv.lock

@@ -2,9 +2,15 @@ version = 1
 revision = 3
 requires-python = ">=3.12"
 resolution-markers = [
-    "python_full_version >= '3.14'",
-    "python_full_version == '3.13.*'",
-    "python_full_version < '3.13'",
+    "python_full_version >= '3.14' and sys_platform == 'win32'",
+    "python_full_version >= '3.14' and sys_platform == 'emscripten'",
+    "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32'",
+    "python_full_version == '3.13.*' and sys_platform == 'win32'",
+    "python_full_version == '3.13.*' and sys_platform == 'emscripten'",
+    "python_full_version == '3.13.*' and sys_platform != 'emscripten' and sys_platform != 'win32'",
+    "python_full_version < '3.13' and sys_platform == 'win32'",
+    "python_full_version < '3.13' and sys_platform == 'emscripten'",
+    "python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 
 [[package]]
@@ -246,6 +252,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/27/44/d2ef5e87509158ad2187f4dd0852df80695bb1ee0cfe0a684727b01a69e0/bcrypt-5.0.0-cp39-abi3-win_arm64.whl", hash = "sha256:f2347d3534e76bf50bca5500989d6c1d05ed64b440408057a37673282c654927", size = 144953, upload-time = "2025-09-25T19:50:37.32Z" },
 ]
 
+[[package]]
+name = "beautifulsoup4"
+version = "4.14.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "soupsieve" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b0/1c6a16426d389813b48d95e26898aff79abbde42ad353958ad95cc8c9b21/beautifulsoup4-4.14.3.tar.gz", hash = "sha256:6292b1c5186d356bba669ef9f7f051757099565ad9ada5dd630bd9de5fa7fb86", size = 627737, upload-time = "2025-11-30T15:08:26.084Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1a/39/47f9197bdd44df24d67ac8893641e16f386c984a0619ef2ee4c51fbbc019/beautifulsoup4-4.14.3-py3-none-any.whl", hash = "sha256:0918bfe44902e6ad8d57732ba310582e98da931428d231a5ecb9e7c703a735bb", size = 107721, upload-time = "2025-11-30T15:08:24.087Z" },
+]
+
 [[package]]
 name = "build"
 version = "1.5.0"
@@ -520,7 +539,7 @@ name = "cuda-bindings"
 version = "12.9.4"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "cuda-pathfinder" },
+    { name = "cuda-pathfinder", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/a9/c1/dabe88f52c3e3760d861401bb994df08f672ec893b8f7592dc91626adcf3/cuda_bindings-12.9.4-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fda147a344e8eaeca0c6ff113d2851ffca8f7dfc0a6c932374ee5c47caa649c8", size = 12151019, upload-time = "2025-10-21T14:51:43.167Z" },
@@ -538,6 +557,39 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/11/d0/c177e29701cf1d3008d7d2b16b5fc626592ce13bd535f8795c5f57187e0e/cuda_pathfinder-1.5.4-py3-none-any.whl", hash = "sha256:9563d3175ce1828531acf4b94e1c1c7d67208c347ca002493e2654878b26f4b7", size = 51657, upload-time = "2026-04-27T22:42:07.712Z" },
 ]
 
+[[package]]
+name = "curl-cffi"
+version = "0.15.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "cffi" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/48/5b/89fcfebd3e5e85134147ac99e9f2b2271165fd4d71984fc65da5f17819b7/curl_cffi-0.15.0.tar.gz", hash = "sha256:ea0c67652bf6893d34ee0f82c944f37e488f6147e9421bef1771cc6545b02ded", size = 196437, upload-time = "2026-04-03T11:12:31.525Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5e/42/54ddd442c795f30ce5dd4e49f87ce77505958d3777cd96a91567a3975d2a/curl_cffi-0.15.0-cp310-abi3-macosx_10_9_x86_64.whl", hash = "sha256:bda66404010e9ed743b1b83c20c86f24fe21a9a6873e17479d6e67e29d8ded28", size = 2795267, upload-time = "2026-04-03T11:11:46.48Z" },
+    { url = "https://files.pythonhosted.org/packages/83/2d/3915e238579b3c5a92cead5c79130c3b8d20caaba7616cc4d894650e1d6b/curl_cffi-0.15.0-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:a25620d9bf989c9c029a7d1642999c4c265abb0bad811deb2f77b0b5b2b12e5b", size = 2573544, upload-time = "2026-04-03T11:11:47.951Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/b3/9d2f1057749a1b07ba1989db3c1503ce8bed998310bae9aea2c43aa64f20/curl_cffi-0.15.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:582e570aa2586b96ed47cf4a17586b9a3c462cbe43f780487c3dc245c6ef1527", size = 10515369, upload-time = "2026-04-03T11:11:50.126Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/1d/6d10dded5ce3fd8157e558ebd97d09e551b77a62cdc1c31e93d0a633cee5/curl_cffi-0.15.0-cp310-abi3-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:838e48212447d9c81364b04707a5c861daf08f8320f9ecb3406a8919d1d5c3b3", size = 10160045, upload-time = "2026-04-03T11:11:52.664Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/12/c70b835487ace3b9ba1502631912e3440082b8ae3a162f60b59cb0b6444d/curl_cffi-0.15.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:2b6c847d86283b07ae69bb72c82eb8a59242277142aa35b89850f89e792a02fc", size = 11090433, upload-time = "2026-04-03T11:11:55.049Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/0d/78edcc4f71934225db99df68197a107386d59080742fc7bf6bb4d007924f/curl_cffi-0.15.0-cp310-abi3-manylinux_2_28_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:9e5e69eee735f659287e2c84444319d68a1fa68dd37abf228943a4074864283a", size = 10479178, upload-time = "2026-04-03T11:11:57.685Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/84/1e101c1acb1ea2f0b4992f5c3024f596d8e21db0d53540b9d583f673c4e7/curl_cffi-0.15.0-cp310-abi3-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:aa1323950224db24f4c510d010b3affa02196ca853fb424191fa917a513d3f4b", size = 10317051, upload-time = "2026-04-03T11:12:00.295Z" },
+    { url = "https://files.pythonhosted.org/packages/28/42/8ef236b22a6c23d096c85a1dc507efe37bfdfc7a2f8a4b34efb590197369/curl_cffi-0.15.0-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:41f80170ba844009273b2660da1964ec31e99e5719d16b3422ada87177e32e13", size = 11299660, upload-time = "2026-04-03T11:12:02.791Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/01/56aeb055d962da87a1be0d74c6c644e251c7e88129b5471dc44ac724e678/curl_cffi-0.15.0-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:1977e1e12cfb5c11352cbb74acef1bed24eb7d226dab61ca57c168c21acd4d61", size = 11945049, upload-time = "2026-04-03T11:12:05.912Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/8c/2abf99a38d6340d66cf0557e0c750ef3f8883dfc5d450087e01c85861343/curl_cffi-0.15.0-cp310-abi3-win_amd64.whl", hash = "sha256:5a0c1896a0d5a5ac1eb89cd24b008d2b718dd1df6fd2f75451b59ca66e49e572", size = 1661649, upload-time = "2026-04-03T11:12:07.948Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/39/dfd54f2240d3a9b96d77bacc62b97813b35e2aa8ecf5cd5013c683f1ba96/curl_cffi-0.15.0-cp310-abi3-win_arm64.whl", hash = "sha256:a6d57f8389273a3a1f94370473c74897467bcc36af0a17336989780c507fa43d", size = 1410741, upload-time = "2026-04-03T11:12:10.073Z" },
+    { url = "https://files.pythonhosted.org/packages/19/6a/c24df8a4fc22fa84070dcd94abeba43c15e08cc09e35869565c0bad196fd/curl_cffi-0.15.0-cp313-abi3-android_24_arm64_v8a.whl", hash = "sha256:4682dc38d4336e0eb0b185374db90a760efde63cbea994b4e63f3521d44c4c92", size = 7190427, upload-time = "2026-04-03T11:12:12.142Z" },
+    { url = "https://files.pythonhosted.org/packages/11/56/132225cb3491d07cc6adcce5fe395e059bde87c68cff1ef87a31c88c7819/curl_cffi-0.15.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:967ad7355bd8e9586f8c2d02eaa99953747549e7ea4a9b25cd53353e6b67fe6d", size = 2795723, upload-time = "2026-04-03T11:12:13.668Z" },
+    { url = "https://files.pythonhosted.org/packages/07/8f/f4f83cd303bef7e8f1749512e5dd157e7e5d08b0a36c8211f9640a2757bf/curl_cffi-0.15.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7e63539d0d839d0a8c5eacf86229bc68c57803547f35e0db7ee0986328b478c3", size = 2573739, upload-time = "2026-04-03T11:12:15.08Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/5c/643d65c7fc9acd742876aa55c2d7823c438cb7665810acd2e66c9976c4d9/curl_cffi-0.15.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:08c799b89740b9bc49c09fbc3d5907f13ac1f845ca52620507ef9466d4639dd5", size = 10521046, upload-time = "2026-04-03T11:12:17.034Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/0b/9b8037113c93f4c5323096163471fa7c35c7676c3f608eeaf1287cd99d58/curl_cffi-0.15.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7b7a92767a888ee90147e18964b396d8435ff42737030d6fb00824ffd6094805", size = 11096115, upload-time = "2026-04-03T11:12:19.694Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/96/fff2fcbd924ef4042e0d67379f751a8a4e3186a91e75e35a4cf218b306ee/curl_cffi-0.15.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:829cc357061ecb99cc2d406301f609a039e05665322f5c025ec67c38b0dc49ce", size = 11305346, upload-time = "2026-04-03T11:12:22.151Z" },
+    { url = "https://files.pythonhosted.org/packages/53/1b/304b253a45ab28691c8c5e8cca1e6cbb9cf8e46dfceae4648dd536f75e73/curl_cffi-0.15.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:408d6f14e346841cd889c2e0962832bb235ba3b6749ebf609f347f747da5e60f", size = 11949834, upload-time = "2026-04-03T11:12:24.986Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/ff/4723d92f08259c707a974aba27a08d0a822b9555e35ca581bf18d055a364/curl_cffi-0.15.0-cp314-cp314t-win_amd64.whl", hash = "sha256:b624c7ce087bfda967a013ed0a64702a525444e5b6e97d23534d567ccc6525aa", size = 1702771, upload-time = "2026-04-03T11:12:28.201Z" },
+    { url = "https://files.pythonhosted.org/packages/59/8c/36bbe06d66fa2b765e4a07199f643a59a9cd1a754207a96335402a9520f4/curl_cffi-0.15.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0b6c0543b993996670e9e4b78e305a2d60809d5681903ffb5568e21a387434d3", size = 1466312, upload-time = "2026-04-03T11:12:30.054Z" },
+]
+
 [[package]]
 name = "dataclasses-json"
 version = "0.6.7"
@@ -660,10 +712,12 @@ dependencies = [
     { name = "llama-index-core" },
     { name = "llama-index-embeddings-huggingface" },
     { name = "llama-index-vector-stores-chroma" },
+    { name = "pandas" },
     { name = "pymupdf" },
     { name = "pypdf" },
     { name = "tokenizers" },
     { name = "transformers" },
+    { name = "yfinance" },
 ]
 
 [package.metadata]
@@ -674,10 +728,12 @@ requires-dist = [
     { name = "llama-index-core", specifier = ">=0.14.0" },
     { name = "llama-index-embeddings-huggingface", specifier = ">=0.6.0" },
     { name = "llama-index-vector-stores-chroma", specifier = ">=0.5.0" },
+    { name = "pandas", specifier = ">=2.0.0" },
     { name = "pymupdf", specifier = ">=1.27.2.3" },
     { name = "pypdf", specifier = ">=6.0.0" },
     { name = "tokenizers", specifier = ">=0.22.0,<=0.23.0" },
     { name = "transformers", specifier = "<5" },
+    { name = "yfinance", specifier = ">=0.2.0" },
 ]
 
 [[package]]
@@ -1675,6 +1731,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/81/08/7036c080d7117f28a4af526d794aab6a84463126db031b007717c1a6676e/multidict-6.7.1-py3-none-any.whl", hash = "sha256:55d97cc6dae627efa6a6e548885712d4864b81110ac76fa4e534c03819fa4a56", size = 12319, upload-time = "2026-01-26T02:46:44.004Z" },
 ]
 
+[[package]]
+name = "multitasking"
+version = "0.0.13"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/be/c3/ac2cc9307fb15cc28ed6d4a9266b216c83ee7fe64299f0264047982bce88/multitasking-0.0.13.tar.gz", hash = "sha256:d896b5df877c9ca5eeddbf0e5994124694d6cb535aba698fb23344c7025155a1", size = 20585, upload-time = "2026-04-23T12:14:15.049Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d3/1c/24dbf69b247f287401c904a396233a43c89fd4fb9b7cd2e50e430e9cd57c/multitasking-0.0.13-py3-none-any.whl", hash = "sha256:ec9243af140c67bfe52dc98d7173c294512735a88e8425c458b250db99dc2b48", size = 16380, upload-time = "2026-04-23T12:14:13.776Z" },
+]
+
 [[package]]
 name = "mypy-extensions"
 version = "1.1.0"
@@ -1815,7 +1880,7 @@ name = "nvidia-cudnn-cu12"
 version = "9.10.2.21"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12" },
+    { name = "nvidia-cublas-cu12", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/ba/51/e123d997aa098c61d029f76663dedbfb9bc8dcf8c60cbd6adbe42f76d049/nvidia_cudnn_cu12-9.10.2.21-py3-none-manylinux_2_27_x86_64.whl", hash = "sha256:949452be657fa16687d0930933f032835951ef0892b37d2d53824d1a84dc97a8", size = 706758467, upload-time = "2025-06-06T21:54:08.597Z" },
@@ -1826,7 +1891,7 @@ name = "nvidia-cufft-cu12"
 version = "11.3.3.83"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-nvjitlink-cu12", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/1f/13/ee4e00f30e676b66ae65b4f08cb5bcbb8392c03f54f2d5413ea99a5d1c80/nvidia_cufft_cu12-11.3.3.83-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:4d2dd21ec0b88cf61b62e6b43564355e5222e4a3fb394cac0db101f2dd0d4f74", size = 193118695, upload-time = "2025-03-07T01:45:27.821Z" },
@@ -1853,9 +1918,9 @@ name = "nvidia-cusolver-cu12"
 version = "11.7.3.90"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12" },
-    { name = "nvidia-cusparse-cu12" },
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-cublas-cu12", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "nvidia-cusparse-cu12", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "nvidia-nvjitlink-cu12", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/85/48/9a13d2975803e8cf2777d5ed57b87a0b6ca2cc795f9a4f59796a910bfb80/nvidia_cusolver_cu12-11.7.3.90-py3-none-manylinux_2_27_x86_64.whl", hash = "sha256:4376c11ad263152bd50ea295c05370360776f8c3427b30991df774f9fb26c450", size = 267506905, upload-time = "2025-03-07T01:47:16.273Z" },
@@ -1866,7 +1931,7 @@ name = "nvidia-cusparse-cu12"
 version = "12.5.8.93"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12" },
+    { name = "nvidia-nvjitlink-cu12", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/c2/f5/e1854cb2f2bcd4280c44736c93550cc300ff4b8c95ebe370d0aa7d2b473d/nvidia_cusparse_cu12-12.5.8.93-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:1ec05d76bbbd8b61b06a80e1eaf8cf4959c3d4ce8e711b65ebd0443bb0ebb13b", size = 288216466, upload-time = "2025-03-07T01:48:13.779Z" },
@@ -2124,6 +2189,67 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/df/b2/87e62e8c3e2f4b32e5fe99e0b86d576da1312593b39f47d8ceef365e95ed/packaging-26.2-py3-none-any.whl", hash = "sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e", size = 100195, upload-time = "2026-04-24T20:15:22.081Z" },
 ]
 
+[[package]]
+name = "pandas"
+version = "3.0.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "numpy" },
+    { name = "python-dateutil" },
+    { name = "tzdata", marker = "sys_platform == 'emscripten' or sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f8/87/4341c6252d1c47b08768c3d25ac487362bf403f0313ddae4a2a26c9b1b4c/pandas-3.0.3.tar.gz", hash = "sha256:696a4a00a2a2a35d4e5deb3fc946641b96c944f02230e4f76137fe35d806c4fc", size = 4651414, upload-time = "2026-05-11T18:54:29.21Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/f1/392f8c5bfc16f66a0d2d41561c01627c228fe7ed2a0d056ef11315042570/pandas-3.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:fed2ff7fd9779120e388e285fc029bd5cf9490cdd2e4166a9ee22c0e49a9ab09", size = 10357846, upload-time = "2026-05-11T18:52:36.143Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/3d/b16412745651e855f357e5e66930248688378853a6e2698a214e331fba1f/pandas-3.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b168fc218fd80a6cbdbdbc1a97ddc7889ed057d7eb45f50d866ceab5f39904c4", size = 9899550, upload-time = "2026-05-11T18:52:38.976Z" },
+    { url = "https://files.pythonhosted.org/packages/31/a8/fa2535168fffcedf67f4f6de28d2dd903a747ca7c8ea6989451aaeb3a92f/pandas-3.0.3-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0383c72c75cdcca61a9e116e611143902dbfd08bff356829c2f6d1cf40a9ca8c", size = 10412965, upload-time = "2026-05-11T18:52:41.915Z" },
+    { url = "https://files.pythonhosted.org/packages/65/b6/09b01cdbc15224e2850365192d17b7bdebb8bdbd8780ed221fcdf0d9a515/pandas-3.0.3-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6dc0b3fd2169c9157deed50b4d519553a3655c8c6a96027136d654592be973a9", size = 10894600, upload-time = "2026-05-11T18:52:45.02Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/a4/2eb28f2fccb4ced4a2c79ab2a5dee9ade1ebf44922ebad6fea158c9f95d4/pandas-3.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:7e65d5407dc0b394f509699650e4a2ec01c0514f21850f453fa60f3be79a5dbf", size = 11422824, upload-time = "2026-05-11T18:52:48.058Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/45/830bb57f533a4604b355e07edcb8ea18cf88b5f94e5fca92f27052d7c597/pandas-3.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:f8894dc474d648fe7b6ff0ca9b0bd73950d19952bc1a6534540762c5d79d305c", size = 11950889, upload-time = "2026-05-11T18:52:50.905Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/c5/fc1b368f303087d20e8c9bf3d6ceb186263cfac0ade735cd938538bea839/pandas-3.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:c7be265b62cef88e253a941e4698604973736dcfe242fdb5198f0f7bc473cdcc", size = 9755463, upload-time = "2026-05-11T18:52:53.386Z" },
+    { url = "https://files.pythonhosted.org/packages/86/bd/fda8f9705b1b09c6ebe14bfc0fa0e4ec8584d54ea673628f157ff55131af/pandas-3.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:557409bc4178e70ee8d9ddb494798e51ebf6ea59330f6be22c51bab2a7db6c49", size = 9066158, upload-time = "2026-05-11T18:52:56.038Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/90/62d8302883c44308c477e222c3daf7c813a34c8e96985882fbd53d964352/pandas-3.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:67b3b64c11910cfa29f4e94a14d3bff9ee693b6fc76055e7cad549cee0aec5fa", size = 10331071, upload-time = "2026-05-11T18:52:58.838Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/ae/6a6493c783a101f165e4356953ba3c74d6f77f0042fa7d753da9dfbb640c/pandas-3.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:39436b377d56d2a2e52d0395bdbee171f01068e99af5250509aceeb929f765c7", size = 9875690, upload-time = "2026-05-11T18:53:01.431Z" },
+    { url = "https://files.pythonhosted.org/packages/62/7c/5df8e9f56c69a2769fbe9382a5ef8f2658c007e376434e1e2cbb57ad895f/pandas-3.0.3-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d4be06d68f9ddcfc645b87534911da79a8fbffc7573c80e0edcf42a5020624d8", size = 10381634, upload-time = "2026-05-11T18:53:04.393Z" },
+    { url = "https://files.pythonhosted.org/packages/99/68/1237369725aa617bb358263d535803e3053fdbc593513ec5ed9c9896b5b6/pandas-3.0.3-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a4eeb6830daf35a71cc09649bd823e2b542dac246cdee9614c6e4bd65028cd6a", size = 10891243, upload-time = "2026-05-11T18:53:07.643Z" },
+    { url = "https://files.pythonhosted.org/packages/25/93/77d108e8af7222b4a503ebde0e30215b1c2e4f8e53a526431890f22d5586/pandas-3.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:1928e07221f82db493cd4af1e23c1bfca524a19a4699887975bff68f49a72bfb", size = 11388659, upload-time = "2026-05-11T18:53:10.634Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/bd/eff5b4399f332ac386c853f6cd2bd3fa2ca0061b9f36ecd9c4d7c4265649/pandas-3.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:51b1fe551acb77dac643c6fda86084d8d446c10fe64b06a9cc29c4cc8540e7f2", size = 11942880, upload-time = "2026-05-11T18:53:13.536Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/20/559ace4200982c3887d0b86bfd0d856a2143ef8ddab63cc07934951a964c/pandas-3.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:a82d532a3351d435432cd913edbccaf8b8e01d4dd0e5ced5a8d2e8ecd94c7e44", size = 9757091, upload-time = "2026-05-11T18:53:16.306Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/66/69055a09fe200f29f922a3eeec4804611900b95f52d932ece3393c3c0c19/pandas-3.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:275c14e0fce14a2ec20eee474aecd305478ea3c1e6f6a9d8fe219a165542717e", size = 9057282, upload-time = "2026-05-11T18:53:18.768Z" },
+    { url = "https://files.pythonhosted.org/packages/57/0e/efe801b0e6811e8e650cd21b7f2608e30f08a7067e2bf6e8752b0d56ee3c/pandas-3.0.3-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:46997386d528eb40376ecd6b033cf4a8a1e5282580f68f43de875b78cba2199d", size = 10767016, upload-time = "2026-05-11T18:53:21.227Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/dc/eb55135a1d5f0f0519f28da1f609a206d2cad1f9c35c32d51e38dd7261ae/pandas-3.0.3-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:261e308dfb22448384b7580cf719d2f998fe2966c92893c3e77d14008af1f066", size = 10420210, upload-time = "2026-05-11T18:53:23.982Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/3e/b1d5d955ce33ffecb407465a60bc32769d74fcf68224b7ae67ae11d4dea4/pandas-3.0.3-cp313-cp313t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dd1a5d1def6a46002e964510bdc67c368aa0951df5d1d9f8365336f5a1f490cd", size = 10336126, upload-time = "2026-05-11T18:53:26.731Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/76/a01261711ab60a22d71b862f0de20e4c504bf80457270ad8cb42110f6abc/pandas-3.0.3-cp313-cp313t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d72828c20c6d6e83e1e22a6a3b47b326b71664112fa9705dcbccfd7a39b62085", size = 10728051, upload-time = "2026-05-11T18:53:29.125Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/21/ea191195e587b18cf682e97f433f81b2d0fbe341380e80a3e0d6e4403c8e/pandas-3.0.3-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:d26cbe1fcfc12e8fd900e2454163e466b2d3af84f7c75481df7683ffc073d870", size = 11350796, upload-time = "2026-05-11T18:53:32.056Z" },
+    { url = "https://files.pythonhosted.org/packages/64/69/f0eaaf54939f0e8c6768fd06be9af2cef9b36048b96dfb9e1b2c685a807e/pandas-3.0.3-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:3e91cec1879ada0624fc3dc9953c5cbd60208e59c0db28f540c5d6d47502422f", size = 11799741, upload-time = "2026-05-11T18:53:34.985Z" },
+    { url = "https://files.pythonhosted.org/packages/45/a4/865e0e510cae5fc2194de4db28be638952de942571ba9125934fd9c01d47/pandas-3.0.3-cp313-cp313t-win_amd64.whl", hash = "sha256:08d789b41f87e0905880e293cedf6197ce71fe67cc081358b1e148a491b9bd13", size = 10499958, upload-time = "2026-05-11T18:53:37.857Z" },
+    { url = "https://files.pythonhosted.org/packages/86/54/effdcc3c0ff7a08037889200e148ebe94c16c4f653be078c7b3675955df1/pandas-3.0.3-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:3650109c0f22879df8bd6179ab9ee3d7f1d1d4e7e0094a3f0032d9f51e2e64ac", size = 10336065, upload-time = "2026-05-11T18:53:41.099Z" },
+    { url = "https://files.pythonhosted.org/packages/68/10/bf2d6738d72748b961a3751ab89522d58c54efc36a8e1a12161216cd45cf/pandas-3.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:bab900348131a7db1f69a7309ef141fd5680f1487094193bcbbb61791573bf8f", size = 9926101, upload-time = "2026-05-11T18:53:43.515Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/e9/e35cf11c8a136e757b956f5f0efdcaa50aecde85ea055f1898dfc68262f3/pandas-3.0.3-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ba7e08b9ac1d54569cd1e256e3668975ed624d6826f7b68df0342b012007bddb", size = 10457553, upload-time = "2026-05-11T18:53:46.394Z" },
+    { url = "https://files.pythonhosted.org/packages/58/3b/1cdec6772bdbaf7b25dab360c59f03cadf05492dd724c6540af905389b07/pandas-3.0.3-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d71c63ae4ebdbf70209742096f1fc46a83a0613c99d4b23766cced9ff8cd62a", size = 10914065, upload-time = "2026-05-11T18:53:49.134Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/c2/1ef644445fcd72e3627bceec77e3560636f87ddce4ed841afe76b83b5bf9/pandas-3.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:e3a2ec42c98ffa2565a67e08e218d06d72576d758d90facb7c00805194d8f360", size = 11459188, upload-time = "2026-05-11T18:53:52.527Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/49/4d8d4f42cbc9c4adc7a1870f269c02cbd6cd40d059622c06fb298addcbad/pandas-3.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:335f62418ed562cfc3c49e9e196375c28b729dcef8543abf4f9438e381bf3c76", size = 11982966, upload-time = "2026-05-11T18:53:55.043Z" },
+    { url = "https://files.pythonhosted.org/packages/38/55/792619469bab9882d8bbd5865d45a72f6478762d04a9af4bf0d08c503e95/pandas-3.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:3c20a521bbb85902f79f7270c80a59e1b5452d96d170c034f207181870f97ac5", size = 9876755, upload-time = "2026-05-11T18:53:58.067Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/af/33c469653b0ba03b50c3a98192d4c07f0c75c66b263ceb097fce0ee97d31/pandas-3.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:a2d2dff8a04f3917b55ab3910c32990f8ddf7eceba114947838cefa976a68977", size = 9198658, upload-time = "2026-05-11T18:54:00.733Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/fa/b8c257bd76b8bd060c3a9151c1fca05e9b9c5e3af5d0f549c0356f6d143d/pandas-3.0.3-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:0d589105b3c14645af1738ff279b2995102d8f7a03b0a66dc8d95550eb513e04", size = 10787242, upload-time = "2026-05-11T18:54:03.564Z" },
+    { url = "https://files.pythonhosted.org/packages/54/eb/f19206ffb0bf1919002969aa448b4702c6594845156a6f8050674855aac3/pandas-3.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:13fc1e853d9e04743d11ba75a985ccbc2a317fe07d8af61e445a6fd24dacd6a6", size = 10436369, upload-time = "2026-05-11T18:54:06.311Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/24/c7c39fb4fe22b71a0c2d78bf0c585c600092d85f94f086d2b3b2f6ca27e2/pandas-3.0.3-cp314-cp314t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:819959dab7bbd0049c15623fbac4e29a191b9528160a61fb1032242d8ced2d9c", size = 10358306, upload-time = "2026-05-11T18:54:09.085Z" },
+    { url = "https://files.pythonhosted.org/packages/16/ec/dd2a9eb7fa1204df88c0864164e35b228ac581062ac612ba0a67fd812e4c/pandas-3.0.3-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:60ae316d3fd75d1858d450d0db0103ea2be3e7d4a95ec2f064f7e2ae63f7b028", size = 10758394, upload-time = "2026-05-11T18:54:11.956Z" },
+    { url = "https://files.pythonhosted.org/packages/95/6e/00c61ea8e85b4f6d8d35e11852a1a4998fc7fafc91c6a602d1cc9c972d64/pandas-3.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:bd3a518890b400d32f9023722dc9a9a5c969f00b415419a3c06c043f09bb5d7d", size = 11375717, upload-time = "2026-05-11T18:54:14.539Z" },
+    { url = "https://files.pythonhosted.org/packages/31/89/8fc1c268969fac43688d65fd92e67df24bd128d53cb4d2eee534cd307399/pandas-3.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9c39be2d709d01fa972a0cabc522389fceca4f3969332ba25a7d6c5802cf976a", size = 11828897, upload-time = "2026-05-11T18:54:17.146Z" },
+    { url = "https://files.pythonhosted.org/packages/56/3b/e7d20dea247a3e6dc0bd8a6953854afbedc03951def4e7371e05e7263e25/pandas-3.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4db8c527972a821cf5286b40ccc57642a39bc62e62022b42f99f8a67fca8c3a1", size = 10900855, upload-time = "2026-05-11T18:54:19.72Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/54/68a0978d1ef8502b8492099beaa6e7a0c1b32e3b5d4f677f5810cb08711c/pandas-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:b2c95f8bfc1ee412bf482605d7bfd30c12d1d26bd59fdd91efeef1d4718decb1", size = 9466464, upload-time = "2026-05-11T18:54:22.754Z" },
+]
+
+[[package]]
+name = "peewee"
+version = "4.0.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9f/09/a3b2a32ce498f405dce4320267e99b1b076c1ea39ad01151a353bc7f81d7/peewee-4.0.6.tar.gz", hash = "sha256:ea2f78f24ff9e3660281dc5b0be8bc00d9a9514bdc40c98e416fcd042b66ac6a", size = 724591, upload-time = "2026-05-20T13:18:17.26Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/69/6a/e1455b94ee48f5666f2e7831b6247098794bfe9747da457111be4d0bea10/peewee-4.0.6-py3-none-any.whl", hash = "sha256:5fa665913c410f0b5faef1469ed0aa9eceb9fef262665ebbb6f29408f826eeeb", size = 146222, upload-time = "2026-05-20T13:18:15.694Z" },
+]
+
 [[package]]
 name = "pillow"
 version = "12.2.0"
@@ -2636,6 +2762,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
 ]
 
+[[package]]
+name = "pytz"
+version = "2026.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ff/46/dd499ec9038423421951e4fad73051febaa13d2df82b4064f87af8b8c0c3/pytz-2026.2.tar.gz", hash = "sha256:0e60b47b29f21574376f218fe21abc009894a2321ea16c6754f3cad6eb7cdd6a", size = 320861, upload-time = "2026-05-04T01:35:29.667Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ec/dd/96da98f892250475bdf2328112d7468abdd4acc7b902b6af23f4ed958ea0/pytz-2026.2-py2.py3-none-any.whl", hash = "sha256:04156e608bee23d3792fd45c94ae47fae1036688e75032eea2e3bf0323d1f126", size = 510141, upload-time = "2026-05-04T01:35:27.408Z" },
+]
+
 [[package]]
 name = "pyyaml"
 version = "6.0.3"
@@ -3088,6 +3223,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" },
 ]
 
+[[package]]
+name = "soupsieve"
+version = "2.8.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/47/2c/0a5f6f8ee0d5589e48c7640213ed5175d52cf540a06725b628cc1a45d6ce/soupsieve-2.8.4.tar.gz", hash = "sha256:e121fd02e975c695e4e9e8774a5ee35d74714b59307868dcc5319ad2d9e3328e", size = 121110, upload-time = "2026-05-24T13:55:57.154Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5e/f5/0c41cb68dcae6b7de4fac4188a3a9589e21fb31df21ea3a2e888db95e6c9/soupsieve-2.8.4-py3-none-any.whl", hash = "sha256:e7e6b0769c8f51ed59acab6e994b00621096cfb1c640a7509295987388fbaf65", size = 37304, upload-time = "2026-05-24T13:55:55.406Z" },
+]
+
 [[package]]
 name = "sqlalchemy"
 version = "2.0.49"
@@ -3405,6 +3549,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" },
 ]
 
+[[package]]
+name = "tzdata"
+version = "2026.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ba/19/1b9b0e29f30c6d35cb345486df41110984ea67ae69dddbc0e8a100999493/tzdata-2026.2.tar.gz", hash = "sha256:9173fde7d80d9018e02a662e168e5a2d04f87c41ea174b139fbef642eda62d10", size = 198254, upload-time = "2026-04-24T15:22:08.651Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ce/e4/dccd7f47c4b64213ac01ef921a1337ee6e30e8c6466046018326977efd95/tzdata-2026.2-py2.py3-none-any.whl", hash = "sha256:bbe9af844f658da81a5f95019480da3a89415801f6cc966806612cc7169bffe7", size = 349321, upload-time = "2026-04-24T15:22:05.876Z" },
+]
+
 [[package]]
 name = "urllib3"
 version = "2.7.0"
@@ -3778,6 +3931,28 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/69/68/c8739671f5699c7dc470580a4f821ef37c32c4cb0b047ce223a7f115757f/yarl-1.23.0-py3-none-any.whl", hash = "sha256:a2df6afe50dea8ae15fa34c9f824a3ee958d785fd5d089063d960bae1daa0a3f", size = 48288, upload-time = "2026-03-01T22:07:51.388Z" },
 ]
 
+[[package]]
+name = "yfinance"
+version = "1.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "beautifulsoup4" },
+    { name = "curl-cffi" },
+    { name = "multitasking" },
+    { name = "numpy" },
+    { name = "pandas" },
+    { name = "peewee" },
+    { name = "platformdirs" },
+    { name = "protobuf" },
+    { name = "pytz" },
+    { name = "requests" },
+    { name = "websockets" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/21/e2/b81f9cac78f1c23e444164f2135e19f849a66774474f8b156fc3702280c3/yfinance-1.4.0.tar.gz", hash = "sha256:6b049c3f28b0d66be54c32d84838ffd60c429277ba378afb0202c4792013c911", size = 153715, upload-time = "2026-05-23T16:28:08.961Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/95/58/31561402a60d317f9c36288223be99eabedc25b61f18d0b69f0889726545/yfinance-1.4.0-py2.py3-none-any.whl", hash = "sha256:6513654be21bd80a4e9e4e24193255fb4b1921618443113826494bf6efcedcb0", size = 137749, upload-time = "2026-05-23T16:28:07.656Z" },
+]
+
 [[package]]
 name = "zipp"
 version = "3.23.1"