cattykit 0.1.0__py3-none-any.whl

cattykit/models/__init__.py

@@ -0,0 +1,37 @@
+from .loading import (
+    ModelInstallationError,
+    ModelNotInstalledError,
+    ModelSourceError,
+    available_models,
+    install_model,
+    load_model,
+    model_info,
+    resolve_model_source,
+)
+from .protocol import CattyKitModel, ModelFactory, ModelPlugin
+from .registry import (
+    DuplicateModelError,
+    InvalidModelPluginError,
+    ModelRegistry,
+    ModelRegistryError,
+    default_registry,
+)
+
+__all__ = [
+    "CattyKitModel",
+    "DuplicateModelError",
+    "InvalidModelPluginError",
+    "ModelFactory",
+    "ModelInstallationError",
+    "ModelNotInstalledError",
+    "ModelSourceError",
+    "ModelPlugin",
+    "ModelRegistry",
+    "ModelRegistryError",
+    "available_models",
+    "default_registry",
+    "install_model",
+    "load_model",
+    "model_info",
+    "resolve_model_source",
+]

cattykit/models/loading.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from collections.abc import Mapping
+from importlib.util import find_spec
+from pathlib import Path
+from typing import Any, Literal
+from urllib.parse import unquote, urlparse
+from urllib.request import url2pathname
+
+from .protocol import CattyKitModel, ModelPlugin
+from .registry import ModelRegistry, default_registry
+
+
+class ModelNotInstalledError(LookupError):
+    """Raised when a requested model plugin is not installed."""
+
+
+class ModelSourceError(ValueError):
+    """Raised when a model source cannot be interpreted."""
+
+
+class ModelInstallationError(RuntimeError):
+    """Raised when pip cannot install a model package."""
+
+
+ModelSourceKind = Literal["name", "url", "path"]
+
+
+OFFICIAL_MODEL_SOURCES: dict[str, str] = {
+    "copycat": (
+        "git+https://github.com/georgeawright/resurrected-copycat.git"
+        "#subdirectory=models/copycat"
+    ),
+}
+
+
+def resolve_model_source(
+    source: str | Path,
+    *,
+    model_sources: Mapping[str, str] = OFFICIAL_MODEL_SOURCES,
+) -> tuple[ModelSourceKind, str]:
+    """Classify a model source and resolve a model name to its package source.
+
+    ``https://`` values are package URLs, while ``Path`` objects, ``file://``
+    URLs, and explicit paths (for example ``./copycat``) are local sources.
+    All other strings are treated as model names and looked up in
+    ``model_sources``.
+    """
+    if isinstance(source, Path):
+        return "path", str(source.expanduser())
+
+    parsed = urlparse(source)
+
+    if parsed.scheme == "https" and parsed.netloc:
+        return "url", source
+
+    if parsed.scheme == "file":
+        if parsed.netloc not in ("", "localhost"):
+            raise ModelSourceError("Only local file URLs are supported.")
+        return "path", url2pathname(unquote(parsed.path))
+
+    if _is_explicit_path(source):
+        return "path", str(Path(source).expanduser())
+
+    if parsed.scheme:
+        raise ModelSourceError(
+            "Model URLs must use HTTPS; use a local path or file:// URL "
+            "for local packages."
+        )
+
+    try:
+        return "name", model_sources[source]
+    except KeyError as error:
+        raise ModelSourceError(
+            f"No CattyKit model source is registered as {source!r}. "
+            "Pass an HTTPS URL or an explicit local path instead."
+        ) from error
+
+
+def install_model(
+    source: str | Path,
+    *,
+    model_sources: Mapping[str, str] = OFFICIAL_MODEL_SOURCES,
+) -> None:
+    """Install a CattyKit model package into the current Python environment.
+
+    A name is resolved through the curated model-source map. HTTPS URLs and
+    explicit local paths are passed directly to pip.
+    """
+    _, package_source = resolve_model_source(source, model_sources=model_sources)
+
+    if find_spec("pip") is None:
+        raise ModelInstallationError(
+            "The active Python environment does not include pip. "
+            "Install the model with your environment manager instead, for example: "
+            f"uv pip install {package_source}"
+        )
+
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "pip", "install", package_source],
+            check=True,
+        )
+    except subprocess.CalledProcessError as error:
+        raise ModelInstallationError(
+            f"Could not install CattyKit model from {package_source!r}."
+        ) from error
+
+
+def available_models(
+    *,
+    registry: ModelRegistry = default_registry,
+) -> tuple[str, ...]:
+    """Return the names of all installed CattyKit models."""
+    return registry.names()
+
+
+def model_info(
+    name: str,
+    *,
+    registry: ModelRegistry = default_registry,
+) -> ModelPlugin:
+    """Return metadata and the factory for an installed model."""
+    try:
+        return registry.get(name)
+    except KeyError as error:
+        raise _model_not_installed_error(
+            name,
+            installed=registry.names(),
+        ) from error
+
+
+def load_model(
+    name: str,
+    *,
+    config: Mapping[str, Any] | None = None,
+    registry: ModelRegistry = default_registry,
+    **kwargs: Any,
+) -> CattyKitModel:
+    """Construct an installed CattyKit model.
+
+    Parameters
+    ----------
+    name:
+        Registered model name, such as ``"copycat"``.
+    config:
+        Optional model-specific configuration.
+    registry:
+        Registry to use. Primarily useful for testing.
+    **kwargs:
+        Additional model-specific factory arguments.
+    """
+    plugin = model_info(name, registry=registry)
+    return plugin.create(config=config, **kwargs)
+
+
+def _model_not_installed_error(
+    name: str,
+    *,
+    installed: tuple[str, ...],
+) -> ModelNotInstalledError:
+    installed_text = ", ".join(installed) if installed else "none"
+
+    lines = [
+        f"CattyKit model {name!r} is not installed.",
+        f"Installed models: {installed_text}.",
+    ]
+
+    source = OFFICIAL_MODEL_SOURCES.get(name)
+
+    if source is not None:
+        lines.extend(
+            [
+                "",
+                "Install the official model with:",
+                f"    python -c \"import cattykit; cattykit.install_model('{name}')\"",
+            ]
+        )
+
+    return ModelNotInstalledError("\n".join(lines))
+
+
+def _is_explicit_path(value: str) -> bool:
+    return value.startswith(("./", "../", "~/", "/")) or "/" in value

cattykit/models/protocol.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CattyKitModel(Protocol):
+    """Minimum interface implemented by a runnable CattyKit model."""
+
+    def solve(self, *args: Any, **kwargs: Any) -> Any:
+        """Run the model and return its result."""
+        ...
+
+    def close(self) -> None:
+        """Release resources owned by the model."""
+        ...
+
+
+@runtime_checkable
+class ModelFactory(Protocol):
+    """Callable used to construct a model plugin."""
+
+    def __call__(
+        self,
+        *,
+        config: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> CattyKitModel:
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class ModelPlugin:
+    """Description of an installed CattyKit model plugin."""
+
+    name: str
+    factory: ModelFactory
+    version: str | None = None
+    description: str | None = None
+
+    def create(
+        self,
+        *,
+        config: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> CattyKitModel:
+        """Construct a model using this plugin's factory."""
+        model = self.factory(config=config, **kwargs)
+
+        if not isinstance(model, CattyKitModel):
+            raise TypeError(
+                f"Factory for model {self.name!r} returned "
+                f"{type(model).__name__}, which does not satisfy "
+                "the CattyKitModel protocol."
+            )
+
+        return model

cattykit/models/registry.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from importlib.metadata import EntryPoint, entry_points
+from typing import Final
+
+from .protocol import ModelPlugin
+
+ENTRY_POINT_GROUP: Final = "cattykit.models"
+
+
+class ModelRegistryError(RuntimeError):
+    """Base exception for model-registry failures."""
+
+
+class DuplicateModelError(ModelRegistryError):
+    """Raised when more than one plugin uses the same model name."""
+
+
+class InvalidModelPluginError(ModelRegistryError):
+    """Raised when an entry point does not provide a valid plugin."""
+
+
+class ModelRegistry:
+    """Registry of installed and explicitly registered CattyKit models."""
+
+    def __init__(self) -> None:
+        self._plugins: dict[str, ModelPlugin] = {}
+        self._discovered = False
+
+    def register(
+        self,
+        plugin: ModelPlugin,
+        *,
+        replace: bool = False,
+    ) -> None:
+        """Register a plugin directly.
+
+        Direct registration is useful for tests and locally defined models.
+        """
+        self._validate_name(plugin.name)
+
+        if plugin.name in self._plugins and not replace:
+            raise DuplicateModelError(
+                f"A CattyKit model named {plugin.name!r} is already registered."
+            )
+
+        self._plugins[plugin.name] = plugin
+
+    def discover(self, *, force: bool = False) -> None:
+        """Discover plugins registered through Python entry points."""
+        if self._discovered and not force:
+            return
+
+        if force:
+            self._plugins.clear()
+
+        discovered = entry_points(group=ENTRY_POINT_GROUP)
+
+        for entry_point in discovered:
+            plugin = self._load_entry_point(entry_point)
+            self.register(plugin)
+
+        self._discovered = True
+
+    def get(self, name: str) -> ModelPlugin:
+        """Return a registered model plugin."""
+        self.discover()
+
+        try:
+            return self._plugins[name]
+        except KeyError as error:
+            raise KeyError(
+                f"No installed CattyKit model is registered as {name!r}."
+            ) from error
+
+    def contains(self, name: str) -> bool:
+        """Return whether a model is registered."""
+        self.discover()
+        return name in self._plugins
+
+    def names(self) -> tuple[str, ...]:
+        """Return installed model names in sorted order."""
+        self.discover()
+        return tuple(sorted(self._plugins))
+
+    def plugins(self) -> tuple[ModelPlugin, ...]:
+        """Return installed plugins sorted by name."""
+        self.discover()
+        return tuple(self._plugins[name] for name in sorted(self._plugins))
+
+    def register_many(
+        self,
+        plugins: Iterable[ModelPlugin],
+        *,
+        replace: bool = False,
+    ) -> None:
+        for plugin in plugins:
+            self.register(plugin, replace=replace)
+
+    @staticmethod
+    def _load_entry_point(entry_point: EntryPoint) -> ModelPlugin:
+        try:
+            loaded_object = entry_point.load()
+        except Exception as error:
+            raise InvalidModelPluginError(
+                f"Could not load model entry point "
+                f"{entry_point.name!r} from {entry_point.value!r}."
+            ) from error
+
+        # Permit the entry point to expose either:
+        #
+        # 1. a ModelPlugin instance; or
+        # 2. a zero-argument function returning a ModelPlugin.
+        if isinstance(loaded_object, ModelPlugin):
+            plugin = loaded_object
+        elif callable(loaded_object):
+            try:
+                plugin = loaded_object()
+            except Exception as error:
+                raise InvalidModelPluginError(
+                    f"Model entry point {entry_point.name!r} raised an "
+                    "exception while creating its plugin descriptor."
+                ) from error
+        else:
+            raise InvalidModelPluginError(
+                f"Model entry point {entry_point.name!r} must expose a "
+                "ModelPlugin or a callable returning one."
+            )
+
+        if not isinstance(plugin, ModelPlugin):
+            raise InvalidModelPluginError(
+                f"Model entry point {entry_point.name!r} returned "
+                f"{type(plugin).__name__}, not ModelPlugin."
+            )
+
+        if plugin.name != entry_point.name:
+            raise InvalidModelPluginError(
+                f"Entry point name {entry_point.name!r} does not match "
+                f"plugin name {plugin.name!r}."
+            )
+
+        return plugin
+
+    @staticmethod
+    def _validate_name(name: str) -> None:
+        if not name:
+            raise ValueError("A model name cannot be empty.")
+
+        if not name.replace("-", "_").isalnum():
+            raise ValueError(
+                "Model names may contain letters, digits, underscores "
+                f"and hyphens; got {name!r}."
+            )
+
+
+default_registry = ModelRegistry()

cattykit/py.typed

@@ -0,0 +1 @@
+# This package provides inline type information.