mklang 0.5.4__py3-none-any.whl

mklang/__init__.py

@@ -0,0 +1,17 @@
+"""mklang — reference interpreter for the mklang language (core v0.2)."""
+
+from .checkpoint import load_checkpoint, save_checkpoint
+from .model import Gate, Machine, State, parse_machine
+from .engine import RunResult, run
+
+__version__ = "0.5.4"
+__all__ = [
+    "Gate",
+    "Machine",
+    "State",
+    "parse_machine",
+    "run",
+    "RunResult",
+    "load_checkpoint",
+    "save_checkpoint",
+]

mklang/checkpoint.py

@@ -0,0 +1,112 @@
+"""Checkpoint frames and envelope I/O for resumable runs (ADR 0007)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+FORMAT = 1
+
+
+def _write_private(path: str | Path, text: str) -> None:
+    """Write text with owner-only (0600) permissions.
+
+    A checkpoint serializes the FULL blackboard — customer text, PII, internal
+    policy — as plaintext JSON, and HITL suspends precisely on the most sensitive
+    cases (escalations), so these files linger longest exactly when they matter
+    most (SPEC §11). Encryption at rest is a host concern and an explicit v0.2
+    non-goal; owner-only permissions are the cheap, real baseline. Create the file
+    restricted from the start (no world-readable window) and chmod to cover a
+    pre-existing file whose mode `os.open` would not tighten. POSIX-only: on
+    Windows the mode is advisory and chmod may be a no-op."""
+    p = Path(path)
+    fd = os.open(p, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(text)
+    try:
+        os.chmod(p, 0o600)
+    except (OSError, NotImplementedError):  # non-POSIX / unsupported filesystem
+        pass
+
+
+def encode_repair(repair_left: dict[tuple[str, int], int]) -> list[list]:
+    """Tuple-keyed repair budgets → JSON-safe [state_id, gate_idx, remaining] triples."""
+    return [[sid, gi, n] for (sid, gi), n in repair_left.items()]
+
+
+def decode_repair(triples: list) -> dict[tuple[str, int], int]:
+    return {(sid, gi): n for sid, gi, n in triples}
+
+
+def make_frame(
+    machine_name: str,
+    state_id: str,
+    ctx: dict,
+    steps: int,
+    total_in: int,
+    total_out: int,
+    feedback: str,
+    repair_left: dict[tuple[str, int], int],
+    trace: list[dict],
+) -> dict:
+    """Snapshot one run() loop-top: everything needed to re-enter the loop."""
+    return {
+        "machine": machine_name,
+        "state": state_id,
+        "ctx": dict(ctx),
+        "steps": steps,
+        "total_in": total_in,
+        "total_out": total_out,
+        "feedback": feedback,
+        "repair_left": encode_repair(repair_left),
+        "trace": list(trace),
+    }
+
+
+def file_sha256(path: str | Path) -> str:
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def save_checkpoint(
+    path: str | Path,
+    machine_name: str,
+    machine_path: str | Path,
+    reason: str,
+    frames: list[dict],
+    cost_budget: int | None,
+    hitl: bool = False,
+) -> None:
+    from . import __version__  # runtime import: __init__ imports engine imports this module
+
+    envelope = {
+        "format": FORMAT,
+        "mklang_version": __version__,
+        "created": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "machine": machine_name,
+        "machine_path": str(machine_path),
+        "machine_sha256": file_sha256(machine_path),
+        "reason": reason,
+        "cost_budget": cost_budget,
+        "hitl": hitl,
+        "frames": frames,
+    }
+    _write_private(path, json.dumps(envelope, ensure_ascii=False, indent=2))
+
+
+def load_checkpoint(path: str | Path) -> dict:
+    ck = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(ck, dict) or ck.get("format") != FORMAT:
+        raise ValueError(f"not an mklang checkpoint (expected format {FORMAT})")
+    for key in ("machine", "machine_path", "machine_sha256", "frames"):
+        if key not in ck:
+            raise ValueError(f"checkpoint missing key {key!r}")
+    if not ck["frames"]:
+        raise ValueError("checkpoint has no frames")
+    return ck
+
+
+def verify_hash(ck: dict, machine_path: str | Path) -> bool:
+    return file_sha256(machine_path) == ck["machine_sha256"]

mklang/cli.py

@@ -0,0 +1,406 @@
+"""`mklang` command-line interface: run and check machines."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .checkpoint import load_checkpoint, save_checkpoint, verify_hash
+from .config import load_provider
+from .engine import run
+from .loader import check_tiers, load_machine, semantic_check
+from .registry import load_registry
+
+
+def _build_llm(prov):
+    from .providers import build_llm
+
+    return build_llm(prov)
+
+
+def _coerce(value: str):
+    """JSON-parse a --set value (so lists/objects/numbers work); fall back to str."""
+    try:
+        return json.loads(value)
+    except (ValueError, TypeError):
+        return value
+
+
+def _apply_sets(ctx: dict, sets: list[str]) -> dict:
+    for kv in sets or []:
+        key, value = kv.split("=", 1)
+        cur = ctx
+        parts = key.split(".")
+        for p in parts[:-1]:
+            nxt = cur.get(p)
+            if not isinstance(nxt, dict):
+                nxt = {}
+                cur[p] = nxt
+            cur = nxt
+        cur[parts[-1]] = _coerce(value)
+    return ctx
+
+
+def _prepare(args, machine_path: str):
+    """Shared run/resume setup. Returns (prov, llm, registry, machine, tools, hooks) or exit code."""
+    prov = load_provider(args.config, args.provider)
+    if not prov.api_key and prov.name != "local":
+        print(f"# warning: no API key for provider '{prov.name}' — set it in .env", file=sys.stderr)
+    llm = _build_llm(prov)
+    registry = load_registry(Path(machine_path).parent, validate=False)
+    try:
+        machine = load_machine(machine_path)
+    except Exception as e:  # noqa: BLE001 — surface load/validation failure cleanly
+        print(f"{machine_path}: ERROR: {getattr(e, 'message', str(e))}", file=sys.stderr)
+        return 2
+    registry[machine.name] = machine
+    errors, warnings = semantic_check(machine, registry, strict=getattr(args, "strict", False))
+    errors.extend(check_tiers(machine, prov.tiers))
+    for w in warnings:
+        print(f"# warning: {w}", file=sys.stderr)
+    if errors:
+        for e in errors:
+            print(f"{machine_path}: error: {e}", file=sys.stderr)
+        return 2
+    from .hooks import load_hook_registry
+    from .tools import load_tool_registry
+
+    tools = load_tool_registry()
+    hooks = load_hook_registry()
+    for sid, s in machine.states.items():
+        if s.kind == "tool" and s.tool not in tools:
+            print(
+                f"# warning: state '{sid}' uses tool '{s.tool}' not in the registry "
+                f"{sorted(tools)} — the run halts if it is reached",
+                file=sys.stderr,
+            )
+        for g in s.gates:
+            if g.hook and g.hook not in hooks:
+                print(
+                    f"# warning: state '{sid}' uses hook '{g.hook}' not in the registry "
+                    f"{sorted(hooks)} — the run halts if it is reached",
+                    file=sys.stderr,
+                )
+    return prov, llm, registry, machine, tools, hooks
+
+
+def _emit(res, checkpoint_path, machine, machine_path, cost_budget, hitl=False) -> int:
+    """Print the result JSON; write a checkpoint on suspension. Exit: 0 done, 3 suspended, 1 halt."""
+    out = {
+        "status": res.status,
+        "error": res.error,
+        "result": res.result,
+        "usage": res.usage,
+        "trace": res.trace,
+    }
+    if res.at is not None:
+        out["at"] = res.at
+    if res.status == "suspended":
+        save_checkpoint(
+            checkpoint_path, machine.name, machine_path, res.error, res.frames, cost_budget, hitl
+        )
+        out["checkpoint"] = str(checkpoint_path)
+        print(
+            f"# suspended ({res.error}) — checkpoint written to {checkpoint_path}", file=sys.stderr
+        )
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    if res.status == "done":
+        return 0
+    return 3 if res.status == "suspended" else 1
+
+
+def cmd_run(args) -> int:
+    if args.hitl and not args.checkpoint:
+        print("--hitl requires --checkpoint (the suspension must land somewhere)", file=sys.stderr)
+        return 2
+    prep = _prepare(args, args.machine)
+    if isinstance(prep, int):
+        return prep
+    prov, llm, registry, machine, tools, hooks = prep
+    ctx = _apply_sets(dict(machine.context), args.set)
+    print(f"# {machine.name} · provider={prov.name} · tiers={prov.tiers}", file=sys.stderr)
+    res = run(
+        machine,
+        ctx,
+        registry,
+        llm,
+        prov.tiers,
+        prov.judge_override(),
+        tier_params=prov.params,
+        cost_budget=args.max_tokens,
+        tools=tools,
+        hooks=hooks,
+        suspendable=args.checkpoint is not None,
+        escalate_suspend=args.hitl,
+    )
+    return _emit(res, args.checkpoint, machine, args.machine, args.max_tokens, hitl=args.hitl)
+
+
+def cmd_resume(args) -> int:
+    try:
+        ck = load_checkpoint(args.checkpoint)
+    except (OSError, ValueError) as e:
+        print(f"{args.checkpoint}: ERROR: {e}", file=sys.stderr)
+        return 2
+    machine_path = args.machine or ck["machine_path"]
+    try:
+        hash_ok = verify_hash(ck, machine_path)
+    except OSError as e:
+        print(f"{machine_path}: ERROR: {e}", file=sys.stderr)
+        return 2
+    if not hash_ok:
+        if not args.force:
+            print(
+                f"{machine_path}: ERROR: machine changed since checkpoint "
+                f"(sha256 mismatch); use --force to resume anyway",
+                file=sys.stderr,
+            )
+            return 2
+        print(
+            f"# warning: {machine_path} changed since checkpoint — resuming anyway", file=sys.stderr
+        )
+    prep = _prepare(args, machine_path)
+    if isinstance(prep, int):
+        return prep
+    prov, llm, registry, machine, tools, hooks = prep
+    cost_budget = args.max_tokens if args.max_tokens is not None else ck.get("cost_budget")
+    if ck.get("reason") == "cost-exhausted" and cost_budget is not None:
+        old = ck.get("cost_budget")
+        if old is not None and cost_budget <= old:
+            print(
+                f"# warning: cost budget {cost_budget} is not above the exhausted "
+                f"{old} — the run will suspend again immediately",
+                file=sys.stderr,
+            )
+    out_path = args.checkpoint_out or args.checkpoint
+    hitl = ck.get("hitl", False) or args.hitl
+    # A human reply lands in the innermost frame's context (the suspended run).
+    _apply_sets(ck["frames"][-1]["ctx"], args.set)
+    print(f"# {machine.name} · resume · provider={prov.name} · tiers={prov.tiers}", file=sys.stderr)
+    res = run(
+        machine,
+        dict(machine.context),
+        registry,
+        llm,
+        prov.tiers,
+        prov.judge_override(),
+        tier_params=prov.params,
+        cost_budget=cost_budget,
+        tools=tools,
+        hooks=hooks,
+        suspendable=True,
+        escalate_suspend=hitl,
+        resume=ck["frames"],
+    )
+    return _emit(res, out_path, machine, machine_path, cost_budget, hitl=hitl)
+
+
+def cmd_lint(args) -> int:
+    from .lint import lint_machine
+
+    ok = True
+    findings_total = 0
+    for path in args.machines:
+        registry = load_registry(Path(path).parent, validate=False)
+        try:
+            machine = load_machine(path)
+        except Exception as e:  # noqa: BLE001 — surface any load/validation failure
+            print(f"{path}: SCHEMA ERROR: {getattr(e, 'message', str(e))}")
+            ok = False
+            continue
+        errors, warnings = semantic_check(machine, registry, strict=args.strict)
+        findings = lint_machine(machine)
+        findings_total += len(findings)
+        for w in warnings:
+            print(f"{path}: warning: {w}")
+        for e in errors:
+            print(f"{path}: error: {e}")
+        for f in findings:
+            print(f"{path}: lint: {f}")
+        if errors:
+            ok = False
+        elif not findings:
+            print(f"{path}: ok")
+    if not ok:
+        return 1
+    return 1 if (args.strict and findings_total) else 0
+
+
+def cmd_test(args) -> int:
+    """Run scenario tests against a machine with a scripted LLM (no API keys)."""
+    import yaml
+
+    from .scripttest import match_expectation, run_scenario
+
+    registry = load_registry(Path(args.machine).parent, validate=False)
+    try:
+        machine = load_machine(args.machine)
+    except Exception as e:  # noqa: BLE001 — surface any load/validation failure
+        print(f"{args.machine}: SCHEMA ERROR: {getattr(e, 'message', str(e))}", file=sys.stderr)
+        return 2
+    registry[machine.name] = machine
+
+    try:
+        doc = yaml.safe_load(Path(args.script).read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as e:
+        print(f"{args.script}: ERROR: {e}", file=sys.stderr)
+        return 2
+    scenarios = (doc or {}).get("scenarios")
+    if not scenarios:
+        print(f"{args.script}: ERROR: no `scenarios:` list", file=sys.stderr)
+        return 2
+
+    all_pass = True
+    for i, sc in enumerate(scenarios):
+        name = sc.get("name", f"scenario[{i}]")
+        expect = sc.get("expect")
+        if expect is None:
+            print(f"FAIL {name}: scenario has no `expect:` block")
+            all_pass = False
+            continue
+        try:
+            result = run_scenario(machine, registry, sc)
+        except Exception as e:  # noqa: BLE001 — a scenario error is a failure, not a crash
+            print(f"FAIL {name}: scenario raised {type(e).__name__}: {e}")
+            all_pass = False
+            continue
+        mismatches = match_expectation(result, expect)
+        if not mismatches:
+            print(f"PASS {name}")
+            continue
+        all_pass = False
+        first = mismatches[0]
+        print(f"FAIL {name}")
+        print(f"       {first.key}: expected {first.expected!r}, got {first.actual!r}")
+        if len(mismatches) > 1:
+            print(f"       (+{len(mismatches) - 1} more mismatch(es))")
+    return 0 if all_pass else 1
+
+
+def cmd_check(args) -> int:
+    ok = True
+    for path in args.machines:
+        registry = load_registry(Path(path).parent, validate=False)
+        try:
+            machine = load_machine(path)
+        except Exception as e:  # noqa: BLE001 — surface any load/validation failure
+            msg = getattr(e, "message", str(e))
+            print(f"{path}: SCHEMA ERROR: {msg}")
+            ok = False
+            continue
+        errors, warnings = semantic_check(machine, registry, strict=args.strict)
+        for w in warnings:
+            print(f"{path}: warning: {w}")
+        for e in errors:
+            print(f"{path}: error: {e}")
+        if errors:
+            ok = False
+        else:
+            print(f"{path}: ok")
+    return 0 if ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="mklang", description="Run and check mklang machines.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("run", help="execute a machine against a provider")
+    r.add_argument("machine")
+    r.add_argument("--config", default="config/runtime.example.yaml")
+    r.add_argument("--provider", default=None, help="override the config's `active` provider")
+    r.add_argument("--set", action="append", default=[], metavar="k.path=value")
+    r.add_argument(
+        "--max-tokens",
+        type=int,
+        default=None,
+        help="cost budget: halt once total tokens reach this",
+    )
+    r.add_argument(
+        "--checkpoint",
+        default=None,
+        metavar="PATH",
+        help="on budget exhaustion suspend and write a resumable checkpoint here "
+        "(contains the full context in plaintext; written 0600, see SPEC §11)",
+    )
+    r.add_argument(
+        "--hitl",
+        action="store_true",
+        help="a fired escalate gate suspends for human review (requires --checkpoint); "
+        "reply via `mklang resume --set`",
+    )
+    r.add_argument(
+        "--strict",
+        action="store_true",
+        help="refuse to run a document whose mklang: version is unsupported "
+        "(version-unsupported); default is a warning",
+    )
+    r.set_defaults(fn=cmd_run)
+
+    s = sub.add_parser("resume", help="resume a suspended run from a checkpoint")
+    s.add_argument("checkpoint")
+    s.add_argument("--config", default="config/runtime.example.yaml")
+    s.add_argument("--provider", default=None, help="override the config's `active` provider")
+    s.add_argument(
+        "--set",
+        action="append",
+        default=[],
+        metavar="k.path=value",
+        help="inject values (e.g. the human reply) into the suspended run's context",
+    )
+    s.add_argument(
+        "--hitl",
+        action="store_true",
+        help="keep suspending on escalate gates even if the checkpoint didn't record it",
+    )
+    s.add_argument(
+        "--max-tokens",
+        type=int,
+        default=None,
+        help="new cost budget (total, including tokens spent before the suspend)",
+    )
+    s.add_argument("--machine", default=None, help="machine path override (if the .mk moved)")
+    s.add_argument(
+        "--checkpoint",
+        dest="checkpoint_out",
+        default=None,
+        metavar="PATH",
+        help="where to write the checkpoint on re-suspension (default: overwrite the input)",
+    )
+    s.add_argument("--force", action="store_true", help="resume even if the machine file changed")
+    s.set_defaults(fn=cmd_resume)
+
+    c = sub.add_parser("check", help="validate machines (schema + semantics)")
+    c.add_argument("machines", nargs="+")
+    c.add_argument(
+        "--strict",
+        action="store_true",
+        help="treat an unsupported mklang: version as an error (version-unsupported)",
+    )
+    c.set_defaults(fn=cmd_check)
+
+    li = sub.add_parser("lint", help="check + static analysis (dead gates, unread outputs, typos)")
+    li.add_argument("machines", nargs="+")
+    li.add_argument("--strict", action="store_true", help="exit 1 when lint findings exist")
+    li.set_defaults(fn=cmd_lint)
+
+    t = sub.add_parser(
+        "test",
+        help="run scenario tests against a machine with a scripted LLM (no API keys)",
+    )
+    t.add_argument("machine")
+    t.add_argument(
+        "--script",
+        required=True,
+        metavar="FILE",
+        help="a .test.yaml of named scenarios (scripted llm/tools/hooks + expect)",
+    )
+    t.set_defaults(fn=cmd_test)
+
+    args = ap.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mklang/config.py

@@ -0,0 +1,50 @@
+"""Runtime configuration: load the tier->model map for a provider, keys from .env."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+from dotenv import find_dotenv, load_dotenv
+
+
+@dataclass
+class ProviderConfig:
+    name: str
+    tiers: dict[str, str]  # fast/balanced/reasoning -> model id
+    api_key: str = ""
+    base_url: str | None = None
+    judge: str | None = None
+    params: dict = field(default_factory=dict)
+
+    def judge_override(self) -> str | None:
+        """The optional global judge-model override (config `judge:`).
+
+        ``None`` means gate judging follows each state's own capability tier
+        (SPEC §2.1) — a `reasoning` state's gates are judged by the reasoning
+        model, not silently downgraded. Set `judge:` only to force one cheaper
+        model for *all* gates as a cost optimization."""
+        return self.judge
+
+
+def load_provider(config_path: str, provider: str | None = None) -> ProviderConfig:
+    """Load a provider block from the runtime YAML; resolve its key from the env.
+
+    `.env` is loaded first (python-dotenv), so keys never live in the config file."""
+    load_dotenv(find_dotenv(usecwd=True))  # search from cwd upward, not the package dir
+    cfg = yaml.safe_load(Path(config_path).read_text(encoding="utf-8"))
+    name = provider or cfg["active"]
+    if name not in cfg.get("providers", {}):
+        raise KeyError(f"provider {name!r} not in {config_path}")
+    p = cfg["providers"][name]
+    api_key = os.environ.get(p.get("api_key_env", ""), "")
+    return ProviderConfig(
+        name=name,
+        tiers=p["tiers"],
+        api_key=api_key,
+        base_url=p.get("base_url"),
+        judge=p.get("judge"),
+        params=p.get("params", {}) or {},
+    )