NormCode is a language for building multi-step AI workflows where you can see exactly what each step receives and produces—no hidden context, no debugging in the dark.
You: "Summarize this document about Q3 earnings"
AI: [reads document, produces summary]
This works well for one-shot tasks.
For more complex work, you might chain several steps:
Step 1: "Extract all financial figures from this document"
Step 2: "Cross-reference these figures with our database"
Step 3: "Flag any discrepancies"
Step 4: "Generate an executive summary"
This is a workflow—and it can get messy.
By Step 4, your AI might be juggling:
- The entire original document (50+ pages)
- All extracted figures (hundreds of numbers)
- Raw database query results
- Notes from earlier steps
Sometimes the AI confuses a number from page 47 with a database entry, or references something that doesn't exist. When things go wrong, it's hard to tell which input caused the issue.
Some people call this "debugging in the dark."
In NormCode, each step only sees what you explicitly pass to it:
<- executive summary
<= generate summary from flagged items
<- discrepancy flags
<= check for mismatches
<- extracted figures
<= extract financial data
<- raw document
<- database results
Reading bottom-up:
- The extraction step sees only the
raw document - The mismatch check sees only
extracted figures+database results - The summary step sees only
discrepancy flags
If something goes wrong at a step, you can see exactly what that step received.
NormCode fits into a three-layer approach for building AI systems that stay aligned with what users actually want:
flowchart TB
A["🧭 NormCode<br/>Authority Layer<br/>Semi-formal contracts<br/>between humans and AI"]
B["🛠 Shared Workspace<br/>Execution Layer<br/>Data, tools, and<br/>task constraints"]
C["🧠 Foundation Models<br/>Understanding Layer<br/>General-purpose reasoning<br/>and generation"]
A --> B --> C
By making data flow and steps explicit, NormCode helps users stay in control of what their AI agents are doing.
<- risk assessment
<= evaluate legal exposure based on the extracted clauses
<- relevant clauses
<= extract clauses related to liability
<- full contract
Here, the risk assessment step only sees the extracted clauses—not the full contract. This keeps things focused and easier to audit.
| Type | LLM? | Cost | Determinism | Examples |
|---|---|---|---|---|
| Semantic | ✅ Yes | Tokens | Non-deterministic | Reasoning, generating, analyzing |
| Syntactic | ❌ No | Free | 100% Deterministic | Collecting, selecting, routing |
In a typical plan, many steps are just data routing—no LLM needed. Only the "thinking" steps cost tokens.
| Property | What it means |
|---|---|
| Automatable | AI can directly derive plan from your natural language instructions |
| Executable | The AI can follow the plan reliably |
| Accountable | You can understand what each step does for tracing |
graph TD
A["Natural Language Task"] --> B["Compiler"]
B --> C["NormCode Plan (.ncd)"]
C <--> D["Canvas App (Visual Debugger)"]
C --> E["Orchestrator"]
E --> F["Execution"]
F --> G["🧠 Foundation Models"]
F --> H["⚙️ Tools & Data"]
F --> I["Final Result + Audit Trail"]
| Component | What it does |
|---|---|
infra/ |
The execution engine (Orchestrator, Blackboard, Agent Sequences) |
canvas_app/ |
Visual debugger with graph view, breakpoints, and real-time execution |
cli_orchestrator.py |
Command-line tool for running orchestrations |
documentation/ |
Guides and reference docs |
git clone https://github.com/your-username/normCode.git
cd normCode
pip install -e .The Canvas App is a visual debugger for executing and inspecting NormCode plans:
python launch_canvas.pyThis automatically:
- Checks and installs Python dependencies (FastAPI, uvicorn, etc.)
- Checks and installs Node.js dependencies (React, Vite, etc.)
- Starts backend (port 8000) and frontend (port 5173)
Options:
python launch_canvas.py --prod # Production mode (no auto-reload)
python launch_canvas.py --skip-deps # Skip dependency checks (faster startup)
python launch_canvas.py --help # Show all optionsPrerequisites: Python 3.11+, Node.js 18+
For headless execution, use the CLI orchestrator:
# Start a new run
python cli_orchestrator.py run --concepts path/to/concepts.json --inferences path/to/inferences.json
# Resume from checkpoint
python cli_orchestrator.py resume --run-id <UUID>
# Fork from a past state
python cli_orchestrator.py fork --from-run <UUID> --concepts new_concepts.json
# List all runs
python cli_orchestrator.py list-runsSee NormCode in action with the base-X addition algorithm (achieves 100% accuracy on arbitrary-length inputs):
python infra/examples/add_examples/ex_add_complete.py<- document summary
<= summarize this text
<- clean text
<= extract main content, removing headers
<- raw document
Read bottom-up:
- Start with
raw document - Run
extract main content...→ producesclean text - Run
summarize this text→ producesdocument summary
Key insight: The summarization step literally cannot see the raw document.
Natural Language → .ncds (draft) → .ncd (formal) → .concept.json + .inference.json → Execution
| Phase | Output | Purpose |
|---|---|---|
| Derivation | .ncds |
Extract structure from natural language |
| Formalization | .ncd |
Add flow indices, sequence types, bindings |
| Post-Formalization | .ncd (enriched) |
Add paradigms, resources, axis annotations |
| Activation | JSON repositories | Generate executable format for orchestrator |
The Orchestrator runs plans with:
- Dependency-driven scheduling — inferences run only when inputs are ready
- SQLite checkpointing — pause, resume, or fork from any cycle
- Full state tracking — inspect what each step saw and produced
| Scenario | Use NormCode? | Rationale |
|---|---|---|
| Multi-step workflow (5+ LLM calls) | ✅ Yes | Isolation and debuggability pay off |
| Auditable AI (legal, medical, finance) | ✅ Yes | You must prove what each step saw |
| Long-running, resumable workflows | ✅ Yes | Built-in checkpointing |
| Quick prototype (1-2 LLM calls) | ❌ No | Overhead exceeds benefit |
| Simple Q&A chatbot | ❌ No | Just prompt the model directly |
Sweet spot: Complex, multi-step workflows where you need to know exactly what happened at each step—and where a failure at step 7 shouldn't corrupt reasoning at step 12.
normCode/
├── infra/ # Core execution engine
│ ├── _agent/ # Agent framework and sequences
│ ├── _orchest/ # Orchestrator and blackboard
│ ├── _states/ # Reference system and tensors
│ └── examples/ # Working examples
├── canvas_app/ # Visual debugger (React + FastAPI)
│ ├── frontend/ # React Flow graph visualization
│ └── backend/ # Execution controller API
├── documentation/ # Comprehensive documentation
│ ├── current/ # Latest guides
│ └── paper/ # Academic paper draft
├── cli_orchestrator.py # Command-line interface
├── launch_canvas.py # One-command Canvas App launcher
└── settings.yaml # LLM API configuration
Create settings.yaml in the project root (see canvas_app/settings.yaml.example):
llm:
provider: openai # or: anthropic, dashscope
api_key: your-api-key-here
model: gpt-4o # or: claude-3-opus, qwen-plus| Guide | Description |
|---|---|
| Overview | What NormCode is and why it exists |
| NCD Format | The formal syntax reference |
| Execution | How plans run at runtime |
| Compilation | The transformation pipeline |
| Canvas App | Visual debugger guide |
NormCode is described in the paper:
NormCode: A Semi-Formal Language for Context-Isolated AI Planning
Multi-step workflows that chain LLM calls suffer from context pollution. NormCode enforces explicit data isolation as a language-level constraint, making AI workflows auditable by construction.
See Arxiv for the full draft.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit issues and pull requests.