zettcode-models 0.1.0__tar.gz

zettcode_models-0.1.0/.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_models-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chang-LeHung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zettcode_models-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: zettcode-models
+Version: 0.1.0
+Summary: A ZettCode plugin: an official model for each vendor API key found in the environment
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode/tree/main/packages/zettcode-models
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+License-File: LICENSE
+Keywords: environment,models,plugin,providers,zettcode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+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: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: zettcode-plugin-api<0.5,>=0.4
+Description-Content-Type: text/markdown
+
+# zettcode-models
+
+A ZettCode plugin that offers an **official model** for each vendor whose API key is in the environment:
+OpenAI, Anthropic, DeepSeek and Z.AI.
+
+Install it as an extra and enable it once:
+
+```bash
+pip install "zettcode[models]"
+```
+
+```toml
+[plugins]
+enable = ["models"]
+```
+
+With `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY` or `ZAI_API_KEY` set (`ZHIPUAI_API_KEY` and
+`ZHIPU_API_KEY` are accepted aliases), the plugin registers that host with its current official model — `GPT-6.1 Sol`,
+`Claude Opus 5.5`, `DeepSeek V4.1 Flash` or `GLM-5.3`. The model appears in `/model` with `from the openai plugin`
+(or `anthropic`, `deepseek`, `zai`); its token is read from the environment and never written to `config.toml`.
+
+The list is static and no endpoint is called at start. The plugin is off by default: a set of ambient keys should not
+change a model list unless the reader asks it to.

zettcode_models-0.1.0/README.md

@@ -0,0 +1,23 @@
+# zettcode-models
+
+A ZettCode plugin that offers an **official model** for each vendor whose API key is in the environment:
+OpenAI, Anthropic, DeepSeek and Z.AI.
+
+Install it as an extra and enable it once:
+
+```bash
+pip install "zettcode[models]"
+```
+
+```toml
+[plugins]
+enable = ["models"]
+```
+
+With `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY` or `ZAI_API_KEY` set (`ZHIPUAI_API_KEY` and
+`ZHIPU_API_KEY` are accepted aliases), the plugin registers that host with its current official model — `GPT-6.1 Sol`,
+`Claude Opus 5.5`, `DeepSeek V4.1 Flash` or `GLM-5.3`. The model appears in `/model` with `from the openai plugin`
+(or `anthropic`, `deepseek`, `zai`); its token is read from the environment and never written to `config.toml`.
+
+The list is static and no endpoint is called at start. The plugin is off by default: a set of ambient keys should not
+change a model list unless the reader asks it to.

zettcode_models-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "zettcode-models"
+description = "A ZettCode plugin: an official model for each vendor API key found in the environment"
+readme = "README.md"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "plugin", "models", "providers", "environment"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "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",
+  "Topic :: Software Development :: User Interfaces",
+  "Typing :: Typed",
+]
+dependencies = [
+  # The plugin contract only: the Provider and ProvidedModel the plugin registers, and the PluginContext it activates
+  # with. The API this release uses is the one that lets a plugin offer models, new in 0.4.
+  "zettcode-plugin-api>=0.4,<0.5",
+]
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode/tree/main/packages/zettcode-models"
+Issues = "https://github.com/Chang-LeHung/zettcode/issues"
+
+[project.entry-points."zettcode.plugin"]
+models = "zettcode.models:ModelsPlugin"
+
+[tool.zettcode]
+# Published on its own line, installed by a reader who wants it, and off until `[plugins] enable` names it.
+plugin = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/zettcode/models/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[dependency-groups]
+# What the tests import beyond the plugin itself. The workspace's own dev group carries the same names for `make test`;
+# this one is what the release workflow installs into the fresh environment it tests the built plugin in.
+dev = ["pytest>=8,<9"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

zettcode_models-0.1.0/src/zettcode/models/__init__.py

@@ -0,0 +1,156 @@
+"""Official models for the vendor API keys found in the environment.
+
+A reader who has ``OPENAI_API_KEY``, ``ANTHROPIC_API_KEY``, ``DEEPSEEK_API_KEY`` or ``ZAI_API_KEY`` set does not
+have to type an address or a model id to try that vendor. The plugin knows the current official model of each host,
+registers it as one :class:`~zettcode.plugin_api.ProvidedModel`, and leaves the token to the runtime, which reads it
+from the variable named here and never writes it to the configuration.
+
+The list is deliberately static: a start asks no vendor for anything, so a key in the environment costs no network
+round trip. It is off by default — ambient keys should not change a model list unless the reader enables the plugin
+with ``[plugins] enable = ["models"]``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from zettcode.plugin_api import Plugin, PluginContext, ProvidedModel, Provider
+
+#: The one place the version is written; ``pyproject.toml`` reads it from here.
+__version__ = "0.1.0"
+
+
+@dataclass(frozen=True, slots=True)
+class Vendor:
+    """One host an environment variable can open.
+
+    Attributes:
+        name: The provider name, which is unique across the application.
+        label: What a list shows for the host.
+        env: The variables that may hold the key, most specific first.
+        base_url: The address the client appends its route to.
+        api: Which protocol the host speaks.
+        model: The vendor's current official model id.
+        display: What ``/model`` shows for it.
+        context_window: Tokens it can carry.
+        multimodal: Whether it takes images.
+    """
+
+    name: str
+    label: str
+    env: tuple[str, ...]
+    base_url: str
+    api: str
+    model: str
+    display: str
+    context_window: int
+    multimodal: bool = False
+
+    def key(self) -> tuple[str, str] | None:
+        """Return the variable that holds this host's key and the key itself, or ``None`` when none is set."""
+        for variable in self.env:
+            value = os.getenv(variable)
+            if value:
+                return variable, value
+        return None
+
+
+#: The official model offered for each host, checked against the vendors' model pages on 2026-11-10. The ids and
+#: windows are the whole of this plugin's knowledge: when a vendor moves on, this table is the one place to edit.
+VENDORS: tuple[Vendor, ...] = (
+    Vendor(
+        "openai",
+        "OpenAI",
+        ("OPENAI_API_KEY",),
+        "https://api.openai.com/v1",
+        "chat",
+        "gpt-6.1-sol",
+        "GPT-6.1 Sol",
+        1_050_000,
+        multimodal=True,
+    ),
+    Vendor(
+        "anthropic",
+        "Anthropic",
+        ("ANTHROPIC_API_KEY",),
+        "https://api.anthropic.com",
+        "anthropic",
+        "claude-opus-5-5",
+        "Claude Opus 5.5",
+        1_000_000,
+        multimodal=True,
+    ),
+    Vendor(
+        "deepseek",
+        "DeepSeek",
+        ("DEEPSEEK_API_KEY",),
+        "https://api.deepseek.com",
+        "chat",
+        "deepseek-v4.1-flash",
+        "DeepSeek V4.1 Flash",
+        1_000_000,
+    ),
+    Vendor(
+        "zai",
+        "Z.AI",
+        ("ZAI_API_KEY", "ZHIPUAI_API_KEY", "ZHIPU_API_KEY"),
+        "https://api.z.ai/api/paas/v4",
+        "chat",
+        "glm-5.3",
+        "GLM-5.3",
+        1_000_000,
+    ),
+)
+
+
+def _provider(vendor: Vendor, variable: str) -> Provider:
+    """Return the host description for one vendor, with the one model it offers."""
+    return Provider(
+        vendor.name,
+        vendor.label,
+        # The vendor names the protocol as the word Provider parses.
+        api=vendor.api,  # type: ignore[arg-type]
+        base_url=vendor.base_url,
+        token_env=variable,
+        models=(
+            ProvidedModel(
+                vendor.model,
+                display_model=vendor.display,
+                context_window=vendor.context_window,
+                multimodal=vendor.multimodal,
+            ),
+        ),
+        note="official model",
+    )
+
+
+class ModelsPlugin(Plugin[PluginContext]):
+    """Offer one official model for each vendor whose API key is in the environment."""
+
+    name = "models"
+    description = "An official model for each vendor API key in the environment"
+
+    @classmethod
+    def default_enabled(cls) -> bool:
+        """Stay off until the reader asks for it: ambient keys should not change a model list by themselves."""
+        return False
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Register the host of every key that is set, with its current official model."""
+        clashes: list[str] = []
+        for vendor in VENDORS:
+            key = vendor.key()
+            if key is None:
+                continue
+            try:
+                ctx.agent.register_provider(_provider(vendor, key[0]))
+            except ValueError as error:
+                # A clash is not swallowed: the loader reports this plugin failed, so the reader sees why the host
+                # is absent instead of finding it missing with no word. Every clash is named, not only the first.
+                clashes.append(f"{vendor.label}: {error}")
+        if clashes:
+            raise ValueError("; ".join(clashes))
+
+
+__all__ = ["ModelsPlugin", "Vendor", "VENDORS", "__version__"]

zettcode_models-0.1.0/tests/test_models.py

@@ -0,0 +1,123 @@
+"""The models plugin: which keys it notices, and the official model each one offers."""
+
+from __future__ import annotations
+
+import pytest
+
+from zettcode.models import VENDORS, ModelsPlugin
+from zettcode.plugin_api import ModelConfig, PluginContext, ZettCodeConfig
+
+ALL_ENV = ("OPENAI_API_KEY", "ANTHROPIC_API_KEY", "DEEPSEEK_API_KEY", "ZAI_API_KEY", "ZHIPUAI_API_KEY", "ZHIPU_API_KEY")
+
+
+def _clear(monkeypatch: pytest.MonkeyPatch) -> None:
+    for variable in ALL_ENV:
+        monkeypatch.delenv(variable, raising=False)
+
+
+def _context(tmp_path) -> PluginContext:
+    config = ZettCodeConfig(
+        workspace=tmp_path, store=tmp_path / "sessions", models=(), harness_dir=tmp_path / "harness"
+    )
+    return PluginContext(config)
+
+
+def test_the_plugin_stays_off_until_the_reader_enables_it():
+    assert ModelsPlugin.default_enabled() is False
+
+
+def test_a_key_registers_its_host_and_its_official_model(tmp_path, monkeypatch):
+    _clear(monkeypatch)
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+    ctx = _context(tmp_path)
+
+    ModelsPlugin().activate(ctx)
+
+    (provider,) = ctx.providers
+    assert (provider.name, provider.label, provider.token_env) == ("openai", "OpenAI", "OPENAI_API_KEY")
+    (model,) = provider.models
+    assert model.model == "gpt-6.1-sol" and model.shown_name == "GPT-6.1 Sol"
+    assert model.context_window == 1_050_000 and model.multimodal is True
+
+
+def test_every_vendor_with_a_key_is_registered(tmp_path, monkeypatch):
+    _clear(monkeypatch)
+    for variable in ("OPENAI_API_KEY", "ANTHROPIC_API_KEY", "DEEPSEEK_API_KEY", "ZAI_API_KEY"):
+        monkeypatch.setenv(variable, "sk-test")
+    ctx = _context(tmp_path)
+
+    ModelsPlugin().activate(ctx)
+
+    assert [provider.name for provider in ctx.providers] == ["openai", "anthropic", "deepseek", "zai"]
+    assert next(provider for provider in ctx.providers if provider.name == "anthropic").models[0].model == (
+        "claude-opus-5-5"
+    )
+
+
+def test_no_key_registers_nothing(tmp_path, monkeypatch):
+    _clear(monkeypatch)
+    ctx = _context(tmp_path)
+
+    ModelsPlugin().activate(ctx)
+
+    assert ctx.providers == ()
+
+
+def test_zai_accepts_its_older_variable_and_keeps_the_one_it_found(tmp_path, monkeypatch):
+    _clear(monkeypatch)
+    monkeypatch.setenv("ZHIPUAI_API_KEY", "sk-test")
+    ctx = _context(tmp_path)
+
+    ModelsPlugin().activate(ctx)
+
+    (provider,) = ctx.providers
+    assert provider.name == "zai" and provider.token_env == "ZHIPUAI_API_KEY"
+    assert provider.models[0].model == "glm-5.3"
+
+
+def test_each_vendor_names_a_model_and_an_address():
+    assert {vendor.name for vendor in VENDORS} == {"openai", "anthropic", "deepseek", "zai"}
+    assert all(vendor.model and vendor.base_url.startswith("https://") for vendor in VENDORS)
+
+
+def test_a_shown_name_clash_is_reported_rather_than_silently_skipped(tmp_path, monkeypatch):
+    _clear(monkeypatch)
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+    config = ZettCodeConfig(
+        workspace=tmp_path,
+        store=tmp_path / "sessions",
+        models=(ModelConfig(model="mine", display_model="GPT-6.1 Sol"),),
+        harness_dir=tmp_path / "harness",
+    )
+    ctx = PluginContext(config)
+
+    with pytest.raises(ValueError, match="already shown as 'GPT-6.1 Sol'"):
+        ModelsPlugin().activate(ctx)
+
+
+def test_every_clash_is_named_in_one_refusal(tmp_path, monkeypatch):
+    _clear(monkeypatch)
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test")
+    config = ZettCodeConfig(
+        workspace=tmp_path,
+        store=tmp_path / "sessions",
+        models=(
+            ModelConfig(model="one", display_model="GPT-6.1 Sol"),
+            ModelConfig(model="two", display_model="Claude Opus 5.5"),
+        ),
+        harness_dir=tmp_path / "harness",
+    )
+
+    with pytest.raises(ValueError) as caught:
+        ModelsPlugin().activate(PluginContext(config))
+
+    message = str(caught.value)
+    assert "OpenAI" in message and "GPT-6.1 Sol" in message
+    assert "Anthropic" in message and "Claude Opus 5.5" in message
+
+
+def test_the_table_is_internally_consistent():
+    assert len({vendor.display for vendor in VENDORS}) == len(VENDORS)
+    assert all(vendor.display and vendor.context_window > 0 for vendor in VENDORS)
+    assert all(vendor.model != vendor.display for vendor in VENDORS)