backtestchat 0.1.0__py3-none-any.whl

backtestchat/paper/store.py

@@ -0,0 +1,209 @@
+"""Thin hand-rolled sqlite store for strategies, paper runs, and trades.
+
+No ORM, no migration framework: CREATE TABLE IF NOT EXISTS on construction
+(single user, so no user_id; money columns are REAL floats; only trades are
+persisted, no per-bar ticks table). LangGraph checkpoints live in a separate
+sqlite file managed by SqliteSaver; this store never touches them.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from pathlib import Path
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS strategies (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    name          TEXT    NOT NULL,
+    strategy_type TEXT    NOT NULL,
+    params_json   TEXT    NOT NULL,
+    symbol        TEXT    NOT NULL,
+    interval      TEXT    NOT NULL,
+    created_at    TEXT    NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS paper_runs (
+    id                 INTEGER PRIMARY KEY AUTOINCREMENT,
+    strategy_id        INTEGER,
+    strategy_type      TEXT    NOT NULL,
+    params_json        TEXT    NOT NULL,
+    symbol             TEXT    NOT NULL,
+    interval           TEXT    NOT NULL,
+    cash_start         REAL    NOT NULL,
+    cash               REAL    NOT NULL,
+    position_qty       REAL    NOT NULL DEFAULT 0,
+    position_avg_price REAL,
+    position_entry_ts  TEXT,
+    last_price         REAL,
+    equity             REAL    NOT NULL,
+    realized_pnl       REAL    NOT NULL DEFAULT 0,
+    note               TEXT    NOT NULL DEFAULT '',
+    status             TEXT    NOT NULL DEFAULT 'active',
+    created_at         TEXT    NOT NULL,
+    last_tick_at       TEXT,
+    last_bar_ts        TEXT
+);
+
+CREATE TABLE IF NOT EXISTS paper_trades (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id       INTEGER NOT NULL,
+    side         TEXT    NOT NULL,
+    ts           TEXT    NOT NULL,
+    price        REAL    NOT NULL,
+    qty          REAL    NOT NULL,
+    equity_after REAL    NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_paper_runs_status ON paper_runs(status);
+CREATE INDEX IF NOT EXISTS idx_paper_trades_run ON paper_trades(run_id);
+"""
+
+# Columns update_run may set (guards against arbitrary SQL injection via keys).
+_RUN_UPDATABLE = {
+    "cash", "position_qty", "position_avg_price", "position_entry_ts",
+    "last_price", "equity", "realized_pnl", "note", "status",
+    "last_tick_at", "last_bar_ts",
+}
+
+
+class Store:
+    """Single-file sqlite store. One instance per process is expected."""
+
+    def __init__(self, db_path: str | Path):
+        self._path = str(db_path)
+        if self._path != ":memory:":
+            Path(self._path).parent.mkdir(parents=True, exist_ok=True)
+        # check_same_thread=False: LangGraph executes tools in worker threads,
+        # so the connection is used off the creating thread. A lock serializes
+        # access (single process, effectively one tool at a time).
+        self._conn = sqlite3.connect(self._path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._lock = threading.RLock()
+        with self._lock:
+            self._conn.executescript(_SCHEMA)
+            self._conn.commit()
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    def __enter__(self) -> "Store":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # -- strategies --------------------------------------------------------
+
+    def save_strategy(self, name, strategy_type, params, symbol, interval, created_at) -> int:
+        with self._lock:
+            cur = self._conn.execute(
+                "INSERT INTO strategies (name, strategy_type, params_json, symbol, "
+                "interval, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+                (name, strategy_type, json.dumps(params), symbol, interval, created_at),
+            )
+            self._conn.commit()
+            return cur.lastrowid
+
+    def get_strategy(self, strategy_id) -> dict | None:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT * FROM strategies WHERE id = ?", (strategy_id,)
+            ).fetchone()
+        return self._strategy_row(row)
+
+    def list_strategies(self) -> list[dict]:
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT * FROM strategies ORDER BY id DESC"
+            ).fetchall()
+        return [self._strategy_row(r) for r in rows]
+
+    # -- runs --------------------------------------------------------------
+
+    def create_run(self, *, strategy_id, strategy_type, params, symbol, interval,
+                   cash_start, created_at) -> int:
+        with self._lock:
+            cur = self._conn.execute(
+                "INSERT INTO paper_runs (strategy_id, strategy_type, params_json, "
+                "symbol, interval, cash_start, cash, position_qty, equity, "
+                "realized_pnl, status, created_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, 0, 'active', ?)",
+                (strategy_id, strategy_type, json.dumps(params), symbol, interval,
+                 cash_start, cash_start, cash_start, created_at),
+            )
+            self._conn.commit()
+            return cur.lastrowid
+
+    def get_run(self, run_id) -> dict | None:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT * FROM paper_runs WHERE id = ?", (run_id,)
+            ).fetchone()
+        return self._run_row(row)
+
+    def list_runs(self, status: str | None = None) -> list[dict]:
+        with self._lock:
+            if status:
+                rows = self._conn.execute(
+                    "SELECT * FROM paper_runs WHERE status = ? ORDER BY id DESC",
+                    (status,),
+                ).fetchall()
+            else:
+                rows = self._conn.execute(
+                    "SELECT * FROM paper_runs ORDER BY id DESC"
+                ).fetchall()
+        return [self._run_row(r) for r in rows]
+
+    def update_run(self, run_id, **fields) -> None:
+        if not fields:
+            return
+        bad = set(fields) - _RUN_UPDATABLE
+        if bad:
+            raise ValueError(f"Cannot update paper_runs columns: {sorted(bad)}")
+        assignments = ", ".join(f"{col} = ?" for col in fields)
+        values = list(fields.values()) + [run_id]
+        with self._lock:
+            self._conn.execute(
+                f"UPDATE paper_runs SET {assignments} WHERE id = ?", values
+            )
+            self._conn.commit()
+
+    # -- trades ------------------------------------------------------------
+
+    def append_trade(self, run_id, side, ts, price, qty, equity_after) -> int:
+        with self._lock:
+            cur = self._conn.execute(
+                "INSERT INTO paper_trades (run_id, side, ts, price, qty, equity_after) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (run_id, side, ts, price, qty, equity_after),
+            )
+            self._conn.commit()
+            return cur.lastrowid
+
+    def list_trades(self, run_id) -> list[dict]:
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT * FROM paper_trades WHERE run_id = ? ORDER BY id", (run_id,)
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    # -- row helpers -------------------------------------------------------
+
+    @staticmethod
+    def _strategy_row(row) -> dict | None:
+        if row is None:
+            return None
+        data = dict(row)
+        data["params"] = json.loads(data.pop("params_json"))
+        return data
+
+    @staticmethod
+    def _run_row(row) -> dict | None:
+        if row is None:
+            return None
+        data = dict(row)
+        data["params"] = json.loads(data.pop("params_json"))
+        return data

backtestchat/render/__init__.py

@@ -0,0 +1,26 @@
+"""Render layer: widget dict builders (the contract) and the deterministic
+plotly renderer. Data tools build widgets; this layer draws them. The LLM never
+writes markup.
+"""
+
+from backtestchat.render.plotly_render import (
+    RenderError,
+    figure_for_widget,
+    render_widget,
+)
+from backtestchat.render.widgets import (
+    backtest_compare_widget,
+    backtest_report_widget,
+    compute_series_stats,
+    price_series_widget,
+)
+
+__all__ = [
+    "RenderError",
+    "backtest_compare_widget",
+    "backtest_report_widget",
+    "compute_series_stats",
+    "figure_for_widget",
+    "price_series_widget",
+    "render_widget",
+]

backtestchat/render/plotly_render.py

@@ -0,0 +1,204 @@
+"""Deterministic widget -> plotly figure -> self-contained HTML file.
+
+Rendering is a pure function of the widget dict (house rule): the same widget
+always yields the same figure. HTML files embed plotly.js inline
+(include_plotlyjs=True) so an artifact opens with no network and no external
+assets. The LLM never touches this module.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+
+# A muted, consistent palette (dark-neutral, readable in a browser).
+_EQUITY_COLOR = "#2563eb"   # blue
+_PRICE_COLOR = "#0f766e"    # teal
+_BUY_COLOR = "#16a34a"      # green
+_SELL_COLOR = "#dc2626"     # red
+_COMPARE_COLORS = ["#2563eb", "#dc2626", "#16a34a", "#d97706", "#7c3aed",
+                   "#0891b2", "#db2777", "#65a30d"]
+
+_METRIC_COLUMNS = [
+    ("label", "Strategy"),
+    ("totalReturnPct", "Total %"),
+    ("cagrPct", "CAGR %"),
+    ("sharpe", "Sharpe"),
+    ("maxDrawdownPct", "MaxDD %"),
+    ("winRate", "Win %"),
+    ("numTrades", "Trades"),
+]
+
+
+class RenderError(ValueError):
+    """Unknown or malformed widget."""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def render_widget(widget: dict, artifacts_dir, filename: str | None = None,
+                  open_browser: bool = False) -> Path:
+    """Render a widget to a self-contained HTML file under artifacts_dir.
+
+    Returns the file Path. Pass an explicit filename for deterministic output
+    (tests); otherwise a unique name is derived from the widget + a timestamp.
+    """
+    fig = figure_for_widget(widget)
+
+    artifacts_dir = Path(artifacts_dir)
+    artifacts_dir.mkdir(parents=True, exist_ok=True)
+    path = artifacts_dir / (filename or _default_filename(widget))
+
+    fig.write_html(str(path), include_plotlyjs=True, full_html=True)
+
+    if open_browser:
+        import webbrowser
+
+        webbrowser.open(path.as_uri())
+
+    return path
+
+
+def figure_for_widget(widget: dict) -> go.Figure:
+    builder = {
+        "priceSeries": _fig_price_series,
+        "backtestReport": _fig_backtest_report,
+        "backtestCompare": _fig_backtest_compare,
+    }.get(widget.get("type"))
+    if builder is None:
+        raise RenderError(f"Unknown widget type: {widget.get('type')!r}")
+    return builder(widget)
+
+
+# ---------------------------------------------------------------------------
+# Figures
+# ---------------------------------------------------------------------------
+
+
+def _fig_price_series(widget: dict) -> go.Figure:
+    points = widget["points"]
+    xs = [p["ts"] for p in points]
+    ys = [p["close"] for p in points]
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=xs, y=ys, mode="lines", name="close",
+        line=dict(color=_PRICE_COLOR, width=1.6),
+    ))
+    stats = widget.get("stats", {})
+    subtitle = ""
+    if stats.get("returnPct") is not None:
+        subtitle = (f"  (last {stats['last']}, {stats['returnPct']:+}% over "
+                    f"{stats['count']} bars)")
+    fig.update_layout(
+        title=f"{widget['symbol']} {widget['interval']} - {widget['range']}{subtitle}",
+        xaxis_title="time", yaxis_title="price",
+        template="plotly_white", hovermode="x unified",
+    )
+    return fig
+
+
+def _fig_backtest_report(widget: dict) -> go.Figure:
+    curve = widget["equityCurve"]
+    xs = [p["ts"] for p in curve]
+    ys = [p["equity"] for p in curve]
+    equity_at = {p["ts"]: p["equity"] for p in curve}
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=xs, y=ys, mode="lines", name="equity",
+        line=dict(color=_EQUITY_COLOR, width=1.8),
+    ))
+
+    _add_trade_markers(fig, widget["trades"], equity_at)
+
+    m = widget["metrics"]
+    subtitle = (f"total {m['totalReturnPct']:+}%  |  Sharpe {m['sharpe']}  |  "
+                f"maxDD {m['maxDrawdownPct']}%  |  {m['numTrades']} trades")
+    fig.update_layout(
+        title=f"{widget['strategyLabel']} on {widget['symbol']} "
+              f"{widget['interval']} ({widget['range']})<br>"
+              f"<sub>{subtitle}</sub>",
+        xaxis_title="time", yaxis_title="equity (USDT)",
+        template="plotly_white", hovermode="x unified",
+    )
+    return fig
+
+
+def _add_trade_markers(fig: go.Figure, trades: list[dict], equity_at: dict) -> None:
+    for side, color, symbol in (("buy", _BUY_COLOR, "triangle-up"),
+                                ("sell", _SELL_COLOR, "triangle-down")):
+        side_trades = [t for t in trades if t["side"] == side]
+        xs = [t["ts"] for t in side_trades if t["ts"] in equity_at]
+        ys = [equity_at[t["ts"]] for t in side_trades if t["ts"] in equity_at]
+        texts = [f"{side} @ {t['price']}" for t in side_trades if t["ts"] in equity_at]
+        if not xs:
+            continue
+        fig.add_trace(go.Scatter(
+            x=xs, y=ys, mode="markers", name=side, text=texts,
+            hovertemplate="%{text}<extra></extra>",
+            marker=dict(color=color, size=10, symbol=symbol,
+                        line=dict(color="white", width=1)),
+        ))
+
+
+def _fig_backtest_compare(widget: dict) -> go.Figure:
+    entries = widget["entries"]
+
+    fig = make_subplots(
+        rows=2, cols=1, row_heights=[0.68, 0.32], vertical_spacing=0.09,
+        specs=[[{"type": "xy"}], [{"type": "table"}]],
+        subplot_titles=("equity curves", "ranked metrics"),
+    )
+
+    for i, entry in enumerate(entries):
+        curve = entry["equityCurve"]
+        fig.add_trace(go.Scatter(
+            x=[p["ts"] for p in curve], y=[p["equity"] for p in curve],
+            mode="lines", name=entry["label"],
+            line=dict(color=_COMPARE_COLORS[i % len(_COMPARE_COLORS)], width=1.6),
+        ), row=1, col=1)
+
+    header = [label for _, label in _METRIC_COLUMNS]
+    columns = []
+    for key, _ in _METRIC_COLUMNS:
+        if key == "label":
+            columns.append([e["label"] for e in entries])
+        else:
+            columns.append([e["metrics"].get(key) for e in entries])
+
+    fig.add_trace(go.Table(
+        header=dict(values=header, fill_color="#1e293b",
+                    font=dict(color="white"), align="left"),
+        cells=dict(values=columns, align="left",
+                   fill_color="#f8fafc"),
+    ), row=2, col=1)
+
+    fig.update_layout(
+        title=f"Strategy comparison - {widget['symbol']} "
+              f"{widget['interval']} ({widget['range']})",
+        template="plotly_white", hovermode="x unified",
+    )
+    fig.update_yaxes(title_text="equity (USDT)", row=1, col=1)
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Filenames
+# ---------------------------------------------------------------------------
+
+
+def _default_filename(widget: dict) -> str:
+    parts = [widget.get("type", "widget")]
+    if widget.get("symbol"):
+        parts.append(widget["symbol"])
+    if widget.get("interval"):
+        parts.append(widget["interval"])
+    parts.append(str(time.time_ns()))
+    return "-".join(parts) + ".html"

backtestchat/render/widgets.py

@@ -0,0 +1,95 @@
+"""Widget dict builders - the render contract.
+
+A widget is a plain JSON-able dict describing a chart. Data tools build widgets
+from tool results; the renderer (plotly_render.py) turns a widget into a
+self-contained HTML file. This is the ONLY thing the renderer understands, and
+the LLM never produces one directly - it just triggers a tool, and the tool
+builds the widget (house rule: data tools do not render; the LLM writes no
+markup).
+
+Widget shapes (the contract):
+
+    priceSeries
+        {type, symbol, interval, range, points:[{ts, close}], stats:{...}}
+
+    backtestReport
+        {type, symbol, interval, range, strategyType, strategyLabel,
+         equityCurve:[{ts, equity}], trades:[{ts, side, price}], metrics:{...}}
+
+    backtestCompare
+        {type, symbol, interval, range,
+         entries:[{strategyType, label, metrics:{...}, equityCurve:[{ts, equity}]}]}
+"""
+
+from __future__ import annotations
+
+
+def compute_series_stats(points: list[dict]) -> dict:
+    """Compact stats for a close-price series (also the payload the
+    get_price_series tool returns to the model - no raw bars in context)."""
+    closes = [p["close"] for p in points]
+    if not closes:
+        return {"count": 0, "first": None, "last": None, "min": None,
+                "max": None, "returnPct": None}
+    first, last = closes[0], closes[-1]
+    return_pct = ((last / first - 1.0) * 100.0) if first else None
+    return {
+        "count": len(closes),
+        "first": round(first, 6),
+        "last": round(last, 6),
+        "min": round(min(closes), 6),
+        "max": round(max(closes), 6),
+        "returnPct": round(return_pct, 2) if return_pct is not None else None,
+    }
+
+
+def price_series_widget(symbol, interval, range_key, points) -> dict:
+    """points: list of {ts, close}."""
+    normalized = [{"ts": p["ts"], "close": float(p["close"])} for p in points]
+    return {
+        "type": "priceSeries",
+        "symbol": symbol,
+        "interval": interval,
+        "range": range_key,
+        "points": normalized,
+        "stats": compute_series_stats(normalized),
+    }
+
+
+def backtest_report_widget(symbol, interval, range_key, strategy_type,
+                           strategy_label, result) -> dict:
+    """result: the engine.run_backtest output
+    {equityCurve, trades, metrics}."""
+    return {
+        "type": "backtestReport",
+        "symbol": symbol,
+        "interval": interval,
+        "range": range_key,
+        "strategyType": strategy_type,
+        "strategyLabel": strategy_label,
+        "equityCurve": result["equityCurve"],
+        "trades": result["trades"],
+        "metrics": result["metrics"],
+    }
+
+
+def backtest_compare_widget(symbol, interval, range_key, entries) -> dict:
+    """entries: list of {strategyType, label, result}. Ranked by total return
+    (descending) so the best strategy leads the table/legend."""
+    built = [
+        {
+            "strategyType": e["strategyType"],
+            "label": e["label"],
+            "metrics": e["result"]["metrics"],
+            "equityCurve": e["result"]["equityCurve"],
+        }
+        for e in entries
+    ]
+    built.sort(key=lambda e: e["metrics"].get("totalReturnPct", 0.0), reverse=True)
+    return {
+        "type": "backtestCompare",
+        "symbol": symbol,
+        "interval": interval,
+        "range": range_key,
+        "entries": built,
+    }

backtestchat/strategy/__init__.py

@@ -0,0 +1,26 @@
+"""Strategy layer: pure indicators, long/flat signal functions, the strategy
+catalog (registry), and the backtest engine. All pure (bars in, results out).
+"""
+
+from backtestchat.strategy.engine import run_backtest, simulate
+from backtestchat.strategy.registry import (
+    STRATEGY_REGISTRY,
+    describe_strategies,
+    is_supported_strategy,
+    strategy_label,
+    strategy_warmup,
+    supported_strategies,
+    validate_params,
+)
+
+__all__ = [
+    "STRATEGY_REGISTRY",
+    "describe_strategies",
+    "is_supported_strategy",
+    "run_backtest",
+    "simulate",
+    "strategy_label",
+    "strategy_warmup",
+    "supported_strategies",
+    "validate_params",
+]