Lumen

The AI-Native Programming Language

Build deterministic agent workflows with static types, first-class AI primitives, and markdown-native source files.

📚 Documentation · 🎮 Playground · 🐛 Issues · 💬 Discussions

Why Lumen?

Building AI systems today means juggling Python notebooks, API clients, prompt templates, and orchestration frameworks. Lumen unifies this into one language:

Quick Start

# Install (One-liner)
curl -fsSL https://raw.githubusercontent.com/alliecatowo/lumen/main/scripts/install.sh | sh

# Or via Cargo
cargo install lumen-lang

# Create your first program
cat > hello.lm.md << 'EOF'
cell main() -> String
  return "Hello, World!"
end
EOF

# Run it
lumen run hello.lm.md

Features

• Algebraic Effects: First-class effect handling with perform and handle constructs
• Markdown-Native Source: Write code and docs together in .lm.md or .lumen files
• Static Typing: Full type inference with compile-time error checking
• AI Tool Dispatch: Typed tool interfaces with policy constraints
• Register-Based VM: Efficient bytecode execution
• Full LSP Support: Hover, document symbols, signature help, semantic tokens, diagnostics

📝 Markdown-Native Source

Write code and documentation together in .lm.md or .lumen, or use .lm for source-only modules:

# User Authentication

This module handles user login and session management.

```lumen
record User
  id: String
  name: String
  email: String where email.contains("@")
end

cell authenticate(email: String, password: String) -> result[User, String]
  # Implementation here
end
```

🔒 Statically Typed

Catch errors at compile time:

cell divide(a: Int, b: Int) -> result[Int, String]
  if b == 0
    return err("Division by zero")
  end
  return ok(a / b)
end

🎯 Algebraic Effects

First-class effect handling with one-shot delimited continuations:

effect Log
  cell info(msg: String) -> Unit
end

cell main() -> String / {Log}
  perform Log.info("Starting")
  return "Done"
end

handle main() with Log.info(msg) -> resume(unit)
  print("LOG: {msg}")
end

🤖 AI-Native Constructs

Tools, grants, and agents are built-in:

use tool llm.chat as Chat

grant Chat
  model "gpt-4o"
  max_tokens 1024
  temperature 0.7

agent Assistant
  cell respond(message: String) -> String / {llm}
    role system: You are a helpful assistant.
    role user: {message}
    return Chat(prompt: message)
  end
end

⚡ Deterministic Runtime

Reproducible execution for auditable AI:

@deterministic true

cell main() -> String
  # Nondeterministic operations rejected at compile time
  # uuid()      # Error!
  # timestamp() # Error!
  return "Deterministic output"
end

🌐 WASM Ready

Compile to WebAssembly for browser execution:

lumen build wasm --target web

Documentation

Examples

See all 30 examples in the examples directory.

Language Tour

Cells (Functions)

cell greet(name: String) -> String
  return "Hello, {name}!"
end

Records with Constraints

record Product
  name: String where length(name) > 0
  price: Float where price >= 0.0
end

Pattern Matching

cell classify(n: Int) -> String
  match n
    0 -> return "zero"
    1 -> return "one"
    _ -> return "many"
  end
end

Error Handling

cell safe_divide(a: Int, b: Int) -> String
  match divide(a, b)
    ok(value) -> return "Result: {value}"
    err(msg) -> return "Error: {msg}"
  end
end

Processes

pipeline DataProcessor
  stages:
    -> extract
    -> transform
    -> load
  
  cell extract(source: String) -> list[Json]
    # Extract data
  end
  
  cell transform(data: list[Json]) -> list[Record]
    # Transform data
  end
  
  cell load(records: list[Record]) -> Int
    # Load data
  end
end

Architecture

┌─────────────────────────────────────────────────────────────┐
│            .lm.md / .lm / .lumen Source Files                 │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Markdown Extraction (.lm.md/.lumen) / Direct Parse (.lm)    │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Lexer → Parser → Resolver → Typechecker → Constraint Val   │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    LIR Bytecode                              │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Register VM                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │  Values  │ │ Futures  │ │  Tools   │ │ Traces   │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────┘

Development

# Clone
git clone https://github.com/alliecatowo/lumen.git
cd lumen

# Build
cargo build --release

# Test (1365+ tests)
cargo test --workspace

# Run
cargo run --bin lumen -- run examples/hello.lm.md

Repository Structure

lumen/
├── docs/                    # VitePress documentation site
│   ├── learn/              # Tutorials and guides
│   ├── reference/          # Language specification
│   ├── api/                # Standard library docs
│   └── examples/           # Example documentation
├── examples/               # Example programs
├── editors/               # Editor support (VS Code)
├── rust/
│   ├── lumen-compiler/    # Compiler pipeline
│   ├── lumen-vm/          # Register-based virtual machine
│   ├── lumen-runtime/     # Runtime: tool dispatch, caching, tracing
│   ├── lumen-cli/         # Command-line interface
│   ├── lumen-lsp/         # Language Server Protocol
│   ├── lumen-wasm/        # WebAssembly bindings
│   └── lumen-provider-*/  # Tool providers (HTTP, JSON, FS, MCP)
├── SPEC.md                # Implementation-accurate spec
└── CLAUDE.md              # AI assistant instructions

Contributing

We welcome contributions! Please see:

• Contributing Guide
• Code of Conduct
• Good First Issues

License

MIT License - see LICENSE for details.

Made with ❤️ by the Lumen community