diff --git a/README.md b/README.md index 68228b8..f030770 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,19 @@ -> **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. +> **Write readable trading rules. Replay every outcome. Keep the final decision in your application.** -**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. +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 with an ordered run log. It does not call an exchange, API, or other external system. -## Quick start: compile, run, and verify +**Alpha reference implementation (v0.1.0).** The examples are trading-oriented, but Nano fits any system where a host supplies numeric signals and must retain control over what happens next. -From a fresh checkout, run a tested Momentum strategy and then the full suite: +## Why Nano + +A rule and an approval are different jobs. Nano makes the rule compact, versioned, and replayable; your application owns data quality, policy, persistence, and real-world effects. That separation makes a decision trail easier to inspect without giving a script authority over your infrastructure. + +## Quick start + +From a fresh checkout, run the bundled Momentum strategy and then the test suite: ```bash git clone https://github.com/DBarr3/Nano.git @@ -35,13 +39,13 @@ python examples/momentum_demo.py python -m pytest -q ``` -The demo compiles the checked-in strategy, injects two RSI values, and prints the proposal that crosses the threshold: +The demo compiles a checked-in strategy, injects two RSI values, and produces a proposed action: ```text BUY BTC at timestamp=300 (confidence=0.91) ``` -This is the small `.nano` program it runs: +This is the complete `.nano` program it runs: ```nano @@ -57,108 +61,53 @@ strategy Momentum { `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. -## How Nano fits into your stack - -```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"] -``` - -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: +## From rule to governed decision -```python -from nano.bridge import Decision, NanoBridge +![From a Nano strategy to a host-governed decision](assets/nano-governed-decision-flow.svg) +Nano owns parsing, IR validation, and deterministic reference evaluation. The host supplies the `MarketFrame`, applies its `DecisionGate`, stores the result, and performs 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. -class ApproveForDemo: - def decide(self, intent, *, frame): - return Decision(intent=intent, approved=True, reason="demo policy") +## Start with the strategy library - -bridge = NanoBridge(ApproveForDemo()) -bridge.load(graph.to_dict()) -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. +The [strategy library](nano/library/README.md) is Nano's community on-ramp: a small, tested corpus of familiar trading ideas translated into the DSL. Every entry pairs readable `.nano` source with expected IR, so quant researchers can learn the language, compare conventions, and contribute a new rule with confidence. | 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) +The library is a conformance corpus, not a performance claim, live signal service, or trading recommendation. -## 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: +[Browse strategies →](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) -1. **What rule should propose an action?** -2. **May that action have consequences here and now?** +## Small by design -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 | +| Nano provides | The host retains | | --- | --- | -| One strategy, schedule, and rule | A v0.1 strategy has at most one `every` block and one `if` rule. | -| Numeric, host-provided signals | Conditions compare named signal series with numeric literals; Nano does not calculate indicators or fetch data. | -| AND-only conditions | Every condition must pass before the rule emits its intents. | -| Five intent actions | `buy`, `sell`, `execute`, `pause`, and `observe` emit proposals. `execute()` does not execute code. | -| Manifest validation | The strategy IR rejects unknown node/effect names and intent nodes without `intent.emit`; it is not a static type system. | -| Agent labels | `agent Name` is metadata today; the interpreter does not coordinate agents. | +| A small strategy source format, validated `StrategyGraph` IR, and deterministic reference evaluation | Signal calculation, data quality, and scheduling | +| Named numeric signal series and AND-only threshold conditions | Policy, approvals, persistence, and external effects | +| Proposed `buy`, `sell`, `execute`, `pause`, and `observe` intents | API calls, exchange execution, and any action with consequences | -There are no variables, arithmetic, functions, imports, `or`/`not`, user-defined actions, type checking, or CLI in the current implementation. The exact grammar and execution semantics are documented in [docs/language.md](docs/language.md). +The current implementation has no variables, arithmetic, functions, imports, `or`/`not`, type system, CLI, LLM runtime, live data feed, or action executor. [`docs/status.md`](docs/status.md) separates implemented behavior from experimental work and future ideas. -## What ships today +## Build with Nano + +Nano stays approachable by keeping its contract narrow and changes reviewable. Contributions are welcome from: -| Implemented and tested | Experimental or optional | Not implemented | -| --- | --- | --- | -| `.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 library | Real quantum-hardware dispatch | Autonomous loop execution or self-modifying deployment | +- **Quant researchers** who can add a strategy and document its signal convention. +- **Application engineers** who can improve integrations, replay coverage, documentation, or developer experience. +- **Language contributors** who can start a focused proposal before changing grammar or IR. -For a fuller implementation map, see [Architecture](docs/architecture.md) and [Status](docs/status.md). +See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and the [issue templates](.github/ISSUE_TEMPLATE/) for a clear place to begin. ## 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) | -| 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. +| Learn the grammar and runtime semantics | [Language reference](docs/language.md) | +| Understand module boundaries | [Architecture](docs/architecture.md) | +| Check implemented versus experimental work | [Status](docs/status.md) | +| Integrate or contribute | [Contributing](CONTRIBUTING.md) | +| Report a security concern | [Security policy](SECURITY.md) | + +The [paper series](docs/papers/README.md) records design arguments and research directions; source and tests define current behavior. diff --git a/assets/nano-governed-decision-flow.svg b/assets/nano-governed-decision-flow.svg new file mode 100644 index 0000000..78511ac --- /dev/null +++ b/assets/nano-governed-decision-flow.svg @@ -0,0 +1,68 @@ + + From a Nano strategy to a host-governed decision + A Nano strategy is compiled to StrategyGraph IR and evaluated with host-provided market data. The runtime emits an intent and run log, then the host decision gate produces a decision record. + + + + + + + + + + + + + + + + + + + + + + Nano + strategy + + + + Nano + compiler + + + + StrategyGraph + IR + + + + Reference + runtime + + + + Intent + and run log + + + + Host decision + gate + + + + Decision + record + + + + Host MarketFrame + + + + + From source to a governed decision + Nano evaluates a rule; the host retains the authority to act. + +