backtestchat 0.1.0__py3-none-any.whl

backtestchat/strategy/signals.py

@@ -0,0 +1,303 @@
+"""Long/flat signal functions.
+
+Each strategy has a `*_series(bars, params) -> (signals, indicators)` function:
+`signals` is the per-bar target position (1 = fully long, 0 = flat) and
+`indicators` is an ordered dict of the named derived series the trade rule
+reads (per-bar lists aligned 1:1 with bars, None during warmup). The
+`*_signals(bars, params) -> list[int]` wrappers keep the original engine
+contract. `bars` is a list of dicts with keys ts/open/high/low/close/volume.
+Warmup bars (before the indicator is defined) are flat (0). Stateful signals
+(rsi/bollinger/donchian/atr_channel) hold their position between an entry and
+exit condition.
+
+Indicator keys are parameterized (e.g. `sma_50`, `bb_lower_20_2`) so consumers
+joining series from multiple strategies never mix differently-parameterized
+series under one name.
+"""
+
+from backtestchat.strategy import indicators as ind
+
+
+def _field(bars, key):
+    return [float(b[key]) for b in bars]
+
+
+def _fmt(value):
+    """Format a numeric param for an indicator key (2.0 -> "2")."""
+    return f"{value:g}"
+
+
+def buy_hold_series(bars, params):
+    return [1] * len(bars), {}
+
+
+def buy_hold_signals(bars, params):
+    return buy_hold_series(bars, params)[0]
+
+
+def ma_crossover_series(bars, params):
+    closes = _field(bars, "close")
+    fast = ind.sma(closes, params["fast"])
+    slow = ind.sma(closes, params["slow"])
+    indicators = {
+        f"sma_{params['fast']}": fast,
+        f"sma_{params['slow']}": slow,
+    }
+    signals = [
+        1 if (fast[i] is not None and slow[i] is not None and fast[i] > slow[i]) else 0
+        for i in range(len(closes))
+    ]
+    return signals, indicators
+
+
+def ma_crossover_signals(bars, params):
+    return ma_crossover_series(bars, params)[0]
+
+
+def ema_crossover_series(bars, params):
+    closes = _field(bars, "close")
+    fast = ind.ema(closes, params["fast"])
+    slow = ind.ema(closes, params["slow"])
+    indicators = {
+        f"ema_{params['fast']}": fast,
+        f"ema_{params['slow']}": slow,
+    }
+    signals = [
+        1 if (fast[i] is not None and slow[i] is not None and fast[i] > slow[i]) else 0
+        for i in range(len(closes))
+    ]
+    return signals, indicators
+
+
+def ema_crossover_signals(bars, params):
+    return ema_crossover_series(bars, params)[0]
+
+
+def macd_series(bars, params):
+    closes = _field(bars, "close")
+    macd_line, signal_line = ind.macd(closes, params["fast"], params["slow"], params["signal"])
+    indicators = {
+        f"macd_{params['fast']}_{params['slow']}": macd_line,
+        f"macd_signal_{params['fast']}_{params['slow']}_{params['signal']}": signal_line,
+    }
+    signals = [
+        1 if (macd_line[i] is not None and signal_line[i] is not None and macd_line[i] > signal_line[i]) else 0
+        for i in range(len(closes))
+    ]
+    return signals, indicators
+
+
+def macd_signals(bars, params):
+    return macd_series(bars, params)[0]
+
+
+def roc_series(bars, params):
+    closes = _field(bars, "close")
+    values = ind.roc(closes, params["period"])
+    indicators = {f"roc_{params['period']}": values}
+    signals = [1 if (values[i] is not None and values[i] > 0) else 0 for i in range(len(closes))]
+    return signals, indicators
+
+
+def roc_signals(bars, params):
+    return roc_series(bars, params)[0]
+
+
+def price_above_sma_series(bars, params):
+    closes = _field(bars, "close")
+    avg = ind.sma(closes, params["window"])
+    indicators = {f"sma_{params['window']}": avg}
+    signals = [
+        1 if (avg[i] is not None and closes[i] > avg[i]) else 0
+        for i in range(len(closes))
+    ]
+    return signals, indicators
+
+
+def price_above_sma_signals(bars, params):
+    return price_above_sma_series(bars, params)[0]
+
+
+def rsi_series(bars, params):
+    """Mean-reversion: enter long below `lower`, exit above `upper` (stateful)."""
+    closes = _field(bars, "close")
+    values = ind.rsi(closes, params["period"])
+    lower, upper = params["lower"], params["upper"]
+
+    out = []
+    position = 0
+    for v in values:
+        if v is None:
+            out.append(0)
+            continue
+        if position == 0 and v < lower:
+            position = 1
+        elif position == 1 and v > upper:
+            position = 0
+        out.append(position)
+
+    return out, {f"rsi_{params['period']}": values}
+
+
+def rsi_signals(bars, params):
+    return rsi_series(bars, params)[0]
+
+
+def bollinger_series(bars, params):
+    """Mean-reversion: enter long below the lower band, exit above the middle (stateful)."""
+    closes = _field(bars, "close")
+    window, num_std = params["window"], params["num_std"]
+    mid = ind.sma(closes, window)
+    std = ind.rolling_std(closes, window)
+
+    upper_band = [
+        (mid[i] + num_std * std[i]) if (mid[i] is not None and std[i] is not None) else None
+        for i in range(len(closes))
+    ]
+    lower_band = [
+        (mid[i] - num_std * std[i]) if (mid[i] is not None and std[i] is not None) else None
+        for i in range(len(closes))
+    ]
+    indicators = {
+        f"bb_mid_{window}": mid,
+        f"bb_upper_{window}_{_fmt(num_std)}": upper_band,
+        f"bb_lower_{window}_{_fmt(num_std)}": lower_band,
+    }
+
+    out = []
+    position = 0
+    for i in range(len(closes)):
+        if lower_band[i] is None:
+            out.append(0)
+            continue
+        if position == 0 and closes[i] < lower_band[i]:
+            position = 1
+        elif position == 1 and closes[i] > mid[i]:
+            position = 0
+        out.append(position)
+
+    return out, indicators
+
+
+def bollinger_signals(bars, params):
+    return bollinger_series(bars, params)[0]
+
+
+def donchian_breakout_series(bars, params):
+    """Trend breakout: enter long above the prior `entry`-day high, exit below the
+    prior `exit`-day low (stateful). Uses prior bars to avoid look-ahead."""
+    highs = _field(bars, "high")
+    lows = _field(bars, "low")
+    closes = _field(bars, "close")
+    entry, exit_w = params["entry"], params["exit"]
+
+    prior_high = [
+        max(highs[i - entry:i]) if i >= entry else None
+        for i in range(len(closes))
+    ]
+    prior_low = [
+        min(lows[i - exit_w:i]) if i >= exit_w else None
+        for i in range(len(closes))
+    ]
+    indicators = {
+        f"prior_high_{entry}": prior_high,
+        f"prior_low_{exit_w}": prior_low,
+    }
+
+    out = []
+    position = 0
+    for i in range(len(closes)):
+        if prior_high[i] is None:
+            out.append(0)
+            continue
+        if position == 0 and closes[i] > prior_high[i]:
+            position = 1
+        elif position == 1 and prior_low[i] is not None and closes[i] < prior_low[i]:
+            position = 0
+        out.append(position)
+
+    return out, indicators
+
+
+def donchian_breakout_signals(bars, params):
+    return donchian_breakout_series(bars, params)[0]
+
+
+def stochastic_series(bars, params):
+    """Long when %K > %D."""
+    highs = _field(bars, "high")
+    lows = _field(bars, "low")
+    closes = _field(bars, "close")
+    k_period, d_period = params["k"], params["d"]
+
+    hh = ind.rolling_max(highs, k_period)
+    ll = ind.rolling_min(lows, k_period)
+
+    percent_k = []
+    for i in range(len(closes)):
+        if hh[i] is None or ll[i] is None or hh[i] == ll[i]:
+            percent_k.append(None)
+        else:
+            percent_k.append(100.0 * (closes[i] - ll[i]) / (hh[i] - ll[i]))
+
+    # %D = SMA of %K over its valid tail.
+    valid = [v for v in percent_k if v is not None]
+    d_tail = ind.sma(valid, d_period)
+    percent_d = [None] * len(closes)
+    first_valid = next((i for i, v in enumerate(percent_k) if v is not None), None)
+    if first_valid is not None:
+        for offset, value in enumerate(d_tail):
+            percent_d[first_valid + offset] = value
+
+    indicators = {
+        f"stoch_k_{k_period}": percent_k,
+        f"stoch_d_{k_period}_{d_period}": percent_d,
+    }
+    signals = [
+        1 if (percent_k[i] is not None and percent_d[i] is not None and percent_k[i] > percent_d[i]) else 0
+        for i in range(len(closes))
+    ]
+    return signals, indicators
+
+
+def stochastic_signals(bars, params):
+    return stochastic_series(bars, params)[0]
+
+
+def atr_channel_series(bars, params):
+    """Keltner-style breakout: enter long above EMA + mult*ATR, exit below EMA (stateful)."""
+    highs = _field(bars, "high")
+    lows = _field(bars, "low")
+    closes = _field(bars, "close")
+    window, mult = params["window"], params["mult"]
+
+    mid = ind.ema(closes, window)
+    atr_vals = ind.atr(highs, lows, closes, window)
+
+    upper = [
+        (mid[i] + mult * atr_vals[i]) if (mid[i] is not None and atr_vals[i] is not None) else None
+        for i in range(len(closes))
+    ]
+    indicators = {
+        f"ema_{window}": mid,
+        f"atr_{window}": atr_vals,
+        f"atr_upper_{window}_{_fmt(mult)}": upper,
+    }
+
+    out = []
+    position = 0
+    for i in range(len(closes)):
+        if upper[i] is None:
+            out.append(0)
+            continue
+        if position == 0 and closes[i] > upper[i]:
+            position = 1
+        elif position == 1 and closes[i] < mid[i]:
+            position = 0
+        out.append(position)
+
+    return out, indicators
+
+
+def atr_channel_signals(bars, params):
+    return atr_channel_series(bars, params)[0]

backtestchat-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: backtestchat
+Version: 0.1.0
+Summary: Local-first agentic strategy lab CLI: chat, backtest, and paper-trade long/flat strategies on keyless Binance public data.
+Project-URL: Homepage, https://github.com/barisarat/backtestchat
+Project-URL: Repository, https://github.com/barisarat/backtestchat
+Project-URL: Issues, https://github.com/barisarat/backtestchat/issues
+Author: Baris Arat
+License: MIT
+License-File: LICENSE
+Keywords: agent,backtest,binance,cli,langgraph,paper-trading,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain>=0.3.0
+Requires-Dist: langgraph-checkpoint-sqlite>=2.0.0
+Requires-Dist: langgraph>=0.2.60
+Requires-Dist: plotly>=5.22.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=0.2.0; extra == 'anthropic'
+Provides-Extra: ollama
+Requires-Dist: langchain-ollama>=0.2.0; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.2.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# backtestchat
+
+An open-source, local-first agentic strategy lab in your terminal. Chat with a
+LangGraph agent to fetch keyless Binance public market data, design and backtest
+long/flat crypto strategies, and run simulated paper trades. Charts render to
+self-contained plotly HTML that opens in your browser.
+
+**Paper-only by design.** backtestchat simulates fills from closed bars. It never
+places real orders and never needs exchange API keys. Market data comes from the
+public, keyless Binance REST API. The only key you supply is your own model
+(BYOK) key, or a local Ollama endpoint.
+
+> backtestchat is a research and simulation tool and a portfolio/learning project.
+> It is not financial advice and not a trading product. Do not use it to make
+> investment decisions.
+
+<!-- TODO: asciinema GIF of a chat session (quote -> backtest -> chart). -->
+<!-- TODO: screenshot of a backtestReport chart. -->
+
+## Quickstart
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/barisarat/backtestchat
+cd backtestchat
+uv sync --extra openai              # deps + the OpenAI model provider
+
+export BACKTESTCHAT_MODEL=openai:gpt-5.4-nano
+export OPENAI_API_KEY=sk-...
+
+uv run backtestchat chat                # talk to the agent
+uv run backtestchat runs sync           # advance paper runs to the latest closed bar
+uv run backtestchat runs list           # check paper run status
+```
+
+Two things to know:
+
+- The `backtestchat` command lives in the project venv, so either prefix every
+  command with `uv run`, or activate the venv once with
+  `source .venv/bin/activate` and call `backtestchat` directly.
+- Always sync with the extra for the provider you use. A plain `uv sync`
+  removes extras, and `backtestchat chat` will fail until you
+  `uv sync --extra openai` again.
+
+Market data works with **zero keys**; only the chat agent needs a model key.
+Other providers (Anthropic, Ollama, ...) are covered under
+[Model setup](#model-setup-byok).
+
+## What it does
+
+- **Chat** with a tool-calling agent (LangGraph) that maps your plain-English
+  requests onto market-data, backtest, and paper-trade actions.
+- **Backtest** ~11 single-signal long/flat strategies (SMA/EMA crossover, MACD,
+  RSI, Bollinger, Donchian, ROC, stochastic, ATR channel, price-vs-SMA,
+  buy & hold) with CAGR, Sharpe, max drawdown, win rate, and trade count.
+- **Compare** several strategies at once, ranked, on one chart.
+- **Paper-trade** a strategy with simulated fills. Runs advance by replaying
+  closed bars - no daemon, no scheduler. Any command can trigger a cheap sync.
+- **Charts** are deterministic plotly HTML written to `./artifacts`. The model
+  never writes HTML; it only triggers the tools that build the charts.
+
+Supported intervals: **15m, 1h, 4h, 1d**. Symbols: any Binance spot pair
+(BTCUSDT, ETHUSDT, SOLUSDT, XRPUSDT, DOGEUSDT, ...).
+
+## Model setup (BYOK)
+
+backtestchat talks to any provider via LangChain's `init_chat_model`, configured with
+a `provider:model` string in `BACKTESTCHAT_MODEL` (or `model = "..."` in
+`./backtestchat.toml`). The default setup uses OpenAI:
+
+```bash
+uv sync --extra openai
+export BACKTESTCHAT_MODEL=openai:gpt-5.4-nano
+export OPENAI_API_KEY=sk-...
+```
+
+Any provider `init_chat_model` supports works the same way: install the matching
+extra (`--extra anthropic`, `--extra ollama`, ...) and set `BACKTESTCHAT_MODEL` to
+that provider's `provider:model` string plus its API key (Ollama runs locally
+and needs no key).
+
+If no model is configured, `backtestchat chat` prints these instructions and exits.
+Check what is resolved with `backtestchat config`.
+
+## Usage
+
+```bash
+uv run backtestchat chat
+```
+
+Then talk to it naturally:
+
+```
+you > what's BTC trading at?
+you > backtest an ma crossover 20/50 on BTCUSDT 1h over the last 3 months
+you > compare that against buy and hold and rsi
+you > save that strategy            # asks you to confirm in the terminal
+you > start a paper run with 5000 usdt   # asks you to confirm
+you > list my paper runs
+```
+
+Charts open automatically in your browser and are saved under `./artifacts`.
+Saving a strategy and starting a paper run pause for a y/n confirmation
+(human-in-the-loop, implemented with LangGraph interrupts).
+
+### Commands
+
+```bash
+backtestchat chat [--new] [--thread ID]   # agent REPL (resumes the last thread by default)
+backtestchat runs list [--status active]  # list paper runs (stored state)
+backtestchat runs sync                    # advance all active runs to the latest closed bar
+backtestchat show [last|FILE]             # open a rendered chart artifact
+backtestchat config                       # print resolved configuration
+```
+
+### How paper runs work
+
+A paper run does not backdate: the first simulated fill happens on the first bar
+that **closes after** you create the run, so a fresh run shows
+"waiting for first tick" until then. Advancing a run replays every closed bar
+since its last processed bar, one signal evaluation per bar. Because the
+already-processed-bar guard is the only cadence control, `backtestchat runs sync` is
+safe to run anytime and is idempotent.
+
+## LangSmith tracing (optional)
+
+Set the standard env vars and traces appear in your LangSmith project - no code
+or flags required:
+
+```bash
+export LANGSMITH_TRACING=true
+export LANGSMITH_API_KEY=...
+```
+
+## Configuration
+
+Resolved in order: environment variables > `./backtestchat.toml` > defaults.
+
+| Key | Env var | Default |
+|---|---|---|
+| model | `BACKTESTCHAT_MODEL` | (unset; required for chat) |
+| data dir | `BACKTESTCHAT_DATA_DIR` | `./data` |
+| artifacts dir | `BACKTESTCHAT_ARTIFACTS_DIR` | `./artifacts` |
+
+`./data` holds the sqlite store (strategies, paper runs, trades) and the
+LangGraph checkpoint database. `./artifacts` holds rendered chart HTML. Both are
+gitignored.
+
+## Development
+
+```bash
+uv sync --extra openai  # dev dependencies included; keep your provider extra
+uv run pytest -q        # deterministic, no network, no model key
+```
+
+The engine, signals, broker window logic, and paper runner are pure and tested
+against fixture bars. Market-data and agent layers are tested with mocked HTTP
+and a scripted fake model, so the whole suite runs offline.
+
+## License
+
+MIT - see [LICENSE](LICENSE).

backtestchat-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+backtestchat/__init__.py,sha256=L8Rctro0jN2DzQwpDcwN94pNIxiWrvDOb8kE-cxUbKw,277
+backtestchat/__main__.py,sha256=uvGwUv7A2HsYAeQQv5M3uyah6RIF-9BJ9JKFHgPXtDE,111
+backtestchat/artifacts.py,sha256=uJ4TI6Vxs4P697M02zDBfFBQX5JhqBiGVG_JFNa7DeM,1781
+backtestchat/cli.py,sha256=LdpTHeA6tRaC_tPGNVhKxp4Hbdp9BHl0Lp3f9xWp8DA,6447
+backtestchat/config.py,sha256=oDCFVOrZnrF-YqsBuajToM1VKZLEz3Cb5sxPOAhPuJg,2663
+backtestchat/agent/__init__.py,sha256=zsRu0ZAkeCL4Ut4vMle4OqEIyxbMmFTHFTYNyFa49-4,467
+backtestchat/agent/chat.py,sha256=w5dwXF5-zD6A7SIjR6EJgb0veYNxE_WUIssLLh2ErXQ,7852
+backtestchat/agent/context.py,sha256=svD4OnnFdK4RHIcubE1T36xIz9Siib_36uoE1tqnXHc,2326
+backtestchat/agent/graph.py,sha256=OwkG3ljsXv60tv4f5u1ZLi2uYJnbIMjl5w2ye6fVR-o,4270
+backtestchat/agent/prompt.py,sha256=2QPXgbQAO9P4QpFZxphp5y1ll7gAA6_JdAMDRLgEbLg,2625
+backtestchat/agent/tools.py,sha256=910HHHjrneX77yREKaoEvAUZqwQXp-vyc3QEPAtsn_8,16324
+backtestchat/broker/__init__.py,sha256=vHHL56FCb2D98fngGZILaKwFOJ_5Mkh4khFjgc2B97o,883
+backtestchat/broker/base.py,sha256=Y7VLjrVkQincgmNMDiYp7B9cnKcDBXHGPqyVJL1B3F0,8253
+backtestchat/broker/binance.py,sha256=6SEhAvSrON6a0vOTF_-u_Wsl1p-zQVUyPGAII75pPMk,9729
+backtestchat/paper/__init__.py,sha256=ML1jQjmfokSiabpWK_NNW4K4CnoaRjz1YJnBXA63PHs,440
+backtestchat/paper/runner.py,sha256=DqOmWGW8NwVllDK6SMvOcL98zRLu0UmvlEDxCtzM_po,8146
+backtestchat/paper/store.py,sha256=8DuI00C76aJXS7dP7CU46FCHQCVEMIdOxaJd82tXvNo,7694
+backtestchat/render/__init__.py,sha256=BpW1kmQ7qpbyzjgucrbj_u2feSnDkV_Ul0xOgPJUDQo,632
+backtestchat/render/plotly_render.py,sha256=baVSqJtudZGJw8bPWI_dvtaS6gNZXcWm-8mfpmItZQQ,7069
+backtestchat/render/widgets.py,sha256=uelPHY6qj8zW-Jk1vbSkBPti_gE0Z1fumA839Wnr7jQ,3350
+backtestchat/strategy/__init__.py,sha256=BwP82fKE9swhXX92AiNBqV1Ty58jYNq_hsvkzduL5Jg,662
+backtestchat/strategy/engine.py,sha256=jp4UheuXtxEQwhjdzsh0ZSmtjCjnq_wm_aPJUZRCHnI,6095
+backtestchat/strategy/indicators.py,sha256=JH5UhQF42k8NVCyDTThn_Xaf2pLgr3BTyo9TU5W0qZg,4907
+backtestchat/strategy/registry.py,sha256=dAss6YEq-TolUrGqXtU5vZvLU-N-5ZsZWTyYm-sYGoA,10326
+backtestchat/strategy/signals.py,sha256=BB8PkiZRa3c8Q31zFKmZnK0skcDZsnwWP4KG-nSaylg,9200
+backtestchat-0.1.0.dist-info/METADATA,sha256=m_fsK4CoKcoJErIy6he7B8lyKuFl6X2xCQhKHgdW9NU,7654
+backtestchat-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+backtestchat-0.1.0.dist-info/entry_points.txt,sha256=BUUDC4t3lf9mvV1jOFtmbT0J1xEzmR_MYsTwTUv0vSs,84
+backtestchat-0.1.0.dist-info/licenses/LICENSE,sha256=IvWZgG54IXnO0mwORHbH0nVGd7cjsly8pAPcc2mcB10,1067
+backtestchat-0.1.0.dist-info/RECORD,,

backtestchat-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

backtestchat-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+backtestchat = backtestchat.cli:app
+btchat = backtestchat.cli:app

backtestchat-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baris Arat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.