backtestchat 0.1.0__py3-none-any.whl

backtestchat/__init__.py

@@ -0,0 +1,8 @@
+"""backtestchat: a local-first agentic strategy lab CLI.
+
+Chat with a LangGraph agent to fetch keyless Binance public market data,
+backtest long/flat strategies, and run simulated paper trades. Paper-only by
+design: no exchange keys, no real orders.
+"""
+
+__version__ = "0.1.0"

backtestchat/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m backtestchat`."""
+
+from backtestchat.cli import app
+
+if __name__ == "__main__":
+    app()

backtestchat/agent/__init__.py

@@ -0,0 +1,11 @@
+"""The agent layer: LangGraph graph, tools, prompt, and context compression.
+
+This is the hand-crafted part of backtestchat. Everything below it (broker, engine,
+paper, render) is boring and testable; the value here is the tool surface and
+the graph wiring.
+"""
+
+from backtestchat.agent.graph import MAX_TOOL_ROUNDS, build_graph
+from backtestchat.agent.tools import ToolContext, build_tools
+
+__all__ = ["MAX_TOOL_ROUNDS", "ToolContext", "build_tools", "build_graph"]

backtestchat/agent/chat.py

@@ -0,0 +1,222 @@
+"""Interactive chat runtime: builds the session and drives the streaming REPL.
+
+Streams model tokens with rich, announces tool calls, handles the sensitive-tool
+approval interrupts (y/n in the terminal), and renders the turn's widgets to
+self-contained HTML afterward - opening the newest in a browser and recording it
+so `backtestchat show last` can reopen it.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import webbrowser
+from dataclasses import dataclass
+
+from langchain_core.messages import (
+    AIMessage,
+    AIMessageChunk,
+    HumanMessage,
+    ToolMessage,
+)
+from langgraph.checkpoint.sqlite import SqliteSaver
+from langgraph.types import Command
+from rich.console import Console
+
+from backtestchat.agent.graph import ABORTED_TOOL_RESULT, build_graph
+from backtestchat.agent.tools import ToolContext, build_tools
+from backtestchat.artifacts import record_last_artifact
+from backtestchat.broker.binance import BinanceBroker
+from backtestchat.config import Config, ensure_dirs
+from backtestchat.paper.store import Store
+from backtestchat.render.plotly_render import render_widget
+
+
+class ModelSetupError(RuntimeError):
+    """The configured model could not be initialized (missing package/key)."""
+
+
+@dataclass
+class Session:
+    graph: object
+    ctx: ToolContext
+    conn: sqlite3.Connection
+
+    def close(self) -> None:
+        self.ctx.broker.close()
+        self.ctx.store.close()
+        self.conn.close()
+
+
+def init_model(model_id: str):
+    """init_chat_model('provider:model'), with friendly setup errors."""
+    from langchain.chat_models import init_chat_model
+
+    try:
+        return init_chat_model(model_id)
+    except ImportError as exc:
+        provider = model_id.split(":", 1)[0]
+        raise ModelSetupError(
+            f"Missing the integration package for provider '{provider}'. "
+            f"Install the matching extra, e.g. `uv sync --extra {provider}`. "
+            f"({exc})"
+        ) from exc
+    except Exception as exc:  # noqa: BLE001 - surface any init failure cleanly
+        raise ModelSetupError(f"Could not initialize model '{model_id}': {exc}") from exc
+
+
+def build_session(cfg: Config) -> Session:
+    ensure_dirs(cfg)
+    model = init_model(cfg.model)
+    broker = BinanceBroker(data_dir=cfg.data_dir)
+    store = Store(cfg.db_path)
+    ctx = ToolContext(broker=broker, store=store, cfg=cfg)
+    tools = build_tools(ctx)
+
+    conn = sqlite3.connect(str(cfg.checkpoint_path), check_same_thread=False)
+    saver = SqliteSaver(conn)
+    graph = build_graph(model, tools, saver)
+    return Session(graph=graph, ctx=ctx, conn=conn)
+
+
+def run_repl(session: Session, thread_id: str, console: Console) -> None:
+    config = {"configurable": {"thread_id": thread_id}}
+    console.print(f"[dim]backtestchat chat (thread: {thread_id}). Paper-only "
+                  f"simulation - not financial advice.[/dim]")
+    console.print("[dim]Type your message, or /exit to quit.[/dim]\n")
+
+    while True:
+        try:
+            text = console.input("[bold cyan]you[/bold cyan] > ").strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print("\n[dim]bye[/dim]")
+            return
+        if not text:
+            continue
+        if text in ("/exit", "/quit", "exit", "quit"):
+            console.print("[dim]bye[/dim]")
+            return
+
+        console.print("[bold green]backtestchat[/bold green] > ", end="")
+        try:
+            _run_turn(session, text, config, console)
+        except Exception as exc:  # noqa: BLE001 - keep the REPL alive
+            console.print(f"\n[red]error:[/red] {exc}")
+
+
+def _run_turn(session: Session, text: str, config: dict, console: Console) -> None:
+    session.ctx.widgets.clear()
+    _reconcile_pending(session.graph, config)
+    _drive(session, {"messages": [HumanMessage(content=text)]}, config, console)
+    _render_widgets(session.ctx, console)
+
+
+def _reconcile_pending(graph, config) -> None:
+    """If a prior turn was killed mid-flight (e.g. Ctrl-C after the model asked
+    for a tool but before it ran), the thread has a PENDING tools step that
+    would otherwise execute that stale tool on the next input. Answer any
+    dangling tool call as the tools node (aborted) so the stale tool never
+    fires and the new turn starts clean.
+    """
+    try:
+        snapshot = graph.get_state(config)
+    except Exception:  # noqa: BLE001 - no/covered checkpoint yet
+        return
+    if not snapshot or not snapshot.next:
+        return
+    messages = (snapshot.values or {}).get("messages", [])
+    if not messages:
+        return
+    last = messages[-1]
+    if not (isinstance(last, AIMessage) and last.tool_calls):
+        return
+    answers = [
+        ToolMessage(content=ABORTED_TOOL_RESULT, tool_call_id=call["id"])
+        for call in last.tool_calls
+    ]
+    try:
+        graph.update_state(config, {"messages": answers}, as_node="tools")
+    except Exception:  # noqa: BLE001 - fall back to the history-repair path
+        pass
+
+
+def _drive(session, payload, config, console) -> None:
+    """Stream one graph run to completion, recursing on approval interrupts."""
+    printed = False
+    for mode, chunk in session.graph.stream(
+        payload, config, stream_mode=["updates", "messages"]
+    ):
+        if mode == "messages":
+            message, _meta = chunk
+            if isinstance(message, AIMessageChunk):
+                piece = _text(message.content)
+                if piece:
+                    console.print(piece, end="", markup=False, highlight=False)
+                    printed = True
+        elif mode == "updates":
+            if "__interrupt__" in chunk:
+                if printed:
+                    console.print()
+                decision = _ask_approval(chunk["__interrupt__"], console)
+                _drive(session, Command(resume=decision), config, console)
+                return
+            _announce_tools(chunk, console)
+    if printed:
+        console.print()
+
+
+def _ask_approval(interrupts, console: Console) -> str:
+    payload = interrupts[0].value or {}
+    summary = payload.get("summary", "Confirm this action?")
+    details = payload.get("details", {})
+    console.print(f"\n[yellow]{summary}[/yellow]")
+    for key, value in details.items():
+        console.print(f"  [dim]{key}:[/dim] {value}")
+    try:
+        answer = console.input("[bold]approve? \\[y/N][/bold] ").strip()
+    except (EOFError, KeyboardInterrupt):
+        answer = "n"
+    return answer or "n"
+
+
+def _announce_tools(update: dict, console: Console) -> None:
+    model_update = update.get("model")
+    if not model_update:
+        return
+    for message in model_update.get("messages", []):
+        for call in getattr(message, "tool_calls", None) or []:
+            console.print(f"[dim]-> {call['name']}({_fmt_args(call.get('args', {}))})[/dim]")
+
+
+def _render_widgets(ctx: ToolContext, console: Console) -> None:
+    if not ctx.widgets:
+        return
+    last_path = None
+    for widget in ctx.widgets:
+        try:
+            path = render_widget(widget, ctx.cfg.artifacts_dir)
+        except Exception as exc:  # noqa: BLE001
+            console.print(f"[red]chart render failed:[/red] {exc}")
+            continue
+        console.print(f"[dim]chart: {path}[/dim]")
+        last_path = path
+    if last_path is not None:
+        record_last_artifact(ctx.cfg, last_path)
+        try:
+            webbrowser.open(last_path.resolve().as_uri())
+        except Exception:  # noqa: BLE001 - headless env, just skip
+            pass
+
+
+def _text(content) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "".join(
+            part.get("text", "") if isinstance(part, dict) else str(part)
+            for part in content
+        )
+    return ""
+
+
+def _fmt_args(args: dict) -> str:
+    return ", ".join(f"{k}={v!r}" for k, v in args.items())

backtestchat/agent/context.py

@@ -0,0 +1,72 @@
+"""Tool-result compression for model context.
+
+Tools compute rich results (full bar arrays, equity curves), but only a COMPACT
+view goes into the model's context - raw series never do. The full data rides
+the widget side channel to the renderer instead.
+
+These helpers are pure and take already-computed pieces, so the tools stay thin.
+"""
+
+from __future__ import annotations
+
+from backtestchat.render.widgets import compute_series_stats
+
+
+def compact_price_series(symbol, interval, range_key, points) -> dict:
+    """Compact stats for a fetched close series (no raw points to the model)."""
+    stats = compute_series_stats(points)
+    return {
+        "symbol": symbol,
+        "interval": interval,
+        "range": range_key,
+        "bars": stats["count"],
+        "start": points[0]["ts"] if points else None,
+        "end": points[-1]["ts"] if points else None,
+        "first": stats["first"],
+        "last": stats["last"],
+        "min": stats["min"],
+        "max": stats["max"],
+        "returnPct": stats["returnPct"],
+        "chart": "priceSeries",
+    }
+
+
+def compact_backtest(symbol, interval, range_key, strategy_type, strategy_label,
+                     params, result) -> dict:
+    """Metrics + config for the model; the equity curve and trades go to the
+    widget, not into context."""
+    return {
+        "symbol": symbol,
+        "interval": interval,
+        "range": range_key,
+        "strategyType": strategy_type,
+        "strategyLabel": strategy_label,
+        "params": params,
+        "metrics": result["metrics"],
+        "tradeCount": len(result["trades"]),
+        "chart": "backtestReport",
+    }
+
+
+def compact_compare(symbol, interval, range_key, entries) -> dict:
+    """Ranked per-strategy metrics only (no equity curves) for the model."""
+    ranked = sorted(
+        entries,
+        key=lambda e: e["result"]["metrics"].get("totalReturnPct", 0.0),
+        reverse=True,
+    )
+    return {
+        "symbol": symbol,
+        "interval": interval,
+        "range": range_key,
+        "ranking": [
+            {
+                "strategyType": e["strategyType"],
+                "label": e["label"],
+                "params": e["params"],
+                "metrics": e["result"]["metrics"],
+            }
+            for e in ranked
+        ],
+        "chart": "backtestCompare",
+    }

backtestchat/agent/graph.py

@@ -0,0 +1,103 @@
+"""The LangGraph agent graph: model node <-> tools node, with a hard cap of 6
+tool rounds per user turn.
+
+LangGraph replaces v4's hand-rolled tool-calling loop (agent_service.py). The
+graph is a standard tool-calling cycle with two refinements:
+
+  - The 6-round cap is enforced INSIDE the model node: once a turn has already
+    produced 6 tool-calling messages, the model is invoked WITHOUT tools, so it
+    must answer from what it has. This avoids ever ending a turn on an
+    unexecuted tool-call message (which would leave a dangling tool_call that
+    breaks the next turn's message pairing).
+  - Human-in-the-loop is a dynamic interrupt() raised inside the sensitive tools
+    (save_strategy, start_paper_run), not a graph-level interrupt_before - so
+    the pause carries a rich summary and only fires for those two tools.
+
+The checkpointer (SqliteSaver) makes each thread resumable and is also what lets
+the dynamic interrupts pause/resume.
+"""
+
+from __future__ import annotations
+
+from langchain_core.messages import (
+    AIMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
+from langgraph.graph import END, START, MessagesState, StateGraph
+from langgraph.prebuilt import ToolNode
+
+from backtestchat.agent.prompt import build_system_prompt
+
+MAX_TOOL_ROUNDS = 6
+
+ABORTED_TOOL_RESULT = (
+    '{"error": "aborted", "message": "The previous tool call did not complete."}'
+)
+
+
+def repair_dangling_tool_calls(messages: list) -> list:
+    """Return a copy of `messages` where every assistant tool_call has a tool
+    response, inserting a synthetic aborted-result ToolMessage for any that do
+    not. Without this, a crash or hard-stop that leaves a tool_call unanswered
+    (in the persisted checkpoint) makes every later turn fail the provider's
+    "tool_calls must be followed by tool messages" rule - a wedged thread.
+    """
+    answered = {
+        m.tool_call_id for m in messages if isinstance(m, ToolMessage)
+    }
+    repaired: list = []
+    for message in messages:
+        repaired.append(message)
+        if isinstance(message, AIMessage) and message.tool_calls:
+            for call in message.tool_calls:
+                call_id = call["id"]
+                if call_id not in answered:
+                    repaired.append(ToolMessage(
+                        content=ABORTED_TOOL_RESULT, tool_call_id=call_id))
+                    answered.add(call_id)
+    return repaired
+
+
+def _tool_rounds_this_turn(messages) -> int:
+    """Count tool-calling AI messages since the last human message."""
+    rounds = 0
+    for message in reversed(messages):
+        if isinstance(message, HumanMessage):
+            break
+        if isinstance(message, AIMessage) and message.tool_calls:
+            rounds += 1
+    return rounds
+
+
+def build_graph(model, tools, checkpointer):
+    """Compile the agent graph. `model` is a chat model (from init_chat_model);
+    `tools` are the built @tool functions; `checkpointer` is a SqliteSaver."""
+    system_prompt = build_system_prompt()
+    model_with_tools = model.bind_tools(tools)
+
+    def call_model(state: MessagesState) -> dict:
+        history = repair_dangling_tool_calls(list(state["messages"]))
+        messages = [SystemMessage(content=system_prompt)] + history
+        # Once the turn has hit the tool-round cap, withhold tools so the model
+        # is forced to answer instead of requesting more.
+        capped = _tool_rounds_this_turn(state["messages"]) >= MAX_TOOL_ROUNDS
+        llm = model if capped else model_with_tools
+        return {"messages": [llm.invoke(messages)]}
+
+    def should_continue(state: MessagesState):
+        last = state["messages"][-1]
+        if isinstance(last, AIMessage) and last.tool_calls:
+            return "tools"
+        return END
+
+    graph = StateGraph(MessagesState)
+    graph.add_node("model", call_model)
+    # handle_tool_errors=True: a raising tool becomes an error ToolMessage rather
+    # than crashing the turn and leaving a dangling tool_call in the checkpoint.
+    graph.add_node("tools", ToolNode(tools, handle_tool_errors=True))
+    graph.add_edge(START, "model")
+    graph.add_conditional_edges("model", should_continue, {"tools": "tools", END: END})
+    graph.add_edge("tools", "model")
+    return graph.compile(checkpointer=checkpointer)

backtestchat/agent/prompt.py

@@ -0,0 +1,62 @@
+"""System prompt for the backtestchat agent.
+
+Embeds the strategy catalog (from the registry) and the canonical encodings
+directly in the system prompt so the model maps user language onto them.
+"""
+
+from __future__ import annotations
+
+from backtestchat.broker.base import NAMED_RANGE_DAYS, SUPPORTED_INTERVALS
+from backtestchat.strategy.registry import describe_strategies
+
+_EXAMPLE_SYMBOLS = "BTCUSDT, ETHUSDT, SOLUSDT, XRPUSDT, DOGEUSDT"
+
+
+def build_system_prompt() -> str:
+    intervals = ", ".join(SUPPORTED_INTERVALS)
+    range_keys = ", ".join(NAMED_RANGE_DAYS)
+    catalog = describe_strategies()
+
+    return f"""You are backtestchat, a terminal agent for designing and paper-trading
+long/flat crypto strategies on Binance public market data. You are a research and
+simulation tool, not a trading product and not financial advice.
+
+Core rules:
+- Paper-only. Fills are simulated from closed bars. There are no real orders and
+  no exchange keys. Never imply otherwise.
+- State every metric and number from a tool result. NEVER invent or estimate
+  prices, returns, Sharpe ratios, or trade counts. If you do not have a tool
+  result for a number, run the tool or say you do not have it.
+- Charts are generated automatically by the tools (a side channel). Do not
+  describe chart files or write any HTML or markup. Just discuss what the data
+  shows.
+- Keep replies concise and plain ASCII (no fancy dashes, curly quotes, or
+  ellipsis characters).
+
+Canonical encodings (map the user's words onto these; the tools accept ONLY
+these exact values):
+- Symbols: Binance spot pairs, e.g. {_EXAMPLE_SYMBOLS}. Uppercase, no slash.
+- Intervals: {intervals}.
+- Range keys: {range_keys}, or a generic Nd / Nw / Nm / Ny form (e.g. 30d, 6w,
+  18m, 3y).
+- Strategy params are BAR counts at the chosen interval.
+
+Strategy catalog (strategy_type: description):
+{catalog}
+
+Paper-run semantics:
+- Starting a run does not backdate: the first simulated fill is on the first bar
+  that CLOSES after the run is created. A brand-new run sits in a
+  "waiting for first tick" state until then.
+- Advancing a run replays every closed bar since its last processed bar, one
+  signal evaluation per bar. Any command can trigger a cheap sync; there is no
+  daemon.
+- Saving a strategy and starting a paper run both require the user to confirm in
+  the terminal first.
+
+Tool-use guidance:
+- If a tool returns an error with valid_options, correct your arguments and retry
+  using one of those options. Do not guess around a structured error.
+- Prefer one tool call at a time; you have a limited number of tool rounds per
+  turn, so be economical.
+"""