How mattschinkel/golemlang works
Golem is an AI-oriented programming language whose canonical program is a typed semantic graph, serialized as bracket-notation .gol text. The principal workflow is source input through parsing and semantic checking, then deterministic compilation and execution; agents can also query, edit, or repair programs structurally. Documented branches include partial programs, constrained generation, capability/effect checks, and machine-readable tooling. The README establishes these capabilities, while sampled source confirms parser, VM, and MCP behavior; links for unsampled subsystems are limited to documented roles.
Main entry points: tools.py MCP tools · checker.py Type checker · ast.py Semantic AST · machine.py Virtual machine
Components 26
Language Core
- Golem source
- Parser
src/golem/parser.py - Semantic AST
src/golem/ast.py - Canonical printer
src/golem/canonical.py - GBNF grammar
src/golem/grammar/gbnf.py
Analysis and Editing
- Type checker
src/golem/checker.py - Contracts and effects
src/golem/contracts.py - Units and dimensions
src/golem/units.py - Partial programs
src/golem/partial.py - Structured diagnostics
src/golem/diagnose.py - Repair candidates
src/golem/repairs.py - Graph edits
src/golem/edits.py
Execution Kernel
- Bytecode compiler
src/golem/vm/compiler.py - Bytecode chunks
src/golem/vm/chunk.py - Virtual machine
src/golem/vm/machine.py - Runtime values
src/golem/values.py - Language CLI
src/golem/bin.py
AI and Tooling
- AI constraints
src/golem/ai_ffi.py - MCP server
src/golem/mcp/server.py - MCP tools
src/golem/mcp/tools.py - Documentation retrieval
src/golem/kb.py - LLM output formatter
src/golem/llm_out.py
Other components
- Program author
- LLM agent
- External LLM
- Program result
Connections 31
- Program author → Golem source: writes
- LLM agent → Golem source: generates
- Golem source → Parser: parses
- Parser → Semantic AST: builds
- Semantic AST → Canonical printer: serializes
- GBNF grammar → LLM agent: constrains generation
- Semantic AST → Type checker: type checks
- Type checker → Contracts and effects: checks effects
- Type checker → Units and dimensions: checks dimensions
- Type checker → Partial programs: analyzes holes
- Type checker → Structured diagnostics: reports
- Structured diagnostics → Repair candidates: suggests fixes
- LLM agent → Graph edits: requests edits
- Graph edits → Semantic AST: transforms
- Semantic AST → Bytecode compiler: lowers
- Bytecode compiler → Bytecode chunks: emits bytecode
- Bytecode chunks → Virtual machine: executes
- Virtual machine → Runtime values: produces
- Language CLI → Parser: accepts source
- Language CLI → Virtual machine: runs programs
- MCP server → MCP tools: dispatches tools
- MCP tools → Parser: parses input
- MCP tools → Type checker: type checks
- MCP tools → Virtual machine: runs code
- MCP tools → AI constraints: constrains values
- MCP tools → Documentation retrieval: retrieves docs
- MCP tools → LLM output formatter: formats output
- External LLM → GBNF grammar: uses constraints
- Virtual machine → Program result: returns value
- Program author → MCP server: sends requests
- LLM agent → MCP server: calls tools