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

Development status

This repository is a development preview, not a production-ready BIM delivery system. Saved-project, geometry, editing and runtime workflows have different supported profiles. Offline checks and API compilation do not replace live Revit acceptance. See the release readiness map for current capabilities and remaining limits, and the register of public promises for what each claim on this page — and each line of the changelog — is backed by, instrument by instrument, with the named borders none of them cross.

Two things on this page are measured against different artefacts, and the difference is named wherever it matters: the published kir-building 0.5.0 on PyPI, and this source tree, which is ahead of it.

Build a building in 60 seconds

pip install kir-building

The compiler demonstration below runs without Revit or a running service once the Python 3.12+ package and its dependencies are installed. Installation may need network access. Optional geometry, browser and live-backend workflows have additional dependencies and separate acceptance requirements.

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 generated Revit execution code, not a complete installed add-in. Emitters handle transactions, millimetre-to-feet conversion and version-specific API choices for supported operations. Execution still needs a compatible wrapper and runtime. Generated witnesses check selected properties; compilation and a returned element ID do not prove that every design requirement was met. Runtime failures and incomplete evidence remain possible.

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 free-standing placement field on this hosted-door builder: its contract requires a host. That structural requirement does not prove the host, family, placement or resulting opening will be suitable in the actual Revit document.

(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, kir build FILE.json, kir project, kir connector and kir capture 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 83 83 — 83 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.

Save a project and continue it

The source checkout also includes a first persistent authoring layer above the operation compiler: named module instances, stable output IDs, immutable revisions and JSON reload. The residential example starts with three concept volumes, develops one section and changes it after reloading, leaving the other two volumes unchanged.

PYTHONPATH=. python examples/residential_project.py --stage changed | PYTHONPATH=. python -m kir project inspect -

This is saved authoring state, not an incremental Revit publisher or verified LOD conversion. See the project contract and runnable workflow for the API, export command and remaining guarantees. Local revision history and addressed diffs are available through kir project; the delivery register names the remaining product work. An explicit Store/5 upgrade enables durable agent tasks, checkpoints and proposal decisions. Task storage preserves authoring work across process restarts; it does not by itself launch an LLM or execute a tool. The explicit recipe-step adapter additionally runs Python once, retains its result and charges the task's tool-call budget. Its Linux worker requires namespaces, chroot, OS resource limits and libseccomp.so.2; missing mandatory isolation refuses before author execution. Unknown previous results are not automatically recomputed. LLM token budgets and a complete autonomous scheduler remain separate work. The residential multi-worker pilot exercises that path on the saved towers/podium project: concurrent edits, a retained conflict, a new coordinator, a further section edit, scoped XY review and the actual browser viewer. Its schematic section is not a finished native BIM model. Opt-in reference surfaces now show its wall axes and floor contours as zero-thickness surfaces with holes. Known bodies and BIM operations are retained; this display layer does not invent types or enter clashes.

The checkout also contains scoped authoring proposals and CLI acceptance, explicit concept-to-section lineage with named losses, and a standalone read-only display inspector with an optional saved-project status panel and CLI. These are separate capabilities: authoring acceptance is not native publication, and an approximate display proxy is not a verified BIM body. The standalone first-send API now joins context capture, compilation, durable input archiving and one transport delivery. Its portable integration tests use explicitly seeded receipts; Windows installation and live Revit acceptance remain separate gates.

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#

(That count, like the 20 252 above, is the published kir-building 0.5.0 run of 2026-09-04. The same two blocks against this source tree today emit 34 355 and 37 134 characters: the emitter has grown since the release, and the refusal codes — KIR-G103, KIR-G101 — are what stayed identical.)

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

Writing into a live model additionally needs the selected Revit installation, its API references and an installed compatible execution backend. Connector source lives in connector/; supported compile targets and accepted live workflows are different guarantees.

Hand it to a model: the MCP server

KIR ships an MCP server, so compatible MCP clients can author, compile and inspect buildings through it. The server needs the mcp extra, 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.

Without the extra the door refuses by name and exits 2: it prints pip install "kir-building[mcp]" and does not announce a surface it cannot serve. (That is the source tree. The published 0.5.0 still dies with a bare ModuleNotFoundError: No module named 'mcp' after listing all seven tools — the refusal was bought on 2026-09-04 and ships with the next release. Instrument: kir/mcp/tests/test_the_door_names_its_missing_extra.py.)

There is also a bridge extra (pip install "kir-building[bridge]"), which installs fastapi. It is only needed for kir.bridge.mock_server — a mock bridge server that returns fixture responses for the bridge contract tests. It is unrelated to the MCP server and to writing into a live model.

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.

kir_write does not ask by default, and that is a decision, not an oversight. KIR_MCP_CONFIRM is off unless the host sets it: the confirmation machinery exists and is tested, but the door writes without a prompt until you turn asking on with KIR_MCP_CONFIRM=session (one consent per document handle) or always. Consent is bound to the program and to the handle, never to the door. Instrument: kir/mcp/tests/test_the_live_door_writes_only_where_it_may.py — including test_off_is_the_default_and_asking_is_opt_in.

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']
контекст: 3709235 знаков C# (Revit 2023) против 11263 знаков программы KIR — 329×

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. The last line is the context-window measurement this page quotes rather than asserts. The third 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, 966505)

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:

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.

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, project, connector, capture;
• 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 445 commits behind it (measured 2026-09-08 with git rev-list --count origin/main..HEAD; last public commit ad78e64, 2026-09-07). 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, 0.7.0 and 0.8.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 194 test_*.py files (2026-09-07), 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-07 it found 41 test files, out of 908, that know the host tree — 7 only through a declared constant, 7 through both a constant and a literal, 27 through a bare literal alone — 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. (The three buckets are named separately because an earlier edition of this paragraph carried two of them and a total that did not add up.)

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.build_skill_text() — 14 774 characters of skill text on 2026-09-07 (the module that generates it, kir/skill.py, is 67 559 characters; the number a model is handed is the text, not the file) — 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
• Every promise on this page, with its instrument and its border: docs/PROMISES_RU.md
• 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.}