zettcode 0.1.7__tar.gz → 0.1.9__tar.gz

zettcode-0.1.9/.gitignore

@@ -0,0 +1,30 @@
+**/.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 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

zettcode-0.1.9/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: zettcode
+Version: 0.1.9
+Summary: A focused terminal coding agent powered by zett-agent
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: agent,coding-agent,llm,terminal,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: POSIX :: Linux
+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: exceptiongroup<2,>=1.2; python_version < '3.11'
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyperclip<2,>=1.9
+Requires-Dist: setproctitle<2,>=1.3.7; os_name == 'posix'
+Requires-Dist: starlette<2,>=0.48
+Requires-Dist: tiktoken<1,>=0.12
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Requires-Dist: truststore<1,>=0.10
+Requires-Dist: uvicorn<1,>=0.35
+Requires-Dist: wcwidth<1,>=0.2
+Requires-Dist: websockets<17,>=15
+Requires-Dist: zett-agent<0.2,>=0.1.17
+Description-Content-Type: text/markdown
+
+# ZettCode
+
+A focused terminal coding agent powered by [zett-agent](https://pypi.org/project/zett-agent/): it reads and edits your
+code, runs commands with your permission, and is driven by a model you choose. The repository also ships a Python SDK
+and an HTTP server.
+
+```bash
+pip install zettcode
+zettcode
+```
+
+- [The guide](https://chang-lehung.github.io/zettcode/) — commands, keys, plugins, configuration
+- [The SDK](https://chang-lehung.github.io/zettcode/sdk/) — drive the agent from Python
+- [The server](https://chang-lehung.github.io/zettcode/server/) — drive it over HTTP
+
+The full README, with the screenshots, is at the root of the repository.
+
+```python
+import zettcode.sdk as zc
+
+result = await zc.prompt("summarize the README", permission="deny")
+print(result.text)
+```

zettcode-0.1.9/README.md

@@ -0,0 +1,23 @@
+# ZettCode
+
+A focused terminal coding agent powered by [zett-agent](https://pypi.org/project/zett-agent/): it reads and edits your
+code, runs commands with your permission, and is driven by a model you choose. The repository also ships a Python SDK
+and an HTTP server.
+
+```bash
+pip install zettcode
+zettcode
+```
+
+- [The guide](https://chang-lehung.github.io/zettcode/) — commands, keys, plugins, configuration
+- [The SDK](https://chang-lehung.github.io/zettcode/sdk/) — drive the agent from Python
+- [The server](https://chang-lehung.github.io/zettcode/server/) — drive it over HTTP
+
+The full README, with the screenshots, is at the root of the repository.
+
+```python
+import zettcode.sdk as zc
+
+result = await zc.prompt("summarize the README", permission="deny")
+print(result.text)
+```

{zettcode-0.1.7 → zettcode-0.1.9}/pyproject.toml

@@ -5,7 +5,6 @@ readme = "README.md"
 requires-python = ">=3.10"
 dynamic = ["version"]
 license = "MIT"
-license-files = ["LICENSE"]
 authors = [{name = "Chang-LeHung"}]
 keywords = ["agent", "llm", "tui", "terminal", "coding-agent"]
 classifiers = [
@@ -19,6 +18,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Typing :: Typed",
 ]
 dependencies = [
@@ -53,7 +53,7 @@ dependencies = [
   # than it did. An exact pin would make zettcode fight every other tool that
   # shares the dependency — including an upgrade of zett-agent itself, which pip
   # would downgrade to satisfy it.
-  "zett-agent>=0.1.15,<0.2",
+  "zett-agent>=0.1.17,<0.2",
 ]
 
 [project.scripts]
@@ -75,53 +75,8 @@ path = "src/zettcode/__init__.py"
 packages = ["src/zettcode"]
 
 [tool.hatch.build.targets.sdist]
-include = ["/src", "/README.md", "/README.zh-CN.md", "/LICENSE", "/pyproject.toml"]
-
-[dependency-groups]
-dev = [
-  # Unlike the conditional runtime deps, these are installed on every
-  # interpreter so mypy can check the 3.10 branch of ``_compat`` for real.
-  "exceptiongroup>=1.2,<2",
-  "mypy>=1.14,<2",
-  "pytest>=8,<9",
-  "pytest-asyncio>=0.26,<2",
-  "pytest-cov>=7.1.0",
-  "ruff>=0.11,<1",
-  "tomli>=2,<3",
-  "viztracer>=1.1.1",
-]
+include = ["/src", "/README.md", "/pyproject.toml"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
-
-[tool.mypy]
-python_version = "3.10"
-files = ["src", "perf"]
-# Check the pydantic storage models as models, not as plain classes.
-plugins = ["pydantic.mypy"]
-warn_unused_ignores = true
-warn_redundant_casts = true
-no_implicit_optional = true
-
-[[tool.mypy.overrides]]
-# Ships no stubs; the runner only calls the two documented functions.
-module = ["pyperclip"]
-ignore_missing_imports = true
-
-[tool.ruff]
-line-length = 120
-target-version = "py310"
-src = ["src", "tests", "perf"]
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
-ignore = ["E501"]
-
-[tool.ruff.lint.isort]
-known-first-party = ["zettcode"]
-
-[tool.ruff.format]
-quote-style = "double"
-indent-style = "space"
-line-ending = "lf"

{zettcode-0.1.7 → zettcode-0.1.9}/src/zettcode/__init__.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 
 #: The one place the version is written. ``pyproject.toml`` reads it from here
 #: and the release workflow checks the tag against it, so a bump is one edit.
-__version__ = "0.1.7"
+__version__ = "0.1.9"
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {

{zettcode-0.1.7 → zettcode-0.1.9}/src/zettcode/_compat.py

@@ -1,6 +1,6 @@
 """Small shims for the language versions this project supports.
 
-ZettCode runs on Python 3.10 through 3.14, so the few things the standard
+ZettCode runs on Python 3.10 through 3.15, so the few things the standard
 library grew in between live here instead of behind version checks at each use.
 """
 

{zettcode-0.1.7 → zettcode-0.1.9}/src/zettcode/app/agent/agent/__init__.py

@@ -22,7 +22,8 @@ is the composition and the lifecycle — building the runtime, and closing it.
 
 from __future__ import annotations
 
-from ....config import ZettCodeConfig
+from zettcode.config import ZettCodeConfig
+
 from ..runtime import ZettCodeRuntime
 from .commands import CommandsMixin
 from .context import ContextMixin

zettcode-0.1.9/src/zettcode/app/agent/agent/commands.py

@@ -0,0 +1,214 @@
+"""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
+
+from zettcode.app.commands import Command, CommandContext, CommandHost, CommandResult
+from zettcode.app.pets import PetCatalog, bundled_pets
+from zettcode.plugins import UiRow
+from zettcode.plugins.services import HOST_LINK, HostLink
+from zettcode.providers import BUILTIN_PROVIDERS, Provider, merge_providers
+from zettcode.statusline import NAMES, unknown
+from zettcode.tui import ThemeCatalog
+
+from ..conversation.presenters import Presenters
+from ..dialogue.mentions import MentionProvider
+from .exports import ExportsMixin
+
+#: The words ``/self-compact`` takes after it, or after ``global``.
+_SELF_COMPACT_WORDS = frozenset({"on", "off", "default"})
+
+
+class CommandsMixin(ExportsMixin):
+    """The ``/new``, ``/compact``, and ``/export`` commands, and the plugins' commands, mentions, and rows."""
+
+    @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.runtime.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.runtime.plugins.builtin_commands
+
+    @property
+    def plugin_mentions(self) -> tuple[MentionProvider, ...]:
+        """Return the ``@`` resource providers the installed plugins registered."""
+        return self.runtime.plugins.mentions
+
+    @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.runtime.plugins.themes, self.runtime.config.themes_dir)
+
+    @property
+    def pets(self) -> PetCatalog:
+        """Return every pet that can be asked for by name: the built-in plugin's, then any other plugin's.
+
+        A plugin bundle that offers none (one built by hand, without the built-in plugin) gets the program's own.
+        """
+        sources = self.runtime.plugins.pets
+        return PetCatalog(sources or bundled_pets())
+
+    @property
+    def plugin_failures(self) -> tuple[str, ...]:
+        """Return one message per plugin that could not be loaded or activated."""
+        return self.runtime.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.runtime.plugins.presenters)
+
+    @property
+    def plugin_rows(self) -> tuple[UiRow, ...]:
+        """Return the header and status rows plugins asked the shell to draw."""
+        return self.runtime.plugins.rows
+
+    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]
+        if not hidden:
+            return "Status line: every part is shown"
+        return f"Status line: {len(hidden)} of {len(NAMES)} 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 and the outcome notice arrive while this await runs: the pass
+        dispatches through the same event dispatcher a turn does, so the
+        transcript animates ``Compacting`` and ends with ``Context compaction
+        applied`` (or ``skipped`` when the summary would not be smaller).
+        """
+        await self.compact()
+        return CommandResult()

{zettcode-0.1.7 → zettcode-0.1.9}/src/zettcode/app/agent/agent/sessions.py

@@ -8,15 +8,17 @@ the rest of the shell does.
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
 from zett_agent.messages import AssistantMessage, UserMessage
+from zett_agent.model import ReasoningEffort
 
 from ..conversation.replay import Replayed, replay
 from ..conversation.transcript import Transcript
 from ..dialogue.title import summarize_title
-from ..storage import Session, SessionInfo
+from ..storage import Session, SessionInfo, SessionStats
 from .context import ContextMixin
 
 #: The name a session shows before the agent has given it a title.
@@ -170,6 +172,13 @@ class SessionsMixin(ContextMixin):
         """List persisted session metadata by recent activity."""
         return await self.runtime.persistence.list_sessions(limit=limit)
 
+    async def session_stats(self, sessions: Sequence[SessionInfo]) -> dict[str, SessionStats]:
+        """Return the entry count and token totals of listed sessions, keyed by session id.
+
+        A session missing from the answer has no totals to show.
+        """
+        return await self.runtime.persistence.session_stats([session.session_id for session in sessions])
+
     async def rename_session(self, title: str) -> str:
         """Store a display title for the active session and return it cleaned.
 
@@ -218,7 +227,9 @@ class SessionsMixin(ContextMixin):
         if not question or not answer:
             return None
         await self.runtime.start()
-        title = await summarize_title(self.runtime.provider, question=question, answer=answer)
+        # A level the model takes, so naming the session cannot be what fails on an endpoint that lacks `low`.
+        effort = self.runtime.active_model.accepted_effort(ReasoningEffort.LOW)
+        title = await summarize_title(self.runtime.provider, question=question, answer=answer, effort=effort)
         if title is None:
             return None
         await self.runtime.persistence.set_title(session_id, title)