zettcode-engine 0.3.4__py3-none-any.whl

zettcode/engine/agent/settings.py

@@ -0,0 +1,269 @@
+"""What the reader can change about how the agent runs: model, reasoning effort, shell permission."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from pathlib import Path
+
+from zettcode.config import NO_MODEL_REFUSAL, ModelConfig, _read_models
+from zettcode.config_edit import (
+    ConfigEditError,
+    add_model,
+    file_entries,
+    remove_model,
+    replace_model,
+    set_self_compaction,
+    write_text_atomically,
+)
+from zettcode.engine.permission import PERMISSION_LEVELS, Permission
+from zettcode.paths import config_path
+
+from .base import AgentBase
+
+
+class SettingsMixin(AgentBase):
+    """Read and change the model, the reasoning effort, and how much of the shell may run unasked."""
+
+    @property
+    def models(self) -> tuple[ModelConfig, ...]:
+        """Return the models available for selection."""
+        return self.runtime.config.models
+
+    @property
+    def active_model(self) -> ModelConfig | None:
+        """Return the model selected for the next turn, or ``None`` when this machine has none configured."""
+        return self.runtime.active_model
+
+    def find_model(self, name: str) -> ModelConfig | None:
+        """Return the configured model a recorded name stands for, if exactly one does."""
+        return self.runtime.find_model(name)
+
+    def use_model(self, name: str | ModelConfig) -> ModelConfig:
+        """Select a configured model for subsequent turns."""
+        return self.runtime.use_model(name)
+
+    # -- the models in the config file --------------------------------------------------
+    @property
+    def config_file(self) -> Path:
+        """Return the file the models are read from and written to."""
+        return config_path()
+
+    def _read_config_file(self, *, allow_missing: bool = False) -> str:
+        """Return the config file's text, or raise :class:`ConfigEditError` saying why not.
+
+        Args:
+            allow_missing: Answer an empty file when there is none. Only what sets a machine up asks for that —
+                the first model, and the list that shows there is nothing to list — because a fresh machine has
+                no config file at all. Every other edit treats a missing file as the reader's file that vanished
+                and says so, rather than writing a new one that would hold none of what theirs did.
+        """
+        path = self.config_file
+        try:
+            return path.read_text(encoding="utf-8")
+        except FileNotFoundError as error:
+            if allow_missing:
+                return ""
+            raise ConfigEditError(f"{path} does not exist") from error
+        except (OSError, UnicodeDecodeError) as error:
+            raise ConfigEditError(f"{path} cannot be read: {error}") from error
+
+    def file_models(self) -> tuple[tuple[ModelConfig, Mapping[str, object]], ...]:
+        """Return each model in the file with the keys the file writes for it.
+
+        The file is the source of truth for editing, not the models the session started with: a
+        reader may have changed it by hand since. The keys are what is *written* — a token left to
+        an environment variable is absent — which is what a rewrite has to start from.
+
+        Raises:
+            ConfigEditError: When the file cannot be read, is not valid, or lays its models out in
+                a way the editor cannot safely change.
+        """
+        text = self._read_config_file(allow_missing=not self.models)
+        path = self.config_file
+        entries = file_entries(text, where=path)
+        try:
+            # A file that lists none is a list with nothing in it, not a refusal: `/config` is how the first
+            # one is written, so the panel it opens must be able to show an empty file.
+            models = _read_models(entries, path, required=False)
+        except ValueError as error:
+            raise ConfigEditError(str(error)) from error
+        return tuple(zip(models, entries, strict=True))
+
+    def _commit_models(self, text: str) -> ModelConfig:
+        """Write the edited text, then make the running session use what it now says.
+
+        The file is written first and the session is changed second, so a write that fails leaves
+        the session as it was, and what the session holds is always something the file holds too.
+        """
+        path = self.config_file
+        try:
+            write_text_atomically(path, text)
+        except OSError as error:
+            raise ConfigEditError(f"{path} could not be written: {error}") from error
+        models = _read_models(file_entries(text, where=path), path)
+        return self.runtime.replace_models(models)
+
+    def add_configured_model(self, entry: Mapping[str, object]) -> ModelConfig:
+        """Add one ``[[models]]`` entry to the file and to this session; return the new model.
+
+        The model in use does not change: adding is not choosing. The new one appears in ``/model``. The exception
+        is the first model a machine has — there is nothing to add it beside — so that one becomes the model in
+        use, and it is chosen here rather than by the file's order: another process may have written an entry
+        since this session started, and ``/config`` announces the entry it just wrote, not that one.
+
+        Args:
+            entry: The keys of the new model as the file writes them.
+
+        Raises:
+            ConfigEditError: When the entry is not a model that can be called, or the file cannot
+                be edited. Nothing is written then.
+        """
+        text = add_model(self._read_config_file(allow_missing=not self.models), entry, where=self.config_file)
+        first = self.runtime.active_model is None
+        self._commit_models(text)
+        model = self.runtime.config.models[-1]
+        return self.runtime.use_model(model) if first else model
+
+    def update_configured_model(self, index: int, entry: Mapping[str, object]) -> ModelConfig:
+        """Rewrite model number ``index`` (from zero) of the file as ``entry``; return the result."""
+        text = replace_model(self._read_config_file(), index, entry, where=self.config_file)
+        self._commit_models(text)
+        return self.runtime.config.models[index]
+
+    def change_compact_percent(self, percent: float) -> tuple[ModelConfig, str | None]:
+        """Compact the model in use at ``percent`` of its window from the next request, and write it to the config file.
+
+        The running session is changed whatever becomes of the file, since the reader asked for it now: a file
+        that cannot be edited (no file, a layout the editor refuses) leaves the change for this run only, and the
+        reason is returned beside the model so it can be said.
+
+        Args:
+            percent: Share of the window, more than 0 and at most 100.
+
+        Returns:
+            The model now in use, and why the file was not changed (``None`` when it was).
+
+        Raises:
+            ValueError: ``percent`` is not between 0 and 100, or no model is configured to compact.
+        """
+        if not 0 < percent <= 100:
+            raise ValueError("The compression share must be more than 0 and at most 100.")
+        if self.runtime.active_model is None:
+            raise ValueError(NO_MODEL_REFUSAL)
+        active = self.runtime.required_model
+        value = int(percent) if float(percent).is_integer() else percent
+        try:
+            for index, (model, entry) in enumerate(self.file_models()):
+                if model == active:
+                    return self.update_configured_model(index, {**entry, "compact_percent": value}), None
+            reason = "the model in use is not in the config file"
+        except ConfigEditError as error:
+            reason = str(error)
+        edited = replace(active, compact_percent=float(percent))
+        models = tuple(edited if model is active else model for model in self.models)
+        return self.runtime.replace_models(models), reason
+
+    def remove_configured_model(self, index: int) -> ModelConfig:
+        """Remove model number ``index`` (from zero) from the file and this session.
+
+        Returns:
+            The model in use afterwards: the one before unless it was the one removed.
+
+        Raises:
+            ConfigEditError: When it is the only model, or the file cannot be edited.
+        """
+        text = remove_model(self._read_config_file(), index, where=self.config_file)
+        return self._commit_models(text)
+
+    @property
+    def self_compaction(self) -> bool:
+        """Return whether the model may request compaction in this session right now."""
+        return self.runtime.self_compacting(self.session_id)
+
+    @property
+    def self_compaction_choice(self) -> bool | None:
+        """Return this session's own choice, or ``None`` when it follows the default."""
+        return self.runtime.self_compaction_choice(self.session_id)
+
+    @property
+    def self_compaction_default(self) -> bool:
+        """Return what a session that has made no choice does: ``[compaction] self`` in the config."""
+        return self.runtime.config.self_compaction
+
+    def use_self_compaction(self, choice: bool | None) -> None:
+        """Set this session's own choice, or give it back with ``None`` so it follows the default.
+
+        Raises:
+            SessionLocked: Another process has the session open; the choice is part of the session.
+            ConfigEditError: The choice could not be saved. Nothing is reported as saved then.
+        """
+        self.require_session()
+        try:
+            self.runtime.choose_self_compaction(self.session_id, choice)
+        except OSError as error:
+            raise ConfigEditError(f"Self-compaction setting was not saved: {error}") from error
+
+    def remember_self_compaction(self, enabled: bool) -> Path:
+        """Write ``[compaction] self = enabled`` into the config file: the default for every session.
+
+        The file is written first and the running configuration changed second, so a write that fails
+        leaves both as they were. A session with a choice of its own keeps it; one without follows this at
+        once. A config file that does not exist is not created for it, as for the theme.
+
+        Returns:
+            The file written.
+
+        Raises:
+            ConfigEditError: When there is no config file, it cannot be read or edited safely, or it cannot
+                be written.
+        """
+        text = set_self_compaction(self._read_config_file(), enabled, where=self.config_file)
+        try:
+            write_text_atomically(self.config_file, text)
+        except OSError as error:
+            raise ConfigEditError(f"{self.config_file} could not be written: {error}") from error
+        self.runtime.config = replace(self.runtime.config, self_compaction=enabled)
+        return self.config_file
+
+    @property
+    def effort(self) -> str:
+        """Return the reasoning effort the next request will ask for."""
+        return self.runtime.effort.value
+
+    @property
+    def efforts(self) -> tuple[str, ...]:
+        """Return the reasoning levels the active model takes, cheapest first; none when no model is configured."""
+        model = self.runtime.active_model
+        return () if model is None else tuple(level.value for level in model.efforts)
+
+    def use_effort(self, name: str) -> str:
+        """Select a reasoning level for later requests and return its value."""
+        return self.runtime.use_effort(name).value
+
+    def approve_all_shell_commands(self) -> None:
+        """Approve every shell command for the rest of this run, without asking."""
+        self.runtime.approve_all_shell_commands()
+
+    @property
+    def permission(self) -> Permission:
+        """Return how much of the shell may run without asking."""
+        return self.runtime.permission
+
+    @property
+    def permissions(self) -> tuple[str, ...]:
+        """Return the permission levels, strictest first."""
+        return tuple(level.value for level in PERMISSION_LEVELS)
+
+    def use_permission(self, name: str | Permission, *, remember: bool = True) -> Permission:
+        """Set how much of the shell may run without asking, and by default remember it for this session."""
+        return self.runtime.use_permission(name, remember=remember)
+
+    @property
+    def harness(self) -> bool:
+        """Return whether the just-in-time harness is on for the next request."""
+        return self.runtime.harness.on
+
+    def use_harness(self, on: bool) -> bool:
+        """Turn the just-in-time harness on or off for later requests, for the rest of this run."""
+        return self.runtime.use_harness(on)

zettcode/engine/agent/turns.py

@@ -0,0 +1,308 @@
+"""Running a turn: building the message, streaming the agent's events, and steering one in flight."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, AsyncIterator, Sequence
+from contextlib import aclosing
+from dataclasses import replace
+from typing import cast
+
+from zett_agent.agent import AgentRunConfig
+from zett_agent.dispatcher import AgentEventDispatcher
+from zett_agent.events import AgentEvent
+from zett_agent.exceptions import AgentResumeError
+from zett_agent.extensions.external import ExternalEvent
+from zett_agent.extensions.steering import STEERING_MESSAGE_EVENT_NAME
+from zett_agent.messages import ImageBytesSource, ImageContent, TextContent, UserMessage
+from zett_agent.model import CacheMode
+from zett_agent.resume import ResumePoint
+
+from zettcode.engine.dialogue.side import ORIGIN, READER, SIDE, WATCHED, question, watched_by
+from zettcode.prompt import MentionPart, PromptPart, carries_image, model_text_part, plain_text
+from zettcode.relay import Relayed
+
+from .base import AgentBase
+
+
+def cache_mode_of(value: CacheMode | str | None, *, side: bool) -> CacheMode:
+    """Return the cache mode one run carries, checking a word the caller wrote.
+
+    A turn of the conversation may extend the provider's cached prefix: the next turn reads it, which is what
+    caching is for. A side question is not replayed, so its own content is not worth writing into the cache; it
+    starts at ``READ``, which still reuses the conversation's warm prefix and marks only the stable parts.
+
+    Raises:
+        ValueError: ``value`` is not one of ``off``, ``read`` and ``read_write``.
+    """
+    if value is None:
+        return CacheMode.READ if side else CacheMode.READ_WRITE
+    try:
+        return CacheMode(value)
+    except ValueError:
+        raise ValueError(f"cache must be off, read or read_write, not {value!r}") from None
+
+
+class TurnsMixin(AgentBase):
+    """Turn the reader's parts into a request, stream what comes back, and steer it."""
+
+    def set_event_dispatcher(self, dispatcher: AgentEventDispatcher) -> None:
+        """Send streamed agent events to the application's transcript projector."""
+        self.runtime.set_event_dispatcher(dispatcher)
+
+    async def stream(
+        self,
+        parts: Sequence[PromptPart],
+        *,
+        hint: str | None = None,
+        side: bool = False,
+        origin: str = READER,
+        watched: bool | None = None,
+        relayed: Relayed | None = None,
+        cache: CacheMode | str | None = None,
+    ) -> AsyncIterator[AgentEvent]:
+        """Run one turn with the selected session, model, and reasoning effort.
+
+        Args:
+            parts: The user turn in the order it was written: text runs and the
+                images the composer interleaved with them. A turn without
+                images is simply one text part.
+            hint: Text appended after the turn: the instructions a ``@``
+                reference contributes, then anything the caller added (the SDK
+                merges them). The text the user typed then rides along as the
+                message's ``prompt`` attribute, so the stored message is what
+                was typed and a restored session shows it.
+            side: Ask without letting the exchange join the conversation; see
+                :mod:`zettcode.engine.dialogue.side`.
+            relayed: The turn is a message another session sent. It is what the model reads
+                (with where it came from), and ``parts`` and ``hint`` are not used.
+            cache: How this request may use the provider's prompt cache: ``"read_write"`` (the default) extends
+                it, ``"read"`` reuses a warm prefix without marking this request's new content for caching, and
+                ``"off"`` sends no cache directive at all. A side question starts at ``"read"`` unless told
+                otherwise, because its answer is never replayed.
+            origin: Who asked a side question — ``"reader"`` for the reader's ``/btw``, or the name of the plugin
+                asking for itself. It is stored with the exchange, and only a reader's own is restored into a transcript
+                by default.
+            watched: Whether a reopened transcript restores this exchange, overriding what ``origin`` implies. It does
+                not make a front end draw it now. Ignored when ``side`` is false.
+
+        Raises:
+            SessionLocked: Another process has the session open. Checked before anything else, and a side
+                question is no exception: the store records it even though it never replays it.
+        """
+        self.require_session()
+        await self.runtime.start()
+        client = self.runtime.started
+        used = self.runtime.required_model.shown_name
+        session_id = self.session_id
+        try:
+            # Closed here, not left to the garbage collector: a consumer that stops early (a `break`, `aclose()`)
+            # throws GeneratorExit in at the `yield`, and the library's stream must unwind then, or the agent is
+            # left in its "generating" phase and refuses the next request.
+            async with aclosing(
+                cast(
+                    "AsyncGenerator[AgentEvent]",
+                    client.stream(
+                        self.request(parts, hint=hint, side=side, origin=origin, watched=watched)
+                        if relayed is None
+                        else relayed.message(),
+                        config=AgentRunConfig(
+                            session_id=session_id,
+                            cache_mode=cache_mode_of(cache, side=side),
+                        ),
+                        model=self.runtime.provider,
+                        reasoning_effort=self.runtime.effort,
+                    ),
+                )
+            ) as events:
+                async for event in events:
+                    yield event
+        finally:
+            if not side:
+                self._remember_model(session_id, used)
+
+    async def resume_point(self) -> ResumePoint | None:
+        """Report where the active session was interrupted, or ``None`` when there is nothing to pick up.
+
+        Nothing is written and no model is called. A session another process has open is refused, as a turn is.
+
+        Raises:
+            SessionLocked: Another process has the session open.
+        """
+        self.require_session()
+        await self.runtime.start()
+        return await self.runtime.started.resume_point(
+            config=AgentRunConfig(session_id=self.session_id), model=self.runtime.provider
+        )
+
+    async def resume_blocker(self) -> str | None:
+        """Say why the active session cannot be picked up, in the library's own words; ``None`` when it can.
+
+        :meth:`resume_point` answers only that there is none. The reason is one the reader can act on — a finished
+        request, a refusal that would be declined again, a context window that is full — and the library says it when
+        a resume is asked for, so it is asked for here and stopped before it starts.
+        """
+        self.require_session()
+        await self.runtime.start()
+        stream = self.runtime.started.stream_resume(
+            config=AgentRunConfig(session_id=self.session_id), model=self.runtime.provider
+        )
+        try:
+            async for _event in stream:
+                return None  # it can be resumed after all; the first event is as far as this looks
+        except AgentResumeError as error:
+            return str(error)
+        finally:
+            await stream.aclose()  # type: ignore[attr-defined]
+        return None
+
+    async def stream_resume(self) -> AsyncIterator[AgentEvent]:
+        """Pick the interrupted request up where it stopped, with the model and effort the next turn would use.
+
+        The library takes none of these from the session, so the same ones a turn would carry are given.
+
+        Raises:
+            SessionLocked: Another process has the session open.
+            AgentResumeError: There is nothing to pick up; :meth:`resume_point` says whether there is.
+        """
+        self.require_session()
+        await self.runtime.start()
+        client = self.runtime.started
+        used = self.runtime.required_model.shown_name
+        session_id = self.session_id
+        try:
+            async with aclosing(
+                cast(
+                    "AsyncGenerator[AgentEvent]",
+                    client.stream_resume(
+                        config=AgentRunConfig(session_id=session_id),
+                        model=self.runtime.provider,
+                        reasoning_effort=self.runtime.effort,
+                    ),
+                )
+            ) as events:
+                async for event in events:
+                    yield event
+        finally:
+            self._remember_model(session_id, used)
+
+    def _remember_model(self, session_id: str, model: str) -> None:
+        """Record the model a turn used in its session, so resuming the session starts on it.
+
+        Done when the turn ends, however it ends — a stopped or failed turn used the model too —
+        and not before it, because a session's folder does not exist until its first message is
+        written. A side question is not part of the conversation and records nothing. Metadata is
+        never worth failing a conversation for, so a store that cannot be written or read here is
+        passed over; the next turn tries again.
+        """
+        try:
+            self.runtime.persistence.set_model(session_id, model)
+        except (OSError, ValueError):
+            pass
+
+    @staticmethod
+    def request(
+        parts: Sequence[PromptPart],
+        *,
+        hint: str | None = None,
+        side: bool = False,
+        origin: str = READER,
+        watched: bool | None = None,
+    ) -> str | UserMessage:
+        """Return the user turn those ordered parts make up.
+
+        Text and images keep the order they were written in inside one
+        ``UserMessage``, so a picture is read where its writer placed it rather
+        than after the whole prompt. A turn with no image stays a plain string.
+        ``hint`` is appended last — as a trailing part when an image is in the
+        turn — and the typed text then rides along as the message's ``prompt``
+        attribute, so storage and a restored session keep it.
+
+        Args:
+            parts: The turn in the order it was written.
+            hint: Instructions the model reads after the turn: what a ``@``
+                reference contributed, then what the caller added.
+            side: Mark the turn as a side question, which the store records but
+                never replays.
+            origin: Who asked it: ``"reader"``, or the name of the plugin asking for itself. The store keeps it beside
+                the side mark.
+            watched: Whether a reopened transcript restores it, overriding what ``origin`` implies. Left out, a
+                reader's question is restored and a plugin's is not; it does not make a front end draw it now.
+        """
+        message = TurnsMixin.turn(parts, hint=hint)
+        if not side:
+            return message
+        if isinstance(message, UserMessage):
+            return replace(
+                message,
+                attributes={
+                    **message.attributes,
+                    SIDE: True,
+                    ORIGIN: origin,
+                    WATCHED: watched_by(origin, watched),
+                },
+                include_in_messages=False,
+            )
+        return question(message, origin=origin, watched=watched)
+
+    @staticmethod
+    def turn(parts: Sequence[PromptPart], *, hint: str | None = None) -> str | UserMessage:
+        """Return the message those parts make up, before any side marking."""
+        if not carries_image(parts):
+            text = plain_text(parts)
+            if hint is None:
+                return text
+            said = "".join(model_text_part(part) for part in parts)
+            return UserMessage(content=f"{said}\n\n{hint}", attributes={"prompt": text})
+        content: list[TextContent | ImageContent] = []
+        for part in parts:
+            if isinstance(part, (str, MentionPart)):
+                text = model_text_part(part)
+                if text:
+                    content.append(TextContent(text))
+                continue
+            data, media_type = part
+            content.append(ImageContent(source=ImageBytesSource(data=data, media_type=media_type)))
+        if hint is not None:
+            content.append(TextContent(hint))
+        message = UserMessage(content=content)
+        if hint is not None:
+            message.attributes["prompt"] = plain_text(parts)
+        return message
+
+    def tasks(self) -> tuple[tuple[str, str], ...]:
+        """Return the current session's plan as display-ready status/content pairs."""
+        todos = self.runtime.todos
+        progress = todos.todos(self.session_id) if todos is not None else None
+        return tuple((item.status.value, item.content) for item in progress.todos) if progress else ()
+
+    def steer(self, message: str | UserMessage) -> bool:
+        """Queue an urgent user message for the request that is running.
+
+        The agent adopts it at the next model or tool boundary and drops the
+        rest of the current task, so the shell offers this only while a turn is
+        in flight. Returns whether a running request accepted the message, which
+        is what tells the shell it may show the message as queued.
+
+        Args:
+            message: What the user typed, as text, or as a message when it carries
+                pictures (see :meth:`turn`): zett-agent's steering inbox takes either.
+                An empty one is refused without asking the agent, and a request that
+                is not running refuses it here.
+        """
+        if isinstance(message, str):
+            if not message.strip():
+                return False
+            payload: dict[str, object] = {"content": message}
+        else:
+            if not message.text.strip() and not message.parts:
+                return False
+            payload = {"message": message}
+        try:
+            agent = self.runtime.started.agent
+        except RuntimeError:
+            return False
+        accepted = agent.emit_external_event(
+            ExternalEvent(name=STEERING_MESSAGE_EVENT_NAME, payload=payload),
+            config=AgentRunConfig(session_id=self.session_id),
+        )
+        return bool(accepted)