From a54358e54df4765b35ae2eca20ce084bcd3ed9e4 Mon Sep 17 00:00:00 2001 From: Aether AI Date: Thu, 23 Jul 2026 08:16:16 -0400 Subject: [PATCH] docs: strengthen quickstart and contribution paths --- .github/ISSUE_TEMPLATE/bug-report.yml | 35 +++++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/language-change.yml | 52 +++++++ .github/ISSUE_TEMPLATE/strategy-library.yml | 69 +++++++++ .github/PULL_REQUEST_TEMPLATE.md | 19 +++ .github/workflows/ci.yml | 8 +- CONTRIBUTING.md | 106 ++++++++------ README.md | 149 ++++++++++---------- examples/momentum_demo.py | 32 +++++ nano/library/README.md | 12 +- tests/test_momentum_demo.py | 20 +++ 11 files changed, 376 insertions(+), 131 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/language-change.yml create mode 100644 .github/ISSUE_TEMPLATE/strategy-library.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 examples/momentum_demo.py create mode 100644 tests/test_momentum_demo.py diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..400a6e9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,35 @@ +name: Bug report +description: Report a reproducible issue in Nano's compiler, IR, runtime, or bridge. +title: "[bug]: " +body: + - type: markdown + attributes: + value: | + Please do not include secrets, private market data, or security-sensitive details. Use SECURITY.md for a vulnerability report. + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: Include a small .nano source, IR, MarketFrame, and traceback or result where possible. + render: text + validations: + required: true + - type: input + id: version + attributes: + label: Nano version or commit + placeholder: 0.1.0 or a commit SHA + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..6cc7308 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Security report + url: https://github.com/DBarr3/Nano/security/advisories/new + about: Please report security-sensitive issues privately. diff --git a/.github/ISSUE_TEMPLATE/language-change.yml b/.github/ISSUE_TEMPLATE/language-change.yml new file mode 100644 index 0000000..bbad4ed --- /dev/null +++ b/.github/ISSUE_TEMPLATE/language-change.yml @@ -0,0 +1,52 @@ +name: Language or IR proposal +description: Propose a focused change to Nano syntax, IR, or reference-runtime behavior. +title: "[language]: " +body: + - type: markdown + attributes: + value: | + Nano is intentionally small. Explain the problem first, then show how the proposal preserves deterministic reference execution and the host-owned decision boundary. + - type: textarea + id: problem + attributes: + label: Problem to solve + description: Describe the concrete limitation or user need. + validations: + required: true + - type: textarea + id: syntax + attributes: + label: Proposed .nano syntax + description: Show a minimal before/after example. + render: nano + validations: + required: true + - type: textarea + id: ir + attributes: + label: Strategy IR impact + description: Show the expected JSON shape or explain why the existing IR remains sufficient. + render: json + validations: + required: true + - type: textarea + id: semantics + attributes: + label: Determinism and replay semantics + description: Explain inputs, ordering, scheduling, and how two identical graph/frame inputs retain the same reference result. + validations: + required: true + - type: textarea + id: boundary + attributes: + label: Host and gate boundary + description: Explain data ownership, policy ownership, and why the proposal cannot bypass a host DecisionGate. + validations: + required: true + - type: textarea + id: compatibility + attributes: + label: Compatibility, tests, and documentation + description: Note migration/versioning impact and the tests/docs that must change. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/strategy-library.yml b/.github/ISSUE_TEMPLATE/strategy-library.yml new file mode 100644 index 0000000..f963f5e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/strategy-library.yml @@ -0,0 +1,69 @@ +name: Strategy library proposal +description: Propose a well-specified trading strategy for Nano's paired source/IR library. +title: "[strategy]: " +body: + - type: markdown + attributes: + value: | + Thanks for helping grow the Nano strategy library. A strategy proposal describes a signal contract for a host to provide; it is not investment advice or a request for live execution. + - type: dropdown + id: category + attributes: + label: Category + options: + - momentum + - mean_reversion + - trend + - volatility + - volume + - risk + - new category proposal + validations: + required: true + - type: input + id: name + attributes: + label: Proposed strategy name + description: Use a concise, lowercase_snake_case name for the future file pair. + placeholder: rsi_oversold_reversal + validations: + required: true + - type: textarea + id: thesis + attributes: + label: Strategy thesis + description: Explain the trading idea in plain language and the intended timeframe. + validations: + required: true + - type: textarea + id: signals + attributes: + label: Host signal contract + description: For every signal, give its formula/data source, unit or range, normalization, lookback convention, and threshold direction. + placeholder: "RSI(14): host-computed RSI, 0-100; emit only when RSI < 30." + validations: + required: true + - type: textarea + id: proposed_source + attributes: + label: Proposed Nano source + description: Draft a v0.1-compatible strategy, if possible. Nano currently supports one schedule, one rule, AND-chained conditions, and five intent actions. + render: nano + - type: textarea + id: intent + attributes: + label: Proposed intent + description: State the action, asset convention, and confidence (if any) the strategy should emit. + validations: + required: true + - type: checkboxes + id: checklist + attributes: + label: Proposal checklist + options: + - label: I understand that Nano emits intents and does not place trades or provide investment advice. + required: true + - label: I will include paired .nano and _ir.json files plus documented signal conventions in a pull request. + required: true + - label: I will run python -m pytest tests/test_library.py -q before requesting review. + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..064f42f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## Why does this change belong in Nano? + + + +## What changed? + + + +## Validation + +- [ ] Focused tests passed. +- [ ] `python -m pytest -q` passed. +- [ ] Documentation and examples match the shipped behavior. + +## Boundary check + +- [ ] The change preserves deterministic reference execution for identical graph/frame inputs. +- [ ] The change does not bypass the host-owned `DecisionGate` or add external actuation to Nano source/runtime. +- [ ] If this adds a strategy, it includes paired `.nano` and `_ir.json` files plus documented host signal conventions. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b27f932..5b295f1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,10 +41,10 @@ jobs: wheel = next(Path("dist").glob("*.whl")) expected = { - "nano/examples/momentum.nano", - "nano/examples/momentum_ir.json", - "nano/library/momentum/rsi_oversold_reversal.nano", - "nano/library/momentum/rsi_oversold_reversal_ir.json", + path.as_posix() + for root in (Path("nano/examples"), Path("nano/library")) + for path in root.rglob("*") + if path.suffix in {".nano", ".json"} } with ZipFile(wheel) as archive: packaged = set(archive.namelist()) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a6bbb7..dceb7d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,73 +1,85 @@ # Contributing to Nano -Thanks for your interest. Nano is a research preview moving fast — contributions that fit the -project's discipline (deterministic, tested, honestly labeled) are very welcome. +Welcome. Nano is an alpha reference implementation, and its best contributions make the small language more useful without making its contract less clear. Quant researchers, application engineers, and documentation contributors all have a meaningful place here. + +## Start here + +| If you want to… | Start with… | +| --- | --- | +| Translate a familiar trading idea | [Add a strategy](#add-a-strategy) | +| Suggest grammar, IR, or runtime behavior | [Open a language proposal](https://github.com/DBarr3/Nano/issues/new?template=language-change.yml) | +| Report a reproducible defect | [Open a bug report](https://github.com/DBarr3/Nano/issues/new?template=bug-report.yml) | +| Improve an explanation or correct a claim | A focused documentation issue or pull request | + +For security-sensitive reports, follow [SECURITY.md](SECURITY.md) instead of opening a public issue. ## Development setup ```bash git clone https://github.com/DBarr3/Nano.git cd Nano -python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate -pip install -e ".[dev]" -python -m pytest tests -q +python -m venv .venv +``` + +Activate the environment: + +```bash +# macOS/Linux +source .venv/bin/activate + +# Windows PowerShell +.venv\Scripts\Activate.ps1 ``` -Python 3.10+. The whole suite runs in under two seconds — run it constantly. +Then install and test: -## Where help is most valuable +```bash +python -m pip install -e ".[dev]" +python -m pytest -q +``` -**Easiest entry: the strategy library.** Add a classic quant strategy to -[`nano/library/`](nano/library/) as `.nano` source plus its expected IR JSON. The library -README documents the format and the conformance rule (source must compile to the expected IR -bit-for-bit). This teaches you the whole pipeline in one PR. +Python 3.10+ is required. The reference suite is intentionally fast; run it often. -**The conformance corpus.** New `.nano` programs in [`nano/examples/`](nano/examples/) that -exercise untested language shapes — each is source + hand-written IR that must match exactly. +## Add a strategy -**The CLI.** `nano compile` / `nano replay` / `nano visualize` are designed but not built. -See [BUILD_ORDER.md](BUILD_ORDER.md) for the intended shape. +The [strategy library](nano/library/README.md) is the easiest way to learn and extend Nano. Every strategy is a paired artifact: readable `.nano` source plus checked-in IR that the suite must reproduce exactly. -**Docs and papers.** Anything in [`docs/papers/`](docs/papers/) that is unclear, overstated, -or wrong — issues and PRs both welcome. The house rule: every claim cites shipped code or is -labeled design/roadmap/research. +1. Open a [strategy proposal](https://github.com/DBarr3/Nano/issues/new?template=strategy-library.yml) for a new idea or use an existing issue. +2. Choose one existing category in `nano/library/`, then add `.nano` and `_ir.json`. +3. Document the signal contract in `//` comments: formula or data source, unit/range, any normalization, and the lookback convention the host must supply. +4. Generate the expected IR with `compile_to_dict()` and keep it formatted like neighboring entries. +5. Run `python -m pytest tests/test_library.py -q`, then the full suite before opening the pull request. -## Architecture in one diagram +Nano v0.1 has one schedule and one rule per strategy, AND-chained numeric conditions, and five intent actions. The host supplies every signal and still owns every real-world action. See the [language reference](docs/language.md) before designing a new strategy shape. -``` -.nano source ──► Compiler (nano/compiler/) ──► Nano IR (nano/ir/) - │ - ┌──────────────────────────────┤ - ▼ ▼ - Interpreter (nano/runtime/) Bridge + gate (nano/bridge/) - pure, deterministic intents → your risk engine - │ │ - └──────── append-only audit log┘ -``` +For a normal strategy addition, the library tests automatically discover the source/IR pair and verify compilation, validation, and replay. Add a focused fire/no-fire test only when the new example covers a meaningful runtime edge not already represented. + +## Propose a language change + +Start with the [language proposal form](https://github.com/DBarr3/Nano/issues/new?template=language-change.yml) before writing an implementation. It asks for the problem, proposed syntax, IR impact, deterministic/replay semantics, host-gate impact, and migration story. -Supporting layers: pattern memory (`nano/memory/`), editor services (`nano/aethercode/`), -optimization loop (`nano/loop/`). Build sequence and rationale: [BUILD_ORDER.md](BUILD_ORDER.md). +This discipline matters: Nano's boundary is intentional. Do not add ambient I/O, an external-actuation primitive, a clock/RNG dependency, or a behavior that lets source bypass the host `DecisionGate`. ## Ground rules -1. **Determinism is non-negotiable.** No ambient clock, RNG, network, or global mutable state - anywhere in the IR, compiler, or runtime paths. Time and entropy are injected inputs. -2. **Programs propose; gates decide.** Never add an actuation primitive to the language or a - side-effecting call to the runtime. If your feature needs an effect, it goes through the - intent/gate boundary. -3. **Tests first-class.** New behavior ships with tests; conformance examples must replay - bit-identically. `python -m pytest tests -q` must pass before any PR. -4. **Honest labeling.** Docs distinguish shipped / design / roadmap / research. Don't promote - a claim past its evidence. +1. **Determinism is non-negotiable.** The reference compiler and runtime do not read an ambient clock, RNG, network, or mutable global state. +2. **Programs propose; gates decide.** Nano emits intents. The host owns policy, persistence, and any external effect. +3. **Tests travel with behavior.** New behavior, examples, and bug fixes include focused coverage; a library pair must compile to its expected IR and replay deterministically. +4. **Documentation is part of the contract.** Label shipped behavior, experiments, and research honestly. Do not promote a claim past its evidence. +5. **Keep changes reviewable.** Prefer one clear reason per pull request and leave a concise record of why the change belongs in Nano. ## Pull requests -- Branch from `main`; keep PRs focused and small. -- Commit style: `: ` (feat, fix, refactor, docs, test, chore). -- Describe *why*, not just what. Link the paper or BUILD_ORDER milestone your change serves - if one applies. +- Branch from `main`; keep pull requests focused and small. +- Use concise commit subjects such as `feat: add strategy fixture` or `docs: clarify signal contract`. +- Complete the pull-request template, including validation and the relevant boundary checks. +- For a strategy, include the source, expected IR, signal comments, and test result together. -## Questions and ideas +## Useful references -Open a GitHub issue — design discussion is welcome, and "this paper's argument doesn't hold -because…" is a first-class contribution. +- [Quick-start demo](examples/momentum_demo.py) +- [Strategy library](nano/library/README.md) +- [Language reference](docs/language.md) +- [Architecture](docs/architecture.md) +- [Status and maturity](docs/status.md) +- [Security policy](SECURITY.md) diff --git a/README.md b/README.md index 6f03648..68228b8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-Nano logo +Nano logo # Nano @@ -12,59 +12,36 @@
-> **Alpha reference implementation (v0.1.0).** Nano compiles a deliberately small `.nano` strategy into validated, serializable IR. Its reference runtime evaluates caller-supplied numeric signals on a caller-supplied schedule and returns proposed actions (`Intent` values) plus an ordered event log. A host-owned gate decides whether to approve any proposal. +> **For quant teams and product engineers: write familiar decision rules, replay them against your own signals, and keep final authority in your own controls.** +> +> Nano is a small, Python-embeddable language for transparent threshold rules. It compiles source into validated IR, evaluates host-provided numeric signals deterministically, and returns proposed `Intent` values plus an ordered run log—not an API call or an order. -Nano is for systems that need repeatable, inspectable threshold decisions without letting the decision rule call an exchange, API, or other external system directly. The checked-in examples are trading-oriented, but the core contract is useful anywhere a host supplies numeric signals, owns the policy boundary, and needs deterministic replay. +**Alpha reference implementation (v0.1.0).** Nano is for systems that need repeatable, inspectable decisions without letting the rule itself call an exchange, API, or other external system. The examples are trading-oriented, but the core contract works anywhere a host supplies numeric signals and owns the policy boundary. -## Why Nano? +## Quick start: compile, run, and verify -A host application often needs to answer two separate questions: +From a fresh checkout, run a tested Momentum strategy and then the full suite: -1. **What rule should propose an action?** -2. **May that action have consequences here and now?** - -Nano keeps those questions separate. A `.nano` program describes the first as a compact, versioned artifact. The host retains the second through its own `DecisionGate`. This makes rule evaluation easy to replay, test, and audit without treating the rule as an authority to act. - -Nano does **not** include an LLM runtime, automatic escalation, a live data feed, an exchange/API connector, or an action executor. Those remain host concerns. +```bash +git clone https://github.com/DBarr3/Nano.git +cd Nano +python -m venv .venv -## From source to a governed decision +# macOS/Linux: source .venv/bin/activate +# Windows PowerShell: .venv\Scripts\Activate.ps1 -```text -.nano source - | - v -lexer -> parser -> canonical StrategyGraph IR - | - v -reference interpreter + injected MarketFrame - | - v -Intent(s) + ordered per-run event log - | - v -optional NanoBridge -> host DecisionGate -> Decision record(s) +python -m pip install -e ".[dev]" +python examples/momentum_demo.py +python -m pytest -q ``` -The reference interpreter is a pure function of a validated strategy graph and a `MarketFrame`: the same inputs produce the same result. A bridge replay is deterministic only when the host gate is deterministic too; `Backtester.verify_replay()` compares two complete runs and reports divergence. - -The base event log is returned in memory with each result. Durable storage, signed receipts, and real-world actuation are outside the core runtime. - -## Run a real strategy - -Create an environment and install the package from a checkout: +The demo compiles the checked-in strategy, injects two RSI values, and prints the proposal that crosses the threshold: -```bash -python -m venv .venv -# macOS/Linux -source .venv/bin/activate -# Windows PowerShell -# .venv\Scripts\Activate.ps1 - -pip install -e ".[dev]" -python -m pytest -q +```text +BUY BTC at timestamp=300 (confidence=0.91) ``` -This is valid Nano v0.1.0 source from the checked-in conformance corpus: +This is the small `.nano` program it runs: ```nano @@ -78,29 +55,24 @@ strategy Momentum { ``` -`RSI(14)` is a source-level signal convention. In v0.1.0, the host computes and injects the `RSI` series; the lookback label is not stored separately in strategy IR. See the [language reference](docs/language.md) for the full rule. +`RSI(14)` is a source-level signal convention. In v0.1.0, the host computes and injects the `RSI` series; Nano does not calculate indicators or fetch market data. See the [language reference](docs/language.md) for the exact contract. -Compile and run it against an injected frame: +## How Nano fits into your stack -```python -from pathlib import Path - -from nano.compiler import compile_source -from nano.runtime import MarketFrame, execute - -source = Path("nano/examples/momentum.nano").read_text(encoding="utf-8") -graph = compile_source(source) -frame = MarketFrame( - timestamps=(0, 300), - signals={"RSI": (45.0, 22.0)}, -) - -result = execute(graph, frame) -print([intent.to_dict() for intent in result.intents]) -# [{'intent': 'BUY', 'timestamp': 300, 'asset': 'BTC', 'confidence': 0.91}] +```mermaid +flowchart LR + source[".nano strategy"] --> compiler["Nano compiler"] + compiler --> graph["StrategyGraph IR"] + graph --> runtime["Reference runtime"] + frame["Host MarketFrame
(timestamps + signals)"] --> runtime + runtime --> intents["Intent(s) + ordered run log"] + intents --> gate["Host DecisionGate"] + gate --> decision["Decision record"] ``` -To involve policy, provide a complete host gate. The gate returns a record; it does not cause Nano to place an order or call an API: +Nano owns parsing, IR validation, and deterministic reference evaluation. Your host owns data quality, policy, persistence, and any real-world action. The same graph and frame produce the same reference result; bridge replay is deterministic when the host gate is deterministic too. + +To add policy, provide a complete gate. Nano records its decision; it never places an order or calls an API: ```python from nano.bridge import Decision, NanoBridge @@ -117,6 +89,41 @@ bridge_result = bridge.run(frame) print([decision.to_dict() for decision in bridge_result.decisions]) ``` +## Explore the quant strategy library + +The strategy library is Nano's community on-ramp: a small, tested collection of familiar trading ideas translated into the DSL. It currently contains **15 paired strategies** across six categories. + +| Momentum | Mean reversion | Trend | Volatility | Volume | Risk | +| --- | --- | --- | --- | --- | --- | +| 4 strategies | 3 strategies | 3 strategies | 2 strategies | 2 strategies | 1 strategy | + +Every entry pairs readable `.nano` source with expected IR. The test suite verifies compilation, `StrategyGraph` round-tripping, and deterministic replay. Use the library to learn the language, prototype an integration, or contribute a well-specified strategy—not as a performance claim, live signal service, or trading recommendation. + +**Bring a rule to the library.** Start with a familiar strategy, document the host-provided signal convention, add its expected IR, and let the conformance suite keep the contract honest. + +[Browse the strategy library →](nano/library/README.md) · [Add a strategy →](CONTRIBUTING.md#add-a-strategy) · [Propose a language change →](https://github.com/DBarr3/Nano/issues/new?template=language-change.yml) + +## Build with Nano + +Nano stays approachable because its contract is deliberately small and every change is reviewable. We welcome: + +- **Quant researchers** translating a strategy into a source/IR pair with a clear signal contract. +- **Application engineers** improving host integration, replay coverage, documentation, or developer experience. +- **Language contributors** proposing grammar or IR changes through a focused issue before implementation. + +Strategy and language proposals start with structured GitHub issue forms; focused pull requests then carry the source, expected IR, tests, and rationale together. See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guide and [the issue templates](.github/ISSUE_TEMPLATE/) for a place to begin. + +## Why the boundary matters + +An application often needs to answer two separate questions: + +1. **What rule should propose an action?** +2. **May that action have consequences here and now?** + +Nano keeps them separate. A `.nano` program describes the first as a compact, versioned artifact; the host retains the second through its own `DecisionGate`. That makes rule evaluation easy to replay, test, and audit without turning a rule into an authority to act. + +Nano does **not** include an LLM runtime, automatic escalation, a live data feed, an exchange/API connector, or an action executor. Those remain host concerns. + ## The language is intentionally small | Current capability | What it means | @@ -137,33 +144,21 @@ There are no variables, arithmetic, functions, imports, `or`/`not`, user-defined | `.nano` lexer, parser, canonical strategy IR, and reference interpreter | `PatternStore` lookup primitive (not wired into the runtime) | LLM calls, automatic escalation, or agent orchestration | | Host `DecisionGate` bridge and deterministic replay checker | `LoopGraph` validation/hash helpers and a deterministic simulator protocol | CLI, type system, `Series`, or general strategy graphs | | Diagnostics, semantic tokens, and IR preview helpers | Protocol-C provenance adapter when its optional dependency is installed | Live feeds, exchange/API execution, or persistent core audit storage | -| Source/IR conformance corpus and strategy corpus | Real quantum-hardware dispatch | Autonomous loop execution or self-modifying deployment | +| Source/IR conformance corpus and strategy library | Real quantum-hardware dispatch | Autonomous loop execution or self-modifying deployment | For a fuller implementation map, see [Architecture](docs/architecture.md) and [Status](docs/status.md). -## A tested strategy corpus - -Nano includes a paired source/IR corpus that keeps the language contract concrete: - -- [`nano/examples/`](nano/examples/) contains the core conformance fixtures. -- [`nano/library/`](nano/library/README.md) contains 15 trading-oriented strategies across momentum, mean-reversion, trend, volatility, volume, and risk categories. - -Each pair is compiled, round-tripped through `StrategyGraph`, and replayed in the test suite. The corpus demonstrates syntax and deterministic behavior; it is not a strategy registry, a performance guarantee, or production trading advice. - ## Documentation | Need | Start here | | --- | --- | +| Run the first example | [Momentum demo](examples/momentum_demo.py) | +| Explore or contribute a strategy | [Strategy library](nano/library/README.md) | | Exact grammar and runtime semantics | [Language reference](docs/language.md) | | Module boundaries and data flow | [Architecture](docs/architecture.md) | | Implemented vs. experimental vs. planned work | [Status](docs/status.md) | -| Strategy-corpus conventions | [Strategy corpus](nano/library/README.md) | | Integration and contribution setup | [Contributing](CONTRIBUTING.md) | | Security boundaries and reporting | [Security policy](SECURITY.md) | | Design essays and research directions | [Paper series](docs/papers/README.md) | The paper series records design arguments and research directions; it is not the API specification. When a paper and the reference documentation differ, the source and tests define current behavior. - -## Contributing - -Nano is most useful when its compact contract stays explicit. Contributions should preserve deterministic reference execution, the intent/gate boundary, conformance coverage, and clear implemented-versus-planned labeling. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and contribution paths. diff --git a/examples/momentum_demo.py b/examples/momentum_demo.py new file mode 100644 index 0000000..947c86a --- /dev/null +++ b/examples/momentum_demo.py @@ -0,0 +1,32 @@ +"""Compile and run the bundled Momentum strategy with host-supplied RSI data.""" + +from pathlib import Path + +from nano.compiler import compile_source +from nano.runtime import MarketFrame, execute + + +_ROOT = Path(__file__).resolve().parents[1] + + +def run_demo() -> tuple[dict[str, object], ...]: + """Return the proposals emitted by the checked-in Momentum fixture.""" + source = (_ROOT / "nano" / "examples" / "momentum.nano").read_text(encoding="utf-8") + graph = compile_source(source) + frame = MarketFrame( + timestamps=(0, 300), + signals={"RSI": (45.0, 22.0)}, + ) + return tuple(intent.to_dict() for intent in execute(graph, frame).intents) + + +def main() -> None: + for intent in run_demo(): + print( + f"{intent['intent']} {intent['asset']} at timestamp={intent['timestamp']} " + f"(confidence={intent['confidence']})" + ) + + +if __name__ == "__main__": + main() diff --git a/nano/library/README.md b/nano/library/README.md index d9e33f1..02cc087 100644 --- a/nano/library/README.md +++ b/nano/library/README.md @@ -1,13 +1,19 @@ -# Nano strategy corpus +# Nano strategy library -This directory is a paired, trading-oriented **conformance corpus** for the Nano v0.1.0 language. It is not a package registry, a live-strategy service, or investment advice. +This directory is Nano's contribution-ready, trading-oriented **strategy library and conformance corpus** for the v0.1.0 language. It is a place to learn from familiar ideas, compare clear signal contracts, and contribute new source/IR pairs—not a live-strategy service or investment advice. Every entry has two files: - `.nano` - source written in the locked Nano grammar - `_ir.json` - the canonical strategy IR expected from that source -`tests/test_library.py` verifies that each pair compiles to the expected IR, round-trips through `StrategyGraph`, and produces deterministic reference-runtime results. The corpus makes the small language contract concrete. +`tests/test_library.py` verifies that each pair compiles to the expected IR, round-trips through `StrategyGraph`, and produces deterministic reference-runtime results. The library gives quant researchers a concrete way to meet the language: start with an idea they already recognize, make its host signal contract explicit, then let the tests preserve that contract. + +## Learn, compare, contribute + +The current library contains 15 strategies across six familiar categories. Browse an entry to see the source, its expected IR, and the feed convention it assumes. When you are ready, a well-documented strategy pair is the most direct contribution to Nano. + +[Add a strategy →](../../CONTRIBUTING.md#add-a-strategy) · [Open a strategy proposal →](https://github.com/DBarr3/Nano/issues/new?template=strategy-library.yml) ## Categories diff --git a/tests/test_momentum_demo.py b/tests/test_momentum_demo.py new file mode 100644 index 0000000..fb00ab2 --- /dev/null +++ b/tests/test_momentum_demo.py @@ -0,0 +1,20 @@ +"""Regression coverage for the README's runnable momentum demo.""" + +import runpy +from pathlib import Path + + +_ROOT = Path(__file__).resolve().parents[1] + + +def test_momentum_demo_emits_the_documented_buy_intent() -> None: + namespace = runpy.run_path(str(_ROOT / "examples" / "momentum_demo.py")) + + assert namespace["run_demo"]() == ( + { + "intent": "BUY", + "timestamp": 300, + "asset": "BTC", + "confidence": 0.91, + }, + )