Nexural Automation

The safety-first engineering lab for NinjaTrader 8 automation

Build the strategy. Prove the research. Break the bridge. Recover the state. Promote only the evidence.

Start here · Academy · NT8 safety spine · Research engine · Architecture · Verification · Docs

[!CAUTION] Research, education, Playback, and simulated execution only. The included bridge has no live-routing mode. This project is not financial advice and passing its tests does not make a strategy safe or profitable. Read the full disclaimer.

What this repository is

Nexural Automation is an executable learning and validation system for NT8 automation engineering. It joins four surfaces that usually live in disconnected projects:

The goal is not to collect another folder of standalone strategies. The goal is to teach and enforce the engineering discipline needed to make automation observable, reproducible, recoverable, and difficult to misuse.

Verified capability status

This table separates automated evidence from claims that still require a human or external environment.

Start here

Requirements: Git, Python 3.11, and PowerShell 7 for the NT8 harness. Node.js 22 is needed only for frontend work. NinjaTrader 8 is needed only for the native compile and desktop verification steps.

Windows

git clone https://github.com/JasonTeixeira/Nexural_Automation.git
cd Nexural_Automation

$env:SETUPTOOLS_USE_DISTUTILS = "stdlib"
cd platforms/python/research/nexural-research
py -3.11 -m pip install -e ".[dev,mcp]"
py -3.11 -m nexural_research.cli quality-gate --threshold 0.95 --json --fast

Run the native safety checks from the repository root:

cd ../../../..
./platforms/ninjatrader/scripts/Test-NT8SafetySpine.ps1

If NT8 is not installed, run the portable kernel and fault suite only:

./platforms/ninjatrader/scripts/Test-NT8SafetySpine.ps1 -SkipNativeCompile

macOS or Linux

git clone https://github.com/JasonTeixeira/Nexural_Automation.git
cd Nexural_Automation
export SETUPTOOLS_USE_DISTUTILS=stdlib
python3.11 -m pip install -e "platforms/python/research/nexural-research[dev,mcp]"
make smoke
make quality-gate

Launch the local API, MCP server, and dashboard with scripts/start-local-stack.ps1 on Windows or scripts/start-local-stack.sh on macOS/Linux.

Automation Academy

The Academy is an executable curriculum, not a page of code snippets. Every lab includes:

• English and Spanish concept material
• a deliberately incomplete starter program and a reference solution
• visible assertions and withheld learner-facing checks
• a deterministic expected trace and seeded fault scenario
• an acceptance rubric tied directly to generated evidence

The hosted grader executes a constrained, data-only trace language. It does not import arbitrary Python or C# from a learner submission. Submitted booleans are ignored; the server replays the source and derives the result.

Five tracks, sixty labs

nexural-research academy catalog --json
nexural-research academy start research.lookahead --learner local-operator --json
nexural-research academy check research.lookahead `
  --learner local-operator `
  --submission ../../../../academy/fixtures/lookahead-safe-submission.json `
  --json
nexural-research academy progress --learner local-operator --json

Curriculum authors can create and validate packages without enabling arbitrary code execution:

python -m nexural_research.academy.authoring new nt8.example `
  --root academy/lessons `
  --track nt8-foundations `
  --title "Example" `
  --title-es "Ejemplo"
python -m nexural_research.academy.authoring validate academy/lessons/nt8-example

Read the Academy contract and learning-item schema.

Native NT8 safety spine

The C# core is platform-portable; the adapters compile against the proprietary NT8 assemblies only in the native harness.

signal file
   │
   ▼
schema + monotonic sequence + age gate
   │
   ▼
exact account/provider gate ── reject anything except Sim101/Playback101
   │
   ▼
reconciliation + risk engine + persistent kill switch
   │
   ▼
order/execution state machine ── journal ── ACK ── durable cursor

The fault suite covers duplicate and non-monotonic signals, stale/future signals, unreconciled startup, every risk limit, partial fills, overfills, illegal transitions, restart persistence, cursor/ACK crash gaps, live-account rejection, and flatten-only kill-switch behavior.

Build a validated NT8 import archive:

./platforms/ninjatrader/scripts/Build-NinjaTraderArchive.ps1

Then follow the explicit desktop import and Playback verification procedure. Native compilation proves API compatibility; it does not prove GUI import, provider behavior, or simulated fill timing.

Research and promotion engine

The Python engine imports strategy exports from NinjaTrader, TradingView, Interactive Brokers, MT4, and TradeStation. It provides:

• 71+ analysis metrics, deflated Sharpe, regime analysis, and Monte Carlo envelopes
• rolling walk-forward evaluation with fitted/frozen evidence requirements
• commission and slippage stress for ES, NQ, RTY, CL, GC, SI, HG, and ZB
• a ten-check gauntlet that can promote only to paper, tune, rewrite, or reject
• self-contained HTML reports, CLI/API access, and eight stable MCP tools

nexural-research gauntlet --input path/to/trades.csv --symbol NQ --strategy-name "NQ Research"
nexural-research costs --symbol NQ --trades 250 --stress-profile elevated
nexural-research report --input path/to/trades.csv
nexural-research mcp-smoke

See the MCP contract, API examples, and gauntlet failure guide.

Architecture

flowchart LR
    A[Academy learner] -->|declarative artifact| G[Trusted Academy runner]
    G --> E[Trace + tests + fault evidence + digest]

    X[Strategy exports] --> R[Python research engine]
    M[MCP / CLI / API / UI] --> R
    R --> Q[Gauntlet promotion gate]

    S[Signal inbox] --> V[NT8 schema, sequence, age gates]
    V --> K[C# risk + execution kernel]
    K --> N[NinjaScript Strategy / AddOn]
    N --> P[Sim101 or Playback101]

    E --> Q
    Q -->|paper evidence only| S
    Q -->|reject / tune / rewrite| Z[Stop with reasons]

Trust-boundary decisions are recorded in ADR 0001 and the threat model.

Verification contract

Run the same gates locally that protect the release path:

# Repository metadata, schemas, secrets, Academy parity
py -3.11 scripts/repo-tools/secret_scan.py
py -3.11 scripts/repo-tools/validate_contract_schemas.py
py -3.11 scripts/repo-tools/validate_beta_evidence.py

# Python engine and Academy
cd platforms/python/research/nexural-research
py -3.11 -m pytest tests --ignore=tests/e2e -q
py -3.11 -m nexural_research.cli quality-gate --threshold 0.95 --json --fast

# Native/portable NT8 checks
cd ../../../..
./platforms/ninjatrader/scripts/Test-NT8SafetySpine.ps1

Releases are built from immutable tags. The release gate builds and tests Python distributions, runs browser/auth/accessibility checks, runs the portable NT8 fault suite, validates the NT8 archive, generates an SPDX SBOM and SHA-256 manifest, signs artifacts through keyless Sigstore, and only then dispatches trusted PyPI and GHCR publication workflows. All third-party GitHub Actions are pinned to immutable commit SHAs.

Repository map

Nexural_Automation/
├── academy/                          # 60 labs, 5 tracks, 5 capstones, schemas, tools
├── platforms/ninjatrader/
│   ├── src/Nexural.NT8.Core/        # portable risk/execution kernel
│   ├── adapters/NinjaScript/         # Strategy and AddOn adapters
│   ├── tests/                        # fault suite and native compile harness
│   ├── scripts/                      # verify and package commands
│   └── docs/                         # safety model, fault matrix, import proof
├── platforms/python/research/
│   └── nexural-research/             # analysis engine, API, MCP, Academy service, UI
├── beta/                             # external evidence contract; no fabricated results
├── schemas/                          # strategy, bridge, beta, and evidence schemas
├── docs/                             # architecture, tutorials, security, operations
├── conductor/                        # product, stack, workflow, and track context
└── .github/workflows/                # CI, native evidence, release, signing, publication

Documentation map

Live documentation: https://jasonteixeira.github.io/Nexural_Automation/

Contributing and responsible disclosure

Contributions must preserve paper-only execution, no-lookahead assumptions, deterministic evidence, and fail-closed behavior. Read CONTRIBUTING.md before opening a pull request.

Report vulnerabilities privately through GitHub Security Advisories. Do not include active credentials, personal trading data, or brokerage identifiers in issues or beta artifacts.

External beta submissions must follow beta/README.md. The repository includes the validation machinery; it does not invent learners, capstones, or successful broker-environment results.

Built by Jason Teixeira for the Nexural ecosystem.

Evidence before promotion. Safety before performance. Simulation before capital.