zettcode-sdk 0.3.4__py3-none-any.whl

zettcode/sdk/handlers.py

@@ -0,0 +1,126 @@
+"""Answering what the model asks of the program: a shell command to approve, a question to answer.
+
+A run cannot be unattended without a rule for these, because the agent is suspended inside the tool call until
+someone answers. The rule is: pass a handler to the run and it answers before the event is yielded; answer the event
+yourself while you are iterating; or do neither, and a command is denied and a question declined. Nothing hangs.
+
+A handler may be a plain function or a coroutine function. What it returns decides the answer::
+
+    def only_git(request):
+        return request.command.startswith("git ")      # True approves, False denies
+
+    async def ask_a_person(request):
+        request.approve(remember=True)                  # answering yourself is fine; return None
+
+``None`` leaves the request unanswered, which means the default (deny, decline) applies once the stream is asked for
+its next event. A run started with ``defer_answers=True`` does not apply the default then: it keeps the request open,
+so a handler that only shows the request to a person (and returns ``None``) can have it answered later, from a panel,
+by the event's own ``approve`` or ``answer``. Whatever is still open when the run ends gets the default.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import TypeAlias
+
+from .events import ApprovalRequested, QuestionAsked
+
+__all__ = [
+    "ApprovalHandler",
+    "QuestionHandler",
+    "approve_all",
+    "approve_commands",
+    "deny_all",
+]
+
+#: Decides one shell command: ``True`` approves, ``False`` denies, ``None`` leaves it to the request's own methods.
+ApprovalHandler: TypeAlias = Callable[[ApprovalRequested], "bool | None | Awaitable[bool | None]"]
+
+#: Answers one question: the text answers it, ``None`` leaves it to the request's own methods.
+QuestionHandler: TypeAlias = Callable[[QuestionAsked], "str | None | Awaitable[str | None]"]
+
+#: Characters that let a shell run something other than the command that was typed: chaining, pipes,
+#: redirection, substitution, grouping and newlines. A command holding one is never matched by a prefix rule.
+SHELL_META = frozenset(";&|<>$`\n\r(){}\\")
+
+
+def approve_all(request: ApprovalRequested) -> bool:
+    """Approve every command. Only for a workspace and a model you would trust with a shell."""
+    return True
+
+
+def deny_all(request: ApprovalRequested) -> bool:
+    """Deny every command; the model is told and carries on without running anything."""
+    return False
+
+
+def approve_commands(*commands: str) -> ApprovalHandler:
+    """Return a handler that approves only the commands named, and denies the rest.
+
+    A command matches when it *is* one of ``commands`` or continues one with arguments (``"git status"`` matches
+    ``git status`` and ``git status -s``, not ``git statusx``). It never matches a command holding a character the
+    shell treats specially (``;``, ``&``, ``|``, redirection, substitution, newlines), because ``git status; rm -rf
+    ~`` starts with ``git status`` too.
+
+    Args:
+        commands: The commands to allow, such as ``"git status"``, ``"git diff"``, ``"pytest"``.
+
+    Raises:
+        ValueError: A command is blank, or holds a character the shell treats specially.
+    """
+    allowed: list[str] = []
+    for command in commands:
+        command = command.strip()
+        if not command:
+            raise ValueError("A command to allow cannot be blank")
+        if SHELL_META & set(command):
+            raise ValueError(f"{command!r} holds a shell character; allow the plain command and not a pipeline")
+        allowed.append(command)
+    rules = tuple(allowed)
+
+    def decide(request: ApprovalRequested) -> bool:
+        text = request.command.strip()
+        if not text or SHELL_META & set(text):
+            return False
+        return any(text == rule or text.startswith(rule + " ") for rule in rules)
+
+    return decide
+
+
+async def apply_approval(request: ApprovalRequested, handler: ApprovalHandler | None) -> None:
+    """Let ``handler`` answer ``request``; it stays unanswered when there is none or it declines to say.
+
+    Raises:
+        TypeError: The handler returned something other than ``True``, ``False`` or ``None``; a truthy string
+            answering "yes" is exactly the mistake that must not approve a shell command.
+    """
+    if handler is None:
+        return
+    outcome = handler(request)
+    if inspect.isawaitable(outcome):
+        outcome = await outcome
+    if request.answered or outcome is None:
+        return
+    if not isinstance(outcome, bool):
+        raise TypeError(f"An approval handler returns True, False or None, not {type(outcome).__name__}")
+    request.approve() if outcome else request.deny()
+
+
+async def apply_question(request: QuestionAsked, handler: QuestionHandler | None) -> None:
+    """Let ``handler`` answer ``request``; a blank answer or ``None`` leaves it for the default.
+
+    Raises:
+        TypeError: The handler returned something other than text or ``None``.
+    """
+    if handler is None:
+        return
+    outcome = handler(request)
+    if inspect.isawaitable(outcome):
+        outcome = await outcome
+    if request.answered or outcome is None:
+        return
+    if not isinstance(outcome, str):
+        raise TypeError(f"A question handler returns text or None, not {type(outcome).__name__}")
+    if outcome.strip():
+        request.answer(outcome)

zettcode/sdk/messenger.py

@@ -0,0 +1,299 @@
+"""This session's line to the others: who is active, a message sent, a message received.
+
+The broker client (:mod:`zettcode.broker.client`) knows the wire; this is the part the rest of the
+application holds. The shell tells it what the session is now and gives it a place to hand a received
+message to, and the ``send_message`` tool and the ``@`` completion ask it who else is there.
+
+It owns one fact the client cannot know: which message the running turn is answering. An agent that
+is answering another agent carries that message's hop count on, which is what stops two sessions
+that keep replying to each other; a turn that began with the reader's own words starts at none.
+
+Nothing here blocks or raises into the shell. Without a broker every method answers as if nobody
+else were running, and a send says so.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from zettcode.broker.client import BrokerClient, Delivered, Incoming, Receipt, RosterEntry, SessionInfo
+from zettcode.broker.models import GroupDelivered, GroupInfo
+from zettcode.broker.protocol import VIA_AGENT, ImageData
+from zettcode.config import ZettCodeConfig
+from zettcode.modes import MODE_STEER
+from zettcode.relay import Relayed
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from pathlib import Path
+
+
+#: How long pieces of text are gathered before they are sent as one, so a stream is a few lines a second and not one per token.
+STREAM_BATCH = 0.06
+
+#: The most characters of text sent in one stream line, well inside what the broker passes (see ``MAX_STREAM``).
+STREAM_CHUNK = 4000
+
+
+class Messenger:
+    """The shell's and the agent's one handle on the other sessions."""
+
+    def __init__(self, client: BrokerClient | None = None, *, workspace: str | Path = "") -> None:
+        """Wrap a client; one is built for the default broker when none is given.
+
+        Args:
+            client: The connection to use. Its callbacks are taken over, so give a client that nothing
+                else is listening to.
+            workspace: The directory this session works in, which other sessions are shown.
+        """
+        self.workspace = str(workspace)
+        self.client = client if client is not None else BrokerClient()
+        self.client.on_message = self._received
+        self.client.on_roster = self._roster_changed
+        self.client.on_conflict = self._conflicted
+        self.client.on_problem = self._troubled
+        #: Where a received message goes; the shell sets it. It returns what this session says to the
+        #: sender: whether it took the message, and what will become of it.
+        self.receiver: Callable[[Relayed], Receipt] | None = None
+        #: Called, on the loop, whenever the roster or the connection changes, so a view can repaint.
+        self.on_change: Callable[[], None] | None = None
+        #: Called with a sentence when another process holds this session's id, and with ``None`` after.
+        self.on_conflict: Callable[[str | None], None] | None = None
+        #: Called with a sentence when the broker has been out of reach for a while, and with ``None`` when it is back.
+        self.on_problem: Callable[[str | None], None] | None = None
+        #: The message the running turn answers, if it answers one.
+        self.answering: Relayed | None = None
+        #: Whether a message the sender marked ``direct`` is run as this session's own prompt; said in the roster.
+        self.direct = False
+        self._started = False
+        self._piece: tuple[str, list[str]] | None = None
+        self._flush: asyncio.TimerHandle | None = None
+
+    @classmethod
+    def create(cls, config: ZettCodeConfig) -> Messenger | None:
+        """Return the messenger this configuration asks for, or ``None`` when sessions are switched off."""
+        if not config.sessions_enabled:
+            return None
+        return cls(workspace=config.workspace)
+
+    # -- the life of the connection ---------------------------------------------------------------
+    @property
+    def started(self) -> bool:
+        """Return whether :meth:`start` has run, which is when it is safe to tell it about the session."""
+        return self._started
+
+    async def start(self) -> None:
+        """Begin connecting in the background. Returns at once, whether or not a broker exists."""
+        self._started = True
+        await self.client.start()
+
+    async def close(self) -> None:
+        """Leave the broker. Quick, and safe to call twice."""
+        self._started = False
+        self.receiver = None
+        await self.client.close()
+
+    # -- what this session is ---------------------------------------------------------------------
+    def describe(self, session_id: str, title: str | None, *, busy: bool) -> None:
+        """Say what this session is now. Cheap when nothing changed, so callers need not check.
+
+        Args:
+            session_id: The active session.
+            title: Its title, or ``None`` while it has none.
+            busy: Whether a request or command is running.
+        """
+        info = SessionInfo(
+            session_id=session_id,
+            title=title or "",
+            workspace=self.workspace,
+            status="working" if busy else "idle",
+            direct=self.direct,
+        )
+        current = self.client.session
+        if current is not None and (current.session_id, current.title, current.status, current.direct) == (
+            info.session_id,
+            info.title,
+            info.status,
+            info.direct,
+        ):
+            return
+        self.client.set_session(info)
+
+    def retire(self) -> None:
+        """Say that this process has no session to be reached at: it only shows one that another process has open."""
+        if self.client.session is not None:
+            self.client.set_session(None)
+
+    # -- the others -------------------------------------------------------------------------------
+    @property
+    def connected(self) -> bool:
+        """Return whether the broker is reachable right now."""
+        return self.client.connected
+
+    @property
+    def conflict(self) -> str | None:
+        """Return why this session is not registered, or ``None``."""
+        return self.client.conflict
+
+    @property
+    def handle(self) -> str:
+        """Return the name the others call this session by, or ``""`` before it is registered."""
+        mine = self.client.session
+        if mine is None:
+            return ""
+        return next((entry.handle for entry in self.client.roster if entry.session_id == mine.session_id), "")
+
+    def peers(self) -> tuple[RosterEntry, ...]:
+        """Return the other active sessions, from memory: this is called as a draft is typed."""
+        return self.client.others()
+
+    def groups(self) -> tuple[GroupInfo, ...]:
+        """Return the group chats this session may write to, from memory."""
+        return self.client.groups
+
+    async def manage_group(self, action: str, name: str, members: list[str] | None = None) -> GroupInfo | None:
+        """Create a group, change who is in it, leave it or delete it (see :meth:`BrokerClient.manage_group`)."""
+        return await self.client.manage_group(action, name, members)
+
+    async def join_group(self, name: str) -> GroupInfo | None:
+        """Put this session in a group as the broker's owner may (see :meth:`BrokerClient.join_group`)."""
+        return await self.client.join_group(name)
+
+    async def history(self, *, with_: str = "", group: str = "", limit: int = 20) -> tuple[list[dict[str, Any]], str]:
+        """Return stored messages with one session, in a group, or all this session's own (see the client)."""
+        return await self.client.history(with_=with_, group=group, limit=limit)
+
+    # -- watching a turn --------------------------------------------------------------------------
+    @property
+    def on_stream(self) -> Callable[[str, dict[str, Any]], None] | None:
+        """Called with a watched session's id and one thing its turn said."""
+        return self.client.on_stream
+
+    @on_stream.setter
+    def on_stream(self, callback: Callable[[str, dict[str, Any]], None] | None) -> None:
+        self.client.on_stream = callback
+
+    def watch(self, session_id: str) -> None:
+        """Ask to be told what a session's turns say as they happen."""
+        self.client.watch(session_id)
+
+    def unwatch(self, session_id: str) -> None:
+        """Stop being told."""
+        self.client.unwatch(session_id)
+
+    def stream(self, kind: str, **fields: Any) -> None:
+        """Say one thing about the running turn to whoever watches it; a no-op when nobody does.
+
+        Pieces of text are gathered for :data:`STREAM_BATCH` seconds and go as one; anything else sends what was
+        gathered first, so the order is the order they happened in.
+        """
+        if not self.client.watched:
+            self._piece = None
+            if self._flush is not None:
+                self._flush.cancel()
+                self._flush = None
+            return
+        if kind in ("text", "thinking"):
+            text = fields.get("text", "")
+            if self._piece is not None and self._piece[0] != kind:
+                self._send_piece()
+            if self._piece is None:
+                self._piece = (kind, [])
+            self._piece[1].append(text)
+            if self._flush is None:
+                self._flush = asyncio.get_running_loop().call_later(STREAM_BATCH, self._send_piece)
+            return
+        self._send_piece()
+        self.client.publish({"t": kind, **fields})
+
+    def _send_piece(self) -> None:
+        if self._flush is not None:
+            self._flush.cancel()
+            self._flush = None
+        piece, self._piece = self._piece, None
+        if piece is None:
+            return
+        kind, parts = piece
+        if kind != "text":
+            self.client.publish({"t": kind})
+            return
+        # A burst of text is cut into lines the broker will pass: one longer than it allows is dropped there, whole.
+        text = "".join(parts)
+        for start in range(0, len(text), STREAM_CHUNK):
+            self.client.publish({"t": "text", "text": text[start : start + STREAM_CHUNK]})
+
+    # -- sending ----------------------------------------------------------------------------------
+    async def send(
+        self,
+        to: str,
+        text: str,
+        *,
+        via: str = VIA_AGENT,
+        direct: bool = False,
+        mode: str = MODE_STEER,
+        images: Sequence[ImageData] = (),
+    ) -> Delivered:
+        """Send a message and return once the other session has taken it.
+
+        A message sent by this session's agent while it is answering another one carries that message's
+        hop count on; a message the reader sent starts again at none.
+
+        Args:
+            to: The session's handle or id.
+            text: What to say.
+            via: How it came: the agent's tool, or the reader.
+            direct: Ask a session that can to run it as its own reader's prompt and answer the sender.
+            mode: What a busy recipient does with it: ``"steer"`` (the default) hands it to the running request,
+                ``"followup"`` waits until that request ends.
+            images: Pictures to send with a ``direct`` message.
+
+        Raises:
+            SendError: Nobody was reached, and why.
+        """
+        hops = self.answering.hops if self.answering is not None and via == VIA_AGENT else 0
+        return await self.client.send(to, text, hops=hops, via=via, direct=direct, mode=mode, images=images)
+
+    async def send_group(
+        self, group: str, text: str, *, via: str = VIA_AGENT, mode: str = MODE_STEER
+    ) -> GroupDelivered:
+        """Write to a group chat this session is in; the hop count is carried on as for :meth:`send`.
+
+        Raises:
+            SendError: Nobody was reached, and why (``denied`` when this session is not in the group).
+        """
+        hops = self.answering.hops if self.answering is not None and via == VIA_AGENT else 0
+        return await self.client.send_group(group, text, hops=hops, via=via, mode=mode)
+
+    # -- what the client reports ------------------------------------------------------------------
+    def _received(self, incoming: Incoming) -> Receipt:
+        """Turn the client's message into the shell's and ask the shell to take it."""
+        receiver = self.receiver
+        if receiver is None:
+            return Receipt(False, "this session is not taking messages yet")
+        sender = incoming.sender
+        return receiver(
+            Relayed(
+                sender_id=sender.session_id,
+                sender=sender.handle,
+                text=incoming.text,
+                via=incoming.via,
+                hops=incoming.hops,
+                direct=incoming.direct,
+                mode=incoming.mode,
+                group=incoming.group,
+                images=incoming.images,
+            )
+        )
+
+    def _roster_changed(self, roster: tuple[RosterEntry, ...]) -> None:
+        if self.on_change is not None:
+            self.on_change()
+
+    def _conflicted(self, message: str | None) -> None:
+        if self.on_conflict is not None:
+            self.on_conflict(message)
+
+    def _troubled(self, message: str | None) -> None:
+        if self.on_problem is not None:
+            self.on_problem(message)

zettcode/sdk/models.py

@@ -0,0 +1,156 @@
+"""The models a config file holds: list them, add one, change one, remove one.
+
+An editor that hosts ZettCode has to be able to set a model up before there is any client: a fresh machine has no
+``~/.zettcode/config.toml``, and a client cannot be made without a model. These functions work on the file itself, so
+they answer with no client, no provider, and no network — the terminal's ``/config`` edits the same file with the same
+helpers, so a model added here reads there, and the other way round.
+
+Nothing is believed until it is read back: the new file is parsed and every entry validated before the call returns,
+and a write that would not parse is undone.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+from zettcode import config as _config
+from zettcode.config_edit import add_model as insert_model
+from zettcode.config_edit import file_entries, replace_model, write_text_atomically
+from zettcode.paths import config_path
+
+from .types import ModelInfo
+
+__all__ = ["add_model", "list_models", "remove_model", "update_model"]
+
+
+def model_info(model: _config.ModelConfig, *, active: bool = False) -> ModelInfo:
+    """Return one configured model as an SDK value; ``active`` is for a client to say, a file cannot."""
+    return ModelInfo(
+        name=model.shown_name,
+        model=model.model,
+        context_window=model.context_window,
+        multimodal=model.multimodal,
+        efforts=tuple(level.value for level in model.efforts),
+        active=active,
+        compact_percent=model.compact_percent,
+        web_search=model.web_search,
+        web_search_name=model.web_search_name,
+        display_model=model.display_model,
+        base_url=model.base_url,
+        api=model.api.value,
+        temperature=model.temperature,
+        can_search=model.can_search,
+        search_name=model.search_name,
+    )
+
+
+def _infos(models: tuple[_config.ModelConfig, ...]) -> tuple[ModelInfo, ...]:
+    """Return the configured models as SDK values; none is marked active, which only a client knows."""
+    return tuple(model_info(model) for model in models)
+
+
+def _path(path: str | Path | None) -> Path:
+    """Return the config file an edit goes to."""
+    return config_path(path)
+
+
+def _read_text(target: Path) -> str:
+    """Return the file's text, or nothing when it does not exist yet."""
+    return target.read_text(encoding="utf-8") if target.is_file() else ""
+
+
+def _write(target: Path, before: str | None, text: str) -> tuple[_config.ModelConfig, ...]:
+    """Write ``text``, read it back, and undo the write when what came back cannot be used."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    write_text_atomically(target, text)
+    try:
+        return _config.read_models(target)
+    except ValueError:
+        if before is None:
+            target.unlink(missing_ok=True)
+        else:
+            write_text_atomically(target, before)
+        raise
+
+
+def list_models(path: str | Path | None = None) -> tuple[ModelInfo, ...]:
+    """Return the models the config file lists, or nothing when it lists none.
+
+    Raises:
+        ValueError: The file does not parse, or an entry is not usable as one.
+    """
+    return _infos(_config.read_models(_path(path)))
+
+
+def add_model(entry: Mapping[str, object], *, path: str | Path | None = None) -> tuple[ModelInfo, ...]:
+    """Add one model to the config file and return every model it now lists.
+
+    The entry uses the file's own keys — ``model``, ``token``, and optionally ``display_model``, ``base_url``,
+    ``anthropic``, ``responses_api``, ``multimodal``, ``web_search``, ``web_search_name``, ``context_window``,
+    ``compact_percent``,
+    ``reasoning_efforts`` — and is validated by reading the file back before returning. The first model is written
+    by hand (the file has no block to insert after); later ones go through the same editor the terminal's ``/config``
+    uses, so the rest of the file, comments included, is left as it was.
+
+    Raises:
+        ValueError: The entry is not a usable model, or the file would not parse.
+    """
+    target = _path(path)
+    # Unconditionally: `read_models` answers () for a file that is not there yet and refuses one that is not a
+    # file, which is what a caller naming a directory has to hear rather than an IsADirectoryError from the write.
+    _config.read_models(target)
+    before = target.read_text(encoding="utf-8") if target.is_file() else None
+    text = insert_model(before or "", entry, where=target)
+    return _infos(_write(target, before, text))
+
+
+def _find(models: tuple[_config.ModelConfig, ...], name: str) -> int:
+    """Return the place of the model called ``name`` (its display name, or its id), as the runtime resolves it."""
+    index = _config.model_index(models, name)
+    if index is None:
+        raise ValueError(f"No model called {name!r}; configured: {', '.join(model.shown_name for model in models)}")
+    return index
+
+
+def update_model(name: str, changes: Mapping[str, object], *, path: str | Path | None = None) -> tuple[ModelInfo, ...]:
+    """Change the model called ``name``, leaving every key not named as it is, and return the new list.
+
+    ``changes`` holds the file's keys. The token is kept unless a new one is given, so a window or a display name can
+    be changed without repeating a secret. A key whose value is ``None`` is removed from the entry, which is how a
+    temperature is cleared and how one protocol flag gives way to another without being left behind as ``false``.
+
+    Raises:
+        ValueError: No model is called ``name``, or the result is not usable.
+    """
+    target = _path(path)
+    models = _config.read_models(target)
+    index = _find(models, name)
+    before = _read_text(target)
+    # The file's own keys, not the model's: a token the environment supplied belongs to the configuration, and
+    # writing it here would copy a secret into the file this dialog shows.
+    entry = dict(file_entries(before, where=target)[index])
+    for key, value in changes.items():
+        if value is None:
+            entry.pop(key, None)
+        else:
+            entry[key] = value
+    text = replace_model(before, index, entry, where=target)
+    return _infos(_write(target, before, text))
+
+
+def remove_model(name: str, *, path: str | Path | None = None) -> tuple[ModelInfo, ...]:
+    """Remove the model called ``name`` and return the rest.
+
+    Raises:
+        ValueError: No model is called ``name``, or it is the last one: a configuration with no models is one no
+            client can be made from, so another has to be added first.
+    """
+    from zettcode.config_edit import remove_model as drop_model
+
+    target = _path(path)
+    models = _config.read_models(target)
+    index = _find(models, name)
+    before = _read_text(target)
+    text = drop_model(before, index, where=target)
+    return _infos(_write(target, before, text))