{"id":45014495,"url":"https://github.com/alliecatowo/lumen","last_synced_at":"2026-02-20T01:00:36.446Z","repository":{"id":338174267,"uuid":"1156831489","full_name":"alliecatowo/lumen","owner":"alliecatowo","description":"Lumen - A markdown-native, statically typed programming language for AI-native systems. Build deterministic agent workflows with first-class AI primitives.","archived":false,"fork":false,"pushed_at":"2026-02-18T20:14:04.000Z","size":20911,"stargazers_count":0,"open_issues_count":11,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-19T04:39:54.875Z","etag":null,"topics":["agent","ai","anthropic","chatgpt","compiler","interpreter","language-design","llm","markdown","openai","programming-language","rust","static-typing","type-system","virtual-machine","wasm","webassembly"],"latest_commit_sha":null,"homepage":"https://alliecatowo.github.io/lumen/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alliecatowo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T05:16:16.000Z","updated_at":"2026-02-18T05:06:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alliecatowo/lumen","commit_stats":null,"previous_names":["alliecatowo/lumen"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alliecatowo/lumen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alliecatowo%2Flumen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alliecatowo%2Flumen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alliecatowo%2Flumen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alliecatowo%2Flumen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alliecatowo","download_url":"https://codeload.github.com/alliecatowo/lumen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alliecatowo%2Flumen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29637914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","anthropic","chatgpt","compiler","interpreter","language-design","llm","markdown","openai","programming-language","rust","static-typing","type-system","virtual-machine","wasm","webassembly"],"created_at":"2026-02-19T00:37:52.940Z","updated_at":"2026-02-20T01:00:36.426Z","avatar_url":"https://github.com/alliecatowo.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/public/logo.svg\" alt=\"Lumen Logo\" width=\"180\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eLumen\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe AI-Native Programming Language\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eBuild deterministic agent workflows with static types, first-class AI primitives, and markdown-native source files.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://alliecatowo.github.io/lumen/\"\u003e\u003cstrong\u003e📚 Documentation\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"https://alliecatowo.github.io/lumen/playground\"\u003e\u003cstrong\u003e🎮 Playground\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/alliecatowo/lumen/issues\"\u003e\u003cstrong\u003e🐛 Issues\u003c/strong\u003e\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/alliecatowo/lumen/discussions\"\u003e\u003cstrong\u003e💬 Discussions\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/alliecatowo/lumen/ci.yml?branch=main\u0026label=CI\u0026style=flat-square\" alt=\"CI Status\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/alliecatowo/lumen/pages.yml?branch=main\u0026label=Docs\u0026style=flat-square\" alt=\"Docs Status\" /\u003e\n  \u003ca href=\"https://open-vsx.org/extension/alliecatowo/lumen-lang\"\u003e\u003cimg src=\"https://img.shields.io/open-vsx/v/alliecatowo/lumen-lang?style=flat-square\u0026label=Open%20VSX\" alt=\"Open VSX\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/crates/v/lumen-lang?style=flat-square\" alt=\"Crates.io\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/alliecatowo/lumen?style=flat-square\" alt=\"License\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/alliecatowo/lumen?style=flat-square\" alt=\"Stars\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Why Lumen?\n\nBuilding AI systems today means juggling Python notebooks, API clients, prompt templates, and orchestration frameworks. **Lumen unifies this into one language:**\n\n| Feature | Lumen | Traditional Stack |\n|---------|-------|-------------------|\n| **Tools** | Typed interfaces with policy constraints | Framework wrappers |\n| **Grants** | Built-in safety limits (tokens, timeouts, domains) | Manual validation |\n| **Agents** | First-class language construct | Class hierarchies |\n| **Processes** | Pipelines, state machines, memory built-in | External libraries |\n| **Effects** | Algebraic effects with handlers, explicit in type signatures | Try/catch or monads, implicit |\n| **Source** | Markdown-native (`.lm.md`, `.lumen`) + raw (`.lm`) | Separate code and docs |\n\n## Quick Start\n\n```bash\n# Install (One-liner)\ncurl -fsSL https://raw.githubusercontent.com/alliecatowo/lumen/main/scripts/install.sh | sh\n\n# Or via Cargo\ncargo install lumen-lang\n\n# Create your first program\ncat \u003e hello.lm.md \u003c\u003c 'EOF'\ncell main() -\u003e String\n  return \"Hello, World!\"\nend\nEOF\n\n# Run it\nlumen run hello.lm.md\n```\n\n## Features\n\n- **Algebraic Effects**: First-class effect handling with `perform` and `handle` constructs\n- **Markdown-Native Source**: Write code and docs together in `.lm.md` or `.lumen` files\n- **Static Typing**: Full type inference with compile-time error checking\n- **AI Tool Dispatch**: Typed tool interfaces with policy constraints\n- **Register-Based VM**: Efficient bytecode execution\n- **Full LSP Support**: Hover, document symbols, signature help, semantic tokens, diagnostics\n\n### 📝 Markdown-Native Source\n\nWrite code and documentation together in `.lm.md` or `.lumen`, or use `.lm` for source-only modules:\n\n````markdown\n# User Authentication\n\nThis module handles user login and session management.\n\n```lumen\nrecord User\n  id: String\n  name: String\n  email: String where email.contains(\"@\")\nend\n\ncell authenticate(email: String, password: String) -\u003e result[User, String]\n  # Implementation here\nend\n```\n````\n\n### 🔒 Statically Typed\n\nCatch errors at compile time:\n\n```lumen\ncell divide(a: Int, b: Int) -\u003e result[Int, String]\n  if b == 0\n    return err(\"Division by zero\")\n  end\n  return ok(a / b)\nend\n```\n\n### 🎯 Algebraic Effects\n\nFirst-class effect handling with one-shot delimited continuations:\n\n```lumen\neffect Log\n  cell info(msg: String) -\u003e Unit\nend\n\ncell main() -\u003e String / {Log}\n  perform Log.info(\"Starting\")\n  return \"Done\"\nend\n\nhandle main() with Log.info(msg) -\u003e resume(unit)\n  print(\"LOG: {msg}\")\nend\n```\n\n### 🤖 AI-Native Constructs\n\nTools, grants, and agents are built-in:\n\n```lumen\nuse tool llm.chat as Chat\n\ngrant Chat\n  model \"gpt-4o\"\n  max_tokens 1024\n  temperature 0.7\n\nagent Assistant\n  cell respond(message: String) -\u003e String / {llm}\n    role system: You are a helpful assistant.\n    role user: {message}\n    return Chat(prompt: message)\n  end\nend\n```\n\n### ⚡ Deterministic Runtime\n\nReproducible execution for auditable AI:\n\n```lumen\n@deterministic true\n\ncell main() -\u003e String\n  # Nondeterministic operations rejected at compile time\n  # uuid()      # Error!\n  # timestamp() # Error!\n  return \"Deterministic output\"\nend\n```\n\n### 🌐 WASM Ready\n\nCompile to WebAssembly for browser execution:\n\n```bash\nlumen build wasm --target web\n```\n\n## Documentation\n\n| Resource | Description |\n|----------|-------------|\n| [Getting Started](https://alliecatowo.github.io/lumen/learn/getting-started) | Installation and first program |\n| [Tutorial](https://alliecatowo.github.io/lumen/learn/tutorial/basics) | Step-by-step language guide |\n| [AI-Native Features](https://alliecatowo.github.io/lumen/learn/ai-native/tools) | Tools, grants, agents, processes |\n| [Language Reference](https://alliecatowo.github.io/lumen/reference/overview) | Complete specification |\n| [API Reference](https://alliecatowo.github.io/lumen/api/builtins) | Standard library |\n| [Playground](https://alliecatowo.github.io/lumen/playground) | Try Lumen in your browser |\n\n## Examples\n\n| Example | Description |\n|---------|-------------|\n| [Hello World](examples/hello.lm.md) | Basic program |\n| [AI Chat](examples/ai_chat.lm.md) | LLM-powered chatbot |\n| [State Machine](examples/state_machine.lm.md) | Machine process |\n| [Data Pipeline](examples/data_pipeline.lm.md) | Pipeline process |\n| [Code Reviewer](examples/code_reviewer.lm.md) | AI code analysis |\n| [Syntax Sugar](examples/syntax_sugar.lm.md) | Pipes, ranges, interpolation |\n| [Fibonacci](examples/fibonacci.lm.md) | Recursive algorithms |\n| [Linked List](examples/linked_list.lm.md) | Generic data structures |\n\nSee all [30 examples](https://github.com/alliecatowo/lumen/tree/main/examples) in the examples directory.\n\n## Language Tour\n\n### Cells (Functions)\n\n```lumen\ncell greet(name: String) -\u003e String\n  return \"Hello, {name}!\"\nend\n```\n\n### Records with Constraints\n\n```lumen\nrecord Product\n  name: String where length(name) \u003e 0\n  price: Float where price \u003e= 0.0\nend\n```\n\n### Pattern Matching\n\n```lumen\ncell classify(n: Int) -\u003e String\n  match n\n    0 -\u003e return \"zero\"\n    1 -\u003e return \"one\"\n    _ -\u003e return \"many\"\n  end\nend\n```\n\n### Error Handling\n\n```lumen\ncell safe_divide(a: Int, b: Int) -\u003e String\n  match divide(a, b)\n    ok(value) -\u003e return \"Result: {value}\"\n    err(msg) -\u003e return \"Error: {msg}\"\n  end\nend\n```\n\n### Processes\n\n```lumen\npipeline DataProcessor\n  stages:\n    -\u003e extract\n    -\u003e transform\n    -\u003e load\n  \n  cell extract(source: String) -\u003e list[Json]\n    # Extract data\n  end\n  \n  cell transform(data: list[Json]) -\u003e list[Record]\n    # Transform data\n  end\n  \n  cell load(records: list[Record]) -\u003e Int\n    # Load data\n  end\nend\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│            .lm.md / .lm / .lumen Source Files                 │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n                          ▼\n┌─────────────────────────────────────────────────────────────┐\n│  Markdown Extraction (.lm.md/.lumen) / Direct Parse (.lm)    │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n                          ▼\n┌─────────────────────────────────────────────────────────────┐\n│  Lexer → Parser → Resolver → Typechecker → Constraint Val   │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n                          ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    LIR Bytecode                              │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n                          ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    Register VM                               │\n│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │\n│  │  Values  │ │ Futures  │ │  Tools   │ │ Traces   │       │\n│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Development\n\n```bash\n# Clone\ngit clone https://github.com/alliecatowo/lumen.git\ncd lumen\n\n# Build\ncargo build --release\n\n# Test (1365+ tests)\ncargo test --workspace\n\n# Run\ncargo run --bin lumen -- run examples/hello.lm.md\n```\n\n## Repository Structure\n\n```\nlumen/\n├── docs/                    # VitePress documentation site\n│   ├── learn/              # Tutorials and guides\n│   ├── reference/          # Language specification\n│   ├── api/                # Standard library docs\n│   └── examples/           # Example documentation\n├── examples/               # Example programs\n├── editors/               # Editor support (VS Code)\n├── rust/\n│   ├── lumen-compiler/    # Compiler pipeline\n│   ├── lumen-vm/          # Register-based virtual machine\n│   ├── lumen-runtime/     # Runtime: tool dispatch, caching, tracing\n│   ├── lumen-cli/         # Command-line interface\n│   ├── lumen-lsp/         # Language Server Protocol\n│   ├── lumen-wasm/        # WebAssembly bindings\n│   └── lumen-provider-*/  # Tool providers (HTTP, JSON, FS, MCP)\n├── SPEC.md                # Implementation-accurate spec\n└── CLAUDE.md              # AI assistant instructions\n```\n\n## Contributing\n\nWe welcome contributions! Please see:\n\n- [Contributing Guide](https://github.com/alliecatowo/lumen/blob/main/CONTRIBUTING.md)\n- [Code of Conduct](https://github.com/alliecatowo/lumen/blob/main/CODE_OF_CONDUCT.md)\n- [Good First Issues](https://github.com/alliecatowo/lumen/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)\n\n## License\n\nMIT License - see [LICENSE](https://github.com/alliecatowo/lumen/blob/main/LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by the Lumen community\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falliecatowo%2Flumen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falliecatowo%2Flumen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falliecatowo%2Flumen/lists"}