zettcode-app 0.4.2__tar.gz

zettcode_app-0.4.2/.gitignore

@@ -0,0 +1,42 @@
+**/.venv/
+**/__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.smoke/
+.coverage
+**/.pytest_cache/
+**/.ruff_cache/
+.zett-tool-output/
+.env
+.DS_Store
+
+# viztracer writes its trace here by default.
+/result.json
+
+# The docs site: dependencies, build output, and VitePress' cache.
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+docs/.vitepress/.temp/
+
+# The TypeScript client is built from its sources; only dist/ is published.
+clients/typescript/dist/
+
+# The gateway's page is built from clients/gateway into the package when a distribution is made (`make gateway-ui`);
+# the build output is not kept in the repository. pyproject's `artifacts` puts it in the wheel all the same.
+packages/zettcode-gateway/src/zettcode/gateway/static/
+
+# The palette gallery is generated by `make palettes`: every widget painted in
+# every palette, written by docs/scripts/palette_gallery.py. Regenerate it
+# rather than committing a 2 MB copy that goes stale the moment a colour moves.
+docs/internal/palettes.html
+
+# The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
+packages/order.txt
+
+# The desktop and phone apps build the gateway's page into their own folders, and electron-builder writes its
+# installers under release/.
+clients/desktop/renderer/
+clients/desktop/release/

zettcode_app-0.4.2/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.5
+Name: zettcode-app
+Version: 0.4.2
+Summary: The terminal application of ZettCode: the conversation model, the shell and its views
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: agent,terminal,tui,zettcode
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: truststore<1,>=0.10
+Requires-Dist: zett-agent<0.3,>=0.2.10
+Requires-Dist: zettcode-broker
+Requires-Dist: zettcode-engine
+Requires-Dist: zettcode-messaging
+Requires-Dist: zettcode-plugin-api
+Requires-Dist: zettcode-presenters
+Requires-Dist: zettcode-sdk
+Requires-Dist: zettcode-tui

zettcode_app-0.4.2/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "zettcode-app"
+description = "The terminal application of ZettCode: the conversation model, the shell and its views"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "terminal", "tui", "agent"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+dependencies = [
+  "zettcode-engine",
+  "zettcode-tui",
+  "zettcode-sdk",
+  "zettcode-broker",
+  # The line to the other sessions, which the shell's agent carries and matches messages against.
+  "zettcode-messaging",
+  "zettcode-plugin-api",
+  "zettcode-presenters",
+  "zett-agent>=0.2.10,<0.3",
+  # The release check verifies the index against the system trust store; imported by `update.py` with a
+  # fallback, so it is a hint rather than a requirement.
+  "truststore>=0.10,<1",
+]
+
+# Parts of the program that need a screen, loaded as plugins by the terminal only; see the engine's plugin loader.
+[project.entry-points."zettcode.plugin"]
+themes = "zettcode.app.plugins.builtins:BuiltinThemes"
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+# One version for the whole repository: the engine ships the file.
+path = "../zettcode-engine/src/zettcode/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

zettcode_app-0.4.2/src/zettcode/app/__init__.py

@@ -0,0 +1,63 @@
+"""ZettCode's application layer, split into its interface and its agent glue.
+
+``ui`` holds what the user sees and drives: the transcript and the application
+shell. ``agent`` holds the adapter that turns agent events into transcript
+entries. This module is the facade over both, so ``from zettcode.app import
+ZettCodeApp`` keeps working for callers that do not care where it lives.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+#: Where each public name lives; read by :func:`__getattr__` on first use.
+_EXPORTS = {
+    "Entry": ".agent",
+    "Transcript": ".agent",
+    "TranscriptProjector": ".agent",
+    "TranscriptSource": ".ui",
+    "TranscriptView": ".ui",
+    "TerminalAgent": ".agent",
+    "ZettCodeApp": ".ui",
+    "ZettCodeRoot": ".ui",
+    "ZettCodeEngine": ".agent",
+}
+
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
+    from .agent import Entry, TerminalAgent, Transcript, TranscriptProjector, ZettCodeEngine
+    from .ui import TranscriptSource, TranscriptView, ZettCodeApp, ZettCodeRoot
+
+
+def __getattr__(name: str) -> object:
+    """Import the module a public name lives in, the first time it is asked for.
+
+    This package is a facade over several subpackages, and a caller that wants
+    one name should not pay for the rest of them — the TUI alone holds the
+    widget library, the Markdown parser, the diff viewer, and the syntax
+    scanners. ``__all__`` is still the public surface.
+    """
+    try:
+        module = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    return getattr(importlib.import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """Return the names this package publishes."""
+    return sorted(__all__)
+
+
+__all__ = [
+    "Entry",
+    "Transcript",
+    "TranscriptProjector",
+    "TranscriptSource",
+    "TranscriptView",
+    "ZettCodeApp",
+    "TerminalAgent",
+    "ZettCodeRoot",
+    "ZettCodeEngine",
+]

zettcode_app-0.4.2/src/zettcode/app/agent/__init__.py

@@ -0,0 +1,47 @@
+"""Agent-facing glue: the conversation model and the events that fill it."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+#: Where each public name lives; read by :func:`__getattr__` on first use.
+_EXPORTS = {
+    "Entry": "zettcode.plugin_api.entries",
+    "Transcript": ".conversation.transcript",
+    "TranscriptProjector": ".conversation.projection",
+    "TerminalAgent": ".agent",
+    "ZettCodeEngine": "zettcode.engine.core",
+}
+
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
+    from zettcode.engine.core import ZettCodeEngine
+    from zettcode.plugin_api.entries import Entry
+
+    from .agent import TerminalAgent
+    from .conversation.projection import TranscriptProjector
+    from .conversation.transcript import Transcript
+
+
+def __getattr__(name: str) -> object:
+    """Import the module a public name lives in, the first time it is asked for.
+
+    This package is a facade over several subpackages, and a caller that wants
+    one name should not pay for the rest of them — the TUI alone holds the
+    widget library, the Markdown parser, the diff viewer, and the syntax
+    scanners. ``__all__`` is still the public surface.
+    """
+    try:
+        module = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    return getattr(importlib.import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """Return the names this package publishes."""
+    return sorted(__all__)
+
+
+__all__ = ["Entry", "Transcript", "TranscriptProjector", "TerminalAgent", "ZettCodeEngine"]

zettcode_app-0.4.2/src/zettcode/app/agent/agent/__init__.py

@@ -0,0 +1,84 @@
+"""The terminal's agent: the engine's agent, plus the commands and preferences only a terminal has.
+
+The engine's agent (:class:`zettcode.engine.agent.ZettCodeAgent`) does the work. This subclass adds what the shell
+asks of it that is not work: the slash commands and what plugins contributed (``commands``), and the theme, the pet
+and the status line the reader can change (``settings``). Its engine is built with the terminal's plugin loader, so
+the commands, palettes, pets, presenters and rows of the plugins are there to be read.
+
+This package is also where the terminal is put together from the engine's parts, so it is what names, for the views, the
+engine objects they hold: ``SessionLink`` (the line to the other sessions) and ``StoredSession`` (a session read from
+the store). The views import those names from here and not from the engine.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeAlias
+
+from zettcode.engine.agent import ZettCodeAgent
+from zettcode.engine.agent.sessions import StoredSession
+from zettcode.engine.core import PluginLoader, ZettCodeEngine
+from zettcode.messaging.messenger import SESSION_LINK, Messenger
+from zettcode.plugin_api.commands import CommandAgent
+
+from .commands import CommandsMixin
+
+#: The line to the other sessions, under the name the views use for it.
+SessionLink: TypeAlias = Messenger
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from collections.abc import Mapping
+
+    from zettcode.config import ZettCodeConfig
+    from zettcode.sdk.client import Client
+
+__all__ = ["SessionLink", "StoredSession", "TerminalAgent"]
+
+
+def _terminal_loader() -> PluginLoader:
+    """Return the terminal's plugin loader, imported when an agent is built and not before."""
+    from zettcode.app.plugins.loader import terminal_plugins
+
+    return terminal_plugins
+
+
+# The contract is last on purpose: `AgentBase`'s concrete `session_id`/`workspace` must win over `CommandAgent`'s
+# abstract properties, or the class becomes uninstantiable.
+class TerminalAgent(CommandsMixin, ZettCodeAgent, CommandAgent):
+    """The agent the terminal application drives."""
+
+    _client: Client | None = None
+
+    @property
+    def messenger(self) -> SessionLink | None:
+        """Return the line to the other sessions, or ``None`` when the configuration switches messaging off."""
+        bundle = getattr(self.runtime, "plugins", None)
+        return None if bundle is None else bundle.find(SESSION_LINK, SessionLink)
+
+    @property
+    def client(self) -> Client:
+        """Return the SDK client over this agent, which is how the shell reaches everything the SDK offers.
+
+        Made on first use and then kept, so the shell and the commands it runs read the same client. The agent still
+        owns closing: the client is a view of it.
+        """
+        if self._client is None:
+            from zettcode.sdk.client import Client
+
+            self._client = Client._around(self)
+        return self._client
+
+    @classmethod
+    async def create(cls, config: ZettCodeConfig, load: PluginLoader | None = None) -> TerminalAgent:
+        """Build the engine with the terminal's plugins and start it."""
+        return cls(await ZettCodeEngine.create(config, load or _terminal_loader()))
+
+    @classmethod
+    def preview(
+        cls,
+        config: ZettCodeConfig,
+        load: PluginLoader | None = None,
+        *,
+        shared: Mapping[str, object] | None = None,
+    ) -> TerminalAgent:
+        """Wrap an engine that still has to start, built with the terminal's plugins, so the shell can paint first."""
+        return cls(ZettCodeEngine.preview(config, load or _terminal_loader(), shared=shared))

zettcode_app-0.4.2/src/zettcode/app/agent/agent/commands.py

@@ -0,0 +1,269 @@
+"""What the agent offers the shell to run and to show: its own commands, and what plugins added.
+
+The commands report through transcript Markdown; commands that present a widget belong to
+the shell, which owns the widgets. The plugin contributions are listed here because the
+agent is where the shell asks for everything the runtime loaded.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+from zettcode.engine.agent.exports import ExportsMixin
+from zettcode.plugin_api.commands import Command, CommandContext, CommandHost, CommandResult
+from zettcode.plugin_api.host import HOST_LINK, HostLink
+from zettcode.plugin_api.pets import PetCatalog
+from zettcode.plugin_api.plugin import TuiPlugins
+from zettcode.plugin_api.presenters import Presenters
+from zettcode.plugin_api.state import TurnSegment, UiRow
+from zettcode.presenters.statusline import NAMES, unknown
+from zettcode.providers import BUILTIN_PROVIDERS, Provider, merge_providers
+from zettcode.tui import ThemeCatalog
+
+from .settings import AppearanceMixin
+
+#: The words ``/self-compact`` takes after it, or after ``global``.
+_SELF_COMPACT_WORDS = frozenset({"on", "off", "default"})
+
+
+class CommandsMixin(AppearanceMixin, ExportsMixin):
+    """The ``/new``, ``/compact``, and ``/export`` commands, and the plugins' commands, mentions, and rows."""
+
+    @property
+    def terminal_plugins(self) -> TuiPlugins:
+        """Return what the plugins contributed to the terminal; the engine was built with the terminal's loader."""
+        plugins = self.runtime.plugins
+        if not isinstance(plugins, TuiPlugins):
+            raise TypeError("This agent's engine was not built with the terminal's plugin loader")
+        return plugins
+
+    @property
+    def commands(self) -> tuple[Command, ...]:
+        """Return the conversation commands the agent owns.
+
+        They report through transcript Markdown; commands that present a widget
+        (such as the model picker) belong to the shell, which owns the widgets.
+        """
+        return (
+            Command("/new", "start a fresh session", "agent", self._command_new),
+            Command("/compact", "summarize the context now", "agent", self._command_compact),
+            Command("/export", "write this session to an HTML file: /export [path]", "agent", self._command_export),
+        )
+
+    def attach_host(self, host: CommandHost) -> None:
+        """Tell the plugins where the shell is, so the words their commands offer can follow the session."""
+        link = self.runtime.plugins.find(HOST_LINK, HostLink)
+        if link is not None:
+            link.attach(host)
+
+    @property
+    def plugin_commands(self) -> tuple[Command, ...]:
+        """Return the commands the installed plugins registered, not counting the built-in ones.
+
+        The shell keeps them after everything built in, so a plugin cannot take over a built-in name;
+        plugin-versus-plugin duplicates are rejected when the plugins load.
+        """
+        return self.terminal_plugins.installed_commands
+
+    @property
+    def builtin_plugin_commands(self) -> tuple[Command, ...]:
+        """Return the commands the program's own plugins registered: ``/resume``, ``/model``, ``/usage`` and the rest."""
+        return self.terminal_plugins.builtin_commands
+
+    @property
+    def providers(self) -> tuple[Provider, ...]:
+        """Return the hosts ``/config`` can offer: the built-in ones, then the plugins' own."""
+        return merge_providers(BUILTIN_PROVIDERS, self.runtime.plugins.providers)
+
+    @property
+    def themes(self) -> ThemeCatalog:
+        """Return every palette that can be asked for by name: the plugins', then the reader's own files.
+
+        Built fresh each time it is asked: it lists names and builds nothing, and the reader's directory may have
+        gained a file since the last look.
+        """
+        return ThemeCatalog(self.terminal_plugins.themes, self.runtime.config.themes_dir)
+
+    @property
+    def pets(self) -> PetCatalog:
+        """Return every pet that can be asked for by name, in the order the plugins registered them.
+
+        Nothing is bundled here: with no pets plugin the catalog is empty.
+        """
+        return PetCatalog(self.terminal_plugins.pets)
+
+    @property
+    def turn_segments(self) -> tuple[TurnSegment, ...]:
+        """Return the items of the line a request ends on, the program's own first, then the plugins'."""
+        return self.terminal_plugins.turn_segments
+
+    @property
+    def pets_switched_off(self) -> bool:
+        """Return whether the reader turned the pets plugin off, which is why a catalog of none is empty."""
+        from zettcode.engine.plugins import off_names
+
+        return "pets" in off_names(self.runtime.config)
+
+    @property
+    def plugin_failures(self) -> tuple[str, ...]:
+        """Return one message per plugin that could not be loaded or activated."""
+        return self.terminal_plugins.failures
+
+    @property
+    def presenters(self) -> Presenters:
+        """Return how this run draws entries: the built-in presenters, and any a plugin outranks them with.
+
+        Built from the bundle rather than from a module-level default for the same reason the palettes are: the
+        program's own rows are registered through the plugin route, so a plugin that draws a kind or a family of
+        rows reaches the transcript without a second path only plugins could not take.
+        """
+        return Presenters(self.terminal_plugins.presenters)
+
+    @property
+    def plugin_rows(self) -> tuple[UiRow, ...]:
+        """Return the header and status rows plugins asked the shell to draw."""
+        return self.terminal_plugins.rows
+
+    @property
+    def plugin_focus_handlers(self) -> tuple[Callable[[bool], None], ...]:
+        """Return the handlers told when the terminal window gains or loses focus."""
+        return self.terminal_plugins.focus_handlers
+
+    @property
+    def plugin_turn_start_handlers(self) -> tuple[Callable[[], None], ...]:
+        """Return the handlers told when a turn of the conversation starts."""
+        return self.terminal_plugins.turn_start_handlers
+
+    @property
+    def plugin_turn_end_handlers(self) -> tuple[Callable[[bool], None], ...]:
+        """Return the handlers told when a turn of the conversation ends."""
+        return self.terminal_plugins.turn_end_handlers
+
+    async def _command_new(self, context: CommandContext) -> CommandResult:
+        """Start a fresh session."""
+        session_id = self.new_session()
+        return CommandResult(notification=f"started session {session_id[:8]}")
+
+    async def _command_export(self, context: CommandContext) -> CommandResult:
+        """Write the session and its context to one HTML file.
+
+        The path argument is optional; without it the file lands in the
+        workspace, named after the session, and the result says where.
+        """
+        path = await self.export_session(context.argument.strip() or None)
+        return CommandResult(message=f"Exported to `{path}`")
+
+    def self_compaction_summary(self) -> str:
+        """Say in one line whether self-compaction is on here, where that comes from, and what the default is."""
+        state = "on" if self.self_compaction else "off"
+        default = "on" if self.self_compaction_default else "off"
+        if self.self_compaction_choice is None:
+            return f"Self-compaction is {state}: this session follows the default ({default})"
+        return f"Self-compaction is {state}: this session chose it; the default is {default}"
+
+    def self_compact_report(self) -> str:
+        """Say what self-compaction is, whether it is on here, and where that comes from."""
+        choice = self.self_compaction_choice
+        default = "on" if self.self_compaction_default else "off"
+        state = "on" if self.self_compaction else "off"
+        source = (
+            f"this session chose it; the config default is **{default}**"
+            if choice is not None
+            else "following the config default (`[compaction] self`)"
+        )
+        return (
+            f"Self-compaction is **{state}** ({source}).\n\n"
+            "When on, the model gets a `compact_context` tool and can summarize its own earlier conversation "
+            "when it judges the detail is no longer needed. The current turn is always kept. "
+            "`/compact` and the automatic threshold work either way.\n\n"
+            "`/self-compact on|off` sets this session; `default` hands it back to the config; "
+            "`global on|off` changes the default for every session that has not chosen."
+        )
+
+    def change_self_compaction(self, argument: str) -> str:
+        """Read or change self-compaction from the words ``/self-compact`` takes, and say what now applies.
+
+        ``on``, ``off`` and ``default`` set this session's own choice; ``global on`` and ``global off``
+        write the default for every session into the config file. A failed write is never reported as saved.
+
+        Raises:
+            ValueError: The words are not ones the command takes, or the change could not be saved.
+        """
+        words = argument.lower().split()
+        scope = "session"
+        if words[:1] == ["global"]:
+            scope, words = "global", words[1:]
+        usage = ValueError("Usage: /self-compact [on|off|default] or /self-compact global on|off")
+        if len(words) > 1 or (scope == "global" and not words) or (words and words[0] not in _SELF_COMPACT_WORDS):
+            raise usage
+        if scope == "global":
+            if words[0] == "default":
+                raise usage
+            self.remember_self_compaction(words[0] == "on")
+        elif words:
+            self.use_self_compaction({"on": True, "off": False, "default": None}[words[0]])
+        return self.self_compact_report()
+
+    def statusline_summary(self) -> str:
+        """Say in one line which parts of the header and the status line are hidden."""
+        hidden = [
+            *(name for name in NAMES if name in self.statusline_hidden),
+            *sorted(self.statusline_hidden - set(NAMES)),
+        ]
+        if not hidden:
+            return "Status line: every part is shown"
+        total = len(NAMES) + len({item.name for item in self.turn_segments} - set(NAMES))
+        return f"Status line: {len(hidden)} of {total} parts hidden ({', '.join(hidden)})"
+
+    def change_statusline(self, argument: str) -> str:
+        """Hide or show parts of the header and status line from the words ``/statusline`` takes.
+
+        ``hide <name>...`` and ``show <name>...`` change the named parts, and ``show all`` brings every one
+        back. The change is written to ``[statusline]`` in the config file, and nothing is changed when any
+        name is not a part.
+
+        Raises:
+            ValueError: The words are not ones the command takes, or the change could not be saved.
+        """
+        words = argument.lower().split()
+        usage = ValueError(
+            f"Usage: /statusline [hide|show] <part>... or /statusline show all; parts: {', '.join(NAMES)}"
+        )
+        if len(words) < 2 or words[0] not in {"hide", "show"}:
+            raise usage
+        visible = words[0] == "show"
+        names = list(NAMES) if visible and words[1:] == ["all"] else words[1:]
+        if stray := unknown(names):
+            raise ValueError(f"No such part: {', '.join(stray)}. Parts: {', '.join(NAMES)}")
+        self.remember_statusline({name: visible for name in names})
+        return self.statusline_summary()
+
+    async def _command_compact(self, context: CommandContext) -> CommandResult:
+        """Summarize the conversation now, whatever its size.
+
+        The row is opened only after the refusal check. That check may read a
+        cold session on a worker, so the interface stays live while it runs;
+        once the row is up, the shell draws it before the pass starts. What
+        follows the first ``await`` is still synchronous token counting and the
+        summary request, so a row created only by ``CompactionStarted`` would
+        reach the screen after the work it was meant to explain.
+        """
+        host = context.host
+        if host is not None:
+            await self.ensure_compactable()
+            host.transcript.start_compaction()
+        try:
+            if host is not None:
+                await host.wait_for_frame()
+                await self._compact_pass()
+            else:
+                await self.compact()
+        except asyncio.CancelledError:
+            if host is not None:
+                host.transcript.complete_compaction("Compacting stopped")
+            raise
+        finally:
+            if host is not None:
+                host.transcript.complete_compaction()
+        return CommandResult()