Brummel
d0ebdf5210
Supersede 'broker is part of the strategy'. A strategy outputs a time-ordered table of position events (event_ts, action[buy/sell/close], position_id, instrument_id, volume; open time = opening event's event_ts, so no open_ts; unsigned volume, direction in action). Brokers become downstream swappable plugins: a deterministic frictionless sim-optimal broker yields synthetic pip-equity for neutral comparison/optimization; realistic broker plugins add currency friction/constraints for viability/deploy. Stays within C7 (scalar columns). Updates CLAUDE.md invariant 7, the walking-skeleton line, provenance, and the day-in-the-life doc. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
92 lines
4.8 KiB
Markdown
92 lines
4.8 KiB
Markdown
# How aura is used — engine, projects, and a day in the life
|
|
|
|
This document describes the *outside* of aura: how you sit in front of it and
|
|
what a research session looks like. The *inside* (the engine's contracts) is the
|
|
design ledger (`docs/design/INDEX.md`).
|
|
|
|
## Engine vs. project (the game-engine split)
|
|
|
|
aura is a **game engine for traders**, and like any game engine it is separate
|
|
from the things built with it:
|
|
|
|
- **This repo (`aura`)** is the **engine**: `aura-core` (the shared contract),
|
|
`aura-std` (universal standard nodes), `aura-engine` (the deterministic sim
|
|
runtime), `aura-cli` (the `aura` binary), and later the egui playground. It
|
|
ships at most `examples/` fixture nodes for its own tests — never your real
|
|
signals.
|
|
- **A research project** is its **own external repo** (e.g. `~/dev/ger40-lab/`),
|
|
with its own git history, its own Gitea repo (its own forward-queue), and a
|
|
cargo dependency on aura. This is where you and Claude author signals and where
|
|
the runs live. (See contract **C16**.)
|
|
|
|
The `aura` CLI is a tool you run *inside* a project directory — it finds the
|
|
project root by walking up to an `Aura.toml`, the way `cargo` finds `Cargo.toml`.
|
|
|
|
## A project repo
|
|
|
|
```
|
|
ger40-lab/ # your research project — a separate repo
|
|
├── Aura.toml # project config: symbols in scope, default data
|
|
│ # window, broker profile, runs dir (schema TBD)
|
|
├── Cargo.toml # depends on aura-core (+ shared node crates)
|
|
├── CLAUDE.md # the project's own skills wiring (authoring discipline)
|
|
├── .claude/dev-cycle-profile.yml
|
|
├── nodes/ # project-local, experimental nodes (cdylib)
|
|
│ └── third-candle-long/
|
|
├── runs/ # the run registry: manifest + metrics per run
|
|
└── (frozen bots, results, …)
|
|
```
|
|
|
|
## Where reusable nodes live (three tiers)
|
|
|
|
Everything that plugs into the engine is fractally a `Node`. Reuse is plain
|
|
cargo, layered by maturity (contract C16):
|
|
|
|
1. **`aura-std`** — universal blocks shipped with the engine (SMA/ATR/RSI,
|
|
resamplers, the `SessionNode`, standard combinators, broker profiles).
|
|
2. **Shared node crates** — cross-project-reusable blocks in their own repos
|
|
(e.g. `Brummel/aura-nodes-fx`), pulled in as cargo git dependencies.
|
|
3. **Project-local `nodes/`** — experimental, project-specific blocks.
|
|
|
|
Promotion is the ordinary Rust gradient: a node proves itself project-local →
|
|
gets extracted into a shared crate → if it turns universal, into `aura-std`.
|
|
Shared nodes are `rlib` dependencies; the hot-reload unit stays the project-side
|
|
`cdylib` that composes them, so editing a shared node still rebuilds and reloads
|
|
the dependent.
|
|
|
|
## Authoring happens in Claude Code (contract C17)
|
|
|
|
aura has no built-in coding-LLM. You author by talking to Claude Code, which
|
|
writes the node crate, builds it, runs it, and reports back. IONOS LLMs appear
|
|
only as a *runtime data source* (e.g. a news-agent node emitting a bias),
|
|
recorded before it enters a backtest, and only with your per-session consent.
|
|
|
|
## A day in the life
|
|
|
|
1. **You** (in Claude Code, inside `ger40-lab/`): "I suspect the 3rd 15m candle
|
|
after GER40 open is long-biased when the first two close bullish — build it as
|
|
a signal."
|
|
2. **Claude** (via the skills pipeline) writes `nodes/third-candle-long/`,
|
|
implements `schema` + `eval` against `aura-core`.
|
|
3. **Backtest:** `aura backtest nodes/third-candle-long --symbol GER40
|
|
--from 2020 --to 2024` → the strategy produces a broker-independent
|
|
**position table** (open/close events); the default **sim-optimal broker**
|
|
projects it into a synthetic **pip**-equity, yielding a metrics table
|
|
(trades, hit-rate, pip-P&L, max-DD, Sharpe) + a run record (manifest +
|
|
metrics) under `runs/`. Add `--broker pepperstone` to project the same table
|
|
through a realistic broker (currency, friction) for viability. (Contract C10.)
|
|
4. **Sweep + Monte-Carlo:** `aura sweep … --grid lookback=5..50,thresh=0.5..0.9
|
|
--mc-seeds 1000` → a distribution of metrics, best params, robustness bands.
|
|
5. **Compose:** "combine it with `momentum-filter` as a weighted sum" → Claude
|
|
writes a composite node (fractal, C9).
|
|
6. **Walk-forward:** `aura walkforward …` → an out-of-sample verdict.
|
|
7. **Freeze:** `aura freeze nodes/strategy-y --broker pepperstone
|
|
--out bots/strategy-y` → a standalone, statically-linked bot (C13).
|
|
8. **(Later) Look:** `aura play` opens the egui playground — equity curve, trade
|
|
overlays on the chart, sweep heatmaps. For *looking*, not authoring (C14).
|
|
|
|
CLI command names and `Aura.toml` are illustrative; the concrete surface is
|
|
designed with the relevant milestone (see the open threads in the design ledger).
|
|
The forward-queue — what to try next — lives in the project's Gitea tracker, not
|
|
in code (contract C18).
|