# mattschinkel/golemlang architecture

> Architecture diagram of the GitHub repository mattschinkel/golemlang, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mattschinkel/golemlang
- Repository: https://github.com/mattschinkel/golemlang

## Overview

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: [`src/golem/mcp/tools.py`](https://github.com/mattschinkel/golemlang/blob/master/src/golem/mcp/tools.py) (MCP tools), [`src/golem/checker.py`](https://github.com/mattschinkel/golemlang/blob/master/src/golem/checker.py) (Type checker), [`src/golem/ast.py`](https://github.com/mattschinkel/golemlang/blob/master/src/golem/ast.py) (Semantic AST), [`src/golem/vm/machine.py`](https://github.com/mattschinkel/golemlang/blob/master/src/golem/vm/machine.py) (Virtual machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Core"]
  node_source["Golem source"]
  node_parser["Parser<br/>[parser.py]"]
  node_ast["Semantic AST<br/>[ast.py]"]
  node_canonical["Canonical printer<br/>[canonical.py]"]
  node_grammar["GBNF grammar<br/>[gbnf.py]"]
end

subgraph group_analysis["Analysis and Editing"]
  node_checker["Type checker<br/>[checker.py]"]
  node_contracts["Contracts and effects<br/>[contracts.py]"]
  node_units["Units and dimensions<br/>[units.py]"]
  node_partial["Partial programs<br/>[partial.py]"]
  node_diagnostics["Structured diagnostics<br/>[diagnose.py]"]
  node_repairs["Repair candidates<br/>[repairs.py]"]
  node_edits["Graph edits<br/>[edits.py]"]
end

subgraph group_execution["Execution Kernel"]
  node_compiler["Bytecode compiler<br/>[compiler.py]"]
  node_chunk["Bytecode chunks<br/>[chunk.py]"]
  node_machine["Virtual machine<br/>[machine.py]"]
  node_values["Runtime values<br/>[values.py]"]
  node_cli["Language CLI<br/>[bin.py]"]
end

subgraph group_ai["AI and Tooling"]
  node_ffi["AI constraints<br/>[ai_ffi.py]"]
  node_mcpserver["MCP server<br/>[server.py]"]
  node_mcptools["MCP tools<br/>[tools.py]"]
  node_knowledge["Documentation retrieval<br/>[kb.py]"]
  node_llmformat["LLM output formatter<br/>[llm_out.py]"]
end

node_author(("Program author"))
node_agent(("LLM agent"))
node_llm(("External LLM"))
node_result["Program result"]

node_author -->|"writes"| node_source
node_agent -->|"generates"| node_source
node_source -->|"parses"| node_parser
node_parser -->|"builds"| node_ast
node_ast -->|"serializes"| node_canonical
node_grammar -.->|"constrains generation"| node_agent
node_ast -->|"type checks"| node_checker
node_checker -->|"checks effects"| node_contracts
node_checker -->|"checks dimensions"| node_units
node_checker -->|"analyzes holes"| node_partial
node_checker -->|"reports"| node_diagnostics
node_diagnostics -->|"suggests fixes"| node_repairs
node_agent -->|"requests edits"| node_edits
node_edits -->|"transforms"| node_ast
node_ast -->|"lowers"| node_compiler
node_compiler -->|"emits bytecode"| node_chunk
node_chunk -->|"executes"| node_machine
node_machine -->|"produces"| node_values
node_cli -->|"accepts source"| node_parser
node_cli -->|"runs programs"| node_machine
node_mcpserver -->|"dispatches tools"| node_mcptools
node_mcptools -->|"parses input"| node_parser
node_mcptools -->|"type checks"| node_checker
node_mcptools -->|"runs code"| node_machine
node_mcptools -->|"constrains values"| node_ffi
node_mcptools -->|"retrieves docs"| node_knowledge
node_mcptools -->|"formats output"| node_llmformat
node_llm -.->|"uses constraints"| node_grammar
node_machine -->|"returns value"| node_result
node_author -->|"sends requests"| node_mcpserver
node_agent -->|"calls tools"| node_mcpserver

click node_parser "https://github.com/mattschinkel/golemlang/blob/master/src/golem/parser.py"
click node_ast "https://github.com/mattschinkel/golemlang/blob/master/src/golem/ast.py"
click node_canonical "https://github.com/mattschinkel/golemlang/blob/master/src/golem/canonical.py"
click node_grammar "https://github.com/mattschinkel/golemlang/blob/master/src/golem/grammar/gbnf.py"
click node_checker "https://github.com/mattschinkel/golemlang/blob/master/src/golem/checker.py"
click node_contracts "https://github.com/mattschinkel/golemlang/blob/master/src/golem/contracts.py"
click node_units "https://github.com/mattschinkel/golemlang/blob/master/src/golem/units.py"
click node_partial "https://github.com/mattschinkel/golemlang/blob/master/src/golem/partial.py"
click node_diagnostics "https://github.com/mattschinkel/golemlang/blob/master/src/golem/diagnose.py"
click node_repairs "https://github.com/mattschinkel/golemlang/blob/master/src/golem/repairs.py"
click node_edits "https://github.com/mattschinkel/golemlang/blob/master/src/golem/edits.py"
click node_compiler "https://github.com/mattschinkel/golemlang/blob/master/src/golem/vm/compiler.py"
click node_chunk "https://github.com/mattschinkel/golemlang/blob/master/src/golem/vm/chunk.py"
click node_machine "https://github.com/mattschinkel/golemlang/blob/master/src/golem/vm/machine.py"
click node_values "https://github.com/mattschinkel/golemlang/blob/master/src/golem/values.py"
click node_cli "https://github.com/mattschinkel/golemlang/blob/master/src/golem/bin.py"
click node_ffi "https://github.com/mattschinkel/golemlang/blob/master/src/golem/ai_ffi.py"
click node_mcpserver "https://github.com/mattschinkel/golemlang/blob/master/src/golem/mcp/server.py"
click node_mcptools "https://github.com/mattschinkel/golemlang/blob/master/src/golem/mcp/tools.py"
click node_knowledge "https://github.com/mattschinkel/golemlang/blob/master/src/golem/kb.py"
click node_llmformat "https://github.com/mattschinkel/golemlang/blob/master/src/golem/llm_out.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_source,node_parser,node_ast,node_canonical,node_grammar toneBlue
class node_checker,node_contracts,node_units,node_partial,node_diagnostics,node_repairs,node_edits toneAmber
class node_compiler,node_chunk,node_machine,node_values,node_cli toneMint
class node_ffi,node_mcpserver,node_mcptools,node_knowledge,node_llmformat toneRose
class node_author,node_agent,node_llm,node_result toneIndigo
```

## Components

### Language Core

- **Golem source**
- [Parser](https://github.com/mattschinkel/golemlang/blob/master/src/golem/parser.py): `src/golem/parser.py`
- [Semantic AST](https://github.com/mattschinkel/golemlang/blob/master/src/golem/ast.py): `src/golem/ast.py`
- [Canonical printer](https://github.com/mattschinkel/golemlang/blob/master/src/golem/canonical.py): `src/golem/canonical.py`
- [GBNF grammar](https://github.com/mattschinkel/golemlang/blob/master/src/golem/grammar/gbnf.py): `src/golem/grammar/gbnf.py`

### Analysis and Editing

- [Type checker](https://github.com/mattschinkel/golemlang/blob/master/src/golem/checker.py): `src/golem/checker.py`
- [Contracts and effects](https://github.com/mattschinkel/golemlang/blob/master/src/golem/contracts.py): `src/golem/contracts.py`
- [Units and dimensions](https://github.com/mattschinkel/golemlang/blob/master/src/golem/units.py): `src/golem/units.py`
- [Partial programs](https://github.com/mattschinkel/golemlang/blob/master/src/golem/partial.py): `src/golem/partial.py`
- [Structured diagnostics](https://github.com/mattschinkel/golemlang/blob/master/src/golem/diagnose.py): `src/golem/diagnose.py`
- [Repair candidates](https://github.com/mattschinkel/golemlang/blob/master/src/golem/repairs.py): `src/golem/repairs.py`
- [Graph edits](https://github.com/mattschinkel/golemlang/blob/master/src/golem/edits.py): `src/golem/edits.py`

### Execution Kernel

- [Bytecode compiler](https://github.com/mattschinkel/golemlang/blob/master/src/golem/vm/compiler.py): `src/golem/vm/compiler.py`
- [Bytecode chunks](https://github.com/mattschinkel/golemlang/blob/master/src/golem/vm/chunk.py): `src/golem/vm/chunk.py`
- [Virtual machine](https://github.com/mattschinkel/golemlang/blob/master/src/golem/vm/machine.py): `src/golem/vm/machine.py`
- [Runtime values](https://github.com/mattschinkel/golemlang/blob/master/src/golem/values.py): `src/golem/values.py`
- [Language CLI](https://github.com/mattschinkel/golemlang/blob/master/src/golem/bin.py): `src/golem/bin.py`

### AI and Tooling

- [AI constraints](https://github.com/mattschinkel/golemlang/blob/master/src/golem/ai_ffi.py): `src/golem/ai_ffi.py`
- [MCP server](https://github.com/mattschinkel/golemlang/blob/master/src/golem/mcp/server.py): `src/golem/mcp/server.py`
- [MCP tools](https://github.com/mattschinkel/golemlang/blob/master/src/golem/mcp/tools.py): `src/golem/mcp/tools.py`
- [Documentation retrieval](https://github.com/mattschinkel/golemlang/blob/master/src/golem/kb.py): `src/golem/kb.py`
- [LLM output formatter](https://github.com/mattschinkel/golemlang/blob/master/src/golem/llm_out.py): `src/golem/llm_out.py`

### Other components

- **Program author**
- **LLM agent**
- **External LLM**
- **Program result**

## Connections

- 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