backtestchat 0.1.0__py3-none-any.whl

backtestchat/cli.py

@@ -0,0 +1,204 @@
+"""backtestchat command-line interface (typer).
+
+Commands: chat (the agent REPL), runs list/sync (paper runs), show (open a
+rendered chart), config (print resolved settings). Heavy imports (the agent
+stack, broker, store) are done lazily inside each command so `backtestchat --help`
+and `config` stay fast and need no model key.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+import typer
+from rich.console import Console
+
+from backtestchat import __version__
+from backtestchat.config import ensure_dirs, load_config
+
+app = typer.Typer(
+    name="backtestchat",
+    help="Local-first agentic strategy lab: chat, backtest, and paper-trade "
+    "long/flat strategies on keyless Binance public data. Paper-only.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+runs_app = typer.Typer(help="Inspect and advance paper runs.", no_args_is_help=True)
+app.add_typer(runs_app, name="runs")
+
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"backtestchat {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the backtestchat version and exit.",
+    ),
+) -> None:
+    """backtestchat: paper-only agentic strategy lab."""
+
+
+_SETUP_HELP = """[yellow]No model configured.[/yellow] backtestchat is BYOK: set BACKTESTCHAT_MODEL to a
+"provider:model" string (or put model = "provider:model" in ./backtestchat.toml).
+
+Example:
+  uv sync --extra openai
+  export BACKTESTCHAT_MODEL=openai:gpt-5.4-nano
+  export OPENAI_API_KEY=...
+
+Any init_chat_model provider works (install its --extra and set the matching
+API key). Market data is keyless; only the model needs a key."""
+
+
+@app.command()
+def chat(
+    new: bool = typer.Option(False, "--new", help="Start a fresh conversation thread."),
+    thread: str | None = typer.Option(None, "--thread", help="Resume a specific thread id."),
+) -> None:
+    """Chat with the strategy agent (resumes the last thread by default)."""
+    from backtestchat.agent.chat import ModelSetupError, build_session, run_repl
+
+    cfg = load_config()
+    if not cfg.model:
+        console.print(_SETUP_HELP)
+        raise typer.Exit(1)
+
+    ensure_dirs(cfg)
+    thread_id = thread or (f"t-{uuid.uuid4().hex[:8]}" if new else "default")
+
+    try:
+        session = build_session(cfg)
+    except ModelSetupError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        run_repl(session, thread_id, console)
+    finally:
+        session.close()
+
+
+def _runs_table(rows: list[dict]):
+    from rich.table import Table
+
+    table = Table(show_header=True, header_style="bold")
+    for col in ("id", "symbol", "interval", "strategy", "status", "equity",
+                "cash", "position", "realizedPnl", "lastBar"):
+        table.add_column(col)
+    for r in rows:
+        table.add_row(
+            str(r["id"]), r["symbol"], r["interval"], r["strategy_type"],
+            r["status"], f"{r['equity']:.2f}", f"{r['cash']:.2f}",
+            f"{r['position_qty']:.6f}", f"{r['realized_pnl']:.2f}",
+            r["last_bar_ts"] or "-",
+        )
+    return table
+
+
+@runs_app.command("list")
+def runs_list(
+    status: str | None = typer.Option(None, "--status", help="Filter by run status (active/stopped)."),
+) -> None:
+    """List paper runs (stored state; run `backtestchat runs sync` to advance them)."""
+    from backtestchat.paper.store import Store
+
+    cfg = load_config()
+    store = Store(cfg.db_path)
+    try:
+        rows = store.list_runs(status)
+    finally:
+        store.close()
+
+    if not rows:
+        console.print("[dim]No paper runs yet. Start one from `backtestchat chat`.[/dim]")
+        return
+    console.print(_runs_table(rows))
+    console.print("[dim]Equity/position reflect the last sync. "
+                  "Run `backtestchat runs sync` to advance to the latest closed bar.[/dim]")
+
+
+@runs_app.command("sync")
+def runs_sync() -> None:
+    """Advance all active paper runs by replaying every closed bar since their
+    last tick."""
+    from backtestchat.broker.base import BrokerError
+    from backtestchat.broker.binance import BinanceBroker
+    from backtestchat.paper.runner import sync_all
+    from backtestchat.paper.store import Store
+
+    cfg = load_config()
+    ensure_dirs(cfg)
+    store = Store(cfg.db_path)
+    if not store.list_runs("active"):
+        console.print("[dim]No active runs to sync.[/dim]")
+        store.close()
+        return
+
+    broker = BinanceBroker(data_dir=cfg.data_dir)
+    try:
+        results = sync_all(store, broker)
+    except BrokerError as exc:
+        console.print(f"[red]sync failed:[/red] {exc}")
+        raise typer.Exit(1)
+    finally:
+        broker.close()
+
+    for r in results:
+        note = f" ({r['note']})" if r.get("note") else ""
+        console.print(
+            f"run {r['run_id']}: [bold]{r['status']}[/bold], "
+            f"{r['bars_processed']} bar(s) processed, equity {r['equity']:.2f}"
+            f"{note}"
+        )
+    console.print(_runs_table(store.list_runs()))
+    store.close()
+
+
+@app.command()
+def show(
+    target: str = typer.Argument("last", help="Artifact to open: 'last', a filename, or a path."),
+) -> None:
+    """Open a rendered chart artifact in the browser."""
+    import webbrowser
+
+    from backtestchat.artifacts import resolve_artifact
+
+    cfg = load_config()
+    path = resolve_artifact(cfg, target)
+    if path is None:
+        console.print(f"[red]No artifact found for '{target}'.[/red] "
+                      f"Charts are written to {cfg.artifacts_dir} during chat.")
+        raise typer.Exit(1)
+
+    console.print(f"opening {path}")
+    try:
+        webbrowser.open(path.resolve().as_uri())
+    except Exception as exc:  # noqa: BLE001 - headless env
+        console.print(f"[yellow]could not open a browser ({exc}); the file is at "
+                      f"{path}[/yellow]")
+
+
+@app.command()
+def config() -> None:
+    """Print the resolved configuration."""
+    cfg = load_config()
+    console.print("[bold]backtestchat config[/bold]")
+    console.print(f"  model         : {cfg.model or '[red]unset[/red] (set BACKTESTCHAT_MODEL)'}")
+    console.print(f"  data_dir      : {cfg.data_dir}")
+    console.print(f"  artifacts_dir : {cfg.artifacts_dir}")
+    console.print(f"  db_path       : {cfg.db_path}")
+
+
+if __name__ == "__main__":
+    app()

backtestchat/config.py

@@ -0,0 +1,89 @@
+"""Configuration resolution for backtestchat.
+
+Resolution order (highest priority first):
+    1. Environment variables
+    2. ./backtestchat.toml (in the current working directory)
+    3. Built-in defaults
+
+Keys:
+    BACKTESTCHAT_MODEL          provider:model string for init_chat_model (BYOK).
+                            No default: an unset model is a hard setup error.
+    BACKTESTCHAT_DATA_DIR       sqlite + checkpoint dir. Default ./data
+    BACKTESTCHAT_ARTIFACTS_DIR  chart HTML output dir. Default ./artifacts
+
+The toml file uses lowercase, unprefixed keys, e.g.:
+
+    model = "openai:gpt-5.4-nano"
+    data_dir = "./data"
+    artifacts_dir = "./artifacts"
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+_CONFIG_FILENAME = "backtestchat.toml"
+
+# key -> (env var name, toml key, default)
+_FIELDS = {
+    "model": ("BACKTESTCHAT_MODEL", "model", None),
+    "data_dir": ("BACKTESTCHAT_DATA_DIR", "data_dir", "./data"),
+    "artifacts_dir": ("BACKTESTCHAT_ARTIFACTS_DIR", "artifacts_dir", "./artifacts"),
+}
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved backtestchat configuration."""
+
+    model: str | None
+    data_dir: Path
+    artifacts_dir: Path
+
+    @property
+    def db_path(self) -> Path:
+        """Path to the application sqlite database."""
+        return self.data_dir / "backtestchat.sqlite3"
+
+    @property
+    def checkpoint_path(self) -> Path:
+        """Path to the LangGraph SqliteSaver checkpoint database."""
+        return self.data_dir / "checkpoints.sqlite3"
+
+
+def _load_toml(cwd: Path) -> dict:
+    path = cwd / _CONFIG_FILENAME
+    if not path.is_file():
+        return {}
+    with path.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def load_config(cwd: Path | None = None) -> Config:
+    """Resolve configuration from env, ./backtestchat.toml, then defaults."""
+    cwd = cwd or Path.cwd()
+    toml_data = _load_toml(cwd)
+
+    resolved: dict[str, str | None] = {}
+    for key, (env_name, toml_key, default) in _FIELDS.items():
+        value = os.environ.get(env_name)
+        if value is None:
+            value = toml_data.get(toml_key)
+        if value is None:
+            value = default
+        resolved[key] = value
+
+    return Config(
+        model=resolved["model"],
+        data_dir=Path(resolved["data_dir"]).expanduser(),
+        artifacts_dir=Path(resolved["artifacts_dir"]).expanduser(),
+    )
+
+
+def ensure_dirs(config: Config) -> None:
+    """Create the runtime data and artifacts directories if missing."""
+    config.data_dir.mkdir(parents=True, exist_ok=True)
+    config.artifacts_dir.mkdir(parents=True, exist_ok=True)

backtestchat/paper/__init__.py

@@ -0,0 +1,22 @@
+"""Paper-trading layer: the sqlite store and the replay-based run advancer.
+
+Single user, float money, and scheduler-free replay advancement.
+"""
+
+from backtestchat.paper.runner import (
+    DEFAULT_STARTING_CASH,
+    create_run,
+    stop_run,
+    sync_all,
+    sync_run,
+)
+from backtestchat.paper.store import Store
+
+__all__ = [
+    "DEFAULT_STARTING_CASH",
+    "Store",
+    "create_run",
+    "stop_run",
+    "sync_all",
+    "sync_run",
+]

backtestchat/paper/runner.py

@@ -0,0 +1,231 @@
+"""Paper-run lifecycle and replay-based advancement.
+
+There is no scheduler: advancing REPLAYS every closed bar since the run's last
+processed bar, in chronological order, one signal evaluation per bar. The
+"already processed this bar ts" guard is the only cadence control, so any CLI
+invocation may safely trigger a sync at any time (idempotent: a sync with no new
+closed bars changes nothing).
+
+Key design points:
+  - Single user; storage is the hand-rolled sqlite Store.
+  - Money is float, not Decimal (fine for a paper sim).
+  - Fills are fractional and fully allocated: a buy converts ALL cash to
+    position at the bar close (qty = cash / price), a sell converts it all
+    back (whole-unit fills would floor to 0 for a $60k asset with $10k cash).
+  - First-tick rule: no backdated fills. The first bar a run may trade is the
+    first bar that CLOSES after the run was created.
+"""
+
+from __future__ import annotations
+
+import time
+
+from backtestchat.broker.base import (
+    INTERVAL_MS,
+    iso_to_ms,
+    ms_to_iso,
+    validate_interval,
+)
+from backtestchat.paper.store import Store
+from backtestchat.strategy.registry import (
+    get_signal_fn,
+    strategy_warmup,
+    validate_params,
+)
+
+DEFAULT_STARTING_CASH = 10_000.0
+
+# Extra bars fetched before the anchor so indicators are warm at the first
+# unprocessed bar.
+_WARMUP_BUFFER = 5
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def create_run(store: Store, broker, *, symbol, interval, strategy_type,
+               params=None, cash=DEFAULT_STARTING_CASH, strategy_id=None,
+               created_ms=None, now_ms=None) -> dict:
+    """Create an active paper run and run its first sync.
+
+    No backdated fills: the run starts flat and waits for the first bar to
+    close after `created_ms` (default now). Passing a past `created_ms` (with
+    `now_ms` at the present) is how a test or a demo replays historical bars.
+    Returns the first sync result dict (which carries the new run_id).
+    """
+    symbol = broker.validate_symbol(symbol)
+    validate_interval(interval)
+    params = validate_params(strategy_type, params or {})
+
+    created_ms = created_ms if created_ms is not None else _now_ms()
+    run_id = store.create_run(
+        strategy_id=strategy_id,
+        strategy_type=strategy_type,
+        params=params,
+        symbol=symbol,
+        interval=interval,
+        cash_start=float(cash),
+        created_at=ms_to_iso(created_ms),
+    )
+    return sync_run(store, broker, run_id, now_ms=now_ms if now_ms is not None else created_ms)
+
+
+def sync_run(store: Store, broker, run_id, now_ms=None) -> dict:
+    """Advance one run by replaying all closed bars since its last processed bar.
+
+    Returns {run_id, status, bars_processed, trades, position_qty, cash, equity,
+    last_bar_ts, note}. status is one of: inactive, no_data, waiting_first_tick,
+    up_to_date, advanced.
+    """
+    now_ms = now_ms if now_ms is not None else _now_ms()
+    run = store.get_run(run_id)
+    if run is None:
+        return {"run_id": run_id, "status": "not_found"}
+    if run["status"] != "active":
+        return _result(run, "inactive", 0, [])
+
+    interval = run["interval"]
+    params = run["params"]
+    warmup = strategy_warmup(run["strategy_type"], params)
+    interval_ms = INTERVAL_MS[interval]
+
+    last_bar_ts = run["last_bar_ts"]
+    created_ms = iso_to_ms(run["created_at"])
+    anchor_ms = iso_to_ms(last_bar_ts) if last_bar_ts else created_ms
+    start_ms = anchor_ms - (warmup + _WARMUP_BUFFER) * interval_ms
+
+    bars = broker.get_bars(run["symbol"], interval, start_ms=start_ms, now_ms=now_ms)
+    if not bars:
+        return _result(run, "no_data", 0, [])
+
+    # Which fetched bars are unprocessed?
+    if last_bar_ts is None:
+        # First tick: a bar is eligible once it CLOSES after creation. Bars are
+        # stamped at open time, so close = open + interval.
+        unprocessed = [
+            i for i, bar in enumerate(bars)
+            if iso_to_ms(bar["ts"]) + interval_ms > created_ms
+        ]
+    else:
+        unprocessed = [i for i, bar in enumerate(bars) if bar["ts"] > last_bar_ts]
+
+    if not unprocessed:
+        status = "waiting_first_tick" if last_bar_ts is None else "up_to_date"
+        note = ("Waiting for the first bar to close after the run was created."
+                if last_bar_ts is None else run["note"])
+        if note != run["note"]:
+            store.update_run(run_id, note=note)
+            run["note"] = note
+        return _result(run, status, 0, [])
+
+    # Signals are trailing-only (no look-ahead), so evaluating once over the
+    # full fetched window and indexing is equivalent to per-bar incremental
+    # evaluation.
+    signal_fn = get_signal_fn(run["strategy_type"])
+    signals = signal_fn(bars, params)
+
+    cash = run["cash"]
+    qty = run["position_qty"]
+    avg = run["position_avg_price"]
+    entry_ts = run["position_entry_ts"]
+    realized = run["realized_pnl"]
+    last_price = run["last_price"]
+    new_trades = []
+
+    for i in unprocessed:
+        bar = bars[i]
+        price = bar["close"]
+        target = signals[i] if i < len(signals) else 0
+
+        if target == 1 and qty == 0 and cash > 0:
+            buy_qty = cash / price
+            cash = 0.0
+            qty = buy_qty
+            avg = price
+            entry_ts = bar["ts"]
+            equity = qty * price
+            new_trades.append(_trade("buy", bar["ts"], price, buy_qty, equity))
+        elif target == 0 and qty > 0:
+            proceeds = qty * price
+            realized += (price - (avg or price)) * qty
+            cash += proceeds
+            sell_qty = qty
+            qty = 0.0
+            avg = None
+            entry_ts = None
+            equity = cash
+            new_trades.append(_trade("sell", bar["ts"], price, sell_qty, equity))
+
+        last_price = price
+        last_bar_ts = bar["ts"]
+
+    equity = cash + qty * (last_price or 0.0)
+
+    for trade in new_trades:
+        store.append_trade(run_id, trade["side"], trade["ts"], trade["price"],
+                           trade["qty"], trade["equity_after"])
+
+    store.update_run(
+        run_id,
+        cash=cash,
+        position_qty=qty,
+        position_avg_price=avg,
+        position_entry_ts=entry_ts,
+        last_price=last_price,
+        equity=equity,
+        realized_pnl=realized,
+        last_bar_ts=last_bar_ts,
+        last_tick_at=ms_to_iso(now_ms),
+        note="",
+    )
+
+    run = store.get_run(run_id)
+    return _result(run, "advanced", len(unprocessed), new_trades)
+
+
+def sync_all(store: Store, broker, now_ms=None) -> list[dict]:
+    """Sync every active run. Returns a result dict per run."""
+    return [
+        sync_run(store, broker, run["id"], now_ms=now_ms)
+        for run in store.list_runs(status="active")
+    ]
+
+
+def stop_run(store: Store, broker, run_id, now_ms=None) -> dict:
+    """Sync a run one last time, then mark it stopped. Returns a final summary."""
+    result = sync_run(store, broker, run_id, now_ms=now_ms)
+    run = store.get_run(run_id)
+    if run is None:
+        return {"run_id": run_id, "status": "not_found"}
+    if run["status"] == "active":
+        store.update_run(run_id, status="stopped")
+        run["status"] = "stopped"
+    summary = _result(run, "stopped", result.get("bars_processed", 0),
+                      result.get("trades", []))
+    summary["realized_pnl"] = run["realized_pnl"]
+    summary["trade_count"] = len(store.list_trades(run_id))
+    return summary
+
+
+def _trade(side, ts, price, qty, equity_after) -> dict:
+    return {"side": side, "ts": ts, "price": price, "qty": qty,
+            "equity_after": equity_after}
+
+
+def _result(run, status, bars_processed, trades) -> dict:
+    return {
+        "run_id": run["id"],
+        "status": status,
+        "bars_processed": bars_processed,
+        "trades": trades,
+        "symbol": run["symbol"],
+        "interval": run["interval"],
+        "strategy_type": run["strategy_type"],
+        "position_qty": run["position_qty"],
+        "cash": run["cash"],
+        "equity": run["equity"],
+        "realized_pnl": run["realized_pnl"],
+        "last_bar_ts": run["last_bar_ts"],
+        "note": run["note"],
+    }