zettcode-skills 0.4.1__tar.gz

zettcode_skills-0.4.1/.gitignore

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

zettcode_skills-0.4.1/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: zettcode-skills
+Version: 0.4.1
+Summary: The skills of ZettCode: the @ references and the tool that lets the model read one, as a part of the agent that lives apart from it
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: agent,skills,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: zett-agent<0.3,>=0.2.7
+Requires-Dist: zettcode-engine

zettcode_skills-0.4.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "zettcode-skills"
+description = "The skills of ZettCode: the @ references and the tool that lets the model read one, as a part of the agent that lives apart from it"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "skills", "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 = [
+  # The plugin base classes and the shape of an @ reference.
+  "zettcode-engine",
+  # The skill extension that discovers and reads them.
+  "zett-agent>=0.2.7,<0.3",
+]
+
+# Parts of the program, not plugins: the `zettcode.plugins` group is what the plugin release line looks for. They are
+# activated with the agent's other parts and `[skills] enabled` is what turns them off.
+[project.entry-points."zettcode.agent"]
+skills = "zettcode.skills.plugin:SkillResources"
+skill-tool = "zettcode.skills.plugin:SkillTool"
+
+[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_skills-0.4.1/src/zettcode/skills/__init__.py

@@ -0,0 +1,13 @@
+"""The skills of ZettCode: the ``@`` provider that offers them to the composer, and the extension that lists them for
+the model and lets it read one.
+
+A part of the program that lives in a distribution of its own, found through the ``zettcode.agent`` entry point and
+activated with the agent's other parts. ``[skills] enabled`` in the configuration is what turns it off.
+"""
+
+from __future__ import annotations
+
+from .mentions import SkillMentions
+from .plugin import SkillResources, SkillTool
+
+__all__ = ["SkillMentions", "SkillResources", "SkillTool"]

zettcode_skills-0.4.1/src/zettcode/skills/mentions.py

@@ -0,0 +1,47 @@
+"""The ``@`` provider for skills."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from zett_agent.extensions.skill import SkillExtension
+
+from zettcode.mention import Mention, MentionProvider
+
+
+class SkillMentions(MentionProvider):
+    """Skills discovered from the configured roots, named for the model to load."""
+
+    kind = "skill"
+    #: A skill is the more specific thing to mean when a repository holds a file of the same name, so it is asked
+    #: ahead of the files whatever order the plugins were registered in (a session still goes first).
+    precedence = -10
+
+    def __init__(self, roots: Sequence[Path]) -> None:
+        """Discover skills once, the same way the agent's skill extension does."""
+        self._skills = {skill.name: skill for skill in SkillExtension(roots).skills}
+
+    def candidates(self, query: str) -> Sequence[Mention]:
+        """List the discovered skills whose name starts with ``query``."""
+        return tuple(
+            Mention(token=f"@{skill.name}", kind=self.kind, name=skill.name, description=skill.description)
+            for skill in self._skills.values()
+            if skill.name.startswith(query)
+        )
+
+    def expand(self, name: str) -> str | None:
+        """Name the skill and leave loading its instructions to the model.
+
+        The system prompt already catalogs every skill, and ``read_skill`` loads
+        the file, so the message only has to say which one the user meant;
+        inlining the body would spend context on instructions that may not be
+        needed.
+        """
+        skill = self._skills.get(name)
+        if skill is None:
+            return None
+        return (
+            f'Use the "{skill.name}" skill: call read_skill(name="{skill.name}") '
+            "if its instructions are useful and not already in context."
+        )

zettcode_skills-0.4.1/src/zettcode/skills/plugin.py

@@ -0,0 +1,51 @@
+"""The plugins that offer skills: to the composer as ``@`` references, and to the model as a list and a tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from zettcode.engine.plugins.plugin import Plugin, PluginSetting
+
+from .mentions import SkillMentions
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zett_agent.extensions.base import AgentExtension
+
+    from zettcode.engine.plugins.context import PluginContext
+    from zettcode.engine.plugins.state import AgentBuild
+
+
+class SkillResources(Plugin):
+    """The ``@`` resource provider for the skills on this machine.
+
+    Registering it from a plugin rather than inside the shell keeps the shell generic: it merges whatever providers
+    the bundle holds, and the skills are simply one of them.
+    """
+
+    name = "skills"
+    setting = PluginSetting("skills_enabled", "skills")
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Offer the discovered skills as ``@`` resources, when skills are on."""
+        if ctx.config.skills_enabled:
+            ctx.agent.register_mention(SkillMentions(ctx.config.skill_search_roots()))
+
+
+class SkillTool(Plugin):
+    """The skills the model can load: their list in the prompt and the tool that reads one."""
+
+    name = "skill-tool"
+    description = "Skills the model can load"
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Hand the agent the skills found under the configured roots, when skills are on."""
+        config = ctx.config
+        if not config.skills_enabled:
+            return
+
+        def build(_: AgentBuild) -> AgentExtension:
+            from zett_agent.extensions.skill import SkillExtension
+
+            return SkillExtension(config.skill_search_roots())
+
+        ctx.agent.register_extension_factory("SkillExtension", build)