Metadata-Version: 2.4
Name: backtestchat
Version: 0.1.1
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 [uv](https://docs.astral.sh/uv/).

### Install as a tool (recommended)

```bash
uv tool install "backtestchat[openai]"   # CLI + OpenAI provider, in an isolated env
backtestchat init                        # save your OpenAI key + model (written 0600)
backtestchat chat                        # talk to the agent
```

`backtestchat init` prompts for your OpenAI API key (hidden) and model and writes
them to `~/.config/backtestchat/config.toml`. After that, `backtestchat` and its
short alias `btchat` work from any directory. Market data needs **zero keys**;
only the chat agent needs a model key.

### From source (for development)

```bash
git clone https://github.com/barisarat/backtestchat
cd backtestchat
uv sync --extra openai              # deps + the OpenAI model provider
uv run backtestchat init            # or export BACKTESTCHAT_MODEL / OPENAI_API_KEY
uv run backtestchat chat
```

In a source checkout the `backtestchat` command lives in the project venv, so
prefix commands with `uv run` (or activate the venv with
`source .venv/bin/activate`). A plain `uv sync` drops extras - re-add yours with
`uv sync --extra openai`. 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)

The quickest path is `backtestchat init`, which stores an OpenAI key + model in
your user-global config. Under the hood backtestchat talks to any provider via
LangChain's `init_chat_model`, configured with a `provider:model` string in
`BACKTESTCHAT_MODEL`.

For another provider, install its extra and point `BACKTESTCHAT_MODEL` at it:

```bash
# installed as a tool:
uv tool install "backtestchat[anthropic]"
export BACKTESTCHAT_MODEL=anthropic:claude-sonnet-4-5
export ANTHROPIC_API_KEY=...

# or in a source checkout:
uv sync --extra ollama
export BACKTESTCHAT_MODEL=ollama:llama3.1     # Ollama runs locally, no key
```

Environment variables override the config file, so you can switch models
per-shell without editing anything. `backtestchat config` shows what resolved
(the API key is masked). If no model is configured, `backtestchat chat` prints
setup instructions and exits.

## 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 init                         # save your OpenAI key + model to the global config
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 (key masked)
```

(`btchat` is a short alias for `backtestchat`.)

### 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` (project-local)
> `~/.config/backtestchat/config.toml` (user-global, written by `backtestchat
init`) > defaults.

| Key | Env var | Default |
|---|---|---|
| model | `BACKTESTCHAT_MODEL` | (unset; required for chat) |
| OpenAI key | `OPENAI_API_KEY` | (unset; stored by `backtestchat init`) |
| data dir | `BACKTESTCHAT_DATA_DIR` | `./data` |
| artifacts dir | `BACKTESTCHAT_ARTIFACTS_DIR` | `./artifacts` |

The user-global config is written with `0600` permissions and holds your model
and OpenAI key; keep secrets out of any project-local `./backtestchat.toml`.
`./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 --group dev   # runtime + OpenAI provider + test deps
uv run --group dev pytest -q         # deterministic, offline, no model key
```

If `uv run pytest` ever reports `pytest: not found`, the local venv has been
pruned back to defaults - `uv run --group dev pytest -q` re-materializes the test
deps for that run.

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).
