runxmd 1.0.0__py3-none-any.whl

runxmd/__init__.py

@@ -0,0 +1,7 @@
+"""XMD — a runtime that executes documents.
+
+v0.0.1: parse an .xmd document, run its workflows with inline-code plugins,
+resolve and persist memory. The document becomes the system.
+"""
+
+__version__ = "1.0.0"

runxmd/agent.py

@@ -0,0 +1,185 @@
+"""Agent engine (Layer 7) — goal -> tasks -> execute -> memory.
+
+`runxmd agent` is **agent-author** mode: unlike `runxmd run` (which may only write
+`runtime.*` memory, per field ownership), the agent command is authorized to
+author `@tasks` generated from the `@goal`. The document grows itself.
+
+Two execution modes (both built):
+
+  1. **Explicit workflow link** — a task annotated `-> workflow_name` runs that
+     `@workflow` and is ticked on success. Default; safe, human-authored.
+  2. **LLM-emitted steps** — for a task with no workflow link, the LLM generates
+     XMD steps which the agent then runs. Gated behind `--autonomous`, because it
+     executes model-generated commands and must be an explicit choice.
+
+Planning (goal -> task list) uses the `@llm` plugin (Anthropic via stdlib
+urllib; key from `ANTHROPIC_API_KEY`). With no key, planning degrades gracefully
+and the agent still executes any pre-existing tasks (agent-in-the-loop mode).
+"""
+from __future__ import annotations
+
+import re
+
+from . import executor, plugins
+from .parser import Section, Task, _parse_steps, parse, to_source
+
+_MAX_TASKS = 8
+
+
+def agent_run(
+    path: str,
+    replan: bool = False,
+    autonomous: bool = False,
+    model: str = None,
+    max_tokens: int = 1024,
+    dry_run: bool = False,
+    out=print,
+):
+    with open(path, encoding="utf-8") as f:
+        doc = parse(f.read())
+
+    goal_sec = doc.section("goal")
+    goal = (goal_sec.text if goal_sec else "").strip()
+    if not goal:
+        out("✗ no @goal to work from — add a @goal section.")
+        return doc
+    out(f"◆ goal: {goal}")
+
+    mem_sec = doc.section("memory")
+    memory = dict(mem_sec.memory) if mem_sec else {}
+    ctx = {"memory": memory}
+    tasks_sec = doc.section("tasks")
+    workflow_names = [w.name for w in doc.workflows() if w.name]
+
+    # 1. PLAN -----------------------------------------------------------------
+    if replan or not (tasks_sec and tasks_sec.tasks):
+        out("\n· planning tasks from goal …")
+        planned = _plan(goal, workflow_names, model, max_tokens, out)
+        if planned:
+            if tasks_sec is None:
+                tasks_sec = Section(kind="tasks")
+                doc.sections.append(tasks_sec)
+            if replan:
+                tasks_sec.tasks = []
+            tasks_sec.tasks.extend(Task(done=False, text=t) for t in planned)
+            out(f"· planned {len(planned)} task(s)")
+            for t in planned:
+                out(f"    - {t}")
+        else:
+            out("· no plan produced — executing any existing tasks instead")
+
+    # 2. EXECUTE --------------------------------------------------------------
+    open_tasks = [t for t in (tasks_sec.tasks if tasks_sec else []) if not t.done]
+    if not open_tasks:
+        out("\n· no open tasks to execute")
+    done = 0
+    for task in open_tasks:
+        target = _target_workflow(task.text)
+        wf = doc.section("workflow", target) if target else None
+        if wf is not None:
+            out(f"\n● task: {task.text}")
+            if dry_run:
+                out(f"  → would run workflow '{target}'")
+                continue
+            ok = executor.run_workflow(wf, memory, ctx, out)
+        elif autonomous:
+            out(f"\n● task (autonomous): {task.text}")
+            if dry_run:
+                out("  → would ask the LLM to generate + run steps")
+                continue
+            ok = _exec_via_llm(task.text, goal, memory, ctx, model, max_tokens, out)
+        else:
+            out(
+                f"\n○ task skipped — no '-> workflow' link "
+                f"(use --autonomous to let the LLM run it): {task.text}"
+            )
+            continue
+        if ok:
+            task.done = True
+            done += 1
+        else:
+            out(f"  ! left open (failed): {task.text}")
+
+    # 3. MEMORY + write-back --------------------------------------------------
+    if dry_run:
+        out("\n· dry run — nothing written")
+        return doc
+    memory["runtime.agent_runs"] = int(memory.get("runtime.agent_runs", 0) or 0) + 1
+    memory["runtime.tasks_done_last"] = done
+    hooks_sec = doc.section("on_done")
+    if hooks_sec:
+        executor._apply_hooks(hooks_sec.hooks, memory, out)
+    if mem_sec is None:
+        mem_sec = Section(kind="memory")
+        doc.sections.append(mem_sec)
+    mem_sec.memory = memory
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(to_source(doc))
+    out(f"\n✓ agent run complete — {done} task(s) executed; memory updated")
+    return doc
+
+
+# --------------------------------------------------------------------------- #
+# Helpers
+# --------------------------------------------------------------------------- #
+def _target_workflow(text: str):
+    if "->" in text:
+        return _slug(text.rsplit("->", 1)[1])
+    return None
+
+
+def _slug(s: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9_]+", "_", s.strip()).strip("_")
+
+
+def _plan(goal, workflow_names, model, max_tokens, out):
+    llm = plugins.get("llm")
+    if llm is None:
+        return []
+    wf_hint = ""
+    if workflow_names:
+        wf_hint = (
+            "\nExisting workflows you may link a task to with ' -> name': "
+            + ", ".join(workflow_names)
+        )
+    prompt = (
+        "You are a planning assistant for the XMD document runtime. Given a "
+        f"project GOAL, output up to {_MAX_TASKS} concrete, ordered tasks — one "
+        "per line, no numbering, no prose. If a task is fulfilled by an existing "
+        "workflow, append ' -> workflow_name'." + wf_hint + "\n\nGOAL:\n" + goal
+    )
+    res = llm({"prompt": prompt, "model": model, "max_tokens": max_tokens}, {})
+    if not res.ok:
+        out(f"  · planner unavailable: {res.error}")
+        return []
+    tasks = []
+    for line in res.output.splitlines():
+        clean = line.strip().lstrip("-*0123456789. \t").strip()
+        if clean:
+            tasks.append(clean)
+    return tasks[:_MAX_TASKS]
+
+
+def _exec_via_llm(task_text, goal, memory, ctx, model, max_tokens, out):
+    llm = plugins.get("llm")
+    if llm is None:
+        out("  · @llm unavailable — cannot generate steps")
+        return False
+    prompt = (
+        "You generate XMD workflow steps. For the TASK below, output ONLY steps "
+        "in this exact format (no prose, no code fences):\n"
+        "- @shell\n  run: <command>\n"
+        "Allowed plugins: @shell, @python (run: block), @write (path, content), "
+        "@read (path), @http (url). Keep it minimal and safe.\n\n"
+        f"GOAL: {goal}\nTASK: {task_text}"
+    )
+    res = llm({"prompt": prompt, "model": model, "max_tokens": max_tokens}, {})
+    if not res.ok:
+        out(f"  · step generation failed: {res.error}")
+        return False
+    steps = _parse_steps(res.output.splitlines())
+    if not steps:
+        out("  · LLM returned no runnable steps")
+        return False
+    out(f"  · LLM generated {len(steps)} step(s)")
+    return executor.run_steps(steps, memory, ctx, out)

runxmd/cli.py

@@ -0,0 +1,102 @@
+"""XMD command-line interface (SPEC §5)."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+
+from . import __version__, executor
+from .parser import parse
+
+
+def _load(path: str):
+    with open(path, encoding="utf-8") as f:
+        return parse(f.read())
+
+
+def main(argv=None) -> int:
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+    p = argparse.ArgumentParser(prog="runxmd", description="runxmd — the XMD runtime v" + __version__)
+    p.add_argument("--version", action="version", version="runxmd " + __version__)
+    sub = p.add_subparsers(dest="cmd")
+
+    pr = sub.add_parser("run", help="execute workflow(s) and persist memory")
+    pr.add_argument("file")
+    pr.add_argument("--workflow", help="run only the named workflow")
+    pr.add_argument("--no-write", action="store_true", help="do not write memory back")
+
+    pw = sub.add_parser("watch", help="re-run the file whenever it changes")
+    pw.add_argument("file")
+    pw.add_argument("--workflow", help="run only the named workflow")
+    pw.add_argument("--interval", type=float, default=1.0, help="poll seconds")
+    pw.add_argument("--max-runs", type=int, default=0, help="stop after N runs (0=forever)")
+    pw.add_argument("--no-write", action="store_true", help="do not write memory back")
+
+    pa = sub.add_parser("agent", help="goal -> tasks -> execute -> memory (Layer 7)")
+    pa.add_argument("file")
+    pa.add_argument("--replan", action="store_true", help="regenerate tasks from the goal")
+    pa.add_argument("--autonomous", action="store_true",
+                    help="let the LLM generate + RUN steps for tasks with no workflow link")
+    pa.add_argument("--model", help="LLM model id for planning/generation")
+    pa.add_argument("--max-tokens", type=int, default=1024)
+    pa.add_argument("--dry-run", action="store_true", help="plan/show without executing or writing")
+
+    pp = sub.add_parser("parse", help="print parsed structure as JSON")
+    pp.add_argument("file")
+
+    pv = sub.add_parser("validate", help="check the file parses; list sections")
+    pv.add_argument("file")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "run":
+        executor.run(args.file, workflow_name=args.workflow, write_back=not args.no_write)
+    elif args.cmd == "watch":
+        flush = lambda *a: print(*a, flush=True)  # noqa: E731 — keep watch output live
+        executor.watch(
+            args.file,
+            workflow_name=args.workflow,
+            interval=args.interval,
+            max_runs=args.max_runs,
+            write_back=not args.no_write,
+            out=flush,
+        )
+    elif args.cmd == "agent":
+        from . import agent
+        agent.agent_run(
+            args.file,
+            replan=args.replan,
+            autonomous=args.autonomous,
+            model=args.model,
+            max_tokens=args.max_tokens,
+            dry_run=args.dry_run,
+        )
+    elif args.cmd == "parse":
+        print(json.dumps(asdict(_load(args.file)), indent=2))
+    elif args.cmd == "validate":
+        return _validate(args.file)
+    else:
+        p.print_help()
+    return 0
+
+
+def _validate(path: str) -> int:
+    try:
+        doc = _load(path)
+    except Exception as e:  # noqa: BLE001 — surface any parse failure to the user
+        print(f"✗ failed to parse {path}: {e}")
+        return 1
+    if not doc.sections:
+        print(f"✗ {path}: no sections found")
+        return 1
+    print(f"✓ {path} — title: {doc.title or '(none)'}")
+    for s in doc.sections:
+        name = f" {s.name}" if s.name else ""
+        print(f"  @{s.kind}{name}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

runxmd/executor.py

@@ -0,0 +1,151 @@
+"""Execution engine (SPEC §3-4).
+
+Loads a document, runs its workflow(s) top-to-bottom, resolving memory
+references per step, applies @on_done hooks, and writes memory back to the file.
+"""
+from __future__ import annotations
+
+import os
+import re
+import time
+
+from . import plugins
+from .memory import substitute
+from .parser import Document, parse, parse_scalar, to_source
+
+# Field ownership (SPEC §4): the runtime may only write memory keys under this
+# reserved namespace. Everything else is agent-owned and never touched by the
+# runtime — this is what makes the two-author document safe instead of lucky.
+RUNTIME_NAMESPACE = "runtime."
+
+_SET_RE = re.compile(r"^set:\s*memory\.([a-zA-Z0-9_.]+)\s*=\s*(.+)$")
+
+
+def run(
+    path: str,
+    workflow_name: str = None,
+    write_back: bool = True,
+    out=print,
+) -> Document:
+    with open(path, encoding="utf-8") as f:
+        doc = parse(f.read())
+
+    mem_sec = doc.section("memory")
+    memory = dict(mem_sec.memory) if mem_sec else {}
+    ctx = {"memory": memory}
+
+    workflows = doc.workflows()
+    if workflow_name:
+        workflows = [w for w in workflows if w.name == workflow_name]
+
+    if not workflows:
+        out("No workflow to run.")
+    for wf in workflows:
+        run_workflow(wf, memory, ctx, out)
+
+    hooks_sec = doc.section("on_done")
+    if hooks_sec:
+        _apply_hooks(hooks_sec.hooks, memory, out)
+
+    if write_back and mem_sec is not None:
+        mem_sec.memory = memory
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(to_source(doc))
+        out("\n· memory written back")
+
+    return doc
+
+
+def watch(
+    path: str,
+    workflow_name: str = None,
+    interval: float = 1.0,
+    max_runs: int = 0,
+    write_back: bool = True,
+    out=print,
+) -> None:
+    """Re-run the document whenever it changes on disk (SPEC §5, reactive seed).
+
+    Self-trigger guard: the mtime baseline is captured *after* our own
+    write-back, so the runtime's own writes never cause an infinite re-run loop —
+    only an external edit advances the mtime past the baseline.
+    """
+    out(f"▶ watching {path} (every {interval}s) — edit & save to re-run, Ctrl+C to stop")
+    last = None
+    runs = 0
+    try:
+        while True:
+            try:
+                mtime = os.path.getmtime(path)
+            except OSError:
+                time.sleep(interval)
+                continue
+            if mtime != last:
+                if last is not None:
+                    out("\n↻ change detected")
+                run(path, workflow_name=workflow_name, write_back=write_back, out=out)
+                runs += 1
+                try:  # baseline AFTER write-back so we don't self-trigger
+                    last = os.path.getmtime(path)
+                except OSError:
+                    last = mtime
+                if max_runs and runs >= max_runs:
+                    out(f"\n· reached max-runs={max_runs}, stopping")
+                    return
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        out("\n· stopped")
+
+
+def run_workflow(wf, memory, ctx, out) -> bool:
+    """Run one workflow's steps; returns True if every step succeeded."""
+    out(f"\n▶ workflow: {wf.name or '(unnamed)'}")
+    return run_steps(wf.steps, memory, ctx, out)
+
+
+def run_steps(steps, memory, ctx, out) -> bool:
+    """Run a list of steps top-to-bottom; returns True if all succeeded."""
+    ok_all = True
+    for idx, step in enumerate(steps, 1):
+        if not _run_step(idx, step, memory, ctx, out):
+            ok_all = False
+    return ok_all
+
+
+def _run_step(idx, step, memory, ctx, out) -> bool:
+    plugin = plugins.get(step.plugin)
+    label = f"  step {idx} @{step.plugin}"
+    if plugin is None:
+        out(f"{label} ✗ unknown plugin")
+        return False
+    params = {k: substitute(v, memory) for k, v in step.params.items()}
+    result = plugin(params, ctx)
+    if result.ok:
+        out(f"{label} ✓")
+        _emit(result.output, out)
+    else:
+        out(f"{label} ✗ (exit {result.code})")
+        _emit(result.error or result.output, out)
+    return result.ok
+
+
+def _emit(text, out) -> None:
+    if text and text.strip():
+        for ln in text.rstrip().splitlines():
+            out(f"      {ln}")
+
+
+def _apply_hooks(hooks, memory, out) -> None:
+    for h in hooks:
+        m = _SET_RE.match(h.strip())
+        if not m:
+            continue
+        key, raw = m.group(1), m.group(2)
+        if not key.startswith(RUNTIME_NAMESPACE):
+            out(
+                f"  ⚠ refused: @on_done may only write runtime-owned memory "
+                f"('{RUNTIME_NAMESPACE}*'); '{key}' is agent-owned and was left "
+                f"untouched."
+            )
+            continue
+        memory[key] = parse_scalar(raw)

runxmd/memory.py

@@ -0,0 +1,22 @@
+"""Memory substitution — power #2 of three (SPEC §4).
+
+Resolves ``{{ memory.<key> }}`` references inside step params before execution.
+Read-in and write-back are handled by the parser + executor; this module is just
+the templating layer.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_REF = re.compile(r"\{\{\s*memory\.([a-zA-Z0-9_.]+)\s*\}\}")
+
+
+def substitute(value: Any, memory: dict) -> Any:
+    """Replace ``{{ memory.key }}`` in a string. Non-strings pass through.
+
+    Missing keys resolve to empty string (SPEC §4).
+    """
+    if not isinstance(value, str):
+        return value
+    return _REF.sub(lambda m: str(memory.get(m.group(1), "")), value)