Laran is an AI-native programming language designed for Language Models (LLMs) to generate, edit, and validate software systems efficiently.
Instead of AI generating thousands of lines of TypeScript or Python, Laran works with canonical JSON specifications that compile to executable code (NestJS, FastAPI, Cloud Functions, etc.).
- Token efficiency: 70-90% reduction vs traditional code repos
- Automatic verification: JSON Schema + semantic validation
- Clear contracts:
requires,ensures,limitswith runtime verification - Capability control: Declarative effects (
db.read,http.call, etc.) - Debug without code: Replay endpoints directly from specs
- Composable: Patterns, modules, and invariants for reuse
npm install -g @jmlaranjeira/laran# Validate a spec
laran validate api.ail.json
# Compile to NestJS
laran compile nest api.ail.json --out ./generated
# Debug an endpoint (dry-run)
laran replay api.ail.json --endpoint CreateUser --input '{"body":{"name":"Test"}}' --dry-runDebug without reading generated code:
# Replay with full trace
laran replay spec.json --endpoint GetUser --input '{"path":{"id":"123"}}' --verbose --dry-run{
"impl": {
"op": "pipeline",
"steps": [
{ "op": "db.find", "table": "Order" },
{ "op": "filter", "expr": "status == 'active'" },
{ "op": "group", "groupBy": "customerId" },
{ "op": "sort", "sortBy": "-total" },
{ "op": "reduce", "reducer": "acc + item.total" }
]
}
}{
"impl": {
"op": "rules",
"rules": [
{ "name": "VIP", "when": "customer.tier == 'VIP'", "then": { "set": { "discount": 0.2 } } },
{ "name": "Bulk", "when": "quantity >= 100", "then": { "set": { "discount": 0.1 } } }
],
"combine": "first"
}
}Apply common functionality with one line:
{
"patterns": [
{ "use": "soft-delete", "params": { "entity": "Task" } },
{ "use": "pagination", "params": { "entity": "Task", "maxPageSize": 50 } },
{ "use": "audit-log", "params": { "entities": ["Task", "User"] } }
]
}Built-in patterns: soft-delete, pagination, audit-log, timestamps, slug
Import/export types and endpoints:
{
"imports": [
{ "from": "./common.ail.json", "import": ["User", "Address"], "as": "common" }
],
"exports": { "all": true }
}Data integrity constraints:
{
"invariants": [
{
"name": "positive-balance",
"constraint": "Account.balance >= 0",
"enforcement": "runtime",
"message": "Balance cannot be negative"
}
]
}Define reusable pure functions in specs:
{
"functions": {
"calculateDiscount": {
"params": { "price": "float", "percent": "float" },
"returns": "float",
"body": { "return": "price * (1 - percent)" }
}
}
}{
"service": "orders-api",
"version": "1.0.0",
"imports": [
{ "from": "./common.ail.json", "import": ["Address"] }
],
"patterns": [
{ "use": "timestamps", "params": { "entity": "Order" } },
{ "use": "soft-delete", "params": { "entity": "Order" } }
],
"types": {
"Order": {
"kind": "struct",
"fields": {
"id": "uuid",
"customerId": "uuid",
"total": "float",
"status": "string",
"shippingAddress": "Address"
}
}
},
"invariants": [
{
"name": "positive-total",
"constraint": "Order.total >= 0",
"enforcement": "runtime"
}
],
"functions": {
"applyDiscount": {
"params": { "total": "float", "discount": "float" },
"returns": "float",
"body": { "return": "total * (1 - discount)" }
}
},
"endpoints": [
{
"name": "ListOrders",
"method": "GET",
"path": "/orders",
"out": "Order[]",
"impl": {
"op": "pipeline",
"steps": [
{ "op": "db.find", "table": "Order" },
{ "op": "sort", "sortBy": "-createdAt" }
]
}
},
{
"name": "CalculateDiscount",
"method": "POST",
"path": "/orders/discount",
"in": { "body": "DiscountRequest" },
"out": "DiscountResult",
"impl": {
"op": "rules",
"rules": [
{ "name": "VIP", "when": "customer.tier == 'VIP'", "then": { "set": { "discount": 0.25 } } },
{ "name": "Gold", "when": "customer.tier == 'GOLD'", "then": { "set": { "discount": 0.15 } } },
{ "name": "Standard", "when": "true", "then": { "set": { "discount": 0 } } }
],
"combine": "first"
}
}
]
}| Command | Description |
|---|---|
laran validate <spec> |
Validate spec against schema |
laran compile nest <spec> --out <dir> |
Compile to NestJS |
laran compile fastapi <spec> --out <dir> |
Compile to FastAPI |
laran replay <spec> --endpoint <name> |
Debug endpoint execution |
laran docs <spec> --out <dir> |
Generate documentation |
laran diff <old> <new> |
Semantic diff with SemVer |
laran test <spec> --out <dir> |
Generate contract tests |
laran plugins --list |
List available plugins |
See the docs/ folder for detailed documentation:
- AIL v2 Overview - Architecture and features
- Pipeline Operations - reduce, group, sort, join
- Rules Engine - Business logic with when/then
- Patterns - Built-in pattern library
- Modules - Import/export system
- Invariants - Data integrity constraints
- Debug Executor - Replay and debugging
laran-spec/
├── src/
│ ├── cli.ts # CLI entry point
│ ├── types.ts # Core AIL types
│ ├── targets/ # Code generators (NestJS, FastAPI, etc.)
│ ├── contracts/ # Contract parsing and validation
│ ├── debugger/ # Replay executor and mock DB
│ ├── patterns/ # Pattern library and loader
│ ├── modules/ # Module resolver and merger
│ ├── invariants/ # Invariant validation and codegen
│ ├── sourcemap/ # Source map generation
│ ├── errors/ # Error taxonomy and suggestions
│ ├── docgen/ # Documentation generator
│ ├── diff/ # Semantic diff
│ ├── plugins/ # Plugin system
│ └── dsl-*/ # Domain DSLs (bot, etl, ui)
├── schema/
│ └── ail-mini.schema.json # Official JSON Schema
├── docs/ # Documentation
└── examples/ # Example specifications
198 tests covering all features:
pnpm testPRs welcome! See the documentation for implementation details.
MIT