ilo 26.5.0

ilo - the token-minimal programming language AI agents write
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

#!/usr/bin/env python3
"""Generate bench/perf-table.md from bench/results.json.

Usage:
    python3 scripts/gen-perf-table.py

Reads  bench/results.json  relative to the repo root and writes
bench/perf-table.md.  Run this script whenever bench/results.json is
updated (e.g. in CI after bench/run.sh).

Website integration
-------------------
If a static-site generator is added under site/, include the generated
file with a snippet such as:

    --8<-- "bench/perf-table.md"       (mkdocs-material)
    {% include "../../bench/perf-table.md" %}   (Jinja / Jekyll)

The file contains only the table and a one-line header comment so it
can be embedded directly without further processing.
"""

import json
import pathlib
import sys

REPO_ROOT = pathlib.Path(__file__).parent.parent
RESULTS = REPO_ROOT / "bench" / "results.json"
OUT = REPO_ROOT / "bench" / "perf-table.md"


def fmt_us(value_us: int) -> str:
    """Format microseconds: show ms when >= 1000, otherwise us."""
    if value_us >= 1000:
        ms = value_us / 1000
        return f"{ms:.1f} ms"
    return f"{value_us} µs"


def ratio(value: int, baseline: int) -> str:
    """Return a ×N.N relative-to-baseline string."""
    r = value / baseline
    if abs(r - round(r)) < 0.05:
        return f"×{r:.0f}"
    return f"×{r:.1f}"


def main() -> None:
    if not RESULTS.exists():
        print(f"ERROR: {RESULTS} not found", file=sys.stderr)
        sys.exit(1)

    data = json.loads(RESULTS.read_text())
    generated = data.get("generated", "unknown")
    benchmarks = data["benchmarks"]

    # Determine column order: ilo-jit first, then others alphabetically
    all_impls: list[str] = []
    for times in benchmarks.values():
        for impl in times:
            if impl not in all_impls:
                all_impls.append(impl)

    preferred = ["ilo-jit", "ilo-vm"]
    ordered = [i for i in preferred if i in all_impls] + sorted(
        i for i in all_impls if i not in preferred
    )

    lines: list[str] = [
        f"<!-- generated by scripts/gen-perf-table.py from bench/results.json ({generated}) -->",
        "",
        "## Performance",
        "",
        "Wall-clock time (lower is better). Baseline = Node.",
        "",
    ]

    # Header row
    header = "| Benchmark | " + " | ".join(ordered) + " |"
    separator = "| --- | " + " | ".join(["---"] * len(ordered)) + " |"
    lines += [header, separator]

    for bench, times in sorted(benchmarks.items()):
        baseline = times.get("Node") or next(iter(times.values()))
        cells: list[str] = []
        for impl in ordered:
            if impl not in times:
                cells.append("—")
            else:
                t = times[impl]
                r = ratio(t, baseline)
                cells.append(f"{fmt_us(t)} ({r})")
        lines.append("| " + bench + " | " + " | ".join(cells) + " |")

    lines += [""]
    OUT.write_text("\n".join(lines))
    print(f"Wrote {OUT}")


if __name__ == "__main__":
    main()