nyrobrain

Nyrobrain Python libraries.

• nyrobrain.execution — translates portfolio signals (a target weight per symbol) into orders at the exchange, on top of nautilus_trader.

What it is for

A portfolio says hold 25% of the book in BTC. Something has to turn that into orders, against whatever is already held and whatever is already working, and keep doing it as the price moves and the target changes — without ever buying past the target. That last clause is the whole library. The failure it exists to prevent is an OMS that re-sends a delta it has already sent and walks a position away from its target.

You write the driver

The library does not ship one. It ships the executor, the guards, the report and the pieces that are dangerous to get wrong; assembling them into a running system is your code, because that is where your choices live.

Start from examples/oms.py — one script, three modes, copy it and change it:

python oms.py --mode backtest --signals signals.jsonl --candles ~/candles
python oms.py --mode paper --minutes 10
python oms.py --mode live  --minutes 10 --environment demo

The executor, the guards and the report are identical in all three. That is the point: a difference in behaviour between two modes is the venue, not the harness.

Two surfaces

Decisions — nyrobrain.execution. Sizing, the delta, the guards, the placement protocol. Imports no nautilus and installs without it, so you can reason about a target without an engine in the process. A placement strategy you write never imports nautilus either.

Assembly — nyrobrain.execution.driver, .backtest, .credentials, .venue, .runner, .report. Nautilus all the way through, because building a node cannot be anything else.

Examples

Runnable, shipped in the package, and executed by the test suite so they cannot rot. Read them in order:

python -m nyrobrain.execution.examples.sizing_a_target       # weight -> target -> delta
python -m nyrobrain.execution.examples.over_delivery_guard   # the invariant, and what it refuses
python -m nyrobrain.execution.examples.your_own_placement    # a placement strategy, no venue needed

Then examples/README.md for the driver itself.

Local development

uv sync --all-extras
uv run pytest

soak is ours rather than yours — a long-run diagnostic for validating the executor over hours, not part of the driver story:

uv run python -m nyrobrain.execution.soak --hours 3 --environment demo

Design maps

Built with the wayfinder method: numbered decision tickets under a map, worked one at a time. Each records not just what was decided but what was measured to decide it.

• .scratch/nyrobrain-execution/map.md — the arithmetic, the guards and the placement seam.
• .scratch/nyrobrain-execution-runners/map.md — driving it from a BacktestEngine and a sandbox.
• .scratch/nyrobrain-execution-live/map.md — against a real venue on Bybit demo, and the nautilus 2 migration.