KIR

A building is a program.
Write buildings in Python. KIR type-checks them and compiles them to Revit C# — offline, for six Revit versions at once.

Build one now · Be wrong on purpose · Design verdict · What you get · MCP server · Why · How it works · Measured numbers · Contribute

---

Build a building in 60 seconds

pip install kir-building

Four direct dependencies, fifteen packages in a clean venv, no sudo. Nothing on this page needs Revit, a licence, a running service or a network — Python 3.12 or newer is the whole requirement.

Save this as room.py:

from kir import compile_program
from kir.dsl import envelope, create_level, create_wall, build

envelope(intent="a room, 6 x 4 m")
level = create_level(elev_mm=0, name="Level 1")
corners = [(0, 0), (6000, 0), (6000, 4000), (0, 4000)]
for a, b in zip(corners, corners[1:] + corners[:1]):
    create_wall(p0_mm=a, p1_mm=b, level=level, height_mm=3000)

program = build()
out = compile_program(program, revit_version="2026", snapshot=None, bulk=True)
print(out.ok, "|", len(out.csharp), "characters of Revit C#")

versions = ["2021", "2022", "2023", "2024", "2025", "2026"]
ok = sum(compile_program(program, revit_version=v, snapshot=None, bulk=True).ok
         for v in versions)
print(f"compiled for {ok} of {len(versions)} Revit versions")

$ python room.py
True | 20252 characters of Revit C#
compiled for 6 of 6 Revit versions

That is nine lines of building. out.csharp is finished Revit add-in code: transactions opened and closed, millimetres converted to feet, API members chosen for that exact Revit release, and every element read back after creation to check it is what you asked for. You did not write any of that, and you cannot get it wrong.

Note what you also did not write. create_level returned a handle, and passing it as level= is the whole of reference management — the language filled in {"by": "ref", "value": "level1"}, the element ids, and the operation ids itself. There is no xyz on a door, no feet anywhere, and no way to say "a window floating in the air": that is not a case KIR validates, it is a sentence the language cannot form.

(Run verbatim on 2026-09-04 against kir-building 0.5.0 installed from PyPI into a python3.12 -m venv created from scratch. The character count includes your intent string, so it moves if you change the text.)

Or one command

The repository ships a kir command that does all of the above and more in one line — it prints the source of a small house, builds it, compiles it for six Revit versions, lists the defaults the compiler chose for you, and judges whether a person could live in it:

git clone https://github.com/5vbkgsghhh-hash/kir && cd kir
pip install .
kir demo

KIR: ЗДАНИЕ — ЭТО ПРОГРАММА. Вот весь исходник этого дома:
    ...
ВЫШЛО 7 операций — слоты, которых ты не назвал, язык заполнил САМ:
   0  create_level   id «level1»
   1  create_floor   id «floor1», level {"by": "ref", "value": "level1"}
   2  create_wall    id «wall1», level {"by": "ref", "value": "level1"}
   ...
КОМПИЛЯЦИЯ, 6/6 версий Revit, без Revit и без сети:
  2021     31506 знаков C#
  2022     31597 знаков C#
  ...
КВИТАНЦИЯ НАЗВАННОГО УМОЛЧАНИЯ, записей 5: выборы, которые сделал КОМПИЛЯТОР, а не автор.
  floor1.type — правило «doc_default»: решит revit, прочтётся обратно из result.floor1.type_name
  ...
═══ ВЕРДИКТ О ЗАМЫСЛЕ: НЕПРИГОДЕН ═══
  HAB030: Помещение 'Гостиная' (жилая) не имеет наружного окна — жить/готовить без
          естественного света нельзя.

(Excerpted from 68 lines of output, run 2026-09-04 from a clone installed into a fresh venv. kir ops, kir skill, kir course, kir doctor and kir build FILE.json are the rest of the surface. The kir command is newer than the current PyPI release (0.5.0) — from pip install kir-building today you get the library, and the room.py above; the command arrives with the next release.)

Two more one-liners, offline, and true of the published package today:

python -c "from kir import spec, sdk; print(len(spec.OPS), len(sdk.builders()))"
python -c "from kir.course import course; course()"

The first prints 82 82 — 82 operations in the registry, and one generated Python builder per operation, so a signature cannot drift from the spec. The second prints the sixteen lessons of the authoring course that ships inside the package.

Language, named rather than glossed. KIR's refusals, the shipped examples and the authoring course an LLM reads are written in Russian today; diagnostic codes (KIR-G101, HAB030), operation names and the whole Python API are language-neutral. English text is not shipped yet.

Be wrong on purpose

The point of a typed IR is what happens when you are wrong. Add a door to room.py:

from kir import compile_program
from kir.dsl import envelope, create_level, create_wall, create_door, build

envelope(intent="a room with a door")
level = create_level(elev_mm=0, name="Level 1")
corners = [(0, 0), (6000, 0), (6000, 4000), (0, 4000)]
walls = [create_wall(p0_mm=a, p1_mm=b, level=level, height_mm=3000)
         for a, b in zip(corners, corners[1:] + corners[:1])]
create_door(host=walls[0], offset_mm=3000, symbol="0915 x 2134mm")

program = build()
out = compile_program(program, revit_version="2026", snapshot=None, bulk=True)
print("ok:", out.ok)
for d in out.diagnostics:
    print(d.code, "|", d.message_ru.splitlines()[0])

ok: False
KIR-G103 | программа требует снапшот модели (census) для ground-стадии (резолв по имени/
default). Снимка требуют: create_door#door1.symbol. Без снимка эти слоты адресуются
только формой {"by": "element_id", "value": <id>}

A wall is geometry, so KIR can build it from numbers alone. A door is a family symbol that must already exist in the document, and offline there is no document to ask. So the compiler stops before emitting anything and names the exact slot — create_door#door1.symbol. Hand it the one catalogue it needs and the same program compiles:

snapshot = {"door_symbols": [{"id": 700, "name": "0915 x 2134mm"}]}
out = compile_program(program, revit_version="2026", snapshot=snapshot, bulk=True)
print("ok:", out.ok, "|", len(out.csharp), "characters of Revit C#")

ok: True | 23031 characters of Revit C#

Now misspell the symbol — symbol="Big Door" — and keep the same snapshot:

ok: False
KIR-G101 | door_symbols: «Big Door» не найден
candidates: [{'id': 700, 'name': '0915 x 2134mm'}]

Nothing was emitted, nothing was half-built, and the refusal names the pool it looked in and what is in that pool. This is the single rule the project is built on: a call ends in exactly one of two typed outcomes — an ok carrying a read-back proof, or a machine-readable refused with candidates and a route. A silently-wrong answer is the forbidden state.

Can a person live in it? Ask before Revit

KIR also judges the building, not just the syntax — habitability rules run over the numbers your program already contains. Save this as verdict.py:

from kir.course import design_check
from kir.dsl import envelope, create_level, create_wall, create_room, build

envelope(intent="is this a place a person can live?")
level = create_level(elev_mm=0, name="Level 1")
corners = [(0, 0), (6000, 0), (6000, 4000), (0, 4000)]
for a, b in zip(corners, corners[1:] + corners[:1]):
    create_wall(p0_mm=a, p1_mm=b, level=level, height_mm=2400)
create_room(xy=(3000, 2000), level=level, name="Living room", function="жилая")

design_check(build()["ops"])

$ python verdict.py
═══ ВЕРДИКТ О ЗАМЫСЛЕ: НЕПРИГОДЕН ═══
источник: САМОПРОВЕРКА — судится ЗАЯВЛЕННОЕ программой, а не построенное
прочитано: doors 0, levels 1, rooms 1, stairs 0, walls 4, windows 0
полигон помещения получили 1 из 1 (100%), высота известна у 0
БЛОКИРУЮЩИЕ 1: HAB030×1
  HAB030: Помещение 'Living room' (жилая) не имеет наружного окна — жить/готовить без
          естественного света нельзя.
НЕ ОЦЕНЕНО правил 13 из 20: HAB061, HAB001, HAB002, HAB003, HAB004, HAB010, HAB011,
                            HAB012, HAB022, HAB031, HAB041, HAB042, HAB050

Unfit: a living room with no exterior window. No Revit was involved. And look at the last line — the verdict names the thirteen rules it could not evaluate and why (no stairs in the program, no known ceiling height), instead of reporting a clean pass it never measured. Coverage you did not have is never rendered as a zero.

What you actually get

A building fits in a context window	The 60-storey tower below is 3 394 685 characters as emitted Revit C# and 13 210 characters as the KIR program a model edits — 257× less, roughly 1M tokens against 4k. That is the difference between a model that can re-plan a floor and one that cannot read the building it was asked to change.
One program, six Revit versions	The same intent compiles differently against Revit 2021 and 2026. You write it once; version choice is the compiler's job, and the six-version compile runs offline before any Revit is opened.
Refusals instead of broken models	Every operation carries declared post-conditions that are read back off the live element after it is created. A violated post-condition rolls the transaction back and returns a typed refusal — never an ok wrapping an error.
Retries are safe	Operation ids are stamped into the model inside the same transaction, so re-running a program skips what is already stamped. Resume-from-op-K is simply "skip what carries a stamp".
It reads buildings too	The reverse pipeline lifts an existing model back into a typed program, and anything it cannot express becomes a typed atom with a reason code, never a silent drop. That is what turns "we can build" into "we can edit what already exists".
82 operations, not 35 516 API members	Walls, floors, roofs, stairs, railings, curtain systems, ducts, pipes, rebar, rooms, tags, families, booleans, sweeps — a closed registry with kinds, bounds and tolerances, replacing an encyclopaedic API a human learns over years.

Writing into a live model additionally needs a Revit 2021–2026 installation, its API reference assemblies, the .NET Roslyn compile service and a separately running bridge — none of which are part of this repository. Everything above runs without them.

Hand it to a model: the MCP server

KIR ships an MCP server, so Claude Desktop, Claude Code or any MCP host can author, compile and inspect buildings through it. The server needs the mcp extra — without it python -m kir.mcp dies with a bare ModuleNotFoundError: No module named 'mcp', so install it explicitly:

pip install "kir-building[mcp]"
python -m kir.mcp            # stdio; --http --port 8765 for Streamable HTTP

INFO kir.mcp: поверхность: kir_author, kir_spec, kir_compile, kir_rehearse, kir_open, kir_write, kir_preview

The extra costs 20 packages on top of the core fifteen. kir.mcp is not in the import kir chain, so installing without it changes nothing else.

tool	what it does	needs Revit
kir_author	Python that builds the program, run in a sandbox; returns typed IR ops	no
kir_spec	the registry contract for one op — call form, slots, bounds, witness tolerances	no
kir_compile	C# for every supported Revit version, inline or as files	no
kir_rehearse	which obligations will not be checked — before a single round-trip	no
kir_preview	a floor plan as deterministic SVG, plus a census of what is not on it	no
kir_open	ask the host which document is open and take a handle to it	yes
kir_write	write a program into that open document — the only door that changes anything	yes

Five of the seven are fully offline: nothing is sent anywhere, every reply carries wrote_nothing: true, and no model is touched. The two live doors are named separately on purpose, and kir_write asks a human before it commits.

kir_preview also carries an MCP Apps UI (ui://kir/floorplan.html): hosts that negotiated the extension render the plan inline, with zoom, per-level sheets and the census panel. Hosts that did not get the same SVG and census as data — the extension adds handling, never content.

The author sandbox runs the script in a separate process with no reachable network (its own namespace, probed on every run), an empty root, no writable filesystem and an import allow-list; its only exit is the list of IR ops, which the compiler then type-checks in full.

To register the server with an MCP host, point it at the interpreter of the venv you installed into, by absolute path. A bare python may not be on PATH at all, and where it is it may be older than this package's floor — stock Ubuntu 22.04 ships Python 3.10:

// stdio server entry
{ "command": "/path/to/venv/bin/python", "args": ["-m", "kir.mcp"] }

(Verified 2026-09-04 against kir-building 0.5.0 from PyPI in a fresh venv: the stdio door completed the MCP handshake at protocol revision 2025-11-25, listed the seven tools above, and kir_author returned a four-wall program with wrote_nothing. --http --port 8797 answered 200 on POST /mcp. The client entry above is configuration, not a command, and was not executed here.)

Why this exists

Language models write code well. They do not write buildings well, and the reason is structural rather than a matter of training scale. A building does not fit in a context window — one of the models we measure against holds 90 758 elements. The work is stateful: a wall must exist before a door can be hosted in it, and that state lives inside an application, not in a file you can diff. It is re-entrant, because the same instruction issued twice must not produce two doors. And it is versioned six ways: the same intent compiles differently against Revit 2021 and Revit 2026.

So the practice today is to have the model write Revit C# directly, and the arithmetic of that practice is available to us. Across 85 374 production compile errors logged over seven weeks, two codes account for 48.4% — CS1061 (32.3%) and CS0117 (16.1%) — and both are the same failure: a member of the Revit API that does not exist. Another ~10% (CS0104/CS0012) are namespace and assembly-reference problems. Roughly 60% of all production compile errors are spent fighting the surface of an API, not describing a building.

KIR is an attempt to fix that: the model concentrates on 3D, geometry and composition; units, transactions, API versions, hosts, witnesses and rollbacks belong to a compiler.

_{The same building, held two ways: as emitted C# no model can read, and as the typed program a model actually edits. The render is a visual companion, not the measurement.}

Python computes the form, KIR proves it

The division of labour is the whole design. Python owns loops, numpy, shapely, parameter search and reusable functions; KIR owns units, versions, transactions and the proof. Clone the repository — the examples are not part of the installed package — and run either demonstration offline:

git clone https://github.com/5vbkgsghhh-hash/kir && cd kir
pip install .
python examples/tower_numpy.py

100 строк питона → 6 опов написано → 840 после экспансии → 780 элементов (программ KIR: 3)
этажей 60, талия 30%, закрутка 120°
ломаная против синуса: 217 мм по радиусу
компиляция: 6/6 версий ['2021', '2022', '2023', '2024', '2025', '2026']

100 lines of Python become the 60-storey tower from examples/tower_numpy.py — 6 authored operations, 840 after expansion, 780 elements, compiled for all six Revit versions. That third line is the house style: stack.transform interpolates linearly while the script asked for a sine, so the example prints piecewise vs. true sine: 217 mm along the radius instead of pretending there is none. An approximation you did not name is a silently wrong answer.

examples/contour_shapely.py does the mirror case: shapely computes an offset ribbon (176 vertices simplified to 18 within a 220 mm tolerance) and KIR places the slab and walls the perimeter. Both ship with their measured outputs in examples/.

Show me the program itself

A KIR program is data, not code. build() returns exactly this, and you can write it by hand:

{
  "ir_version": "1.0",
  "intent": "one bay: wall + door + window",
  "ops": [
    {"op": "create_wall", "id": "wall1",
     "p0_mm": [0, 0], "p1_mm": [6000, 0],
     "level": {"by": "name", "value": "Level 1"}, "height_mm": 3300},
    {"op": "create_door", "id": "door1",
     "host": {"by": "ref", "value": "wall1"},
     "offset_mm": 1200, "sill_mm": -100,
     "symbol": {"by": "name", "value": "0915 x 2134mm"},
     "mirrored": false, "hand_flipped": false, "facing_flipped": false}
  ]
}

Hand that dict straight to kir.compile_program(program, revit_version="2026", snapshot=...). Everything above it is a front end over exactly this JSON, and no front end can express anything the registry lacks or hide a refusal.

Two front ends

kir.dsl — used everywhere on this page — accumulates implicitly: a call places its operation in the current program and hands back a handle. kir.sdk is the explicit form, where a call returns a dict you pass to p.add(...); it adds macros such as stack, which is what the tower example needs. Both are generated from the registry at import time, one builder per op, so neither can drift from the spec:

import numpy as np
from kir import sdk

p = sdk.program(intent="tower with a waist")
with p.stack(levels=20, h_mm=3600,
             transform=sdk.transform(scale_xy_top=[0.8, 0.8],
                                     twist_deg_total=24)) as floor:
    for a in np.linspace(0, 2 * np.pi, 12, endpoint=False):
        floor.add(sdk.create_column(xy=[20000 * np.cos(a), 20000 * np.sin(a)],
                                    level=sdk.BY_MACRO, symbol="К 300x300"))

p.stats()   # {'ops_written': 1, 'ops_expanded': 260, 'elements': 240}

snap = {"column_symbols_structural": [{"id": 6011, "name": "К 300x300"}]}
out = p.compile(version="2023", snapshot=snap)
out.ok, len(out.csharp)   # (True, 935314)

One authored op becomes 260 and 240 elements. Get the symbol name wrong and the refusal names the pool it searched — KIR-G101 column_symbols_structural: «К 300x300» не найден — rather than failing somewhere later.

How it works

flowchart TB
    subgraph FWD["FORWARD — intent becomes a building"]
        direction LR
        SDK["Python front end<br/>kir.dsl · kir.sdk · numpy · shapely"]
        PROG["Typed program<br/>KIR JSON, ops + refs"]
        REG["Registry<br/>one source of truth:<br/>schema · grammar · docs · emitters"]
        GRND["ground<br/>symbolic selectors to ElementIds"]
        PLAN["typecheck + plan<br/>mm only · DAG · txn partitions"]
        EMIT["emit<br/>per-version C#"]
        GATE["Roslyn gate<br/>2021–2026"]
        RUN["live Revit<br/>one TransactionGroup"]
        SDK --> PROG --> REG --> GRND --> PLAN --> EMIT --> GATE --> RUN
    end

    RUN --> WIT["witness<br/>read the RESULT back, not the call"]
    WIT --> OUT{"exactly two<br/>typed outcomes"}
    OUT -->|ok| OKN["geometry_ok · semantic_ok · topology_ok"]
    OUT -->|refused| REFN["diagnostics + candidates + route<br/>KIR-G/T/L/E/C/X/W codes"]
    REFN -.->|"IR-level repair, max 3 rounds"| PROG

    subgraph REV["REVERSE — a building becomes a program"]
        direction LR
        DOC["live model"]
        L0["extract to L0<br/>48 categories · full-model census"]
        L1["lift to typed ops<br/>or a typed ATOM with a reason"]
        FOLD["fold to canon<br/>template-canon/4 · fidelity-canon/1"]
        MAT["materialize<br/>chunked programs, host-atomic"]
        DOC --> L0 --> L1 --> FOLD --> MAT
    end

    RUN -.-> DOC
    MAT -.->|"rebuild · edit · diff"| PROG

A stage-by-stage account of both pipelines lives in the language contracts under kir/specs/ (SPEC_V1.md, the decompile spec) and the design specs under docs/laws/. Shorter orientation: docs/KIR.md, docs/RUNTIME.md, docs/BUILDING_GRAPH.md, docs/CLASH.md.

What happens to one op

sequenceDiagram
    autonumber
    participant M as Model — the LLM
    participant K as KIR compiler
    participant R as Revit — live document

    M->>K: create_wall — p0, p1, level by name, height 3300 mm
    K->>K: parse · typecheck · mm to feet · plan the DAG
    K->>R: snapshot query — resolve selectors
    R-->>K: level id, wall type pool

    alt selector missing or ambiguous
        K-->>M: refused KIR-G102 + candidates + route
    else grounded
        K->>K: emit C# for THIS Revit version
        K->>R: TransactionGroup — Wall.Create, op_id stamped
        R-->>K: new element id
        K->>R: read the element BACK
        R-->>K: LocationCurve, height param, level id
        alt postconditions hold
            K-->>M: ok + witness — geometry_ok, semantic_ok, topology_ok
        else violated
            K->>R: RollBack
            K-->>M: refused KIR-X004 + which axis failed
        end
    end

A building has a history

A single write is not the whole story. A real project gets read, edited, and read again dozens of times, and for most of this project's life nothing here remembered that revision N and revision N+1 were the same building — every rebuild started from zero. Four modules close that gap, and together they are exactly a version-control system, mapped onto concepts a reader already knows:

git concept	KIR module	what it actually is
content-addressed object store	merkle	a Merkle DAG over the folded building tree — a repeated floor is one node, not N
a history you can replay	journal	append-only per-building revision log; replaying it reconstructs any past revision exactly
applying a diff	rebuild	materializes only the delta between two revisions instead of the whole building
three-way merge	merge3	base / current document / target revision, with a real conflicting verdict — never a silent overwrite

The merged state is deliberately identity-free — a canonical op carries no ElementId — which is exactly what makes it mergeable; a program is still materialized from one concrete revision, never from the merge itself. The routes that drive these four against an open Revit document are part of a private product and are not in this open-core slice, but their offline half ships and runs right here, no bridge and no Revit needed:

pytest kir/decompile/tests/test_merkle.py kir/decompile/tests/test_rebuild.py \
       kir/decompile/tests/test_journal.py kir/decompile/tests/test_merge3.py
107 passed, 1 warning in 6.65s   -- run 2026-09-04, Python 3.12, this repository, no Revit
                                 -- the count is the claim; the seconds are this machine's

pytest is not pulled in by pip install . — it arrives with the dev extra; see Working on KIR itself.

Checked invariants

The reverse pipeline enforces five checked invariants: full document coverage, a reason recorded for every element it cannot express, witnesses that match the data actually read, contamination marking for partial reads, and neutral identifiers. Each invariant is backed by a test or verification run; a violation stops the build or run.

flowchart LR
    subgraph LAWS["§18 — five invariants"]
        direction TB
        L1["1 · CENSUS<br/>lifted + atoms + not_read<br/>= the whole document"]
        L2["2 · RECEIPT<br/>every cut emits<br/>element_id + typed_reason"]
        L3["3 · WITNESS AXIS<br/>sign only the axis<br/>you actually read"]
        L4["4 · CONTAMINATION<br/>a partial read marks<br/>everything derived from it"]
        L5["5 · NEUTRALITY<br/>no device ids, install paths,<br/>or locale-only keys"]
    end

    subgraph CORE["what they enclose"]
        direction TB
        C1["compile"] --> C2["execute in Revit"] --> C3["read back"] --> C4["publish a number"]
    end

    L1 -->|"run-fatal identity check + CI fixture"| CORE
    L2 -->|"rows + failures contract on every side stage"| CORE
    L3 -->|"certificate lint: kind to legal reader"| CORE
    L4 -->|"header round-trip test + A5 gate on partial data"| CORE
    L5 -->|"CI pattern lint"| CORE

    CORE --> R1["built, with a witness"]
    CORE --> R2["typed refusal, with a route"]
    CORE -.->|forbidden by construction| R3["silently wrong"]

Full account: docs/laws/TYPED_HONESTY_SPEC.md — Five Conservation Laws of Honesty for an AI Agent in CAD.

Measured, not promised

Everything below is derived from an instrument on the date shown, not from memory. The re-runnable rows are checked by a shipped instrument that reads this very table and recomputes each number — python3.12 tools/readme_numbers.py --check returns 1 on any divergence. Rows marked historical are older runs whose instrument or corpus is not shipped here; they carry their date and cannot be re-run from this repository alone.

Fact	Value	Date / how
Ops in the registry	82 — 77 writing, 5 query	2026-09-04, len(spec.OPS)
Generated SDK builders	82 — one per op	2026-09-04, len(sdk.builders()) == len(spec.OPS)
Source size	301 production modules, 694 test files	2026-09-04, python3.12 tools/readme_numbers.py --check
Python syntax check	1029 files parsed, 0 errors	2026-09-04, ast.parse over every *.py outside build/
Install into a clean venv	PASS — exit 0, 15 packages, no sudo	2026-09-04, pip install . in a fresh python3.12 -m venv
Install from PyPI with the MCP extra	PASS — 35 packages, kir-building 0.5.0	2026-09-04, pip install "kir-building[mcp]"
The room.py above, from the PyPI package	PASS — 6/6 versions, 20 252 chars of C#, no snapshot	2026-09-04, the block at the top of this page
Offline six-version compile of the shipped example	PASS — 3 programs, 840 ops, 780 elements, 6/6 versions	2026-09-04, python examples/tower_numpy.py from a clone
MCP door	PASS — handshake at revision 2025-11-25, 7 tools listed, stdio and --http	2026-09-04, kir-building[mcp] 0.5.0 from PyPI
Version-control half, offline	107 passed, under 10 s	2026-09-04, pytest kir/decompile/tests/test_{merkle,rebuild,journal,merge3}.py
Emitted C# for the 60-storey tower, one version	3 394 685 characters against 13 210 for the KIR program — 257×	2026-09-04, Revit 2023, compact JSON, from a clone
Historical live baseline	31 of 31 writing ops had a witnessed run — of the 31 that existed then	2026-07-28 local telemetry; telemetry is not shipped here
Historical six-version compile gate	1 056 Roslyn compilations, PASS	2026-07-28 local gate run
Historical reverse-direction coverage	48 categories; 92.83% on the 90 758-element R2026 model	2026-07-27/28 local runs
Historical production compile errors structurally inexpressible in KIR	≈60% of 85 374 over seven weeks	local report; completeness caveats apply

Repository layout

Everything here is the compiler and its instruments; the product that hosts them is a separate repository. Revit is one target of several, and the package is agnostic about which one it emits for.

• kir/ — the forward compiler: registry, typecheck, plan, per-version emitters, typed diagnostics, witness/acceptance machinery;
• kir/dsl.py, kir/sdk.py — the two Python front ends, both generated from the registry;
• kir/__main__.py — the kir command: demo, ops, skill, course, doctor, build;
• kir/decompile/ — the reverse pipeline: extract, lift, fold, materialize, and the version-control half (merkle, journal, rebuild, merge3);
• kir/checker/, kir/clash/ — the judge and the clash pipeline;
• kir/mcp/ — the MCP door: seven tools, five of them offline;
• kir/instruments/ — instruments that run offline, without Revit: compile_gate_offline, bounds_audit, unwired_census, scope_audit, snapshot_janitor, canon_state, and others;
• kir/course/, kir/skill.py — the authoring course and the skill an LLM is handed;
• kir/specs/ — the language contracts: SPEC_V1.md, the decompile spec;
• kir/bridge/ — the client side of the bridge protocol, plus a mock server for offline runs;
• kir/tests/ and kir/*/tests/ — the unit, contract, golden and property tests;
• examples/ — small SDK programs that compile offline. Cloned only: examples/ is not in the wheel, so pip install kir-building does not give you these files;
• docs/laws/ — the design specs behind the honesty, merkle and verified layers.

The Revit bridge itself, the .NET Roslyn compile service, the product's admin routes, runtime data, credentials and logs are intentionally not part of this repository.

The published source lags behind the published package, and by how much. The wheel on PyPI is built from an internal working tree; the public GitHub mirror is refreshed rarely and, as of this release, is 425 commits behind it (last public commit: 2026-09-01). So the Source link on the PyPI page will show you code older than the package you just installed — the kir command, this README and the 0.6.0 fixes are not there yet. We would rather say this than let the two look identical. What you install is what the numbers on this page were measured against; the mirror is what lags. If you need the exact source of a release, open an issue and ask — the mirror is pushed on request, not on a schedule.

What a bare install does not get you. kir.ports.supplied() prints what the host environment has handed the language; in a clean install it prints () — nothing. That is the definition, not a fault: the language on its own has been given no environment. Everything on this page works at (); live writing is what needs a host to register ports.

Working on KIR itself

To work against the tree instead of an installed copy:

python3.12 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
PYTHONPATH="$PWD" python -m pytest \
    kir/decompile/tests/test_merkle.py kir/decompile/tests/test_rebuild.py \
    kir/decompile/tests/test_journal.py kir/decompile/tests/test_merge3.py -q

Three traps worth naming, all bought by measurement rather than reasoning:

• Name the four files; do not point pytest at the directory. kir/decompile/tests collects 185 test_*.py files, and one of them allocates about 5 GB and takes the rest of the run down with it. The four named above are the ones the number in the table refers to.
• PYTHONPATH must be absolute. A bare PYTHONPATH=. is shadowed by any stray kir.py beside you, and the refusal then blames the wrong module.
• Four direct dependencies, and httpx is one of them. It looks like bridge-only machinery, but compile_client.py sits in the package import chain; dropping it into an extra made import kir fail in a clean venv. The dependency list is settled by a run, not by an argument.

Machine-specific paths: measured, not asserted. python3.12 tools/host_path_census.py sweeps the shipped tests for absolute paths of the machine they were measured on: on 2026-09-04 it found 35 test files that know the host tree — 7 of them only through a declared constant, 21 through a bare literal — and exactly 1 of those rides in the built wheel (kir/tests/conftest.py). No credentials, keys or device identifiers were found anywhere in the wheel.

For auditors

Beyond the compiler core in kir/:

• Language contracts: kir/specs/ — SPEC_V1.md, KIR_DECOMPILE_SPEC.md
• Laws of honesty / verified / merkle: docs/laws/
• LLM authoring skill + sandbox course: kir/skill.py (14 774 characters, 2026-09-04) and kir/course/ — python -c "from kir.course import course; course()" prints its sixteen lessons
• README numbers, recomputed: python3.12 tools/readme_numbers.py --check
• CI evidence & secret boundary: .github/workflows/kir-evidence.yml, kir-security.yml
• Offline instruments, runnable with no Revit: kir/instruments/ — each one is expected to name what it could not read rather than report a zero it never measured

---

_{Apache License 2.0 — see LICENSE.}