backtestchat 0.1.0__py3-none-any.whl

backtestchat/agent/tools.py

@@ -0,0 +1,378 @@
+"""The 10 agent tools (v1), thin wrappers over the broker / engine / store /
+render layers.
+
+The compress-for-model and widget-side-channel patterns are implemented as
+LangChain @tool functions built over a ToolContext.
+
+House rules enforced here:
+  - Tools return compact JSON for the model (see agent/context.py); raw bar and
+    equity arrays never enter context - they ride the widget side channel.
+  - Widgets are collected on ctx.widgets and rendered AFTER the model reply.
+  - Errors are loud and structured: {"error", "message", "valid_options"} so the
+    model can self-correct. No fuzzy parsing; canonical encodings only.
+  - save_strategy and start_paper_run pause for terminal confirmation via a
+    LangGraph interrupt (the human-in-the-loop showcase).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from langchain_core.tools import tool
+from langgraph.types import interrupt
+
+from backtestchat.agent.context import (
+    compact_backtest,
+    compact_compare,
+    compact_price_series,
+)
+from backtestchat.broker.base import (
+    SUPPORTED_INTERVALS,
+    Broker,
+    BrokerError,
+    UnknownIntervalError,
+    UnknownRangeError,
+    UnknownSymbolError,
+    validate_interval,
+)
+from backtestchat.config import Config
+from backtestchat.paper import runner
+from backtestchat.paper.store import Store
+from backtestchat.render.widgets import (
+    backtest_compare_widget,
+    backtest_report_widget,
+    price_series_widget,
+)
+from backtestchat.strategy.engine import run_backtest as engine_run_backtest
+from backtestchat.strategy.registry import (
+    STRATEGY_REGISTRY,
+    strategy_label,
+    supported_strategies,
+    validate_params,
+)
+
+
+@dataclass
+class ToolContext:
+    """Shared services + the per-turn widget sink the tools write to."""
+
+    broker: Broker
+    store: Store
+    cfg: Config
+    widgets: list = field(default_factory=list)
+
+
+def _err(code, message, valid_options=None) -> str:
+    payload = {"error": code, "message": message}
+    if valid_options is not None:
+        payload["valid_options"] = valid_options
+    return json.dumps(payload)
+
+
+def _map_exception(exc: Exception) -> str:
+    """Turn a known service exception into a structured, self-repairing error."""
+    if isinstance(exc, UnknownSymbolError):
+        return _err("unknown_symbol", str(exc), exc.suggestions)
+    if isinstance(exc, UnknownIntervalError):
+        return _err("unknown_interval", str(exc), exc.valid_options)
+    if isinstance(exc, UnknownRangeError):
+        return _err("unknown_range", str(exc), exc.valid_options)
+    if isinstance(exc, BrokerError):
+        return _err("data_error", str(exc))
+    if isinstance(exc, ValueError):
+        return _err("invalid_params", str(exc))
+    raise exc
+
+
+def _is_yes(decision) -> bool:
+    if isinstance(decision, bool):
+        return decision
+    return str(decision).strip().lower() in (
+        "y", "yes", "approve", "ok", "okay", "confirm", "true",
+    )
+
+
+def build_tools(ctx: ToolContext) -> list:
+    """Build the 10 tools bound to a ToolContext. Returns a list of tools to
+    pass to bind_tools / ToolNode."""
+
+    @tool
+    def get_quote(symbol: str) -> str:
+        """Get the latest price and 24h change for a Binance spot symbol
+        (e.g. BTCUSDT)."""
+        try:
+            return json.dumps(ctx.broker.get_quote(symbol))
+        except (BrokerError, ValueError) as exc:
+            return _map_exception(exc)
+
+    @tool
+    def get_price_series(symbol: str, interval: str, range_key: str) -> str:
+        """Fetch a close-price series and plot it. interval is one of
+        15m/1h/4h/1d; range_key is a named key (1m/3m/6m/1y/2y/5y) or an
+        Nd/Nw/Nm/Ny form. Returns compact stats; the chart is generated
+        separately."""
+        try:
+            symbol = ctx.broker.validate_symbol(symbol)
+            validate_interval(interval)
+            bars = ctx.broker.get_bars(symbol, interval, range_key=range_key)
+            if not bars:
+                return _err("no_data", f"No closed {interval} bars for {symbol}.")
+            points = [{"ts": b["ts"], "close": b["close"]} for b in bars]
+            ctx.widgets.append(price_series_widget(symbol, interval, range_key, points))
+            return json.dumps(compact_price_series(symbol, interval, range_key, points))
+        except (BrokerError, ValueError) as exc:
+            return _map_exception(exc)
+
+    @tool
+    def list_strategies() -> str:
+        """List the available strategy types with their default parameters and a
+        one-line description of each."""
+        catalog = []
+        for key in supported_strategies():
+            entry = STRATEGY_REGISTRY[key]
+            catalog.append({
+                "strategyType": key,
+                "label": entry["label"],
+                "description": entry["description"],
+                "defaults": validate_params(key, {}),
+            })
+        return json.dumps({"strategies": catalog})
+
+    @tool
+    def run_backtest(symbol: str, interval: str, range_key: str,
+                     strategy_type: str, params: dict | None = None) -> str:
+        """Backtest one long/flat strategy over a symbol/interval/range and plot
+        the equity curve. params are bar counts at the chosen interval; omit to
+        use defaults. Returns metrics + trade count."""
+        try:
+            symbol = ctx.broker.validate_symbol(symbol)
+            validate_interval(interval)
+            if strategy_type not in STRATEGY_REGISTRY:
+                return _err("unknown_strategy",
+                            f"Unknown strategy '{strategy_type}'.",
+                            supported_strategies())
+            norm = validate_params(strategy_type, params or {})
+            bars = ctx.broker.get_bars(symbol, interval, range_key=range_key)
+            result = engine_run_backtest(bars, strategy_type, norm, interval=interval)
+            label = strategy_label(strategy_type, norm)
+            ctx.widgets.append(backtest_report_widget(
+                symbol, interval, range_key, strategy_type, label, result))
+            return json.dumps(compact_backtest(
+                symbol, interval, range_key, strategy_type, label, norm, result))
+        except (BrokerError, ValueError) as exc:
+            return _map_exception(exc)
+
+    @tool
+    def compare_strategies(symbol: str, interval: str, range_key: str,
+                           strategies: list[dict]) -> str:
+        """Backtest several strategies on the same symbol/interval/range and
+        rank them. strategies is a list of {strategy_type, params}. Returns a
+        ranked metrics table and plots the equity curves together."""
+        try:
+            symbol = ctx.broker.validate_symbol(symbol)
+            validate_interval(interval)
+            bars = ctx.broker.get_bars(symbol, interval, range_key=range_key)
+
+            entries, skipped = [], []
+            for spec in strategies:
+                stype = spec.get("strategy_type")
+                if stype not in STRATEGY_REGISTRY:
+                    skipped.append({"strategyType": stype, "error": "unknown_strategy"})
+                    continue
+                try:
+                    norm = validate_params(stype, spec.get("params") or {})
+                    result = engine_run_backtest(bars, stype, norm, interval=interval)
+                except ValueError as exc:
+                    skipped.append({"strategyType": stype, "error": str(exc)})
+                    continue
+                entries.append({
+                    "strategyType": stype,
+                    "label": strategy_label(stype, norm),
+                    "params": norm,
+                    "result": result,
+                })
+
+            if not entries:
+                return _err("no_results",
+                            "None of the requested strategies could be backtested.",
+                            supported_strategies())
+
+            ctx.widgets.append(backtest_compare_widget(
+                symbol, interval, range_key,
+                [{"strategyType": e["strategyType"], "label": e["label"],
+                  "result": e["result"]} for e in entries]))
+            payload = compact_compare(symbol, interval, range_key, entries)
+            if skipped:
+                payload["skipped"] = skipped
+            return json.dumps(payload)
+        except (BrokerError, ValueError) as exc:
+            return _map_exception(exc)
+
+    @tool
+    def save_strategy(strategy_type: str, params: dict, symbol: str,
+                      interval: str, name: str | None = None) -> str:
+        """Save a strategy blueprint (type + params + symbol + interval) for
+        later reuse. Requires the user to confirm in the terminal first."""
+        try:
+            symbol = ctx.broker.validate_symbol(symbol)
+            validate_interval(interval)
+            if strategy_type not in STRATEGY_REGISTRY:
+                return _err("unknown_strategy",
+                            f"Unknown strategy '{strategy_type}'.",
+                            supported_strategies())
+            norm = validate_params(strategy_type, params or {})
+            label = strategy_label(strategy_type, norm)
+            display_name = name or f"{label} {symbol} {interval}"
+        except (BrokerError, ValueError) as exc:
+            return _map_exception(exc)
+
+        decision = interrupt({
+            "action": "save_strategy",
+            "summary": f"Save strategy '{display_name}'?",
+            "details": {"strategyType": strategy_type, "params": norm,
+                        "symbol": symbol, "interval": interval},
+        })
+        if not _is_yes(decision):
+            return json.dumps({"status": "cancelled",
+                               "message": "User declined to save the strategy."})
+
+        # Post-approval writes must never raise out of the tool: an exception on
+        # the interrupt-resume path escapes ToolNode's error handling and would
+        # leave a dangling tool_call in the thread checkpoint.
+        try:
+            strategy_id = ctx.store.save_strategy(
+                display_name, strategy_type, norm, symbol, interval, _now_iso())
+        except Exception as exc:  # noqa: BLE001
+            return _err("store_error", f"Failed to save strategy: {exc}")
+        return json.dumps({
+            "status": "saved", "strategyId": strategy_id, "name": display_name,
+            "strategyType": strategy_type, "symbol": symbol, "interval": interval,
+        })
+
+    @tool
+    def list_saved_strategies() -> str:
+        """List strategies the user has saved."""
+        rows = [
+            {"id": s["id"], "name": s["name"], "strategyType": s["strategy_type"],
+             "params": s["params"], "symbol": s["symbol"], "interval": s["interval"]}
+            for s in ctx.store.list_strategies()
+        ]
+        return json.dumps({"strategies": rows})
+
+    @tool
+    def start_paper_run(strategy_id: int | None = None,
+                        strategy_type: str | None = None,
+                        params: dict | None = None, symbol: str | None = None,
+                        interval: str | None = None,
+                        cash: float = runner.DEFAULT_STARTING_CASH) -> str:
+        """Start a paper (simulated) run from a saved strategy id OR an inline
+        spec (strategy_type + symbol + interval + optional params). Paper-only:
+        no real orders. Requires the user to confirm in the terminal first."""
+        try:
+            if strategy_id is not None:
+                saved = ctx.store.get_strategy(strategy_id)
+                if saved is None:
+                    return _err("unknown_strategy_id",
+                                f"No saved strategy with id {strategy_id}.")
+                strategy_type = saved["strategy_type"]
+                params = saved["params"]
+                symbol = saved["symbol"]
+                interval = saved["interval"]
+            if not (strategy_type and symbol and interval):
+                return _err("missing_spec",
+                            "Provide a strategy_id, or all of strategy_type, "
+                            "symbol, and interval.")
+            symbol = ctx.broker.validate_symbol(symbol)
+            validate_interval(interval)
+            if strategy_type not in STRATEGY_REGISTRY:
+                return _err("unknown_strategy",
+                            f"Unknown strategy '{strategy_type}'.",
+                            supported_strategies())
+            norm = validate_params(strategy_type, params or {})
+            label = strategy_label(strategy_type, norm)
+        except (BrokerError, ValueError) as exc:
+            return _map_exception(exc)
+
+        decision = interrupt({
+            "action": "start_paper_run",
+            "summary": f"Start a paper run of {label} on {symbol} {interval} "
+                       f"with {cash:.0f} USDT?",
+            "details": {"strategyType": strategy_type, "params": norm,
+                        "symbol": symbol, "interval": interval, "cash": cash},
+        })
+        if not _is_yes(decision):
+            return json.dumps({"status": "cancelled",
+                               "message": "User declined to start the paper run."})
+
+        # As with save_strategy, never raise past this point (interrupt-resume
+        # path) so the thread checkpoint cannot be poisoned by a dangling call.
+        try:
+            result = runner.create_run(
+                ctx.store, ctx.broker, symbol=symbol, interval=interval,
+                strategy_type=strategy_type, params=norm, cash=cash,
+                strategy_id=strategy_id)
+        except (BrokerError, ValueError) as exc:
+            return _map_exception(exc)
+        except Exception as exc:  # noqa: BLE001
+            return _err("run_error", f"Failed to start paper run: {exc}")
+
+        return json.dumps({
+            "status": "started", "runId": result["run_id"],
+            "runStatus": result["status"], "symbol": symbol, "interval": interval,
+            "strategyType": strategy_type, "strategyLabel": label,
+            "startingCash": cash,
+            "note": "No backdated fills: the first simulated fill is on the "
+                    "first bar that closes after now. Sync later to advance it.",
+        })
+
+    @tool
+    def list_paper_runs(status: str | None = None) -> str:
+        """List paper runs (optionally filtered by status: active/stopped).
+        Triggers a cheap sync first so equity and position are current."""
+        try:
+            runner.sync_all(ctx.store, ctx.broker)
+        except BrokerError:
+            pass  # list stored state even if a sync fetch fails
+        rows = [
+            {"id": r["id"], "symbol": r["symbol"], "interval": r["interval"],
+             "strategyType": r["strategy_type"], "status": r["status"],
+             "equity": round(r["equity"], 2), "cash": round(r["cash"], 2),
+             "positionQty": r["position_qty"],
+             "realizedPnl": round(r["realized_pnl"], 2),
+             "lastBarTs": r["last_bar_ts"], "note": r["note"]}
+            for r in ctx.store.list_runs(status)
+        ]
+        return json.dumps({"runs": rows})
+
+    @tool
+    def stop_paper_run(run_id: int) -> str:
+        """Sync a paper run one last time, then stop it. Returns a final
+        summary (equity, realized PnL, trade count)."""
+        try:
+            summary = runner.stop_run(ctx.store, ctx.broker, run_id)
+        except (BrokerError, ValueError) as exc:
+            return _map_exception(exc)
+        if summary.get("status") == "not_found":
+            return _err("unknown_run_id", f"No paper run with id {run_id}.")
+        return json.dumps({
+            "status": "stopped", "runId": run_id,
+            "equity": round(summary.get("equity", 0.0), 2),
+            "realizedPnl": round(summary.get("realized_pnl", 0.0), 2),
+            "tradeCount": summary.get("trade_count", 0),
+            "symbol": summary.get("symbol"), "interval": summary.get("interval"),
+        })
+
+    return [
+        get_quote, get_price_series, list_strategies, run_backtest,
+        compare_strategies, save_strategy, list_saved_strategies,
+        start_paper_run, list_paper_runs, stop_paper_run,
+    ]
+
+
+def _now_iso() -> str:
+    import time
+
+    from backtestchat.broker.base import ms_to_iso
+
+    return ms_to_iso(int(time.time() * 1000))

backtestchat/artifacts.py

@@ -0,0 +1,57 @@
+"""Rendered-artifact bookkeeping: the "last artifact" pointer and resolution.
+
+Kept dependency-light (stdlib only) so the CLI `show` command can use it without
+importing the chat/agent stack.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from backtestchat.config import Config
+
+LAST_ARTIFACT_FILE = "last_artifact.txt"
+
+
+def record_last_artifact(cfg: Config, path: Path) -> None:
+    """Remember the most recently rendered artifact (for `show last`)."""
+    try:
+        (cfg.data_dir / LAST_ARTIFACT_FILE).write_text(str(path))
+    except OSError:
+        pass
+
+
+def last_artifact(cfg: Config) -> Path | None:
+    """The artifact recorded by the last render, if it still exists."""
+    pointer = cfg.data_dir / LAST_ARTIFACT_FILE
+    if not pointer.is_file():
+        return None
+    path = Path(pointer.read_text().strip())
+    return path if path.is_file() else None
+
+
+def newest_artifact(cfg: Config) -> Path | None:
+    """The most recently modified HTML file in the artifacts dir."""
+    htmls = sorted(cfg.artifacts_dir.glob("*.html"), key=lambda p: p.stat().st_mtime)
+    return htmls[-1] if htmls else None
+
+
+def resolve_artifact(cfg: Config, target: str) -> Path | None:
+    """Resolve a `show` target to an artifact path.
+
+    'last'/'latest' -> the recorded pointer, else the newest HTML. Otherwise a
+    direct path, a filename under the artifacts dir, or a substring match.
+    """
+    if target in ("last", "latest"):
+        return last_artifact(cfg) or newest_artifact(cfg)
+
+    direct = Path(target)
+    if direct.is_file():
+        return direct
+
+    named = cfg.artifacts_dir / target
+    if named.is_file():
+        return named
+
+    matches = sorted(cfg.artifacts_dir.glob(f"*{target}*.html"))
+    return matches[-1] if matches else None

backtestchat/broker/__init__.py

@@ -0,0 +1,41 @@
+"""Market-data broker layer.
+
+`base` holds the Broker interface plus the pure frequency/window logic and the
+structured broker errors. `binance` is the keyless public-REST implementation.
+"""
+
+from backtestchat.broker.base import (
+    BARS_PER_YEAR,
+    INTERVAL_MS,
+    SUPPORTED_INTERVALS,
+    Broker,
+    BrokerError,
+    UnknownIntervalError,
+    UnknownRangeError,
+    UnknownSymbolError,
+    bars_per_year,
+    drop_forming_klines,
+    iso_to_ms,
+    kline_to_bar,
+    ms_to_iso,
+    resolve_range_days,
+    validate_interval,
+)
+
+__all__ = [
+    "BARS_PER_YEAR",
+    "INTERVAL_MS",
+    "SUPPORTED_INTERVALS",
+    "Broker",
+    "BrokerError",
+    "UnknownIntervalError",
+    "UnknownRangeError",
+    "UnknownSymbolError",
+    "bars_per_year",
+    "drop_forming_klines",
+    "iso_to_ms",
+    "kline_to_bar",
+    "ms_to_iso",
+    "resolve_range_days",
+    "validate_interval",
+]