Nodus

# Nodus

> An orchestration DSL and embedded runtime for building agentic hosts.
> Created by Shawn Knight — [Masterplan Infinite Weave](https://www.the-master-plan.com/)

Nodus is the execution layer of the Masterplan Infinite Weave ecosystem — a bytecode-compiled
language whose runtime provides durable, inspectable, capability-jailed task orchestration (embedded runtimes deny subprocess, network and env by default),
with a clean handoff boundary to model-driven decisions your host supplies. `workflow`, `goal`,
`step` and `after` are language constructs; task graphs are a runtime library the compiler
feeds. There is no model in the core. It embeds in Python via `NodusRuntime` and
ships a 36-package companion ecosystem for AI agent infrastructure.

## Install

```
pip install nodus-lang
```

## Core Documentation

- [README.md](https://github.com/Masterplanner25/Nodus/blob/main/README.md): Getting started, install, quick start, stdlib overview, ecosystem
- [docs/language/LANGUAGE_SPEC.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/language/LANGUAGE_SPEC.md): Full language spec — syntax, types, control flow, coroutines, stdlib, stability labels
- [docs/runtime/ARCHITECTURE.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/runtime/ARCHITECTURE.md): Runtime architecture, execution pipeline, builtin registry
- [docs/runtime/EXECUTION_INVARIANTS.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/runtime/EXECUTION_INVARIANTS.md): Documented runtime invariants (VM, scheduler, module, sandbox, coroutine)
- [docs/governance/LANGUAGE_STABILITY_INDEX.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/LANGUAGE_STABILITY_INDEX.md): Per-surface stability tiers (Stable / Mostly Stable / Experimental)
- [docs/governance/COMPANION_LIBRARY_CONTRACT.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/COMPANION_LIBRARY_CONTRACT.md): APIs a companion library may depend on; compatibility promises
- [docs/onboarding/NODUS.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/onboarding/NODUS.md): Project identity, capabilities, ecosystem, embedding API overview
- [CHANGELOG.md](https://github.com/Masterplanner25/Nodus/blob/main/CHANGELOG.md): Version history
- [llms-full.txt](https://github.com/Masterplanner25/Nodus/blob/main/llms-full.txt): Full content summaries for AI indexers

## User Guide

- [docs/guide/getting-started.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/getting-started.md): Install, first script, REPL, two-file project, error basics
- [docs/guide/agent-host-boundary.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/agent-host-boundary.md): agent_call / agent_call_async / agent_available / agent_describe / `action agent`, registering a handler with NodusRuntime.register_agent, the nine-key result envelope, and why an agent failure is soft
- [docs/guide/ai-primitives.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/ai-primitives.md): std:tool (MCP-compatible registry), std:identity, std:effects, std:memory, std:retry, std:circuit_breaker
- [docs/guide/ecosystem.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/ecosystem.md): 35 companion packages — roles, install tiers, nodus-sdk unified entry point
- [docs/guide/embedding-nodus.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/embedding-nodus.md): NodusRuntime API, sandboxing, on_error, shutdown, async concurrency, type marshaling
- [docs/guide/library-entry-points.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/library-entry-points.md): How to publish a Nodus companion library via nodus.nd entry-point
- [docs/guide/types-and-values.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/types-and-values.md): Numbers, strings, lists, maps, records, nil, functions as values
- [docs/guide/error-handling.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/error-handling.md): try/catch/finally, throw, err.kind reference, err record shape
- [docs/guide/modules-and-imports.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/modules-and-imports.md): Import syntax, exports, stdlib modules, resolution order
- [docs/guide/standard-library.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/standard-library.md): Complete stdlib function reference
- [docs/guide/workflows-and-tasks.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/workflows-and-tasks.md): Workflow/goal DSL, step dependencies, state, checkpoints, retries
- [docs/guide/real-world-integration.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/real-world-integration.md): Production-shaped integration — embedded runtime + WAIT/RESUME gates, event routing, dynamic .nd generation
- [examples/webhook_bridge/](https://github.com/Masterplanner25/Nodus/blob/main/examples/webhook_bridge/): FastAPI + nodus serve bridge — dynamic .nd generation, step retry, SQL audit log, replay; its Status section records what serve cannot yet do (#855, #857, #858)
- [docs/guide/debugging.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/guide/debugging.md): --trace flags, nodus check, interactive debugger

## Runnable Code

Every path here runs as-is from a checkout. `nodus test-examples` runs the first
group from an installed wheel too — they ship inside the package.

- [examples/](https://github.com/Masterplanner25/Nodus/tree/main/examples): The example suite `nodus test-examples` executes — hello, features, three import forms, stdlib, and a multi-file project layout
- [examples/project_layout_demo/README.md](https://github.com/Masterplanner25/Nodus/blob/main/examples/project_layout_demo/README.md): How a multi-file Nodus project is laid out — entry point, sibling module, `utils/index.nd`
- [examples/orchestration/README.md](https://github.com/Masterplanner25/Nodus/blob/main/examples/orchestration/README.md): Concurrent agent fan-out — `fan_out`, schema-forced `typed()` calls, a nested judge panel run against stub agents, and a wall-clock overlap test
- [demos/RUNME.md](https://github.com/Masterplanner25/Nodus/blob/main/demos/RUNME.md): Three demos showing what the stack does that others do not — start here to run them
- [demos/agent_orchestration/DESIGN.md](https://github.com/Masterplanner25/Nodus/blob/main/demos/agent_orchestration/DESIGN.md): Agent orchestration demo — design and walkthrough
- [demos/embed_worker/README.md](https://github.com/Masterplanner25/Nodus/blob/main/demos/embed_worker/README.md): Embedding Nodus as a worker in a Python host
- [demos/package_conversion/README.md](https://github.com/Masterplanner25/Nodus/blob/main/demos/package_conversion/README.md): Converting an existing package to run on Nodus

## AI Assistant Assets

- [skills/nodus.skill](https://github.com/Masterplanner25/Nodus/blob/main/skills/nodus.skill): Claude Code skill for Nodus v4 with language rules, error patterns, stdlib guidance, and verified examples
- [skills/project-CLAUDE.md](https://github.com/Masterplanner25/Nodus/blob/main/skills/project-CLAUDE.md): Project-root `CLAUDE.md` template for Nodus projects
- [skills/nodus/SKILL.md](https://github.com/Masterplanner25/Nodus/blob/main/skills/nodus/SKILL.md): Codex skill entrypoint for Nodus v4
- [skills/project-AGENTS.md](https://github.com/Masterplanner25/Nodus/blob/main/skills/project-AGENTS.md): Project-root `AGENTS.md` template for Codex sessions

## Runtime Reference

- [docs/runtime/FAILURE_AND_DEGRADATION_MODEL.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/runtime/FAILURE_AND_DEGRADATION_MODEL.md): Failure categories and degradation behavior
- [docs/runtime/OPERATOR_OR_EMBEDDER_RUNBOOK.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/runtime/OPERATOR_OR_EMBEDDER_RUNBOOK.md): Production runbook for embedders
- [docs/architecture/INFINITY_PATTERN_MAPPING.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/architecture/INFINITY_PATTERN_MAPPING.md): How Nodus implements the Infinity Algorithm execution model

## Governance

- [docs/governance/SECURITY_POSTURE.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/SECURITY_POSTURE.md): Security boundaries, enforcement paths, transport-specific trust model
- [docs/governance/RELEASE_GATES.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/RELEASE_GATES.md): Release gate checklist (10 gates including pre-publish creator validation)
- [docs/governance/ISSUE_RESPONSE_POLICY.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/ISSUE_RESPONSE_POLICY.md): Bug response timelines and commitments
- [docs/governance/TECH_DEBT.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/TECH_DEBT.md): Open known issues with fix directions and skills

## Migration

- [docs/migration/v3-to-v4.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/migration/v3-to-v4.md): Breaking changes v3.x → v4.0
- [docs/migration/v2-to-v3.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/migration/v2-to-v3.md): Breaking changes v2.x → v3.0

## Wiki

- [Nodus Wiki](https://github.com/Masterplanner25/Nodus/wiki) — complete language reference wiki (24 pages covering syntax, stdlib, workflows, embedding, roadmap, changelog)
  - [Getting Started](https://github.com/Masterplanner25/Nodus/wiki/Getting-Started)
  - [Language Overview](https://github.com/Masterplanner25/Nodus/wiki/Language-Overview)
  - [Syntax Reference](https://github.com/Masterplanner25/Nodus/wiki/Syntax-Reference)
  - [Standard Library](https://github.com/Masterplanner25/Nodus/wiki/Standard-Library)
  - [Embedding API](https://github.com/Masterplanner25/Nodus/wiki/Embedding-API)
  - [Workflows and Task Graphs](https://github.com/Masterplanner25/Nodus/wiki/Workflows-and-Task-Graphs)
  - [Type System](https://github.com/Masterplanner25/Nodus/wiki/Type-System)
  - [Error Handling](https://github.com/Masterplanner25/Nodus/wiki/Error-Handling)

## Ecosystem

Nodus is the core runtime of the Masterplan Infinite Weave ecosystem.

- [Masterplan Infinite Weave](https://www.the-master-plan.com/) — the broader ecosystem
- [github.com/Masterplanner25](https://github.com/Masterplanner25) — all 35 companion packages
- [nodus-mcp](https://github.com/Masterplanner25/nodus-mcp) — MCP protocol client + server
- [nodus-extension](https://github.com/Masterplanner25/nodus-extension) — plugin framework
- [nodus-sdk](https://github.com/Masterplanner25/nodus-sdk) — unified install: `pip install nodus-sdk`

## Creator

Shawn Knight — creator of Nodus and architect of the Masterplan Infinite Weave.

- Web: [the-master-plan.com](https://www.the-master-plan.com/)
- GitHub: [Masterplanner25](https://github.com/Masterplanner25)
- Medium: [Masterplan Infinite Weave](https://medium.com/masterplan-infinite-weave)

## Key Concepts

- **Nodus** — orchestration DSL and embedded runtime. File extension: `.nd`.
- **Masterplan Infinite Weave** — the AI-native ecosystem Nodus is the execution layer of.
- **Infinity Algorithm** — the I→T→C→R→O→Feedback execution model Nodus implements as a first-class language construct through workflows, goals, and task graphs.
- **NodusRuntime** — Python embedding API: `from nodus import NodusRuntime`
- **Task graph** — persistent, resumable directed execution graph used by workflow/goal DSLs.
- **std:tool** — MCP-compatible tool registry. Names must be dotted (`"myapp.tool_name"`).
- **int vs float** — `42i` is int; `42` is float. `type(42i)` = "int", `type(42)` = "float".
- **String interpolation** — `"\(expr)"` embeds an expression in a string literal.
- **Stability tiers** — Stable (frozen), Mostly Stable (refinements OK), Experimental (may change). Run `nodus stability` to see the full surface index.
- **AI-native primitives** — std:identity (trace IDs), std:effects (EXACTLY_ONCE), std:sys (versioned dispatch), std:memory (share/recall), std:retry, std:circuit_breaker.
- **Coroutines** — cooperative, spawned with `spawn(coroutine(fn))`, scheduled with `run_loop()`. [Experimental]
- **Channels** — typed message passing via `channel()`, `send()`, `recv()`, `close()`. [Experimental]
- **Companion Library Contract** — companion libraries may only depend on APIs listed in `docs/governance/COMPANION_LIBRARY_CONTRACT.md`.
- **Bootstrapping** — Nodus will compile itself in itself; a decided long-term direction, not a maybe. It constrains design now: a feature needing a separate "systems" subset signals the abstraction level is wrong. `examples/expr_compiler.nd` is a lexer/parser/evaluator already written in Nodus. Blocker is runtime throughput, not semantics: ~400K instr/sec on CPython for a hot arithmetic loop, ~320K on a compiler workload. PyPy runs Nodus unmodified and is worth ~23x on the loop but only ~4-5x on the compiler workload -- a JIT's best case is not a promise. A further 1.5x needs no new runtime: the VM retains an event per call/return, unbounded and unread (#522). See `docs/language/LANGUAGE_VISION.md`.

## Package

- PyPI: `nodus-lang` (v5.15.0 — current stable, published 2026-09-25)
- Install: `pip install nodus-lang`
- Full 36-package companion ecosystem live: `pip install nodus-sdk[agent,sql,fastapi]`
- Requires Python >= 3.10