nexustrade 0.1.0__tar.gz

nexustrade-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+typescript/dist/
+typescript/node_modules/
+python/dist/
+python/build/
+python/*.egg-info/
+.venv-stats/
+**/__pycache__/

nexustrade-0.1.0/AGENTS.md

@@ -0,0 +1,232 @@
+# AGENTS.md — NexusTrade Python SDK
+
+Instructions for coding agents (Claude Code, Cursor, Codex, and friends) writing
+NexusTrade strategies with this package. Humans: [README.md](README.md) is the
+friendlier read.
+
+## What this package is
+
+A typed client plus ~170 **generated** builders for authoring trading
+strategies. The builders are generated from the same indicator specification the
+NexusTrade engine executes, so a book assembled from them is structurally valid
+before it ever leaves the process.
+
+```
+author a portfolio  →  submit a job  →  poll until terminal  →  read result
+```
+
+## Setup
+
+```bash
+pip install nexustrade
+export NEXUSTRADE_API_KEY=sk-...
+export NEXUSTRADE_API_BASE_URL=https://nexustrade.io/api/v1
+```
+
+```python
+import nexustrade as nt
+client = nt.NexusTradeClient.from_environment()
+```
+
+Keys come from https://nexustrade.io/developers. Never hardcode one into a file
+you write; read it from the environment.
+
+## Rules that matter
+
+**1. Use the builders. Never hand-write the JSON.**
+
+```python
+# Right — validated shape, correct wire names
+nt.buy(nt.stock_asset("SPY"), 100)
+
+# Wrong — silently diverges from the engine's schema
+{"type": "Buy", "targetAsset": {"symbol": "SPY"}, "amount": 100}
+```
+
+If you cannot find a builder, list them (`nt.__all__`) rather than inventing a
+dict. A hand-written payload that the API accepts can still mean something
+different from what you intended.
+
+**2. Every mutation needs an idempotency key, and it must be deterministic.**
+
+Jobs cost money. A retry with the *same* key returns the original operation; a
+retry with a new key launches a second paid job.
+
+```python
+# Right — same logical run reuses the key across retries
+nt.create_backtest(handle, idempotency_key="momentum-2024-v1")
+
+# Wrong — every retry is a new billable job
+nt.create_backtest(handle, idempotency_key=f"run-{time.time()}")
+```
+
+Reusing a key with a *different* payload is a `409 idempotency_conflict`. Version
+the key when the request changes: `momentum-2024-v2`.
+
+**3. `create_*` does not wait. Poll.**
+
+```python
+operation = nt.create_backtest(handle, idempotency_key="k")
+# operation["result"] is ABSENT here — the job has not run yet.
+finished = nt.wait_for_backtest(operation["id"])
+print(finished["result"])
+```
+
+A timeout does not cancel the job. Call the waiter again with the same id;
+do not resubmit.
+
+**4. Batch when you have several.**
+
+```python
+operations = nt.create_backtests([h1, h2, h3], idempotency_key="sweep-v1")
+results = nt.wait_for_backtests(operations)
+```
+
+One request, one key, one rate-limit slot — instead of three of each.
+
+**5. Percent semantics.** `buy(asset, 100)` is **100% of portfolio**, not 100
+shares. Deployment and allocation parameters are percentages unless a builder
+says otherwise.
+
+**6. Credentials come from the environment, or a `.env` file.** Both
+`NEXUSTRADE_API_KEY` and `NEXUSTRADE_API_BASE_URL` are read from the process
+environment first, then from a `.env` at or above the working directory. Never
+hardcode a key into a file you write, and never print one. Exported values win
+over the file, so a `.env` cannot silently override a deployment's real config.
+
+**7. The base install is stdlib-only.** `nt.lake.*` needs `pip install
+'nexustrade[lake]'`; `nt.spec_curve` and friends need `[stats]`. Missing extras
+raise an `AttributeError` that names the extra to install — read it rather than
+guessing.
+
+## Recipes
+
+<details open>
+<summary><b>Buy and hold</b></summary>
+
+```python
+import nexustrade as nt
+
+book = nt.portfolio("Buy and hold SPY", [
+    nt.strategy("Buy", nt.always(), nt.buy(nt.stock_asset("SPY"), 100)),
+])
+```
+</details>
+
+<details>
+<summary><b>Condition on an indicator</b></summary>
+
+Indicators support Python comparison operators; the result is a `Condition`.
+
+```python
+oversold = nt.RSI(nt.stock_asset("AAPL"), 14) < 30
+
+book = nt.portfolio("Dip buyer", [
+    nt.strategy("Buy the dip", oversold, nt.buy(nt.stock_asset("AAPL"), 25)),
+    nt.strategy(
+        "Take profit",
+        nt.PositionPercentChange(nt.stock_asset("AAPL")) > 10,
+        nt.sell(nt.stock_asset("AAPL"), 100),
+    ),
+])
+```
+
+Combine with `nt.multi`, `nt.at_least`, `nt.at_most`, `nt.exactly`.
+</details>
+
+<details>
+<summary><b>Rank and rotate a universe</b></summary>
+
+`CANDIDATE` is the placeholder for "each name being evaluated". Use it inside a
+pipeline; use a concrete asset outside one.
+
+```python
+book = nt.portfolio("Momentum", [
+    nt.strategy("Rotate", nt.always(), nt.dynamic_rebalance(
+        universe_config=nt.universe("SP500"),
+        pipeline=[
+            nt.filter(nt.Price(nt.CANDIDATE) > nt.SMA(nt.CANDIDATE, 200)),
+            nt.select_top(nt.RSI(nt.CANDIDATE, 14), 10),
+        ],
+        weight_indicator=nt.RSI(nt.CANDIDATE, 14),
+        limit=10,
+        deployment_percent=80,
+    )),
+], initial_value=100_000)
+```
+
+`deployment_percent=80` invests 80% of the portfolio across the selection and
+leaves the rest in cash. It is a **total** cap, not a per-name one.
+</details>
+
+<details>
+<summary><b>Backtest, optimize, walk forward</b></summary>
+
+```python
+bt = nt.backtest(book, start_date="2024-01-01", end_date="2024-12-31")
+
+opt = nt.optimization(book, start_date="2022-01-01", end_date="2024-12-31")
+
+wf = nt.walk_forward(book, global_start_date="2022-01-01",
+                     global_end_date="2024-12-31", fold_count=4)
+```
+
+Note walk-forward uses `global_start_date` / `global_end_date` / `fold_count`,
+not `start_date` / `end_date`. Each handle goes to its matching
+`create_*` + `wait_for_*` pair.
+</details>
+
+<details>
+<summary><b>Query the data lake</b></summary>
+
+```python
+result = nt.lake.sql(
+    "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
+    ["AAPL"],
+    max_rows=10_000,
+)
+frame = result.to_pandas()
+```
+
+Always parameterize with `?` rather than interpolating into the SQL string.
+Requires the `[lake]` extra.
+</details>
+
+## Errors
+
+All failures raise `NexusTradeApiError` with a stable `.status`, `.code`, and
+`.message`. Branch on `.code`, never on message text.
+
+| Code | What to do |
+| --- | --- |
+| `invalid_token` | Key missing/expired, or an OAuth JWT was used. Only `sk-` keys work here. |
+| `insufficient_scope` | The key lacks `read` / `write` / `lake`. Do not retry. |
+| `invalid_portfolio` | The book is malformed — fix the builders, do not retry as-is. |
+| `idempotency_conflict` | Same key, different payload. Version the key. |
+| `rate_limit_exceeded` | Back off and retry. |
+| `operation_timeout` | Job still running. Re-poll the same id; never resubmit. |
+
+`status == 0` means no HTTP status applies: the request never reached the API
+(`transport_error`), or the reply failed an envelope check.
+
+## Out of scope
+
+Not in this SDK. Do not attempt to reach them through it:
+
+- **Screener** — MCP only.
+- **Live trading and order placement** — deliberately excluded.
+- **Agent runs** — the NexusTrade agent API is not exposed here yet.
+
+## Verifying your work
+
+```python
+# Assemble the book and inspect the JSON before spending money on a backtest.
+import json
+print(json.dumps(book, indent=2))
+```
+
+If you are editing this repository rather than consuming it:
+
+```bash
+PYTHONPATH=. python3 -m unittest discover -s tests -t .
+```

nexustrade-0.1.0/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+Claude Code reads this file automatically. The guidance for working in this
+repository lives in **[AGENTS.md](AGENTS.md)** — a single source shared by every
+agent tool, so the two can never drift.
+
+Read AGENTS.md before writing NexusTrade strategy code.

nexustrade-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starks Technology, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexustrade-0.1.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: nexustrade
+Version: 0.1.0
+Summary: Typed Python SDK for NexusTrade portfolio authoring, backtesting, and optimization
+Project-URL: Homepage, https://nexustrade.io
+Project-URL: Repository, https://github.com/austin-starks/nexustrade-py
+Author: Starks Technology
+License: MIT License
+        
+        Copyright (c) 2026 Starks Technology, LLC
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: algorithmic-trading,backtesting,nexustrade,portfolio,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: lake
+Requires-Dist: duckdb==1.3.2; extra == 'lake'
+Requires-Dist: pandas==2.3.3; extra == 'lake'
+Requires-Dist: pyarrow==20.0.0; extra == 'lake'
+Provides-Extra: stats
+Requires-Dist: numpy==2.2.6; extra == 'stats'
+Requires-Dist: pandas==2.3.3; extra == 'stats'
+Requires-Dist: scipy==1.15.3; extra == 'stats'
+Requires-Dist: statsmodels==0.14.6; extra == 'stats'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://nexustrade.io/logo192.jpeg" alt="NexusTrade" width="88" height="88">
+
+# NexusTrade Python SDK
+
+**Author trading strategies in typed Python. Backtest them on the engine that runs them live.**
+
+[![PyPI](https://img.shields.io/pypi/v/nexustrade.svg)](https://pypi.org/project/nexustrade/)
+[![Python](https://img.shields.io/pypi/pyversions/nexustrade.svg)](https://pypi.org/project/nexustrade/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Types](https://img.shields.io/badge/types-py.typed-informational.svg)](https://peps.python.org/pep-0561/)
+
+[Quickstart](#quickstart) · [Authoring](#authoring-strategies) · [Polling](#jobs-run-on-the-engine--you-poll) · [Lake SQL](#lake-sql) · [Auth](#authentication) · [Errors](#errors)
+
+</div>
+
+---
+
+```bash
+pip install nexustrade
+```
+
+The base install is **stdlib-only** — no third-party dependencies, importable anywhere.
+
+```bash
+pip install 'nexustrade[lake]'    # DuckDB/pandas analysis of lake results
+pip install 'nexustrade[stats]'   # spec curves, Newey-West, bootstrap
+```
+
+## Quickstart
+
+```python
+from nexustrade import NexusTradeClient, always, backtest, buy, portfolio, stock_asset, strategy
+
+nt = NexusTradeClient(api_key="sk-...", base_url="https://nexustrade.io/api/v1")
+
+book = portfolio("Example", [
+    strategy("Buy SPY", always(), buy(stock_asset("SPY"), 100)),
+])
+
+operation = nt.create_backtest(
+    backtest(book, start_date="2024-01-01", end_date="2024-12-31"),
+    idempotency_key="example-v1",
+)
+result = nt.wait_for_backtest(operation["id"])
+print(result["result"])
+```
+
+## Authoring strategies
+
+Every builder is generated from the same indicator specification the NexusTrade
+engine runs, so a book is **valid by construction** rather than by convention.
+Indicators compose with ordinary Python operators.
+
+```python
+import nexustrade as nt
+
+book = nt.portfolio("Momentum", [
+    nt.strategy(
+        "Rotate into strength",
+        nt.always(),
+        nt.dynamic_rebalance(
+            universe_config=nt.universe("SP500"),
+            pipeline=[
+                nt.filter(nt.Price(nt.CANDIDATE) > nt.SMA(nt.CANDIDATE, 200)),
+                nt.select_top(nt.RSI(nt.CANDIDATE, 14), 10),
+            ],
+            weight_indicator=nt.RSI(nt.CANDIDATE, 14),
+            limit=10,
+            deployment_percent=80,
+        ),
+    ),
+], initial_value=100_000)
+```
+
+<details>
+<summary><b>What you can build</b> — 170+ generated builders</summary>
+
+| Group | Examples |
+| --- | --- |
+| **Price & volume** | `Price` `OpeningPrice` `HighOfDay` `VWAP` `Volume` `GapPercentage` |
+| **Technicals** | `SMA` `EMA` `RSI` `BollingerBand` `AverageTrueRange` `CrossAbove` |
+| **Position state** | `PositionValue` `PositionPercentChange` `PositionMaxDrawdown` |
+| **Portfolio state** | `PortfolioValue` `BuyingPower` `MaxDrawdown` `InitialValue` |
+| **Fundamentals** | `Fundamental` `Economic` `DaysUntilEarnings` `IsIndexMember` `IsIndustry` |
+| **Options** | `OptionDaysToExpiration` `OptionCollateral` `OptionUnrealizedPnL` `open_option` `close_option` |
+| **Actions** | `buy` `sell` `deposit` `withdraw` `alert` `dynamic_rebalance` `rebalance_option` |
+| **Selection** | `filter` `select_top` `select_percentile` `universe` |
+| **Logic** | `always` `at_least` `at_most` `exactly` `fewer_than` `multi` |
+
+Full list: `python -c "import nexustrade; print(nexustrade.__all__)"`
+
+</details>
+
+## Jobs run on the engine — you poll
+
+`create_*` enqueues work and returns immediately. It does **not** block until
+results exist. There are no webhooks today.
+
+Every job kind reports the same envelope, so one poller serves all of them:
+
+```python
+{
+  "id": "op_...",
+  "kind": "backtest",          # backtest | optimization | walk_forward
+  "status": "queued",          # queued | running | completed | failed | cancelled
+  "result": {...},             # present only once terminal
+  "error": {"code": ..., "message": ..., "retryable": ...},
+}
+```
+
+```python
+finished = nt.wait_for_backtest(operation["id"])   # blocks on deterministic backoff
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `timeout_seconds` | `900` | Give up waiting (the job keeps running) |
+| `poll_interval_seconds` | `2` | First interval; backs off 1.5× |
+| `max_poll_interval_seconds` | `15` | Interval ceiling |
+| `raise_on_failure` | `True` | Raise on `failed`/`cancelled` instead of returning |
+
+A timeout raises `operation_timeout` and does **not** cancel the job — call the
+waiter again with the same id rather than resubmitting.
+
+**Batches.** `create_backtests` submits many in one request and returns one
+operation each; `wait_for_backtests(operations)` waits on all of them. Prefer it
+over a loop: one request, one idempotency key, one rate-limit slot.
+
+**Optimization and walk-forward** follow the identical shape:
+
+```python
+study = nt.create_walk_forward(
+    nt.walk_forward(book, global_start_date="2022-01-01",
+                    global_end_date="2024-12-31", fold_count=4),
+    idempotency_key="wf-v1",
+)
+nt.wait_for_walk_forward(study["id"])
+```
+
+## Lake SQL
+
+Read-only SQL over the NexusTrade market-data lake. Results are durable Parquet
+parts rather than an implicitly materialized array, so a large result is
+explicit rather than an out-of-memory surprise.
+
+```python
+import nexustrade as nt
+
+result = nt.lake.sql(
+    "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
+    ["AAPL"],
+    max_rows=10_000,
+)
+frame = result.to_pandas()             # memory-bounded
+for batch in result.iter_batches():    # or stream within your own budget
+    ...
+```
+
+Requires the `[lake]` extra. NexusTrade resolves `lake.*` server-side and picks a
+compatible backing engine; your SQL does not change when it does.
+
+## Authentication
+
+Create a key at **[nexustrade.io/developers](https://nexustrade.io/developers)**
+(Profile → API Keys). Keys start with `sk-` and are shown once.
+
+```python
+nt = NexusTradeClient(api_key="sk-...", base_url="https://nexustrade.io/api/v1")
+# or set NEXUSTRADE_API_KEY / NEXUSTRADE_API_BASE_URL and:
+nt = NexusTradeClient.from_environment()
+```
+
+Both variables are also read from a **`.env` file** at or above the current
+directory, so a local project works with no exports and no `python-dotenv`:
+
+```bash
+# .env
+NEXUSTRADE_API_KEY=sk-...
+NEXUSTRADE_API_BASE_URL=https://nexustrade.io/api/v1
+```
+
+The real environment always wins — a `.env` value is used only when the variable
+is absent, so a stale file can never override what you exported. Nothing is
+written back to `os.environ`. Opt out with `NEXUSTRADE_DISABLE_DOTENV=1`.
+
+| Scope | Grants |
+| --- | --- |
+| `read` | `get_backtest`, `get_optimization`, `get_walk_forward` |
+| `write` | `create_portfolio`, `create_backtest(s)`, `create_optimization`, `create_walk_forward` |
+| `lake` | Lake catalog, query lifecycle, manifests, result parts |
+
+A key missing the scope gets `403 insufficient_scope`.
+
+> **OAuth is not accepted here.** NexusTrade's OAuth flow serves the MCP server.
+> These endpoints take `sk-` API keys only; a bearer JWT is rejected with
+> `401 invalid_token`.
+
+**Transport hardening.** HTTPS is required (except loopback). The client refuses
+cross-origin redirects, so the credential cannot be replayed to another host, and
+refuses to follow a redirect on any non-GET request, so a redirect can never
+re-submit a paid job.
+
+## Idempotency
+
+Every mutation takes a key. Reusing the same key with the same request returns
+the original resource instead of launching a second paid job — so a retry after
+a network failure is free.
+
+```python
+nt.create_backtest(handle, idempotency_key="momentum-2024-v1")
+```
+
+## Errors
+
+```python
+from nexustrade import NexusTradeApiError
+
+try:
+    nt.create_backtest(handle, idempotency_key="run-1")
+except NexusTradeApiError as error:
+    if error.code == "rate_limit_exceeded":
+        ...
+    raise
+```
+
+| Status | Code | Meaning |
+| --- | --- | --- |
+| 401 | `invalid_token` | Missing, malformed, or expired key (or an OAuth JWT) |
+| 403 | `insufficient_scope` | Key lacks `read`, `write`, or `lake` |
+| 400 | `invalid_request`, `invalid_portfolio` | Malformed input |
+| 400 | `invalid_idempotency_key` | Must match `[A-Za-z0-9._:-]{1,160}` |
+| 409 | `idempotency_conflict` | Key reused with a different payload |
+| 404 | `not_found`, `operation_not_found` | Unknown or not yours |
+| 429 | `rate_limit_exceeded` | Back off and retry |
+
+`status` is `0` when no HTTP status describes the failure: `transport_error`
+(never reached the API), `unsafe_redirect`, or an `invalid_response` envelope
+check on an otherwise-successful reply.
+
+## Timeouts
+
+`HttpTransport(timeout_seconds=...)` (default 30) is urllib's per-socket-operation
+timeout, so a slow-but-progressing response is not cut off mid-stream. Neither it
+nor the poll timeout bounds how long a *job* takes.
+
+## Scope
+
+Portfolio drafting, backtesting, optimization, walk-forward studies, and
+read-only SQL over the market-data lake, versioned under `/api/v1/nexustrade`.
+The screener and live trading remain outside this surface.
+
+## Using this SDK with a coding agent
+
+See **[AGENTS.md](AGENTS.md)** — the conventions, invariants, and recipes an
+agent needs to write correct NexusTrade strategies on the first pass.
+
+## License
+
+MIT