What Problem Does It Solve?
When you chain multiple LLM calls together, context pollution causes failures. By step 4, the model has 50 pages of documents, raw database results, and extraction metadata all swimming in context. It hallucinates because it's drowning in noise.
The NormCode solution: Each step is a sealed room. It only sees what you explicitly pass in. No hidden context, no accidental leakage. When something goes wrong, you can see exactly what that step received.
Example: Document Analysis Pipeline
NormCode uses indentation to show data dependencies. Each step only receives what is explicitly passed 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 raw document.
The mismatch check sees extracted figures + database results.
The summary step sees only discrepancy flags—never the full document.
Semantic vs. Syntactic Steps
NormCode distinguishes between two types of operations. Semantic steps may call an LLM, but many can be optimized to use scripts instead—syntactic steps are always free, instant, and deterministic.
| Type | LLM? | Cost | Determinism | Examples |
|---|---|---|---|---|
| Semantic | ⚡ Maybe | Tokens or Free | Varies | Reasoning, generating, analyzing (LLM or script) |
| Syntactic | ❌ No | Free | 100% Deterministic | Collecting, selecting, routing, looping |
A typical 20-step plan might only call an LLM 8 times. Some semantic steps can be optimized to scripts for speed and cost. Syntactic operations are always free: grouping data, selecting values, controlling flow, and iterating.
Progressive Formalization
NormCode uses a compilation pipeline that progressively transforms rough ideas into executable plans. Each phase adds structure while preserving intent—making complex logic explicit and auditable.
Natural Language Instruction → WHAT and WHY
↓
Phase 1: Derivation → IN WHAT ORDER
↓
Phase 2: Formalization → Grammar consistency check
↓
Phase 3: Post-Formalization → Contextualization + Resource Demand
↓
Phase 4: Activation → Actual Resources + Executables
↓
Orchestrator Executes
Why this matters: The instruction defines intent (what and why). Derivation determines execution order. Formalization ensures grammar consistency. Post-formalization adds context and declares resource needs. Activation resolves actual resources and executables. Each stage can be reviewed, so complex logic becomes transparent.
Dive Deeper
Explore the documentation to learn how to write NormCode plans:
Syntax Reference
Learn the <- and <= markers, concept types, and operators.
Execution Model
How plans run—dependency resolution, orchestration, and checkpointing.
Compilation
The 4-phase pipeline from natural language to executable JSON repositories.
Examples
Real-world patterns: linear flows, loops, conditionals, and error handling.
Core Principles
1. Data Isolation
Each step only sees what you explicitly pass to it. No hidden context, no context pollution. If something goes wrong, you can see exactly what that step received.
2. Full Auditability
Inspect what each step saw and produced. Complete state tracking with SQLite checkpointing—pause, resume, or fork from any cycle.
3. Efficient Execution
Many steps are just data routing—no LLM needed. Only the "thinking" steps cost tokens. Dependency-driven scheduling ensures optimal performance.
4. Semi-Formal Balance
Structured enough for reliable execution, readable enough for human review. AI can generate NormCode, and non-programmers can verify the logic.
5. Progressive Formalization
Start with a rough draft, then incrementally refine. The compiler transforms natural language into explicit structure—each phase answering a specific question while preserving intent.
When to Use NormCode
| Scenario | Use NormCode? | Why |
|---|---|---|
| Multi-step workflow (5+ LLM calls) | ✅ Yes | Isolation pays off |
| Auditable AI (legal, medical, finance) | ✅ Yes | Need proof of reasoning |
| Long-running resumable workflows | ✅ Yes | Built-in checkpointing |
| Simple Q&A chatbot | ❌ No | Just prompt directly |