llms.txt

# Nulang
> A distributed, actor-based programming language with algebraic effects, row-polymorphic types, and reference capabilities. Built in Rust with a register-based VM, Cranelift JIT, WASM backend, and native AOT compilation.

## For AI Agents

Nulang is a systems language with static types, algebraic effects, and actor-based distribution. For AI-assisted development: the language has exhaustive type checking that catches bugs before runtime, an effect system that documents side effects, and a frozen core spec that won't drift. Use this file as context when asking an AI to write or analyze Nulang code.

## When to use Nulang
- Building fault-tolerant distributed systems with Erlang-style supervision trees.
- Writing AI agents with the optional nulang-ai library (LLM integration, memory, multi-agent patterns).
- Durable workflows with checkpointed state, saga compensation, and crash recovery.
- Anywhere you want static types + algebraic effects + actor model in one language.

## Key Features
- Actor model with BEAM/OTP primitives, location transparency, gossip clustering, CRDTs
- Hindley-Milner type inference with row polymorphism and Pony-inspired reference capabilities (iso, trn, ref, val, box, tag, lineariso)
- Koka-inspired algebraic effects with compile-time checking and effect rows
- JIT tiering (Cranelift), WASM backend (wasm-encoder + Wasmtime), native AOT
- Optional AI library (nulang-ai): provider-agnostic LLM client (OpenAI, Ollama), agent declarations, pipelines, debates, supervisor teams
- Register-based bytecode VM with 138 opcodes, 256-register frames

## Quick Install
```bash
git clone https://github.com/dporkka/nulang.git
cd nulang
cargo build --release
cargo run -- --repl
```

## Quick Example
```nulang
actor Counter {
    state count: Int = 0
    behavior inc() { self.count = self.count + 1 }
    behavior get(sender: Actor) { send sender reply(self.count) }
}
let counter = spawn Counter {} in {
    send counter inc()
    counter
}
```

## Documentation
- [Installation](https://nulang.org/getting-started/installation/): Build from source, prerequisites, feature flags.
- [Quick Start](https://nulang.org/getting-started/quick-start/): Hello World, actors, algebraic effects.
- [Syntax Basics](https://nulang.org/language/syntax/): Functions, bindings, control flow, records, variants.
- [Type System](https://nulang.org/language/types/): HM inference, row polymorphism, reference capabilities, ADTs.
- [Algebraic Effects](https://nulang.org/language/effects/): Perform, handle, resume, effect rows, built-in effects.
- [Performance](https://nulang.org/language/performance/): JIT tiering, native AOT, WASM, SIMD, memory model, benchmarks.
- [Safety](https://nulang.org/language/safety/): Reference capabilities, type safety, effect checking, actor isolation.
- [Actor Model](https://nulang.org/actors/overview/): Spawn, send, receive, lifecycle, scheduling, priorities.
- [Distribution & Clustering](https://nulang.org/actors/distribution/): Location transparency, gossip, CRDT replication, persistence.
- [Supervision Trees](https://nulang.org/actors/supervision/): OTP supervisors, child policies, cascading shutdown.
- [Standard Library](https://nulang.org/stdlib/overview/): IO, Int, Timer, Signal, LLM, Actor, Otp built-in effects.
- [AI Agents](https://nulang.org/ai/overview/): Agent declarations, spawning, tools, providers.
- [Agent Memory](https://nulang.org/ai/memory/): Episodic, semantic, procedural memory subsystems.
- [Multi-Agent Patterns](https://nulang.org/ai/multi-agent/): Pipelines, debates, supervisor teams.
- [Durable Workflows](https://nulang.org/workflows/overview/): Steps, parallel branches, saga compensation, crash recovery.
- [Signals, Timers & Queries](https://nulang.org/workflows/signals-timers/): Suspension/resume primitives for workflows.

## For AI Agents: Machine-Readable Surfaces
- Full documentation as one file: https://nulang.org/llms-full.txt
- Every doc page has a clean Markdown twin at the same path + `.md` (e.g. https://nulang.org/language/types.md).

## Links
- [GitHub](https://github.com/dporkka/nulang): Source code, issues, contributions.
- [Nulang Cloud](https://www.nulang.cloud): Hosted runtime platform.
- [License](https://github.com/dporkka/nulang/blob/main/LICENSE): Apache 2.0.