nodus-lang 4.0.7

An orchestration DSL and embedded runtime for agentic systems

Nodus

v4.0.7 stable on PyPI — pip install nodus-lang · Full 33-package companion ecosystem live: pip install nodus-sdk[agent,sql,fastapi]

pip install nodus-lang
nodus init
nodus run
nodus repl

Nodus is an orchestration DSL and embedded runtime for building agentic systems, created by Shawn Knight as part of the Masterplan Infinite Weave ecosystem. It implements the Infinity Algorithm's execution model as a first-class language construct. It gives AI workflows, tool chains, and agent pipelines a proper language — one where coroutines, task graphs, workflows, and goals are first-class constructs rather than library conventions layered over Python.

If you're building multi-step AI agents, embedding a scripting layer in a Python application, or wiring together tools via MCP or A2A, Nodus is the execution layer.

For a machine-readable project index see llms.txt.

The Nodus ecosystem spans 33 standalone packages, all available at github.com/Masterplanner25. A unified SDK (nodus-sdk) provides a single installation story: pip install nodus-sdk[agent,sql,fastapi].

Install

Requires Python 3.10+.

pip install nodus-lang

For the optional FastAPI/Uvicorn server stack:

pip install "nodus-lang[server]"

Quick Start

Create a project:

mkdir my-app
cd my-app
nodus init
nodus run

nodus init creates nodus.toml and src/main.nd.

nodus run executes the current project's src/main.nd when run inside a project root.

Start the REPL:

nodus repl

Useful REPL commands:

• :help shows REPL commands.
• :quit exits the REPL.

Run A File

Create hello.nd:

print("hello")

Run it explicitly:

nodus run hello.nd

When you provide a file path, Nodus runs only that file. When you run nodus run with no file inside a project, Nodus runs only src/main.nd.

Common Commands

• nodus --version
• nodus run hello.nd
• nodus run
• nodus repl
• nodus check hello.nd
• nodus check
• nodus fmt hello.nd

Standard Library

Import standard library modules with the std: prefix:

import "std:http" as http
let r = http.get("https://api.example.com/data")
print(r.body)

The full standard library ships with Nodus — no extra installs required for core modules:

Networking and I/O

Module	What it does
std:http	HTTP client — GET, POST, PUT, DELETE, PATCH; async variants; SSE streaming
std:subprocess	Run processes — sp.run(argv), sp.spawn(argv) for async + channel output
std:fs	Filesystem — read, write, append, exists, listdir, mkdir

Data and encoding

Module	What it does
std:json	json.parse(str) / json.stringify(val)
std:math	Arithmetic, trig, rounding, min/max
std:string	Split, join, trim, replace, starts_with, ends_with, case conversion
std:encoding	Base64 encode/decode, URL encode/decode
std:hash	SHA-256 / SHA-512 for data and files — returns record with .to_hex()

Time and system

Module	What it does
std:time	now_ms(), sleep(ms), UTC offset, format/parse timestamps
std:secrets	Cryptographic random tokens and bytes

AI-native orchestration (v4.0)

Module	What it does
std:tool	Register and dispatch tools — MCP-compatible namespaced registry
std:identity	trace_id(), session_id(), execution_unit_id() — propagated automatically
std:effects	EXACTLY_ONCE idempotency — resolve, pending, complete, action_id
std:sys	Versioned syscall dispatch — uniform {status, data, error, trace_id} response shape
std:memory	share(ns, key, val), recall_from(ns, key), recall_all(ns), forget(ns, key)
std:retry	retry.call(func, policy) — exponential backoff, jitter, max attempts
std:circuit_breaker	cb.create(name, cfg) / cb.call(name, func) — three-state breaker

Testing

Module	What it does
std:test	test.assert_eq, test.assert_err, test.flush_async — built-in test framework

Documentation

• Language Specification — full syntax, types, control flow, imports, coroutines
• Ecosystem Specs - implementation specs for proposed Nodus libraries and frameworks
• Architecture — runtime pipeline and module system
• Changelog — version history
• Contributing — development setup, code style, and contribution process
• llms.txt — machine-readable project index for AI tools
• llms-full.txt — full content summaries for AI indexers

Using with Claude Code

If you write Nodus with Claude Code, a language skill is available that teaches Claude the idioms, gotchas, and workflow patterns specific to Nodus v4:

1. Download skills/nodus.skill and skills/project-CLAUDE.md from this repo.
2. Copy project-CLAUDE.md to your project root as CLAUDE.md (fill in your project name).
3. Drop nodus.skill in your project's .claude/commands/ folder.
4. Claude will apply Nodus-specific rules automatically in every session.

The skill covers: record vs map distinction, the closure outer-let pattern, spawn() coroutine wrapping, workflow result bracket notation, NodusRuntime embedding defaults (timeout_ms=None, allowed_paths=CWD since v4.0.1), all 19 stdlib modules, and 15 verified complete example programs.

Using with Codex

If you write Nodus with Codex, a Codex-native skill and project template are available:

1. Copy skills/project-AGENTS.md to your project root as AGENTS.md and fill in your project name if needed.
2. Copy the skills/nodus/ folder to $CODEX_HOME/skills/nodus or ~/.codex/skills/nodus.
3. Start a Codex session in your Nodus project. Codex can auto-trigger the skill, or you can invoke $nodus explicitly.

The Codex skill covers the same core language hazards: record vs map distinction, closure outer-let mutation, spawn() coroutine wrapping, workflow result bracket notation, import rules, and NodusRuntime embedding defaults (timeout_ms=None, allowed_paths=CWD since v4.0.1), while keeping deeper material in reference files for on-demand loading.

---

Creator & Ecosystem

Nodus is created and maintained by Shawn Knight as part of the Masterplan Infinite Weave — an AI-native execution framework built on the Infinity Algorithm. Nodus is the runtime layer that makes the Infinity Algorithm's orchestration constructs executable as a first-class language.

From the creator's writing:

• Why I'm Building A.I.N.D.Y. (Or Any Tool, Really) — the strategic context behind Nodus
• Duality of Progress: Master Index — the Infinity Algorithm framework Nodus executes
• AI Search Optimization — the discoverability philosophy this project embodies