zettcode-sdk 0.3.4__py3-none-any.whl

zettcode/daemon/state.py

@@ -0,0 +1,356 @@
+"""What the daemons leave on disk: the folder each one records itself in, and the registry of those folders.
+
+A daemon's conversation is an ordinary session, so it is stored where every session is
+(``~/.zettcode/sessions/<workspace>/<session-id>/`` where the layout is that of the session store); nothing here
+duplicates it. This module owns the other half — the process:
+
+    ~/.zettcode/daemon/<workspace path, levels joined with ->/
+    ├── workspace.txt                 <- the path the folder belongs to, as the session store writes it
+    └── <session-id>/
+        ├── state.json                <- pid, status, model, effort, when it started (see :class:`State`)
+        ├── state.lock                <- held while state.json is read and written, so two writers do not clobber
+        ├── heartbeat                 <- touched every few seconds: a pid that lives but has stopped working
+        └── log                       <- what the daemon had to say: a failed turn, a refused message
+
+The folder is named after the session id, so the id is the one handle a reader needs: ``daemon kill``, ``list`` and
+``send_message(to=...)`` all take it. A :class:`Record` is one such folder; :class:`Registry` is all of them, and
+:meth:`Registry.record` is the only way to a folder, created or not.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from zettcode.filelock import SingletonLock
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from collections.abc import Callable
+
+#: Bumped when the meaning of a field changes, so a file written by another version is not trusted blindly.
+PROTOCOL = 1
+
+#: How long a start may take before a state file that never appeared counts as a failed spawn.
+START_SECONDS = 10.0
+
+#: What a daemon is doing, as ``list`` words it. ``starting`` is a spawn the broker has not answered yet;
+#: ``stopping`` is a kill that has been asked for and not yet landed.
+STATUSES = ("starting", "idle", "working", "stopping")
+
+#: How stale a heartbeat may be and still count as alive: three times the tick the daemon writes it on.
+STALE_SECONDS = 30.0
+
+#: The names of the files one daemon's folder holds.
+STATE_FILE = "state.json"
+BEAT_FILE = "heartbeat"
+LOG_FILE = "log"
+
+#: The lock a write to ``state.json`` is taken on: a daemon refreshes it while a reader may be relabelling it, and
+#: a read-modify-write must not overwrite what the other just wrote.
+STATE_LOCK = "state.lock"
+
+#: How long a state write may wait for the other writer. Both hold it for one small file, so a wait is a moment.
+STATE_LOCK_WAIT = 2.0
+
+#: The file in the daemon folder that says which workspace path the folder belongs to.
+OWNER_FILE = "workspace.txt"
+
+
+def pid_runs(pid: int) -> bool:
+    """Return whether a process with this id exists on this machine.
+
+    POSIX asks with signal zero. Windows cannot: ``os.kill(pid, 0)`` there *is* ``CTRL_C_EVENT``, so it would send a
+    Ctrl+C rather than ask anything. It goes through the kernel's own handle instead.
+    """
+    if pid <= 0:
+        return False
+    if os.name == "nt":  # pragma: no cover - exercised on Windows only
+        return _windows_pid_runs(pid)
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # somebody else's process, so it is there
+    except OSError:
+        return False
+    return True
+
+
+def _windows_pid_runs(pid: int) -> bool:  # pragma: no cover - exercised on Windows only
+    """Return whether a process with this id exists, by asking the kernel rather than signalling it."""
+    import ctypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)  # type: ignore[attr-defined]
+    process_query_limited_information = 0x1000
+    still_active = 259
+    handle = kernel32.OpenProcess(process_query_limited_information, False, pid)
+    if not handle:
+        return False
+    try:
+        code = ctypes.c_ulong()
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+            return False
+        return code.value == still_active
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+@dataclass(frozen=True, slots=True)
+class State:
+    """What one daemon says about itself, as its ``state.json`` holds it.
+
+    Attributes:
+        session_id: The session the daemon runs; its folder name, and the id a reader passes to ``kill``.
+        workspace: The directory it works in, absolute.
+        pid: The process id, so a live one can be found and a dead one noticed.
+        status: One of :data:`STATUSES`.
+        token: The word the process that spawned it waits for, so a spawn can tell its own child from an old one.
+        started_at: Seconds since the epoch, for the "for 8m" column.
+        model: The model it was started on, as the entry is shown; ``None`` until it has one.
+        effort: The reasoning level it was started on, or ``None`` for the model's own default.
+        title: The session's name, once it has one: what a reader recognises it by.
+        name: The label the reader gave this daemon when starting it, if any: what it is *for*.
+        permission: The shell level it runs at: ``deny``, ``safe`` or ``full``.
+        requested_model: A model a reader asked for while it runs, to be used from the next turn.
+        requested_effort: A reasoning level a reader asked for while it runs, likewise.
+        requested_error: Why the last requested model or level could not be put in force, or ``None``.
+        broker: Whether the session broker was reachable at the last check, or ``None`` before one.
+        input_tokens: Everything the session has sent to the model so far, cache reads included.
+        output_tokens: Everything the model has generated for it, reasoning included.
+        context_tokens: How full the context was on the newest call, or ``None`` before one was made.
+        context_window: The window of the model it runs on, or ``None`` when it recorded no model.
+    """
+
+    session_id: str
+    workspace: str
+    pid: int
+    status: str
+    token: str
+    started_at: float
+    model: str | None = None
+    effort: str | None = None
+    title: str | None = None
+    name: str | None = None
+    permission: str | None = None
+    requested_model: str | None = None
+    requested_effort: str | None = None
+    requested_error: str | None = None
+    broker: bool | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    context_tokens: int | None = None
+    context_window: int | None = None
+    keep: bool = False
+    protocol: int = PROTOCOL
+
+    @classmethod
+    def load(cls, folder: Path) -> State | None:
+        """Return the state recorded in ``folder``, or ``None`` when there is none to believe.
+
+        A file that does not parse, or that names another protocol, is no answer: the folder is then reported by its
+        name alone, which is enough to kill it and see it is not one of ours.
+        """
+        try:
+            data = json.loads((folder / STATE_FILE).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        if not isinstance(data, dict) or data.get("protocol") != PROTOCOL:
+            return None
+        known = {item.name for item in fields(cls)}
+        try:
+            return cls(**{key: value for key, value in data.items() if key in known})
+        except TypeError:
+            return None
+
+    def save(self, folder: Path) -> None:
+        """Write this state into ``folder`` atomically, so a reader never sees half of it."""
+        folder.mkdir(parents=True, exist_ok=True)
+        temporary = folder / f".state.{os.getpid()}.tmp"
+        temporary.write_text(json.dumps(asdict(self), indent=2) + "\n", encoding="utf-8")
+        os.replace(temporary, folder / STATE_FILE)
+
+
+class Record:
+    """One daemon's folder: what it said about itself, and the proofs of life around it.
+
+    Reading a record reads its state once, at construction, and whether the process is there: a command that lists
+    ten daemons asks the disk ten times, and nothing between two reads of one record can change the answer without
+    the file changing too.
+    """
+
+    def __init__(self, folder: Path) -> None:
+        """Take the folder, read what is in it, and decide whether its process is still there."""
+        self.folder = folder
+        self.state: State | None = State.load(folder)
+        self.alive = self._alive()
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging only
+        return f"Record({str(self.folder)!r}, {self.status})"
+
+    @property
+    def session_id(self) -> str:
+        """Return the session the folder belongs to: the recorded one, or the folder's name."""
+        return self.state.session_id if self.state is not None else self.folder.name
+
+    @property
+    def status(self) -> str:
+        """Return what to show as its status: ``dead`` when the process is gone, else the state it wrote."""
+        if not self.alive:
+            return "dead"
+        return self.state.status if self.state is not None else "unknown"
+
+    @property
+    def dead(self) -> bool:
+        """Return whether this is an entry whose process is gone."""
+        return not self.alive
+
+    @property
+    def log_path(self) -> Path:
+        """Return the file the daemon writes its own account into."""
+        return self.folder / LOG_FILE
+
+    def seconds(self, now: float | None = None) -> float:
+        """Return how long it has been running, or zero when it never said."""
+        if self.state is None:
+            return 0.0
+        return max(0.0, (now if now is not None else time.time()) - self.state.started_at)
+
+    def _alive(self) -> bool:
+        """Return whether the process the state names is running and keeping its heartbeat.
+
+        A pid alone is not enough: pids are reused, and a daemon that wedged now holds a file forever. The heartbeat
+        is the part a wedged process stops writing, so both have to say yes.
+        """
+        if self.state is None or self.state.pid <= 0 or not pid_runs(self.state.pid):
+            return False
+        try:
+            age = time.time() - (self.folder / BEAT_FILE).stat().st_mtime
+        except OSError:
+            return False
+        return age <= STALE_SECONDS
+
+    def save(self, state: State) -> None:
+        """Write this record's state, and believe what was written."""
+        state.save(self.folder)
+        self.state = state
+
+    def change(self, produce: Callable[[State | None], State], *, wait: float = STATE_LOCK_WAIT) -> State:
+        """Read the state under a lock, let ``produce`` make the new one, write it, and believe it.
+
+        A daemon writes its state as a turn begins and ends; a reader changes its label while the daemon runs. Both
+        go through here, so the file is read *inside* the lock: a write cannot overwrite a field the other writer
+        put there after this caller read the record.
+
+        Args:
+            produce: Makes the new state from the one on disk, or from ``None`` when there is none.
+            wait: Seconds to wait for the lock. A caller on an event loop passes ``0`` and takes a failure for an
+                answer, rather than blocking the loop on a lock another process holds for a moment.
+        """
+        lock = SingletonLock(self.folder / STATE_LOCK)
+        if not lock.acquire(wait=wait):
+            raise OSError("another process is writing the daemon's state")
+        try:
+            state = produce(State.load(self.folder))
+            state.save(self.folder)
+            self.state = state
+            return state
+        finally:
+            lock.release()
+
+    def beat(self) -> None:
+        """Write the heartbeat: proof that this process is still doing its rounds."""
+        try:
+            (self.folder / BEAT_FILE).write_text(str(time.time()), encoding="utf-8")
+        except OSError:
+            pass
+
+    def log(self, text: str) -> None:
+        """Append one line to the daemon's log; a log that cannot be written is not worth failing a daemon over."""
+        stamp = time.strftime("%Y-%m-%d %H:%M:%S")
+        try:
+            with self.log_path.open("a", encoding="utf-8") as log:
+                log.write(f"{stamp} {text}\n")
+        except OSError:
+            pass
+
+    def remove(self) -> None:
+        """Remove this record and the folder it lives in, leaving its session where it is."""
+        shutil.rmtree(self.folder, ignore_errors=True)
+        parent = self.folder.parent
+        try:
+            if parent.is_dir() and not any(parent.iterdir()):
+                parent.rmdir()
+        except OSError:
+            pass
+
+
+class Registry:
+    """Every daemon recorded under one root: the folders, and the workspace each folder belongs to.
+
+    The root is ``$ZETTCODE_DAEMON_DIR`` or ``~/.zettcode/daemon``. A workspace's folders sit under a name derived
+    from its path by the session store's own helper, so the two trees say the same thing about the same project.
+    """
+
+    def __init__(self, root: Path | None = None) -> None:
+        """Point at a root, or at the default one."""
+        self.root = root if root is not None else _default_root()
+
+    def workspace(self, workspace: str | Path, *, create: bool = False) -> Path:
+        """Return the folder this workspace's daemons are recorded in.
+
+        Args:
+            workspace: The directory the daemons work in.
+            create: Make the folder and write the note saying whose it is, when it is not there yet.
+        """
+        # Imported here, not at the top: `engine.storage` is the session store's package, and loading it would make
+        # `daemon --help` pay for the whole store. Only two path helpers are wanted, and only when a folder is.
+        from zettcode.engine.storage.layout import claim_workspace, open_workspace
+
+        folder = open_workspace(self.root, workspace)
+        if create:
+            claim_workspace(folder, workspace)
+        return folder
+
+    def record(self, workspace: str | Path, session_id: str, *, create: bool = False) -> Record:
+        """Return the record one daemon keeps itself in, made when ``create`` is set."""
+        folder = self.workspace(workspace, create=create) / session_id
+        if create:
+            folder.mkdir(parents=True, exist_ok=True)
+        return Record(folder)
+
+    def all(self) -> tuple[Record, ...]:
+        """Return every daemon recorded under the root, whichever workspace it works in, in no particular order.
+
+        A folder with no readable state is still a record: its process may be there (a crash halfway through a
+        start), and a reader who wants it gone can kill it by the name of the folder.
+        """
+        found: list[Record] = []
+        for workspace in self._folders(self.root):
+            for folder in self._folders(workspace):
+                if any((folder / name).exists() for name in (STATE_FILE, BEAT_FILE, LOG_FILE)):
+                    found.append(Record(folder))
+        return tuple(found)
+
+    def find(self, session_id: str) -> Record | None:
+        """Return the daemon whose session is ``session_id``, whichever workspace it works in."""
+        return next((record for record in self.all() if record.session_id == session_id), None)
+
+    @staticmethod
+    def _folders(path: Path) -> tuple[Path, ...]:
+        """Return the directories directly under ``path``, or nothing when it cannot be read."""
+        try:
+            return tuple(sorted(item for item in path.iterdir() if item.is_dir()))
+        except OSError:
+            return ()
+
+
+def _default_root() -> Path:
+    """Return the folder the daemons are recorded under: ``$ZETTCODE_DAEMON_DIR``, or ``~/.zettcode/daemon``."""
+    override = os.getenv("ZETTCODE_DAEMON_DIR")
+    return Path(override).expanduser() if override else Path.home() / ".zettcode" / "daemon"

zettcode/doctor.py

@@ -0,0 +1,167 @@
+"""Find out whether the configured models work: what ``zettcode doctor`` does.
+
+A model entry can be wrong in ways that only show up on the first request: a token that was revoked, a base URL
+with a typo, a model id the endpoint does not serve, an endpoint that speaks the other protocol. The reader finds out
+in the middle of a task. This module asks every configured model one trivial question, all at once, and says for each
+whether it answered and, if it did not, in the provider's own words why not.
+
+The question costs a handful of tokens: a one-line prompt at the cheapest reasoning level the entry accepts. Nothing
+is written to a session, no tool is offered, and no extension runs: the request goes to the provider adapter
+directly, so what is measured is the entry and the endpoint and nothing of this program.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from zettcode.config import ModelConfig, ZettCodeConfig
+
+#: Seconds one model may take to answer before it is reported as not answering.
+TIMEOUT = 30.0
+
+#: What every model is asked. One short line, so the reply is a token or two.
+QUESTION = "Reply with the single word: ok"
+
+#: Characters of a provider's explanation kept in the report; the rest is a page of HTML or a stack of JSON.
+DETAIL_LIMIT = 200
+
+
+@dataclass(frozen=True, slots=True)
+class Probe:
+    """What asking one model came to.
+
+    Attributes:
+        model: The entry that was asked.
+        ok: Whether it answered.
+        seconds: How long the answer, or the failure, took.
+        detail: When it answered, the reply (trimmed); when it did not, why.
+        tokens: ``(input, output)`` tokens the answer cost, or ``None`` when it did not answer or did not say.
+    """
+
+    model: ModelConfig
+    ok: bool
+    seconds: float
+    detail: str = ""
+    tokens: tuple[int, int] | None = None
+
+
+def _one_line(text: str) -> str:
+    """Return ``text`` as a single line no longer than :data:`DETAIL_LIMIT`."""
+    line = " ".join(text.split())
+    return line if len(line) <= DETAIL_LIMIT else line[: DETAIL_LIMIT - 1] + "…"
+
+
+async def _ask(model: ModelConfig) -> tuple[str, tuple[int, int] | None]:
+    """Send the question to ``model`` and return its reply and the tokens it cost; raises what the provider raises."""
+    from zett_agent.messages import UserMessage
+    from zett_agent.model import ModelEventType, ModelRequest
+
+    from zettcode.engine.core import _build_provider
+
+    provider = _build_provider(model)
+    try:
+        request = ModelRequest(messages=[UserMessage(content=QUESTION)], reasoning_effort=model.efforts[0])
+        async for event in provider.stream(request):
+            if event.type is not ModelEventType.RESPONSE or event.response is None:
+                continue
+            response = event.response
+            stop = response.stop
+            if stop is not None and stop.reason.value == "refusal":
+                raise RuntimeError(f"the model refused the question: {stop.describe()}")
+            content = response.message.content
+            reply = content if isinstance(content, str) else "".join(getattr(part, "text", "") for part in content)
+            usage = response.usage
+            tokens = (usage.input_tokens, usage.output_tokens) if usage.input_tokens or usage.output_tokens else None
+            return reply, tokens
+        raise RuntimeError("the stream ended without a reply")
+    finally:
+        await provider.aclose()
+
+
+async def probe(
+    model: ModelConfig,
+    *,
+    timeout: float = TIMEOUT,
+    ask: Callable[[ModelConfig], Awaitable[tuple[str, tuple[int, int] | None]]] = _ask,
+) -> Probe:
+    """Ask one model the question and report how it went; never raises.
+
+    Args:
+        model: The entry to ask.
+        timeout: Seconds to wait for the answer.
+        ask: Sends the question; injectable so a test needs no network.
+    """
+    started = time.monotonic()
+    try:
+        reply, tokens = await asyncio.wait_for(ask(model), timeout)
+    except asyncio.TimeoutError:
+        return Probe(model, False, time.monotonic() - started, f"no answer within {timeout:g} seconds")
+    except Exception as error:  # noqa: BLE001 - every kind of failure is an answer to "does it work"
+        text = _one_line(str(error)) or type(error).__name__
+        return Probe(model, False, time.monotonic() - started, text)
+    return Probe(model, True, time.monotonic() - started, _one_line(reply), tokens)
+
+
+async def diagnose(
+    models: Sequence[ModelConfig],
+    *,
+    timeout: float = TIMEOUT,
+    ask: Callable[[ModelConfig], Awaitable[tuple[str, tuple[int, int] | None]]] = _ask,
+) -> list[Probe]:
+    """Ask every model at once and return the probes in the order the models are configured."""
+    return list(await asyncio.gather(*(probe(model, timeout=timeout, ask=ask) for model in models)))
+
+
+def format_report(probes: Sequence[Probe]) -> list[str]:
+    """Return the lines that tell the reader which models work, one per model, and a closing tally."""
+    if not probes:
+        return ["no models are configured"]
+    width = max(len(probe.model.shown_name) for probe in probes)
+    lines: list[str] = []
+    for item in probes:
+        mark = "ok  " if item.ok else "FAIL"
+        name = item.model.shown_name.ljust(width)
+        if item.ok:
+            cost = f", {item.tokens[0]} in / {item.tokens[1]} out" if item.tokens else ""
+            lines.append(f"{mark} {name}  {item.seconds:.1f}s  {item.model.api.value}{cost}")
+        else:
+            lines.append(f"{mark} {name}  {item.seconds:.1f}s  {item.model.api.value}: {item.detail}")
+    failed = sum(not item.ok for item in probes)
+    lines.append(
+        f"{len(probes)} model{'s' * (len(probes) != 1)} checked: "
+        + ("all answered" if not failed else f"{len(probes) - failed} answered, {failed} did not")
+    )
+    return lines
+
+
+def doctor_program(
+    config: ZettCodeConfig,
+    *,
+    timeout: float = TIMEOUT,
+    ask: Callable[[ModelConfig], Awaitable[tuple[str, tuple[int, int] | None]]] = _ask,
+    say: Callable[[str], None] = print,
+) -> int:
+    """Check the configured models from the command line: what ``zettcode doctor`` does.
+
+    Args:
+        config: The settings, whose models are asked.
+        timeout: Seconds each model may take.
+        ask: Sends the question; injectable so a test needs no network.
+        say: Where the report goes.
+
+    Returns:
+        ``0`` when every model answered, ``1`` when one did not or none is configured.
+    """
+    from zettcode.paths import config_path
+    from zettcode.version import __version__
+
+    say(f"ZettCode {__version__} · config {config_path()}")
+    probes = asyncio.run(diagnose(config.models, timeout=timeout, ask=ask))
+    for line in format_report(probes):
+        say(line)
+    return 0 if probes and all(item.ok for item in probes) else 1