qanat

Qanat is an agent-first backtesting engine that turns your raw data into portfolio weights through a pipeline of steps you define.

The idea

In Qanat, you build a strategy as a pipeline of tables.

It starts with your raw data: prices, news, or anything else you track. From there, you define each step of the pipeline. A step reads one or more tables and writes a new one, so you can clean the data, calculate metrics, and score your symbols. The final step outputs your portfolio weights, detailing exactly what to hold and how much.

Qanat replays this pipeline across historical data, one date at a time. It prices the portfolio's holdings, accounts for fees, and outputs a complete PnL table.

Nothing is hidden. Every table is visible on your screen, with its row count and the logic that created it. If a number looks off, you open that table and inspect the data.

As your project grows, you can plug in new data sources and build new steps on top of them.

You don't have to write the code yourself. Describe what you want in plain English, and the agent will build the step, run it, and show you the resulting table.

Qanat is built for retail traders who rebalance daily or weekly. You can't out-race an institutional hedge fund on speed, and with a longer horizon, you don't need to.

Quick start

You need Python 3.10 or newer.

uv tool install qanat-fdtl                 # or: pip install qanat-fdtl
qanat init my-alpha --demo && cd my-alpha
qanat serve

The console opens on http://127.0.0.1:8420.

--demo builds four working strategies, runs the pipeline, and prices each one, so the console opens with real numbers in it. It takes about fifteen seconds. The data is synthetic, so this works with no API key and no network. Leave --demo off for an empty project.

Qanat makes no network calls on its own. The only outbound requests are the ones your data sources make.

Needs nothing but Docker, and brings its own Postgres:

git clone https://github.com/fidetolabs/qanat.git && cd qanat
docker compose up --build

Postgres is on localhost:5433, not 5432, because 5432 is often taken already. User, password and database are all qanat. Bind a directory to /project to use your own project instead of the demo.

If a port is already in use, set the host ports yourself:

POSTGRES_HOST_PORT=5434 QANAT_HOST_PORT=8421 docker compose up --build

To start over, docker compose down -v && docker compose up --build.

Use it with an agent

This is the main way to work with Qanat. You describe what you want, and the agent writes the step, runs it, and shows you the table it produced.

Add it to any MCP client:

{ "mcpServers": { "qanat": { "command": "qanat", "args": ["mcp"], "cwd": "/path/to/my-alpha" } } }

For Claude Code, claude mcp add qanat -- qanat mcp. Add --read-only and the agent can look at everything but change nothing.

Things you can ask for:

• "What is in this project, and what feeds the momentum strategy?" The agent traces the table back to its sources and answers with data, not a guess.
• "Add a momentum strategy and backtest it." Before running anything, it comes back with what your data can actually cover and asks you to choose the window, the rebalance, and the costs.
• "Which of my strategies actually works?" It lists every one with what it earned, so it compares instead of speculating.
• "Why did it lose money in March?" It opens that period and shows what was held, what each name returned, and what was traded to get there.
• "Does my news table line up with my prices?" It profiles both in the database and answers in spans, not row counts -- which is how you find out a strategy across the two would hold nothing for eleven months before it earns a cent.

The console and the agent are two views of the same project, so they can never disagree about its state -- and in the console they are one view. The agent talks to the console's own API, so what it reads and changes appears in the thread as it happens and the panel beside it follows along: ask about a table and the table opens, ask for a replay and the equity curve is what you are looking at when the answer lands.

The full tool list is in docs/agents.md, and what the console does with it is in docs/console.md.

How it works

Everything lives in one qanat.yaml. Nothing hides in application code.

project: equity
store: ./data/qanat.duckdb

universes:                         # which symbols a portfolio may hold
  - id: sp500
    symbols: ./universes/sp500.csv

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:                           # where data comes from
  - id: prices
    to: [raw.daily_prices]
    connector: rest
    options:
      url: https://api.example.com/v1/bars
      headers: { Authorization: "Bearer ${PRICE_API_KEY}" }

steps:                             # each one reads tables and writes tables
  - id: momentum
    from: [normalized.prices]
    to:   [features.momentum]
    script: steps/momentum.py
    options: { lookback: 20 }

  - id: alpha_momentum             # the step that writes weights is the strategy
    from: [features.momentum, features.risk]
    to:   [weights.momentum]
    script: steps/alpha_momentum.py
    universe: sp500
    rebalance: 20d

backtest:                          # what prices the portfolio, and what it costs
  prices: normalized.prices
  fee_bps: 5
  slippage_bps: 10
  live: false                      # true, and `qanat serve` keeps scoring it forward
  live_alphas: []                  # which one to price: not ours to guess once you have two

A step is a .sql file, or a .py file with a run(ctx) function:

def run(ctx):
    bars = ctx.read("normalized.prices")      # only tables the step declared in `from`
    held = ctx.universe()                     # the symbols it may hold
    return df

ctx.read() refuses any table the step did not list, so a missing dependency is an error instead of a wrong number.

The five stages

Each stage holds tables, and data only moves forward through them.

qanat check enforces the rules that keep this honest, and refuses to run a project that breaks one. They are written out in docs/contract.md.

The commands you need

qanat --help lists the rest. qanat tui gives you the console in the terminal if you prefer to stay there.

A source or a step can also run on a clock, or run whenever its input changes. Set schedule: or when: on it, or fill it in from the console.

Backtest

A backtest replays the pipeline over a period that already happened and prices what i