tithon 0.1.0__py3-none-any.whl

tithon/__init__.py

@@ -0,0 +1,3 @@
+"""Tithon — persistent remote interactive Python sessions (Phase 0 PoC)."""
+
+__version__ = "0.0.1"

tithon/__main__.py

@@ -0,0 +1,7 @@
+"""Enable `python -m tithon ...` (a robust alternative to the `tithon` console
+script when it isn't on PATH — e.g. inside a VSCode remote/tunnel extension host).
+"""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

tithon/artifacts.py

@@ -0,0 +1,91 @@
+"""Rich-output artifact store: image payloads become real files on disk.
+
+Base64 image data never enters the journal (SPEC.md) — it is decoded
+on receipt, written to ``<workdir>/.tithon/outputs/`` with an sha-based
+filename, deduplicated by sha256, and the message content carries only a
+``$tithon_artifact`` reference.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+from pathlib import Path
+
+from .journal import Journal
+
+EXTENSIONS = {"image/png": "png", "image/jpeg": "jpg"}
+OUTPUTS_REL = Path(".tithon") / "outputs"
+
+
+class ArtifactStore:
+    def __init__(self, workdir: Path, journal: Journal):
+        self.workdir = workdir
+        self.outputs_dir = workdir / OUTPUTS_REL
+        self.journal = journal
+        self._counter = 0
+
+    def extract(self, exec_id: str, content: dict) -> list[str]:
+        """Replace rich image mime payloads in ``content['data']`` with refs.
+
+        Returns the artifact ids referenced (possibly empty). Mutates content.
+        """
+        data = content.get("data")
+        if not isinstance(data, dict):
+            return []
+        refs: list[str] = []
+        for mime, ext in EXTENSIONS.items():
+            payload = data.get(mime)
+            if not isinstance(payload, str):
+                continue
+            try:
+                raw = base64.b64decode(payload, validate=False)
+            except Exception:
+                continue
+            sha = hashlib.sha256(raw).hexdigest()
+            existing = self.journal.find_artifact(sha)
+            if existing is not None:
+                rel_path = existing[3]
+            else:
+                self.outputs_dir.mkdir(parents=True, exist_ok=True)
+                fname = f"{exec_id}_{self._counter}_{sha[:8]}.{ext}"
+                self._counter += 1
+                rel_path = str(OUTPUTS_REL / fname)
+                (self.workdir / rel_path).write_bytes(raw)
+                self.journal.register_artifact(sha, sha, mime, rel_path, len(raw))
+            data[mime] = {
+                "$tithon_artifact": {
+                    "artifact_id": sha,
+                    "mime": mime,
+                    "rel_path": rel_path,
+                    "sha256": sha,
+                }
+            }
+            refs.append(sha)
+        return refs
+
+    def delete(self, artifact_id: str) -> None:
+        """Remove a superseded artifact's file and journal row.
+
+        Called when no live folded snapshot references the artifact anymore (a
+        live-updating matplotlib plot supersedes its previous frame every step,
+        so without this ``.tithon/outputs/`` grows one file per step forever).
+        """
+        row = self.journal.find_artifact(artifact_id)
+        if row is not None:
+            rel_path = row[3]
+            (self.workdir / rel_path).unlink(missing_ok=True)
+        self.journal.delete_artifact(artifact_id)
+
+    def sweep(self, keep: set[str]) -> int:
+        """Delete every registered artifact whose id is not in ``keep``.
+
+        Run once after the daemon rebuilds its folds on (re)start, to reclaim
+        frames that accumulated before this GC existed or while the daemon was
+        down. Returns the number of artifacts removed.
+        """
+        removed = 0
+        for artifact_id, _rel_path in self.journal.all_artifacts():
+            if artifact_id not in keep:
+                self.delete(artifact_id)
+                removed += 1
+        return removed

tithon/cli.py

@@ -0,0 +1,241 @@
+"""Tithon CLI: ``tithon daemon | run | attach | status``."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+
+def get_home() -> Path:
+    return Path(os.environ.get("TITHON_HOME", str(Path.home() / ".tithon"))).expanduser()
+
+
+def sock_path() -> str:
+    return str(get_home() / "daemon.sock")
+
+
+async def _connect():
+    from websockets.asyncio.client import unix_connect
+
+    return unix_connect(sock_path(), max_size=None)
+
+
+def cmd_daemon(args) -> int:
+    home = get_home()
+    home.mkdir(parents=True, exist_ok=True)
+    level = getattr(logging, args.log_level.upper())
+    fmt = "%(asctime)s %(name)s %(levelname)s %(message)s"
+    root = logging.getLogger()
+    root.setLevel(level)
+    # Always write to daemon.log for post-mortem analysis.
+    fh = logging.FileHandler(str(home / "daemon.log"))
+    fh.setFormatter(logging.Formatter(fmt))
+    root.addHandler(fh)
+    # Always echo to stderr so `tithon daemon` shows live activity in the terminal.
+    sh = logging.StreamHandler()
+    sh.setFormatter(logging.Formatter(fmt))
+    root.addHandler(sh)
+    from .daemon import Daemon
+
+    asyncio.run(Daemon(home, Path.cwd()).run())
+    return 0
+
+
+def _render_output(payload: dict) -> None:
+    msg_type = payload.get("msg_type")
+    content = payload.get("content", {})
+    if msg_type == "stream":
+        out = sys.stderr if content.get("name") == "stderr" else sys.stdout
+        out.write(content.get("text", ""))
+        out.flush()
+    elif msg_type == "execute_result":
+        text = (content.get("data") or {}).get("text/plain", "")
+        print(text)
+    elif msg_type == "error":
+        for line in content.get("traceback", []):
+            print(line, file=sys.stderr)
+    elif msg_type in ("display_data", "update_display_data"):
+        data = content.get("data") or {}
+        for value in data.values():
+            if isinstance(value, dict) and "$tithon_artifact" in value:
+                print(f"[artifact] {value['$tithon_artifact']['rel_path']}")
+                break
+        else:
+            print(f"[display] {sorted(data)}")
+
+
+async def _run(args) -> int:
+    async with await _connect() as ws:
+        await ws.send(json.dumps({"op": "attach", "last_seen_seq": -1, "session": args.session}))
+        while True:
+            m = json.loads(await ws.recv())
+            if m.get("op") == "sync":
+                break
+        await ws.send(json.dumps({"op": "execute", "code": args.code, "session": args.session}))
+        exec_id = None
+        buffered: list[dict] = []
+
+        def handle(ev: dict) -> str | None:
+            """Returns final status if this event completes our execution."""
+            if ev.get("exec_id") != exec_id:
+                return None
+            kind = ev.get("kind")
+            if kind == "output":
+                _render_output(ev.get("payload", {}))
+            elif kind == "done":
+                return ev.get("payload", {}).get("status", "ok")
+            return None
+
+        while True:
+            m = json.loads(await ws.recv())
+            op = m.get("op")
+            if op == "execute_ack":
+                exec_id = m["exec_id"]
+                if args.no_wait:
+                    print(exec_id)
+                    return 0
+                for ev in buffered:
+                    status = handle(ev)
+                    if status is not None:
+                        return 0 if status == "ok" else 1
+                buffered.clear()
+            elif op == "event":
+                if exec_id is None:
+                    buffered.append(m)
+                    continue
+                status = handle(m)
+                if status is not None:
+                    return 0 if status == "ok" else 1
+
+
+def cmd_run(args) -> int:
+    coro = _run(args)
+    if args.timeout > 0:
+        coro = asyncio.wait_for(coro, args.timeout)
+    return asyncio.run(coro)
+
+
+async def _attach(args) -> int:
+    async with await _connect() as ws:
+        await ws.send(json.dumps(
+            {"op": "attach", "last_seen_seq": args.since, "session": args.session}))
+        async for raw in ws:
+            text = raw if isinstance(raw, str) else raw.decode()
+            print(text, flush=True)
+            m = json.loads(text)
+            if args.once and m.get("op") == "sync":
+                return 0
+            if args.until_done and m.get("op") == "event" and m.get("kind") == "done":
+                return 0
+    return 0
+
+
+def cmd_attach(args) -> int:
+    return asyncio.run(_attach(args))
+
+
+async def _status(args) -> int:
+    async with await _connect() as ws:
+        op = {"op": "status"}
+        if args.session is not None:
+            op["session"] = args.session
+        await ws.send(json.dumps(op))
+        m = json.loads(await ws.recv())
+        print(json.dumps(m, indent=2))
+    return 0
+
+
+def cmd_status(args) -> int:
+    return asyncio.run(_status(args))
+
+
+async def _kernel_op(op: str, session: str) -> int:
+    async with await _connect() as ws:
+        await ws.send(json.dumps({"op": op, "session": session}))
+        m = json.loads(await ws.recv())
+        print(json.dumps(m, indent=2))
+    return 0
+
+
+def cmd_restart(args) -> int:
+    return asyncio.run(_kernel_op("restart_kernel", args.session))
+
+
+def cmd_interrupt(args) -> int:
+    return asyncio.run(_kernel_op("interrupt", args.session))
+
+
+async def _shutdown(kill_kernels: bool) -> int:
+    async with await _connect() as ws:
+        await ws.send(json.dumps({"op": "shutdown", "kill_kernels": kill_kernels}))
+        try:
+            m = json.loads(await ws.recv())
+            print(json.dumps(m, indent=2))
+        except Exception:
+            pass
+    return 0
+
+
+def cmd_shutdown(args) -> int:
+    return asyncio.run(_shutdown(args.kill_kernels))
+
+
+def main(argv=None) -> None:
+    p = argparse.ArgumentParser(prog="tithon")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("daemon", help="run the tithon daemon (foreground)")
+    sp.add_argument(
+        "--log-level",
+        default="INFO",
+        metavar="LEVEL",
+        help="logging verbosity: DEBUG|INFO|WARNING|ERROR (default: INFO)",
+    )
+    sp.set_defaults(fn=cmd_daemon)
+
+    sp = sub.add_parser("run", help="execute code in a session")
+    sp.add_argument("-c", "--code", required=True)
+    sp.add_argument("--session", default="default", help="session id (file uri); per-file kernel")
+    sp.add_argument("--no-wait", action="store_true", help="submit and exit (prints exec_id)")
+    sp.add_argument("--timeout", type=float, default=0.0)
+    sp.set_defaults(fn=cmd_run)
+
+    sp = sub.add_parser("attach", help="attach and stream events as NDJSON")
+    sp.add_argument("--session", default="default", help="session id (file uri); per-file kernel")
+    sp.add_argument("--since", type=int, default=0, help="last seen seq (0=full snapshot)")
+    sp.add_argument("--once", action="store_true", help="exit after backlog sync")
+    sp.add_argument("--until-done", action="store_true", help="exit after a done event")
+    sp.set_defaults(fn=cmd_attach)
+
+    sp = sub.add_parser("status", help="print daemon status (all sessions) or one session")
+    sp.add_argument("--session", default=None, help="session id; omit for all-sessions status")
+    sp.set_defaults(fn=cmd_status)
+
+    sp = sub.add_parser("restart", help="restart a session's kernel (fresh namespace)")
+    sp.add_argument("--session", default="default", help="session id (file uri)")
+    sp.set_defaults(fn=cmd_restart)
+
+    sp = sub.add_parser("interrupt", help="interrupt the running cell (SIGINT)")
+    sp.add_argument("--session", default="default", help="session id (file uri)")
+    sp.set_defaults(fn=cmd_interrupt)
+
+    sp = sub.add_parser("shutdown", help="stop the daemon (kernels stay detached unless --kill-kernels)")
+    sp.add_argument("--kill-kernels", action="store_true",
+                    help="also kill kernels (fresh start, e.g. interpreter switch)")
+    sp.set_defaults(fn=cmd_shutdown)
+
+    args = p.parse_args(argv)
+    try:
+        sys.exit(args.fn(args))
+    except (ConnectionRefusedError, FileNotFoundError) as e:
+        print(f"tithon: cannot reach daemon at {sock_path()}: {e}", file=sys.stderr)
+        sys.exit(2)
+    except (asyncio.TimeoutError, TimeoutError):
+        print("tithon: timed out", file=sys.stderr)
+        sys.exit(3)
+    except KeyboardInterrupt:
+        sys.exit(130)