zettcode-sdk 0.3.4__py3-none-any.whl

zettcode/sdk/commands.py

@@ -0,0 +1,9 @@
+"""The plain commands of the plugin system, for a program that runs one.
+
+A plugin registers these on ``ctx.commands``: text for any front end to show, or a preset for a turn. They are
+re-exported here because the server may not import the engine — the SDK is the door it has.
+"""
+
+from zettcode.engine.plugins.commands import PlainCommand, PlainCommandContext, TextCommandResult, TurnCommandResult
+
+__all__ = ["PlainCommand", "PlainCommandContext", "TextCommandResult", "TurnCommandResult"]

zettcode/sdk/daemons.py

@@ -0,0 +1,244 @@
+"""Background agents, from code: start one, list them, read what one logged, stop one.
+
+A daemon is a session with nobody at the keyboard (see ``docs/guide/daemons.md``). ``zettcode daemon`` is its
+command line; this module is the same thing for a program, so a front end that manages daemons does not parse the
+output of a command or reach into the folders the daemons keep their records in::
+
+    from zettcode.sdk.daemons import list_daemons, spawn_daemon, stop_daemon
+
+    daemon = await spawn_daemon("~/project", name="reviewer", permission="safe")
+    print(daemon.session_id)             # message it with ``Client.send`` or the ``send_message`` tool
+    for item in list_daemons():
+        print(item.session_id, item.status)
+    await stop_daemon(daemon.session_id)
+
+A daemon is a separate process, so none of this is bound by the one-workspace-per-process rule of a
+:class:`~zettcode.sdk.client.Client`. Nothing here imports the daemon's own code until it is used.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .errors import ConfigurationError, DaemonStartError, SessionNotFoundError
+from .types import DaemonInfo
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zettcode.daemon.state import Record
+
+__all__ = ["PERMISSIONS", "daemon_log", "delete_daemon", "list_daemons", "spawn_daemon", "stop_daemon", "update_daemon"]
+
+#: The shell levels a daemon can be given. There is no ``ask``: nobody is there to answer it.
+PERMISSIONS = ("deny", "safe", "full")
+
+
+def _info(record: Record) -> DaemonInfo:
+    """Return the SDK's value for a daemon's record."""
+    state = record.state
+    if state is None:
+        return DaemonInfo(session_id=record.session_id, status=record.status)
+    return DaemonInfo(
+        session_id=record.session_id,
+        workspace=state.workspace,
+        status=record.status,
+        name=state.name,
+        title=state.title,
+        model=state.model,
+        effort=state.effort,
+        permission=state.permission,
+        pid=state.pid,
+        started_at=state.started_at,
+        input_tokens=state.input_tokens,
+        output_tokens=state.output_tokens,
+        context_tokens=state.context_tokens,
+        context_window=state.context_window,
+        requested_model=state.requested_model,
+        requested_effort=state.requested_effort,
+        requested_error=state.requested_error,
+        broker=state.broker,
+    )
+
+
+def list_daemons() -> list[DaemonInfo]:
+    """Return every daemon recorded on this machine, whichever workspace it works in, newest first.
+
+    A daemon whose process is gone is listed with the status ``dead`` until it is stopped, which removes the record.
+    This reads a few small files per daemon, so it is cheap to call often.
+    """
+    from zettcode.daemon.state import Registry
+
+    found = sorted(Registry().all(), key=lambda record: record.state.started_at if record.state else 0.0, reverse=True)
+    return [_info(record) for record in found]
+
+
+async def spawn_daemon(
+    workspace: str | Path,
+    *,
+    model: str | None = None,
+    effort: str | None = None,
+    resume: str | None = None,
+    name: str | None = None,
+    title: str | None = None,
+    permission: str = "safe",
+) -> DaemonInfo:
+    """Start a background agent and return it once it can be messaged.
+
+    Args:
+        workspace: The directory it works in; it has to exist.
+        model: The model to run on, by the name :func:`~zettcode.sdk.models.list_models` gives, or ``None`` for the
+            first configured.
+        effort: The reasoning level, or ``None`` for the model's own.
+        resume: A stored session of that workspace to continue instead of starting an empty one.
+        name: A label saying what the daemon is for, recorded beside it.
+        title: What to call the session. ``None`` lets it name itself from its first answer.
+        permission: Its shell level: ``deny`` (no shell), ``safe`` (every command in a sandbox) or ``full``. The
+            default is ``safe``, not the ``full`` the command line starts with: a program starting an agent that
+            asks nobody should have to say so.
+
+    Raises:
+        ConfigurationError: The permission is not one of :data:`PERMISSIONS`, or the workspace is not a directory.
+        DaemonStartError: The process exited, or never became reachable; the message is what it said.
+    """
+    if permission not in PERMISSIONS:
+        raise ConfigurationError(f"A daemon's permission is one of {', '.join(PERMISSIONS)}, not {permission!r}")
+    folder = Path(workspace).expanduser()
+    if not folder.is_dir():
+        raise ConfigurationError(f"No such directory: {folder}")
+    from zettcode.daemon.process import Daemons, SpawnFailed
+
+    def start() -> Record:
+        return Daemons().start(
+            folder,
+            model=model,
+            effort=effort,
+            resume=resume,
+            name=name or None,
+            title=title or None,
+            permission=permission,
+        )
+
+    try:
+        record = await asyncio.to_thread(start)
+    except SpawnFailed as error:
+        raise DaemonStartError(str(error), str(error.log) if error.log is not None else None) from error
+    return _info(record)
+
+
+async def stop_daemon(session_id: str, *, force: bool = False, keep: bool = False) -> str:
+    """Stop a daemon and say in one sentence what happened.
+
+    The session itself stays, with everything the daemon did, so it can be opened afterwards. By default the
+    daemon's record is removed too; with ``keep`` it stays, listed as ``dead``, so the daemon can be started again
+    (``spawn_daemon(..., resume=session_id)``) or removed for good with :func:`delete_daemon`. A daemon whose
+    process was already gone only has its record removed (or kept).
+
+    Args:
+        session_id: The daemon, as :func:`list_daemons` gives it.
+        force: Stop it even in the middle of a turn, which throws that turn away.
+        keep: Leave the record, as a dead one, instead of removing it.
+
+    Raises:
+        SessionNotFoundError: No daemon has that session.
+        ConfigurationError: It is working on a turn and ``force`` was not given.
+    """
+    from zettcode.daemon.process import Daemons, StillWorking
+    from zettcode.daemon.state import Registry
+
+    registry = Registry()
+    record = registry.find(session_id)
+    if record is None:
+        raise SessionNotFoundError(f"No daemon runs session {session_id!r}")
+    try:
+        return await asyncio.to_thread(lambda: Daemons(registry).stop(record, force=force, keep=keep))
+    except StillWorking as error:
+        raise ConfigurationError(str(error)) from error
+
+
+async def delete_daemon(session_id: str) -> str:
+    """Remove a daemon for good: its record and its conversation. This cannot be undone.
+
+    Raises:
+        SessionNotFoundError: No daemon has that session.
+        ConfigurationError: Its process is still running (stop it first), or its session is open in another process.
+    """
+    from zettcode.daemon.process import Daemons, StillRunning, UpdateFailed
+    from zettcode.daemon.state import Registry
+
+    registry = Registry()
+    record = registry.find(session_id)
+    if record is None:
+        raise SessionNotFoundError(f"No daemon runs session {session_id!r}")
+    try:
+        return await asyncio.to_thread(Daemons(registry).delete, record)
+    except (StillRunning, UpdateFailed) as error:
+        raise ConfigurationError(str(error)) from error
+
+
+async def update_daemon(
+    session_id: str,
+    *,
+    title: str | None = None,
+    name: str | None = None,
+    model: str | None = None,
+    effort: str | None = None,
+) -> DaemonInfo:
+    """Change what is recorded about a daemon: its session's name, its own label, or what it runs on.
+
+    The label may be changed while the daemon runs; it keeps what a reader put there. The title is the session's,
+    and a session is written to only by the process holding its lock, so naming one waits until the daemon is
+    stopped (a running daemon names its own session from the first answer, and ``name_it`` costs nothing once it
+    has one). A model or an effort is a request the running daemon puts in force before its next turn; a daemon
+    that is not running cannot be moved to another model.
+
+    Args:
+        session_id: The daemon, as :func:`list_daemons` gives it.
+        title: The name to give its session, or ``None`` to leave it.
+        name: The label to record, ``""`` to clear it, or ``None`` to leave it.
+        model: The model it should run from the next turn on, by display name or id, or ``None`` to leave it.
+        effort: The reasoning level it should run from the next turn on, or ``None`` to leave it.
+
+    Raises:
+        SessionNotFoundError: No daemon has that session.
+        ConfigurationError: The daemon still runs, its session is open in another process, the title is blank or
+            too long, or the model or effort is not one this machine has configured.
+    """
+    from zettcode.daemon.process import Daemons, UpdateFailed
+    from zettcode.daemon.state import Registry
+
+    registry = Registry()
+    record = registry.find(session_id)
+    if record is None:
+        raise SessionNotFoundError(f"No daemon runs session {session_id!r}")
+    try:
+        updated = await asyncio.to_thread(
+            Daemons(registry).update, record, title=title, name=name, model=model, effort=effort
+        )
+    except UpdateFailed as error:
+        raise ConfigurationError(str(error)) from error
+    return _info(updated)
+
+
+def daemon_log(session_id: str, *, lines: int = 200) -> str:
+    """Return the last ``lines`` lines a daemon wrote about itself: the tools it ran and the turns that failed.
+
+    Raises:
+        SessionNotFoundError: No daemon has that session.
+    """
+    from zettcode.daemon.state import Registry
+
+    record = Registry().find(session_id)
+    if record is None:
+        raise SessionNotFoundError(f"No daemon runs session {session_id!r}")
+    wanted = max(1, lines)
+    try:
+        with record.log_path.open("rb") as handle:
+            # The end of the file is enough: a log that has grown for weeks is not read whole for its last lines.
+            handle.seek(0, 2)
+            size = handle.tell()
+            handle.seek(max(0, size - wanted * 400))
+            tail = handle.read().decode("utf-8", errors="replace")
+    except OSError:
+        return ""
+    return "\n".join(tail.splitlines()[-wanted:])

zettcode/sdk/errors.py

@@ -0,0 +1,132 @@
+"""The errors the SDK raises.
+
+Everything the SDK raises on purpose is a :class:`ZettCodeError`, so a program can catch one class for "ZettCode
+refused or failed". The original error is kept as ``__cause__`` wherever there was one, and a few of these also
+inherit the built-in a caller would already be catching (``LookupError``, ``TimeoutError``), so existing handlers
+keep working.
+
+Cancellation is never wrapped: ``asyncio.CancelledError`` goes through untouched, because swallowing or renaming it
+breaks the caller's own cancellation.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ClientClosedError",
+    "ConfigurationError",
+    "DaemonStartError",
+    "NothingToDoError",
+    "RunError",
+    "RunTimeoutError",
+    "SendError",
+    "SessionBusyError",
+    "SessionLockedError",
+    "SessionNotFoundError",
+    "WorkspaceConflictError",
+    "ZettCodeError",
+]
+
+
+class ZettCodeError(Exception):
+    """Base class of every error the SDK raises on purpose."""
+
+
+class ConfigurationError(ZettCodeError, ValueError):
+    """The configuration, or something chosen from it, is not usable.
+
+    Raised for an unreadable config file, an unknown setting name, a model, reasoning effort, or permission level
+    that does not exist, and a workspace that is not a directory. The message says which, and what would have worked.
+    """
+
+
+class ClientClosedError(ZettCodeError):
+    """The client was closed, so it can no longer run anything."""
+
+
+class SessionBusyError(ZettCodeError):
+    """A run is already in progress on this client.
+
+    A client has one conversation running at a time, exactly as the terminal application does. Wait for the run to
+    end, stop it (leave the ``async for`` or cancel the task), or use another client for parallel work.
+    """
+
+
+class SessionLockedError(ZettCodeError):
+    """Another process has this session open, so this one may only read it.
+
+    Sessions are locked by the process that has them open. Reading history is still possible; running, renaming,
+    compacting and exporting are refused until the other process lets go.
+    """
+
+
+class SessionNotFoundError(ZettCodeError, LookupError):
+    """The store holds no session with that id, or its file cannot be read."""
+
+
+class NothingToDoError(ZettCodeError):
+    """The request is fine but there is nothing for it to act on.
+
+    Continuing a conversation that was not interrupted, or compacting one that is already compacted. The message
+    says why, in the application's own words.
+    """
+
+
+class WorkspaceConflictError(ZettCodeError):
+    """Another client in this process already works in a different directory.
+
+    The coding tools resolve relative paths against the process's working directory, which is global to the
+    process, so two clients on different workspaces would edit each other's files. Close the other client, or run the
+    second one in a process of its own.
+    """
+
+
+class RunError(ZettCodeError):
+    """A run ended with an error from the model, the provider, or the network.
+
+    Attributes:
+        retryable: Whether trying the same request again could succeed: a timeout, a dropped connection, a rate
+            limit, or a server error. A rejected key or a malformed request is not.
+        partial_text: What the model had already said when the error came, which is often still worth keeping.
+    """
+
+    def __init__(self, message: str, *, retryable: bool = False, partial_text: str = "") -> None:
+        super().__init__(message)
+        self.retryable = retryable
+        self.partial_text = partial_text
+
+
+class RunTimeoutError(RunError, TimeoutError):
+    """A run took longer than the ``timeout`` it was given and was stopped.
+
+    The conversation keeps whatever the run had already added to it, as it does for a run the reader stops.
+    """
+
+    def __init__(self, seconds: float, *, partial_text: str = "") -> None:
+        super().__init__(f"The run did not finish within {seconds:g}s", retryable=True, partial_text=partial_text)
+        self.seconds = seconds
+
+
+class SendError(ZettCodeError):
+    """A message to another session did not arrive.
+
+    Attributes:
+        reason: ``offline`` when there is no broker, ``lost`` when the connection ended with the message in flight (it
+            may or may not have been delivered), otherwise the broker's own reason (``unknown``, ``ambiguous``,
+            ``rejected``, ``timeout``, ``loop``, ``rate``, ``empty``, ``too_long``).
+    """
+
+    def __init__(self, reason: str, message: str) -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
+class DaemonStartError(ZettCodeError):
+    """A background agent was started and never became reachable.
+
+    Attributes:
+        log: The file the child process wrote its first words to, when there is one: the reason it gave is in it.
+    """
+
+    def __init__(self, message: str, log: str | None = None) -> None:
+        super().__init__(message)
+        self.log = log