Metadata-Version: 2.5
Name: nyrobrain
Version: 0.1.0
Summary: Nyrobrain libraries. nyrobrain.execution translates portfolio signals into exchange orders.
Author-email: Marcus Lee <marcuslee@balaenaquant.com>
License: Proprietary
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.13
Provides-Extra: aegis
Requires-Dist: bq-nats-client>=0.1.6; extra == 'aegis'
Provides-Extra: execution
Requires-Dist: nautilus-trader==2.0.0rc4; extra == 'execution'
Requires-Dist: pandas>=2.2; extra == 'execution'
Requires-Dist: pyarrow>=17; extra == 'execution'
Provides-Extra: prime
Requires-Dist: httpx>=0.27; extra == 'prime'
Description-Content-Type: text/markdown

# 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`](src/nyrobrain/execution/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`](src/nyrobrain/execution/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`](../.scratch/nyrobrain-execution/map.md)
  — the arithmetic, the guards and the placement seam.
- [`.scratch/nyrobrain-execution-runners/map.md`](../.scratch/nyrobrain-execution-runners/map.md)
  — driving it from a `BacktestEngine` and a sandbox.
- [`.scratch/nyrobrain-execution-live/map.md`](../.scratch/nyrobrain-execution-live/map.md)
  — against a real venue on Bybit demo, and the nautilus 2 migration.
