otto-cli-agent 0.1.2__tar.gz → 0.1.4__tar.gz

{otto_cli_agent-0.1.2 → otto_cli_agent-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: otto-cli-agent
-Version: 0.1.2
+Version: 0.1.4
 Summary: Otto: a terminal AI agent built around measured results -- one agent loop, a rubric-first evaluator, tiered memory, multi-vendor routing, and six benchmark harnesses.
 Project-URL: Repository, https://github.com/siddharth23P/otto_agent
 Project-URL: Issues, https://github.com/siddharth23P/otto_agent/issues
@@ -46,11 +46,12 @@ Requires-Dist: langchain>=1.4.0
 Requires-Dist: langfuse>=4.15.1
 Requires-Dist: langgraph>=1.2.11
 Requires-Dist: numpy>=1.26.2
-Requires-Dist: openpyxl>=3.1.5; sys_platform != 'android'
+Requires-Dist: openpyxl>=3.1.5
 Requires-Dist: prompt-toolkit>=3.0.53
-Requires-Dist: python-docx>=1.1.2; sys_platform != 'android'
+Requires-Dist: python-docx>=1.1.2
 Requires-Dist: python-dotenv>=1.2.3
-Requires-Dist: reportlab>=4.2; sys_platform != 'android'
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: reportlab>=4.2
 Requires-Dist: textual>=8.2.8
 Requires-Dist: tiktoken>=0.14.0
 Requires-Dist: typer>=0.27.2

{otto_cli_agent-0.1.2 → otto_cli_agent-0.1.4}/README.md

@@ -138,6 +138,7 @@ one interpreter per run), `OTTO_PYTHON_SESSION_MEMORY_MB` (that interpreter's
 address-space ceiling on Linux, default 8192, 0 for none),
 `OTTO_EMBEDDING_MODEL` (`provider:model`; local BGE is the floor),
 `OTTO_MODEL_PRICES` (a JSON file that overrides the price table),
+`OTTO_PROMPT_CACHE=0` (turn off input-token caching, on by default for all four vendors),
 `OTTO_IGNORE_ROUTES=1` (use the shipped routing table untouched; evals do),
 `OTTO_BROWSER_PYTHON` (an interpreter with Playwright and `pyte`, which
 enables the browser and terminal tools), `OTTO_HOME` (where state lives,

{otto_cli_agent-0.1.2 → otto_cli_agent-0.1.4}/agent/phone/README.md

@@ -11,7 +11,8 @@ and binds these through [agent/embed.py](../embed.py).
 | `backend.py` | `PhoneBackend`, the Protocol a host implements (tree, tap, type, press, swipe, scroll, screenshot, apps, launch, settings, install); `PhoneError` with a code and a hand-over flag; `JsonBackend`, the adapter over a bridge whose methods return JSON envelopes |
 | `digest.py` | the accessibility snapshot as bounded, inert text: one `[index] "label" role flags @x,y` line per element, password fields never shown; `find_node` resolves a text target (exact, then unique substring, else the candidates) |
 | `guard.py` + `assets/guard_rules.json` | the rules the phone enforces and this side pre-checks: denied packages, money words, sensitive-screen patterns (two signals required), pay words (never tappable), forward words that become pay words next to a checkout signal, commit words (only through `phone_commit`); a broken rules file is a `GuardRulesError` on every verdict |
-| `tools.py` | `phone_tools(backend)`: nine `ExtraTool`s, `PHONE_GUIDANCE`, and the standing tools a phone cannot run |
+| `actions.py` | the phone's premapped actions as a searchable dictionary: `search`, `describe`; never listed in the prompt |
+| `tools.py` | `phone_tools(backend)`: nine `ExtraTool`s, plus `phone_find` / `phone_action` when the bridge offers `actions()`; `PHONE_GUIDANCE`, and the standing tools a phone cannot run |
 | `notes.py` + `assets/app_notes/` | per-app notes shown after an app's screen the first time it is in front in a run: seeded `<package>.md` files (facts checked on a real phone; Amazon and Settings only) and notes learned by earlier runs, 800 characters in all; guidance only, never read by the guard |
 
 ## The tools

otto_cli_agent-0.1.4/agent/phone/actions.py

@@ -0,0 +1,111 @@
+"""The phone's premapped actions as a dictionary the agent searches.
+
+The app (otto_android actions/ActionCatalog.kt) offers any number of actions -- set an alarm, write an
+SMS, share a file -- each with typed fields. None of them is written into the prompt: the agent calls
+`phone_find` with what it wants to do, reads the matching entries in full, then `phone_action` runs one
+by name. The prompt stays the same size however many actions the phone has.
+
+An entry, as the bridge sends it:
+    {"name": "alarm.set", "summary": "set an alarm in the clock app", "effect": "change|read|confirm",
+     "group": "clock", "keywords": ["wake", "alarm clock"],
+     "params": [{"name": "hour", "type": "integer", "required": true, "doc": "0-23", "min": 0, "max": 23,
+                 "choices": [...]}]}
+"""
+from __future__ import annotations
+
+import re
+
+#: Most entries one search returns in full.
+MAX_FOUND = 5
+
+_WORD = re.compile(r"[a-z0-9]+")
+#: Words that say nothing about which action is meant.
+_FILLER = frozenset("a an the to for of on in my me please set up do can you with and or".split())
+
+
+def clean_menu(menu: object) -> list[dict]:
+    """The entries that have a name, in the phone's order; anything else is dropped."""
+    if not isinstance(menu, list):
+        return []
+    return [a for a in menu if isinstance(a, dict) and isinstance(a.get("name"), str) and a["name"]]
+
+
+def _words(text: str) -> list[str]:
+    return [w for w in _WORD.findall(text.lower()) if w not in _FILLER]
+
+
+def _stem(word: str) -> str:
+    """Crude, but enough for "alarms"/"alarm", "sharing"/"share", "texted"/"text"."""
+    for suffix in ("ing", "ed", "es", "s"):
+        if len(word) > len(suffix) + 2 and word.endswith(suffix):
+            return word[: -len(suffix)]
+    return word
+
+
+def search(menu: list[dict], query: str, limit: int = MAX_FOUND) -> list[dict]:
+    """The entries that best match `query`: a word in the name or the keywords counts most, then the
+    summary, then the group and the fields; ties keep the phone's order. An exact name wins outright."""
+    query = query.strip().lower()
+    for entry in menu:
+        if entry["name"].lower() == query:
+            return [entry]
+    wanted = {_stem(w) for w in _words(query)}
+    if not wanted:
+        return []
+    scored = []
+    for order, entry in enumerate(menu):
+        fields = entry.get("params") or []
+        places = (
+            (3, entry["name"]),
+            (3, " ".join(map(str, entry.get("keywords") or []))),
+            (2, str(entry.get("summary") or "")),
+            (1, str(entry.get("group") or "")),
+            (1, " ".join(f"{p.get('name', '')} {p.get('doc', '')} {' '.join(map(str, p.get('choices') or []))}"
+                         for p in fields if isinstance(p, dict))),
+        )
+        score = 0
+        for weight, text in places:
+            have = {_stem(w) for w in _words(text)}
+            score += weight * len(wanted & have)
+        if score:
+            scored.append((-score, order, entry))
+    scored.sort(key=lambda s: s[:2])
+    # A match far weaker than the best is noise ("call dad" also names a volume stream).
+    floor = -scored[0][0] / 3 if scored else 0
+    return [entry for score, _, entry in scored[:limit] if -score >= floor]
+
+
+def describe(entry: dict) -> str:
+    """One entry in full: how to call it, and what each field takes.
+
+        alarm.set -- set an alarm in the clock app
+          hour: integer 0..23, required
+          days: list of mon|tue|..., optional -- repeat on these days
+    """
+    you = " (the person finishes it: the phone is handed to them)" if entry.get("effect") == "confirm" else ""
+    lines = [f"{entry['name']} -- {entry.get('summary', '')}{you}".rstrip(" -")]
+    for p in entry.get("params") or []:
+        if not isinstance(p, dict):
+            continue
+        kind = {"string": "text", "string_list": "list of text"}.get(str(p.get("type")), str(p.get("type", "any")))
+        if p.get("choices"):
+            kind = ("list of " if p.get("type") == "string_list" else "") + "|".join(map(str, p["choices"]))
+        if p.get("min") is not None or p.get("max") is not None:
+            kind += f" {_num(p.get('min'))}..{_num(p.get('max'))}"
+        need = "required" if p.get("required", True) else "optional"
+        doc = f" -- {p['doc']}" if p.get("doc") else ""
+        lines.append(f"  {p.get('name')}: {kind}, {need}{doc}")
+    if len(lines) == 1:
+        lines.append("  (no fields)")
+    return "\n".join(lines)
+
+
+def _num(value: object) -> str:
+    if value is None:
+        return ""
+    return str(int(value)) if isinstance(value, float) and value.is_integer() else str(value)
+
+
+def near(menu: list[dict], name: str) -> list[str]:
+    """Names to suggest for a name the phone does not have."""
+    return [e["name"] for e in search(menu, name.replace(".", " ").replace("_", " "), limit=3)]

{otto_cli_agent-0.1.2 → otto_cli_agent-0.1.4}/agent/phone/backend.py

@@ -34,7 +34,7 @@ from typing import Any, Protocol, runtime_checkable
 #: capability the device lacks (no accessibility service running, no
 #: screenshot permission); `timeout` a gesture or capture that never
 #: completed.
-ERROR_CODES = ("guard", "refused", "stale", "unsupported", "failed", "timeout")
+ERROR_CODES = ("guard", "refused", "stale", "unsupported", "invalid", "failed", "timeout")
 
 
 class PhoneError(Exception):
@@ -150,6 +150,18 @@ class JsonBackend:
     def install(self, package: str = "", query: str = "") -> dict:
         return self._call("install", str(package or ""), str(query or ""))
 
+    # Optional, not part of PhoneBackend: the phone's own action registry (the Android app's
+    # actions/ActionCatalog.kt). A backend without it simply offers no phone_action tool.
+
+    def actions(self) -> list[dict]:
+        """[{"name", "summary", "effect": read|change|confirm, "params": [{"name", "type", ...}]}]."""
+        reply = self._call("actions")
+        return list(reply.get("actions") or []) if isinstance(reply, dict) else []
+
+    def run_action(self, name: str, args: dict) -> dict:
+        """{"done", "handed_over"?, "data"?}"""
+        return self._call("run_action", str(name), json.dumps(args or {}))
+
 
 def _unwrap(method: str, reply: Any) -> Any:
     """The `data` of an ok envelope, a PhoneError for an error envelope, and

{otto_cli_agent-0.1.2 → otto_cli_agent-0.1.4}/agent/phone/tools.py

@@ -42,6 +42,7 @@ from collections.abc import Callable
 from typing import Any
 
 from agent.phone import digest as _digest
+from agent.phone import actions as _actions
 from agent.phone import guard
 from agent.phone import notes as _notes
 from agent.phone.backend import PhoneBackend, PhoneError
@@ -61,6 +62,8 @@ PHONE_DISABLED_STANDING_TOOLS: frozenset[str] = frozenset({
 #: Bound with the tools (agent/pipeline/toolkit.py `guidance=`).
 PHONE_GUIDANCE = (
     "You are working on the person's Android phone through phone_* tools. "
+    "The phone is the last resort: use phone_* only for steps that need the device, and make "
+    "files with make_document, never in an app. "
     "Look, act, look again: phone_screen shows what is on screen with a [number] per element; "
     "phone_act acts on one element by its text and shows the screen after. "
     "When you already know the next few steps (tap the search box, type the query, press enter -- the "
@@ -128,14 +131,13 @@ def _default_vision(question: str, data: bytes, media_type: str) -> str:
     """The `look` tool's path: the routed vision model, words back, vendor
     exceptions translated into Otto's own so the loop reads a failed call."""
     from agent.pipeline import tools as pt
-    from agent.pipeline.vision import describe_image
-    from agent.router.mapping import Task
+    from agent.pipeline.vision import describe_with_fallback
 
-    llm = pt._get_router().chat_model(Task.VISION)
-    try:
-        return describe_image(llm, base64.b64encode(data).decode(), media_type, question)
-    except Exception as exc:
-        raise pt._translated(llm, exc) from exc
+    # Down the VISION chain (Gemini 3.8/3.7/3.6 Flash, then Claude, then GPT-5-mini) when a model
+    # cannot answer; one retry each, so an account out of credit costs seconds, not a minute.
+    answer, _ = describe_with_fallback(pt._get_router(), base64.b64encode(data).decode(), media_type,
+                                       question, max_retries=1)
+    return answer
 
 
 def phone_tools(backend: PhoneBackend, *, vision: Vision | None = None) -> list[ExtraTool]:
@@ -735,6 +737,54 @@ def phone_tools(backend: PhoneBackend, *, vision: Vision | None = None) -> list[
         except PhoneError as exc:
             return _failed(name, exc)
 
+    def phone_find(body: str) -> ToolResult:
+        name = "phone_find"
+        parsed = json_body(name, body)
+        if isinstance(parsed, ToolResult):
+            return parsed
+        query = str(parsed.get("query") or "").strip()
+        if not query:
+            groups: dict[str, list[str]] = {}
+            for entry in menu:
+                groups.setdefault(str(entry.get("group") or "other"), []).append(entry["name"])
+            listing = "\n".join(f"{group}: {', '.join(names)}" for group, names in groups.items())
+            return ToolResult(stdout=f"{len(menu)} actions; search one to see its fields.\n{listing}", stderr="", returncode=0)
+        found = _actions.search(menu, query)
+        if not found:
+            return ToolResult(stdout=f"no premapped action for {query!r} -- use the screen tools", stderr="", returncode=0)
+        text = "\n".join(_actions.describe(entry) for entry in found)
+        return ToolResult(stdout=text + '\nRun one with phone_action {"action": name, ...fields}.', stderr="", returncode=0)
+
+    def phone_action(body: str) -> ToolResult:
+        name = "phone_action"
+        parsed = json_body(name, body)
+        if isinstance(parsed, ToolResult):
+            return parsed
+        action = str(parsed.pop("action", "") or "")
+        entry = next((e for e in menu if e["name"] == action), None)
+        if entry is None:
+            hint = ", ".join(_actions.near(menu, action)) or "none close -- search with phone_find"
+            return _bad(name, f"the phone has no action {action!r}; nearest: {hint}")
+        if (app := str(parsed.get("app") or "")) and (why := guard.package_verdict(app, "")):
+            return _refuse(name, why)
+        try:
+            result = backend.run_action(action, parsed)
+        except PhoneError as exc:
+            failed = _failed(name, exc)
+            if exc.code == "invalid":
+                # The whole entry, so the next call can be right without another search.
+                failed = dataclasses.replace(failed, stderr=f"{failed.stderr}\n{_actions.describe(entry)}")
+            return failed
+        text = str(result.get("done") or "done")
+        if result.get("data") is not None:
+            text += "\n" + json.dumps(result["data"], ensure_ascii=False)[:MAX_ACTION_DATA]
+        if result.get("handed_over"):
+            # A message, call or event the person finishes: stop, and say what is ready for them.
+            return ToolResult(stdout=f"GUARD: {name}: {text}{HANDOVER_TAIL}", stderr="", returncode=0)
+        return ToolResult(stdout=text, stderr="", returncode=0)
+
+    menu = _action_menu(backend)
+
     tools = [
         ExtraTool("phone_screen", "The phone's screen as text: the app in front and every element with a "
                   "[number], its text, role, flags and centre. Empty body {}.", phone_screen,
@@ -770,9 +820,45 @@ def phone_tools(backend: PhoneBackend, *, vision: Vision | None = None) -> list[
                                                             "query": {"type": "string"}}},
                   fold=_digest.fold_result),
     ]
+    # The phone's premapped actions, as a dictionary: searched, never listed in the prompt.
+    if menu:
+        tools[:0] = [
+            ExtraTool("phone_find", FIND_DESCRIPTION, phone_find, mutates=False,
+                      schema={"type": "object", "properties": {"query": {"type": "string"}}}),
+            ExtraTool("phone_action", ACTION_DESCRIPTION, phone_action, mutates=False,
+                      schema={"type": "object", "required": ["action"], "properties": {"action": {"type": "string"}}}),
+        ]
     return [dataclasses.replace(tool, call=_logged(tool.name, tool.call)) for tool in tools]
 
 
+#: How much of an action's returned data (contacts found) goes back to the model.
+MAX_ACTION_DATA = 1500
+
+
+def _action_menu(backend) -> list[dict]:
+    """The phone's action registry, or [] when this phone has none (an older app, a fake)."""
+    lister = getattr(backend, "actions", None)
+    if lister is None:
+        return []
+    try:
+        menu = lister()
+    except Exception as exc:  # noqa: BLE001 -- no registry is a phone without the tool, not a failed turn
+        logger.info("phone actions unavailable: %s", exc)
+        return []
+    return _actions.clean_menu(menu)
+
+
+FIND_DESCRIPTION = (
+    "Search the phone's premapped actions (alarms, timers, calendar, torch, volume, media, DND, messages, calls, "
+    "contacts, sharing, links, maps, clipboard, notes, more) by what you want done; returns matches with their "
+    "fields. Search before reading screens. Empty query lists all."
+)
+ACTION_DESCRIPTION = (
+    "Run an action phone_find returned: {\"action\": name, ...its fields}. One marked 'the person finishes it' "
+    "opens the screen and hands the phone to them."
+)
+
+
 #: How much of a body or a result one log line carries.
 MAX_LOGGED = 160
 
@@ -799,9 +885,9 @@ def _asked(body: str) -> str:
         if not isinstance(step, dict):
             shown.append("?")
             continue
-        fields = {k: v for k, v in step.items() if k != "text"}
-        if "text" in step:
-            fields["text"] = f"<{len(str(step['text']))} chars>"
+        # What a person would write (a typed text, a message, a note) or whom it goes to is logged as its length.
+        private = ("text", "body", "subject", "notes", "to", "cc", "phone", "number", "query")
+        fields = {k: (f"<{len(str(v))} chars>" if k in private else v) for k, v in step.items()}
         shown.append(" ".join(f"{k}={_digest.inert_text(str(v), 60)}" for k, v in fields.items()))
     return " ; ".join(shown)[:MAX_LOGGED]
 

otto_cli_agent-0.1.4/agent/pipeline/documents.py

@@ -0,0 +1,323 @@
+"""Documents otto makes: Markdown into PDF, Word, Excel or PowerPoint, in this process.
+
+The research route converts its report with a script on the workspace's interpreter, which a host
+with code execution off (the Android app) does not have -- so on a phone there was no way to make a
+file, and a request for one went to the phone's own apps instead (2026-09-17: "create a pdf from
+this doc" drove My Files and Google Docs for minutes). These writers need no subprocess: pure-Python
+libraries (reportlab, python-docx, openpyxl, python-pptx; lxml and Pillow have Android builds).
+
+One small Markdown reader feeds all four: headings, paragraphs, bullet and numbered lists, tables
+and fenced code. Emphasis and links are reduced to their text.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+FORMATS = ("pdf", "docx", "xlsx", "pptx", "md")
+#: Where make_document writes, inside the workspace.
+OUT_DIR = "documents"
+
+_HEADING = re.compile(r"^(#{1,6})\s+(.*)$")
+_BULLET = re.compile(r"^\s*[-*+]\s+(.*)$")
+_NUMBERED = re.compile(r"^\s*\d+[.)]\s+(.*)$")
+_RULE = re.compile(r"^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$")
+
+
+@dataclass
+class Block:
+    kind: str                       # heading | paragraph | bullets | numbered | table | code
+    text: str = ""
+    level: int = 0
+    items: list[str] = field(default_factory=list)
+    rows: list[list[str]] = field(default_factory=list)
+
+
+def plain(text: str) -> str:
+    """Markdown emphasis, code spans and links reduced to their text."""
+    text = re.sub(r"\*\*(.+?)\*\*|__(.+?)__", lambda m: m.group(1) or m.group(2), text)
+    text = re.sub(r"(?<![\w*])\*(?!\s)(.+?)(?<!\s)\*(?!\w)", r"\1", text)
+    text = re.sub(r"(?<!\w)_(?!\s)(.+?)(?<!\s)_(?!\w)", r"\1", text)
+    text = re.sub(r"!?\[([^\]]*)\]\([^)]*\)", r"\1", text)
+    return re.sub(r"`([^`]*)`", r"\1", text).strip()
+
+
+def _cells(line: str) -> list[str]:
+    inner = line.strip()
+    inner = inner[1:] if inner.startswith("|") else inner
+    inner = inner[:-1] if inner.endswith("|") else inner
+    return [plain(c) for c in re.split(r"(?<!\\)\|", inner)]
+
+
+def parse(markdown: str) -> list[Block]:
+    blocks: list[Block] = []
+    para: list[str] = []
+    fence: list[str] | None = None
+
+    def flush() -> None:
+        if para:
+            blocks.append(Block("paragraph", plain(" ".join(para))))
+            para.clear()
+
+    lines = markdown.replace("\r\n", "\n").split("\n")
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if line.strip().startswith("```"):
+            if fence is None:
+                flush()
+                fence = []
+            else:
+                blocks.append(Block("code", "\n".join(fence)))
+                fence = None
+            i += 1
+            continue
+        if fence is not None:
+            fence.append(line)
+            i += 1
+            continue
+        s = line.rstrip()
+        if not s.strip():
+            flush()
+        elif m := _HEADING.match(s):
+            flush()
+            blocks.append(Block("heading", plain(m.group(2)), level=len(m.group(1))))
+        elif s.lstrip().startswith("|"):
+            flush()
+            rows = []
+            while i < len(lines) and lines[i].lstrip().startswith("|"):
+                if not _RULE.match(lines[i]):
+                    rows.append(_cells(lines[i]))
+                i += 1
+            width = max(len(r) for r in rows)
+            blocks.append(Block("table", rows=[r + [""] * (width - len(r)) for r in rows]))
+            continue
+        elif (m := _BULLET.match(s)) or (n := _NUMBERED.match(s)):
+            flush()
+            kind = "bullets" if m else "numbered"
+            item = plain((m or n).group(1))
+            if blocks and blocks[-1].kind == kind and not blocks[-1].text:
+                blocks[-1].items.append(item)
+            else:
+                blocks.append(Block(kind, items=[item]))
+        else:
+            if blocks and blocks[-1].kind in ("bullets", "numbered") and not para and line.startswith("  "):
+                blocks[-1].items[-1] += " " + plain(s)
+            else:
+                para.append(s.strip())
+        i += 1
+    if fence is not None:
+        blocks.append(Block("code", "\n".join(fence)))
+    flush()
+    return blocks
+
+
+def title_of(blocks: list[Block], fallback: str) -> str:
+    return next((b.text for b in blocks if b.kind == "heading"), fallback)
+
+
+# -- writers -----------------------------------------------------------------------------------
+
+def _docx(blocks: list[Block], target: Path, title: str) -> None:
+    from docx import Document
+
+    doc = Document()
+    doc.core_properties.title = title
+    for b in blocks:
+        if b.kind == "heading":
+            doc.add_heading(b.text, min(b.level - 1, 4) if b.level > 1 else 0)
+        elif b.kind == "paragraph":
+            doc.add_paragraph(b.text)
+        elif b.kind in ("bullets", "numbered"):
+            style = "List Bullet" if b.kind == "bullets" else "List Number"
+            for item in b.items:
+                doc.add_paragraph(item, style=style)
+        elif b.kind == "table":
+            table = doc.add_table(rows=len(b.rows), cols=len(b.rows[0]))
+            table.style = "Table Grid"
+            for r, row in enumerate(b.rows):
+                for c, value in enumerate(row):
+                    cell = table.cell(r, c)
+                    cell.text = value
+                    if r == 0:
+                        for run in cell.paragraphs[0].runs:
+                            run.bold = True
+        elif b.kind == "code":
+            for code_line in b.text.split("\n"):
+                doc.add_paragraph(code_line, style="No Spacing")
+    doc.save(str(target))
+
+
+def _pdf(blocks: list[Block], target: Path, title: str) -> None:
+    from xml.sax.saxutils import escape
+
+    from reportlab.lib import colors
+    from reportlab.lib.pagesizes import A4
+    from reportlab.lib.styles import getSampleStyleSheet
+    from reportlab.lib.units import cm
+    from reportlab.platypus import ListFlowable, ListItem, Paragraph, Preformatted, SimpleDocTemplate, Spacer, Table, TableStyle
+
+    styles = getSampleStyleSheet()
+    heading = {1: styles["Title"], 2: styles["Heading1"], 3: styles["Heading2"]}
+    body = styles["BodyText"]
+    story = []
+    for b in blocks:
+        if b.kind == "heading":
+            story.append(Paragraph(escape(b.text), heading.get(b.level, styles["Heading3"])))
+        elif b.kind == "paragraph":
+            story += [Paragraph(escape(b.text), body), Spacer(1, 0.2 * cm)]
+        elif b.kind in ("bullets", "numbered"):
+            story.append(ListFlowable([ListItem(Paragraph(escape(i), body)) for i in b.items],
+                                      bulletType="bullet" if b.kind == "bullets" else "1"))
+            story.append(Spacer(1, 0.2 * cm))
+        elif b.kind == "table":
+            data = [[Paragraph(escape(v), body) for v in row] for row in b.rows]
+            table = Table(data, repeatRows=1, hAlign="LEFT")
+            table.setStyle(TableStyle([
+                ("GRID", (0, 0), (-1, -1), 0.4, colors.grey),
+                ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#eeeeee")),
+                ("VALIGN", (0, 0), (-1, -1), "TOP"),
+            ]))
+            story += [table, Spacer(1, 0.3 * cm)]
+        elif b.kind == "code":
+            story.append(Preformatted(b.text, styles["Code"]))
+    SimpleDocTemplate(str(target), pagesize=A4, title=title, leftMargin=2 * cm, rightMargin=2 * cm,
+                      topMargin=2 * cm, bottomMargin=2 * cm).build(story or [Paragraph("", body)])
+
+
+def _number(value: str):
+    """A cell's value as a number when it reads as one ("1,200", "12.5", "40%"), else the text."""
+    s = value.strip().replace(",", "")
+    try:
+        if s.endswith("%"):
+            return float(s[:-1]) / 100
+        return int(s) if re.fullmatch(r"-?\d+", s) else float(s)
+    except ValueError:
+        return value
+
+
+def _xlsx(blocks: list[Block], target: Path, title: str) -> None:
+    """Every table on a sheet of its own (named by the heading above it), numbers as numbers; any
+    other text on a "Notes" sheet."""
+    from openpyxl import Workbook
+    from openpyxl.styles import Font
+    from openpyxl.utils import get_column_letter
+
+    wb = Workbook()
+    wb.remove(wb.active)
+    used: set[str] = set()
+
+    def sheet(name: str):
+        base = re.sub(r"[\[\]:*?/\\]", " ", name).strip()[:28] or "Sheet"
+        unique, n = base, 2
+        while unique.lower() in used:
+            unique, n = f"{base[:25]}-{n}", n + 1
+        used.add(unique.lower())
+        return wb.create_sheet(unique)
+
+    last_heading = title
+    notes = []
+    for b in blocks:
+        if b.kind == "heading":
+            last_heading = b.text
+            notes.append([b.text])
+        elif b.kind == "table":
+            ws = sheet(last_heading)
+            for r, row in enumerate(b.rows):
+                ws.append(row if r == 0 else [_number(v) for v in row])
+            for cell in ws[1]:
+                cell.font = Font(bold=True)
+            ws.freeze_panes = "A2"
+            for c in range(1, len(b.rows[0]) + 1):
+                width = max(len(str(ws.cell(r, c).value or "")) for r in range(1, ws.max_row + 1))
+                ws.column_dimensions[get_column_letter(c)].width = min(max(10, width + 2), 60)
+        elif b.kind == "paragraph" or b.kind == "code":
+            notes.append([b.text])
+        else:
+            notes += [[("• " if b.kind == "bullets" else f"{k}. ") + item] for k, item in enumerate(b.items, 1)]
+    has_text = any(b.kind not in ("heading", "table") for b in blocks)
+    if has_text or (notes and not wb.sheetnames):
+        ws = sheet("Notes")
+        for row in notes:
+            ws.append(row)
+        ws.column_dimensions["A"].width = 100
+    if not wb.sheetnames:
+        wb.create_sheet("Sheet")
+    wb.save(str(target))
+
+
+def _pptx(blocks: list[Block], target: Path, title: str) -> None:
+    """A title slide, then a slide per heading: its paragraphs and list items as bullets (at most
+    eight a slide, the rest on continuation slides), and a table as a table."""
+    from pptx import Presentation
+    from pptx.util import Inches, Pt
+
+    prs = Presentation()
+    prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+    first = prs.slides.add_slide(prs.slide_layouts[0])
+    first.shapes.title.text = title
+    subtitle = next((b.text for b in blocks if b.kind == "paragraph"), "")
+    if len(first.placeholders) > 1:
+        first.placeholders[1].text = subtitle[:200]
+
+    slides: list[tuple[str, list]] = []
+    current: tuple[str, list] | None = None
+    for b in blocks:
+        if b.kind == "heading":
+            if b.text == title and current is None:
+                continue
+            current = (b.text, [])
+            slides.append(current)
+            continue
+        if current is None:
+            current = (title, [])
+            slides.append(current)
+        if b.kind == "paragraph" and b.text != subtitle:
+            current[1].append(b.text)
+        elif b.kind in ("bullets", "numbered"):
+            current[1].extend(b.items)
+        elif b.kind == "table":
+            current[1].append(b)
+        elif b.kind == "code":
+            current[1].extend(b.text.split("\n")[:8])
+
+    for heading, items in slides:
+        bullets = [i for i in items if isinstance(i, str)]
+        tables = [i for i in items if isinstance(i, Block)]
+        chunks = [bullets[k:k + 8] for k in range(0, len(bullets), 8)] or ([[]] if not tables else [])
+        for n, chunk in enumerate(chunks):
+            slide = prs.slides.add_slide(prs.slide_layouts[1])
+            slide.shapes.title.text = heading if n == 0 else f"{heading} (cont.)"
+            frame = slide.placeholders[1].text_frame
+            for k, text in enumerate(chunk):
+                para = frame.paragraphs[0] if k == 0 else frame.add_paragraph()
+                para.text = text[:300]
+                para.font.size = Pt(20 if len(chunk) <= 5 else 16)
+        for table_block in tables:
+            slide = prs.slides.add_slide(prs.slide_layouts[5])
+            slide.shapes.title.text = heading
+            rows, cols = len(table_block.rows), len(table_block.rows[0])
+            shape = slide.shapes.add_table(rows, cols, Inches(0.5), Inches(1.5), Inches(12.3), Inches(0.4) * rows)
+            for r, row in enumerate(table_block.rows):
+                for c, value in enumerate(row):
+                    shape.table.cell(r, c).text = value
+                    shape.table.cell(r, c).text_frame.paragraphs[0].font.size = Pt(14)
+    prs.save(str(target))
+
+
+WRITERS = {"docx": _docx, "pdf": _pdf, "xlsx": _xlsx, "pptx": _pptx}
+
+
+def write(markdown: str, target: Path, fmt: str, title: str = "") -> Path:
+    """`markdown` as a `fmt` file at `target`. Raises ValueError for an unknown format, and the
+    writer's own error (a missing library, a bad table) otherwise."""
+    if fmt not in FORMATS:
+        raise ValueError(f"no {fmt!r} format; choose one of {', '.join(FORMATS)}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if fmt == "md":
+        target.write_text(markdown, encoding="utf-8")
+        return target
+    blocks = parse(markdown)
+    WRITERS[fmt](blocks, target, title or title_of(blocks, target.stem))
+    return target