Loom Prototype (v0.4.0)

Loom is a small language prototype optimized for LLM automation. It is intentionally AST-first and ID-centric:

• S-expression syntax
• explicit IDs on every node (@<id>)
• strict explicit typing (i64, i1)
• structured JSON patching by node ID
• machine-readable CLI output
• non-empty program form (single function or non-empty function list)

Python version policy

• Supported runtime: Python 3.13

Canonical CLI policy

• Supported invocation path: loom
• JSON output is the only CLI output mode
• python -m loom.cli is internal and not part of the public interface

What is in this repo

• loom/sexpr.py: S-expression parser/printer
• loom/ast.py: strict AST + parser from S-expressions
• loom/type_checker.py: semantic/type validation
• loom/codegen.py: LLVM IR generation + JIT execution via llvmlite
• loom/patch.py: JSON patch document model and patch engine
• loom/cli.py: machine-first CLI (check, run, compile, patch, validate)
• loom/tests/: parser/type/codegen/patch/CLI tests
• docs/: language spec, patch spec, migration, CLI contract, release checklist

Quickstart from clean checkout

python3.13 -m venv .venv
source .venv/bin/activate
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip install -e ".[dev]"

Local quality workflow

make check
make smoke

Targets:

• make venv: create .venv with python3.13
• make install: install runtime + dev dependencies
• make test: unit tests
• make lint: Ruff
• make coverage: coverage report with fail-under threshold
• make check: lint + coverage + unit tests
• make dist: build wheel and sdist
• make smoke: canonical CLI smoke commands using loom
• make release-smoke: install built wheel in fresh venv and run smoke checks

CLI JSON contract (current)

All responses return:

{
  "ok": true,
  "command": "check|run|compile|patch|validate|cli",
  "schema_version": "1",
  "data": {},
  "errors": []
}

command is "cli" for pre-dispatch parser/usage failures (for example unknown subcommands or invalid global flags).

Failure shape:

{
  "ok": false,
  "command": "patch",
  "schema_version": "1",
  "data": {},
  "errors": [
    {
      "code": "PATCH_TARGET_NOT_FOUND",
      "message": "...",
      "node_id": 999,
      "node_kind": "statement",
      "op_index": 0
    }
  ]
}

Canonical demo flow

loom check examples/multi_functions.loom
loom run examples/multi_functions.loom --fn add --args 10 32
loom compile examples/multi_functions.loom --emit llvm-ir
loom validate examples/multi_functions.loom --patch examples/patches/replace_add_rhs.json --atomic --typecheck
loom patch examples/multi_functions.loom --patch examples/patches/replace_add_rhs.json --atomic --out /tmp/patched.loom
loom run /tmp/patched.loom --fn add --args 2 3

Python API

from loom import sexpr, ast, type_checker, codegen, patch

source = """
(fn @1 add ((@2 a i64) (@3 b i64)) i64
  (block @4
    (ret @5 (add_i64 @6 (var @7 a i64) (var @8 b i64)))
  )
)
"""

program = ast.parse_program(sexpr.parse_sexpr(source))
type_checker.check_program(program)
funcs = codegen.compile_program(program)
print(funcs["add"](10, 32))

Pre-1.0 Policy

• Loom is pre-1.0 and may evolve quickly.
• CLI and patch schema changes are allowed between minor versions.
• Behavior changes are documented in CHANGELOG.md.

Docs

• Language spec: docs/LANGUAGE_SPEC.md
• Patch spec: docs/PATCH_SPEC.md
• CLI spec: docs/CLI_SPEC.md
• Integration guide: docs/INTEGRATION_GUIDE.md
• Historical notes: docs/MIGRATION_v0.2.md
• Release checklist: docs/RELEASE.md
• Changelog: CHANGELOG.md