qanat

<p align="center"> <img src="https://raw.githubusercontent.com/fidetolabs/qanat/main/assets/hero.jpg" alt="A qanat cut open: shaft mouths and fields on the surface, the tunnel running beneath them, and a man walking it" width="560"> </p> <h1 align="center">Qanat</h1> <p align="center"> <i>An MCP server for quant factor processing and backtesting.</i> </p> <p align="center"> <a href="https://github.com/fidetolabs/qanat/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-a2e65d?style=flat-square"></a> <a href="https://github.com/fidetolabs/qanat/blob/main/pyproject.toml"><img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-a2e65d?style=flat-square"></a> <a href="#status"><img alt="Status" src="https://img.shields.io/badge/status-beta-e8c069?style=flat-square"></a> <a href="https://discord.gg/JUmwATScS8"><img alt="Discord members" src="https://img.shields.io/badge/dynamic/json?logo=discord&logoColor=white&label=Discord&query=%24.approximate_member_count&url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FJUmwATScS8%3Fwith_counts%3Dtrue&color=5865F2&style=flat-square"></a> </p> Qanat is a data platform for quant factors. Give it any source that has a timestamp. It processes the data, stores it, and serves it to your agent over MCP. You write one YAML file saying where the data comes from and what to do with it. Qanat runs that, replays it over history one date at a time, and prices what the portfolio held after fees. Connect it to your agent and ask. It is built for people who rebalance daily or weekly. You cannot beat a hedge fund on speed, and over that horizon you do not need to. ## Install Python 3.10 or newer. ```bash uv tool install qanat-fdtl # or: pip install qanat-fdtl qanat init my-alpha --demo && cd my-alpha ``` `--demo` builds four strategies and prices them in about fifteen seconds, so there is something real to look at. The data is synthetic, so it needs no key and no network. Leave it off for an empty project. Qanat makes no network calls of its own. The only ones are what your sources do. ## Connect it to an agent ```bash claude mcp add qanat -- qanat mcp --scope research ``` Any MCP client works: ```json { "mcpServers": { "qanat": { "command": "qanat", "args": ["mcp"], "cwd": "/path/to/my-alpha" } } } ``` Then ask for things: - **"What is in this project, and what feeds the momentum strategy?"** It traces the table back to its sources and answers from the rows. - **"Add a momentum strategy and test it."** Before running anything it comes back with what your data covers and asks you to pick the window, the rebalance and the costs. - **"Which of my strategies works?"** It lists each one with what it earned. - **"Why did it lose money in March?"** It opens that period and shows what was held and what each name returned. ## Scopes `--scope` picks which tools your agent gets. There are three, and each one contains the one before it. | | tools | | | --- | --- | --- | | `--scope data` | 6 | read the tables, including as they stood on a past date | | `--scope research` | 19 | adds running a replay, reading the result, comparing runs | | *(default)* | 31 | adds writing steps, ingest and scheduling | Every tool definition is sent on every request, so a narrow scope costs fewer tokens and leaves the agent a shorter list to choose from. Pick the smallest one that does the job. The split also decides what a caller can break. `set_bar` sits in `full`, so an agent connected at `research` can record what it tried and cannot lower the line those attempts are held to. Full table in **[docs/agents.md](https://github.com/fidetolabs/qanat/blob/main/docs/agents.md)**. ## Serving it to something that is not on this machine ```bash qanat mcp --http --port 8421 --scope research --token "$QANAT_MCP_TOKEN" # server only qanat serve --port 8421 --scope research --token "$QANAT_MCP_TOKEN" # and the scheduler ``` Both speak MCP's Streamable HTTP transport on `/mcp`. The scope is fixed by the flag that started the server, so nothing in a request can widen it. One process serves one project, because the store takes one writer. Two projects means two processes. It binds to 127.0.0.1 unless you say otherwise, and it refuses any other address without a token. ## How a project is written Everything is in one `qanat.yaml`. ```yaml project: equity store: ./data/qanat.duckdb stages: # order here is order in the pipeline - { id: raw, kind: raw } - { id: normalized, kind: features } - { id: features, kind: features } - { id: weights, kind: weights } - { id: pnl, kind: pnl } sources: - id: prices to: [raw.daily_prices] connector: rest options: url: https://api.example.com/v1/bars headers: { Authorization: "Bearer ${PRICE_API_KEY}" } steps: - id: alpha_momentum # the step that writes weights is the strategy from: [features.momentum] to: [weights.momentum] script: steps/alpha_momentum.py rebalance: 20d backtest: prices: normalized.prices fee_bps: 5 slippage_bps: 10 ``` A step is a `.sql` file, or a `.py` file with a `run(ctx)`: ```python def run(ctx): bars = ctx.read("normalized.prices") # only tables the step declared in `from` return df ``` `ctx.read()` refuses any table the step did not list, so a missing dependency is an error instead of a wrong number. Data moves forward through the stages and never back: `raw` holds it as it arrived, `normalized` types and deduplicates it, `features` holds what you measure, `weights` holds one table per strategy, and `pnl` holds what each one earned. `qanat check` refuses a project that breaks the rules. They are written out in **[docs/contract.md](https://github.com/fidetolabs/qanat/blob/main/docs/contract.md)**. ## Replaying it ```bash qanat backtest --from 2015-01-01 --to 2024-12-31 qanat report 14 ``` A replay walks the period one date at a time. Every step reads only the rows that existed on that date, so a step cannot see the future. It prices what the portfolio held, takes off fees and slippage, and the headline number is what is left. Three kinds of period come out of it: in-sample, out-of-sample, and live. Live is the only one that cannot be arrived at by looking, because it is priced after a `live_from` date that was stamped before the rows existed. More in **[docs/backtest.md](https://github.com/fidetolabs/qanat/blob/main/docs/backtest.md)**. ## How many did you try A Sharpe of 2.2 on the first attempt is interesting. The same figure picked out of fifty is what noise looks like, and nothing inside a backtest tells those apart. So Qanat keeps the count. ```bash qanat backtest --from … --to … # then, whether it worked or not: # record_trial: what you were testing, and what you decided # list_trials: how many distinct questions that adds up to ``` Set a bar and the count feeds into it: ```yaml backtest: bar: rule: count # none · floor · count alpha: 0.05 gate: true ``` `count` divides the significance by the number of attempts. `floor` is a fixed t-statistic whatever you tried. With `gate: true`, calling a result live fails until it clears. Loosening the bar is recorded with who did it, because the thing proposing strategies is also the thing that can move the line. ## What ships with it Four strategies, so there is something to replay on day one: `momentum`, `reversal`, `low_vol` and `neutral_momentum`. Each writes an ordinary step file you can edit or throw away. **The tool is what is given away here. The strategy never is.** Four connectors: `rest` for an HTTP endpoint, `sql` for anything SQLAlchemy reaches, `csv` for a path or a URL, and `synthetic` for a fake market that runs before you have any key. The store is a DuckDB file, or Postgres on localhost. Four examples. `examples/fx-bundled` is real data in the repo: 27 years of ECB rates, 126 KB, no key needed. ## Status Beta. It does what this page says on my own work, and few other people have run it. If something breaks, open an [issue](https://github.com/fidetolabs/qanat/issues) or say so on [Discord](https://discord.gg/JUmwATScS8). **MCP is the only door.** What you install is the engine, the CLI that operates it, and the MCP server. There is no screen and no second HTTP API: your agent client is the screen. `qanat serve` runs the scheduler and serves this same MCP over HTTP from the process holding the store, which is also how the unattended pass reaches the project. Not implemented: backfills, incremental windows, and live trading. Qanat produces a portfolio, on history and going forward. **It does not place an order.** Two limits worth knowing before you lean on the honesty machinery. The window is not sealed: the point-in-time views stop a step seeing the future, but nothing stops the agent reading past a date while it decides what to try. And there is no search goal, because a loop that proposes strategies and keeps the winners is an expensive way to fool yourself until the bar gates rather than reports. Qanat runs one kind of pipeline, the kind that ends in a portfolio. Airflow, Dagster and Prefect handle arbitrary DAGs and distributed execution. Reach for those when you need them. Issues and pull requests welcome. See **[CONTRIBUTING.md](https://github.com/fidetolabs/qanat/blob/main/CONTRIBUTING.md)**. ## License MIT. See [LICENSE](https://github.com/fidetolabs/qanat/blob/main/LICENSE). Copyright (c) 2026 fidetolabs