zettcode-engine 0.3.4__py3-none-any.whl

zettcode/engine/plugins/plugin.py

@@ -0,0 +1,190 @@
+"""The plugin base class and the bundle of what the loaded plugins produced.
+
+:class:`Plugin` is what an author subclasses: identity, one activation hook, and
+the composed hook groups from :mod:`zettcode.engine.plugins.mixins`.
+:class:`Plugins` is the other direction — the host extension, services, and
+providers the loader hands the application, plus whatever failed to load.
+
+A plugin is activated with one :class:`PluginContext`: the engine's own plugins take a
+:class:`~zettcode.engine.plugins.container.PluginContext`, and the terminal's take its subclass, which also
+registers commands, palettes, pets, presenters and rows.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar
+
+from .context import PluginContext
+from .mixins import PluginAgentMixin
+from .services import lookup, require
+from .state import AgentBuild, Contribution
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only, so the imports stay lazy
+    from collections.abc import Mapping
+
+    from zett_agent.extensions.base import AgentExtension
+
+    from zettcode.mention import MentionProvider
+    from zettcode.providers import Provider
+
+    from .extension import PluginExtension
+
+_C = TypeVar("_C", bound=PluginContext)
+_T = TypeVar("_T")
+
+
+@dataclass(frozen=True, slots=True)
+class PluginSetting:
+    """The configuration key that decides whether a compiled-in plugin does its work.
+
+    A plugin installed as a distribution is switched by `[plugins] disable` in the configuration. One compiled into the program has no
+    file of its own: what turns its work off is a setting the reader already has, such as ``[skills] enabled``. A
+    plugin that declares one is listed by a panel with a switch, and the switch writes that key; a plugin that does
+    not is not listed, because there is nothing a reader could do about it.
+
+    Attributes:
+        field: The attribute of :class:`~zettcode.config.ZettCodeConfig` that holds it now, for the state a list
+            shows and for a running process to keep up with.
+        table: The configuration table it is written to.
+        key: The key inside that table.
+    """
+
+    field: str
+    table: str
+    key: str = "enabled"
+
+    @property
+    def path(self) -> str:
+        """Return it the way the configuration file spells it, ``skills.enabled``."""
+        return f"{self.table}.{self.key}"
+
+
+class Plugin(PluginAgentMixin, Generic[_C], ABC):
+    """Base class for one ZettCode plugin.
+
+    The hooks are grouped into mixins, and :class:`Plugin` composes the agent flow group
+    (:class:`PluginAgentMixin`). A subclass overrides only the stages it takes part in, and each default does
+    nothing; the finer agent groups (setup, run, turn, model, tool, maintenance, events, middleware) mirror
+    ``zett-agent``'s extension mixins one for one, so an author who knows the extension docs already knows where a
+    hook belongs.
+
+    Attributes:
+        name: Unique registration identity. Defaults to the class name; set it
+            when the entry-point name is not the label you want in
+            diagnostics. When it is empty the entry-point name is used, and a
+            plugin that declares neither falls back to the class name.
+        description: One-line summary of what the plugin adds, for diagnostics.
+        priority: Hook order against every other extension: lower runs first,
+            and equal priorities keep registration order.
+        setting: The configuration key that turns its work off, for a plugin compiled into the program; ``None`` when
+            the plugin is installed as a distribution, which `[plugins] disable` reaches instead.
+    """
+
+    #: Identity the loader may resolve and record; a plain attribute, so a
+    #: nameless class can be given its entry-point name at load time.
+    name: str = ""
+    #: How the distribution that carries it is called — the entry-point name for an installed plugin, its own
+    #: name for a builtin. `/plugins` shows it when it differs from :attr:`name`, because `[plugins] disable` and the
+    #: switch file are matched against it.
+    origin: str = ""
+    description: ClassVar[str] = ""
+    priority: ClassVar[int] = 100
+    #: The configuration key that decides whether a compiled-in plugin does its work, or ``None`` when there is none:
+    #: a plugin the reader cannot turn off is left out of the list rather than shown without a switch.
+    setting: ClassVar[PluginSetting | None] = None
+
+    def activate(self, container: _C) -> None:
+        """Run once at startup, before any agent client is built.
+
+        This is the place to register what the plugin contributes, and to read the
+        configuration. It is synchronous on purpose: the shell must know the
+        full command list before it paints, and a plugin that needs asynchronous
+        setup can do it in the lifecycle hooks, which all run on the agent loop.
+
+        Args:
+            container: The resolved settings and the registration surface.
+        """
+
+
+@dataclass(frozen=True, slots=True)
+class Plugins:
+    """Everything the installed plugins contributed to the agent, and what failed to load.
+
+    Attributes:
+        host: The single extension that drives every loaded plugin; ``None``
+            when none loaded. The agent is handed one extension, not one per
+            plugin, so plugin-wide behaviour has one place to live.
+        mentions: ``@`` resource providers the plugins registered, in load and
+            registration order; the shell merges them with the builtin skills.
+        providers: Model providers the plugins described, in load and registration order; the
+            shell offers them in ``/config`` after the built-in ones.
+        contributed: The ``zett-agent`` extensions the plugins registered through ``register_extension`` and
+            ``register_extension_factory``, in load and registration order. :meth:`agent_extensions` turns them
+            into the extensions the agent is given, beside the host, so each keeps the priority it declares.
+        services: Objects the runtime handed over and the plugins provided, by name; read them with
+            :meth:`service` and :meth:`find`.
+        plain_commands: Commands a plugin registered on ``ctx.commands``, in load and registration order, each
+            typed ``"plugin"``. The terminal turns them into shell commands; another front end reads them here.
+        failures: One message per plugin that could not be loaded or activated, ``origin: why``, read from
+            :attr:`failed`. A plugin that cannot be loaded is reported rather than taking the whole application
+            with it; the shell reports these where the user can see them.
+        failed: The failures themselves, one ``(origin, why)`` pair each, for a list that groups them by the plugin
+            they belong to. This is the one record; :attr:`failures` is written from it.
+        builtins: The origins of the plugins compiled into the program, in load order. They always load, so a switch
+            cannot leave one out, and a list can say which rows are the program's own.
+    """
+
+    host: PluginExtension | None = None
+    mentions: tuple[MentionProvider, ...] = ()
+    providers: tuple[Provider, ...] = ()
+    contributed: tuple[Contribution, ...] = ()
+    services: Mapping[str, object] = field(default_factory=dict)
+    plain_commands: tuple[object, ...] = ()
+    failed: tuple[tuple[str, str], ...] = ()
+    builtins: tuple[str, ...] = ()
+
+    @property
+    def failures(self) -> tuple[str, ...]:
+        """Return each failure as the one line a transcript shows, ``origin: why``."""
+        return tuple(f"{origin}: {why}" for origin, why in self.failed)
+
+    def find(self, name: str, kind: type[_T]) -> _T | None:
+        """Return the service under ``name``, or ``None`` when no loaded plugin provides it.
+
+        For what the application can do without: the plan panel has nothing to show when nobody keeps a
+        plan. A service that exists but is the wrong type is still an error, because that is a plugin
+        bug and not an absence.
+        """
+        return lookup(self.services, name, kind)
+
+    def service(self, name: str, kind: type[_T]) -> _T:
+        """Return the service under ``name``, checked to be a ``kind``.
+
+        Raises:
+            LookupError: When nothing provides it; a plugin that failed to load provides nothing, and
+                the message says which service is missing.
+            TypeError: When the name is taken by an object of another type.
+        """
+        return require(self.services, name, kind)
+
+    def agent_extensions(self, build: AgentBuild | None = None) -> tuple[AgentExtension, ...]:
+        """Return the extensions the plugins hand the agent, in registration order.
+
+        Args:
+            build: What exists while the agent is being built. Factories are called with it; without it
+                (outside a build) only the extensions registered whole are returned.
+        """
+        built = (contribution.build(build) for contribution in self.contributed)
+        return tuple(extension for extension in built if extension is not None)
+
+    @property
+    def plugins(self) -> tuple[Plugin[Any], ...]:
+        """Return the loaded plugins, in the order the host will call them."""
+        return self.host.plugins if self.host is not None else ()
+
+    @property
+    def extensions(self) -> tuple[PluginExtension, ...]:
+        """Return the one extension to register, or nothing when no plugin loaded."""
+        return (self.host,) if self.host is not None else ()

zettcode/engine/plugins/services.py

@@ -0,0 +1,68 @@
+"""The names objects are shared under between the runtime and the plugins, and the lookup both use.
+
+A service is an object found by name. Two kinds travel this way:
+
+* **What the runtime hands the plugins** before any of them activates: the state of the session that
+  extensions are built on (``POLICY``, ``PERSISTENCE``, ``MODELS``, ``COMPACTION_COUNTER``,
+  ``MESSENGER``, ``SELECTED_MODEL``). The runtime owns them and keeps using them itself.
+* **What a plugin provides** for the rest of the application, and for the plugins loaded after it
+  (``APPROVAL``, ``USAGE``, ``CONTEXT``, ``SIDES``, ``COMPACTION``, ``CAPABILITIES``, ``TODOS``).
+
+The names are constants so that a misspelt one is an import error rather than a lookup that fails
+only when the feature is first used.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from collections.abc import Mapping
+
+#: Handed over by the runtime.
+POLICY = "policy"
+HARNESS = "harness"
+PERSISTENCE = "persistence"
+MODELS = "models"
+COMPACTION_COUNTER = "compaction-counter"
+MESSENGER = "messenger"
+SELECTED_MODEL = "selected-model"
+
+#: Provided by the built-in plugins.
+APPROVAL = "approval"
+USAGE = "usage"
+CONTEXT = "context"
+SIDES = "sides"
+COMPACTION = "compaction"
+CAPABILITIES = "capabilities"
+TODOS = "todos"
+
+_T = TypeVar("_T")
+
+
+def lookup(services: Mapping[str, object], name: str, kind: type[_T]) -> _T | None:
+    """Return the service called ``name`` as a ``kind``, or ``None`` when nobody provides it.
+
+    Raises:
+        TypeError: When the name is taken by an object of another type; that is a plugin bug, not an
+            absence, and hiding it as ``None`` would send the search somewhere else.
+    """
+    if name not in services:
+        return None
+    found = services[name]
+    if not isinstance(found, kind):
+        raise TypeError(f"Service {name!r} is a {type(found).__name__}, not a {kind.__name__}")
+    return found
+
+
+def require(services: Mapping[str, object], name: str, kind: type[_T]) -> _T:
+    """Return the service called ``name`` as a ``kind``.
+
+    Raises:
+        LookupError: When nobody provides it; the message names the service.
+        TypeError: When the name is taken by an object of another type.
+    """
+    found = lookup(services, name, kind)
+    if found is None:
+        raise LookupError(f"No plugin provides the {name!r} service")
+    return found

zettcode/engine/plugins/settings.py

@@ -0,0 +1,117 @@
+"""The keys one plugin reads from the configuration, and the defaults it supplies for them.
+
+The configuration file cannot know which plugins are installed or what their keys mean, so it keeps each plugin's
+table as it was written (``[plugins.recap] after_seconds = 180``). A plugin says what it reads and what the value is
+when the reader has not written one; from then on the reader's value wins, checked against the default's type, and a
+key the plugin never declared is an error rather than a silent default.
+
+::
+
+    given = ctx.settings.declare(after_seconds=180, cache_ttl_seconds=300)
+    after = given["after_seconds"]      # 180, or what [plugins.recap] says
+
+A type is the default's: a whole number for an ``int``, true or false for a ``bool``, text for a ``str``, and a number
+for a ``float`` (a whole one is accepted and comes back as a float). Anything else — a list, a table, a string where a
+number was declared — is refused when the plugin activates, naming the plugin, the key and the file it came from.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeAlias
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from collections.abc import Mapping
+
+#: What a plugin's settings may hold: what TOML calls a scalar.
+Value: TypeAlias = bool | int | float | str
+
+__all__ = ["PluginSettings", "Value"]
+
+
+def _matches(value: object, default: Value) -> bool:
+    """Return whether a value from the file has the type its declared default has."""
+    if isinstance(default, bool):
+        return isinstance(value, bool)
+    if isinstance(default, int):
+        return isinstance(value, int) and not isinstance(value, bool)
+    if isinstance(default, float):
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    return isinstance(value, str)
+
+
+#: How each type is described in a refusal, in the words a reader of the file would use.
+_WORDS = {bool: "true or false", int: "a whole number", float: "a number", str: "text"}
+
+
+def _as_written(value: object, default: Value) -> Value:
+    """Return the reader's value as the default's type, or raise naming what was expected."""
+    if not _matches(value, default):
+        expected = _WORDS[type(default)]
+        raise ValueError(f"must be {expected}, not {type(value).__name__}")
+    if isinstance(default, float) and isinstance(value, int):
+        return float(value)
+    return value  # type: ignore[return-value]  # narrowed by `_matches`
+
+
+class PluginSettings:
+    """The keys one plugin declares, with the reader's values in front of its defaults.
+
+    Args:
+        plugin: The plugin's name, which is the entry-point name a ``[plugins.<name>]`` table is written under.
+        given: What the reader wrote in that table, checked as each key is declared.
+    """
+
+    def __init__(self, plugin: str = "", given: Mapping[str, object] | None = None) -> None:
+        """Keep the plugin's name and the values the reader wrote, if any."""
+        self.plugin = plugin
+        self._given: dict[str, object] = dict(given or {})
+        self._defaults: dict[str, Value] = {}
+
+    def declare(self, **defaults: object) -> dict[str, object]:
+        """Declare the keys the plugin reads and return the values in effect.
+
+        Declaring the same key twice keeps the first default, so two call sites cannot disagree about what the
+        value means; the reader's value is applied to whichever default was declared first.
+
+        Args:
+            **defaults: One default per key, whose type is the type the reader's value must have.
+
+        Returns:
+            Each declared key with the reader's value when there is one, else the default.
+
+        Raises:
+            ValueError: A default is not a scalar, or the reader's value for a key is not the declared type.
+        """
+        for key, default in defaults.items():
+            if not isinstance(default, (bool, int, float, str)):
+                raise ValueError(f"{self._where(key)} declares a default that is not a string, a number or a boolean")
+            self._defaults.setdefault(key, default)
+        return {key: self.get(key) for key in defaults}
+
+    def get(self, key: str) -> Value:
+        """Return the value in effect for one declared key.
+
+        Raises:
+            ValueError: The plugin never declared that key (reading it would always be a default it never chose),
+                or the reader's value is not the type the default declares.
+        """
+        if key not in self._defaults:
+            raise ValueError(f"{self._where(key)} is not a setting this plugin declared")
+        default = self._defaults[key]
+        if key not in self._given:
+            return default
+        value = self._given[key]
+        try:
+            return _as_written(value, default)
+        except ValueError as error:
+            hint = f" (declared as {type(default).__name__})" if isinstance(default, float) else ""
+            raise ValueError(f"{self._where(key)} {error}{hint}") from None
+
+    def values(self) -> dict[str, object]:
+        """Return every declared key with the value in effect, for a plugin that wants them all at once."""
+        return {key: self.get(key) for key in self._defaults}
+
+    def _where(self, key: str) -> str:
+        """Return the place a problem is reported against: the plugin's table when it has a name."""
+        table = f"[plugins.{self.plugin}]" if self.plugin else "the plugin settings"
+        return f"Config key {key!r} in {table}"

zettcode/engine/plugins/state.py

@@ -0,0 +1,64 @@
+"""What a plugin hands the agent: extensions, ready now or built when the agent is."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeAlias
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only, so the imports stay lazy
+    from zett_agent.extensions.base import AgentExtension
+    from zett_agent.model import AgentModel
+
+
+@dataclass(frozen=True, slots=True)
+class AgentBuild:
+    """What exists when the agent is being built, and not before.
+
+    A plugin activates while the shell is still being drawn, before any provider exists. An extension
+    that needs one, or that is costly to import, is registered as a factory and called with this when
+    the runtime builds the agent.
+
+    Attributes:
+        model: The provider the agent starts on.
+    """
+
+    model: AgentModel
+
+
+#: Builds an extension once the agent is being built; ``None`` means this run has none to add.
+ExtensionFactory: TypeAlias = Callable[[AgentBuild], "AgentExtension | None"]
+
+
+@dataclass(frozen=True, slots=True)
+class Contribution:
+    """One ``zett-agent`` extension a plugin hands the agent: ready now, or built when the agent is.
+
+    Attributes:
+        name: The extension's name, known before it exists so that a clash is caught at load.
+        extension: The extension itself, when it was registered whole.
+        factory: What builds it, when it was registered as a factory.
+    """
+
+    name: str
+    extension: AgentExtension | None = None
+    factory: ExtensionFactory | None = None
+
+    def build(self, build: AgentBuild | None) -> AgentExtension | None:
+        """Return the extension, building it if it is a factory and the agent is being built.
+
+        Args:
+            build: What exists at build time; ``None`` outside a build, where a factory yields nothing.
+
+        Raises:
+            ValueError: When the factory built an extension under another name than it announced; the
+                load-time clash check would have been checking the wrong name.
+        """
+        if self.extension is not None:
+            return self.extension
+        if build is None or self.factory is None:
+            return None
+        made = self.factory(build)
+        if made is not None and made.name != self.name:
+            raise ValueError(f"Extension registered as {self.name!r} was built as {made.name!r}")
+        return made