zettcode-engine 0.4.0__tar.gz → 0.4.1__tar.gz

{zettcode_engine-0.4.0 → zettcode_engine-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode-engine
-Version: 0.4.0
+Version: 0.4.1
 Summary: The agent core of ZettCode: the runtime over zett-agent, and the leaf types it is written on
 Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
 Author: Chang-LeHung

{zettcode_engine-0.4.0 → zettcode_engine-0.4.1}/src/zettcode/engine/core.py

@@ -106,7 +106,7 @@ def _load_engine_plugins(config: ZettCodeConfig, shared: Mapping[str, object]) -
     compaction, the MCP client) is :mod:`zettcode.sdk.builtins`, which passes its own loader here. A runtime built
     this way still honours ``[plugins]`` for the distributions and single files a reader installed.
     """
-    return load_plugins(config, builtins=(), shared=shared)
+    return load_plugins(config, builtins=(), shared=shared, agent=False)
 
 
 def build_system_prompt(config: ZettCodeConfig, *, now: datetime | None = None) -> str:

{zettcode_engine-0.4.0 → zettcode_engine-0.4.1}/src/zettcode/engine/plugins/loader.py

@@ -65,6 +65,30 @@ PLUGIN_ENTRY_POINT_GROUP = "zettcode.plugins"
 #: load them: they would import the whole terminal to offer it nothing.
 TERMINAL_PART_GROUP = "zettcode.terminal"
 
+#: Entry-point group the program publishes the plugins that compose the agent under (the tools, the session log, the
+#: permission, the compaction, ...). Every loader reads it, and none of it can be switched off: these are the program as
+#: much as a compiled-in plugin is, and a configuration key such as ``[skills] enabled`` is what turns a feature off.
+#: They are activated by ``(rank, name)`` and then by ``deps``.
+AGENT_PART_GROUP = "zettcode.agent"
+
+#: Who may publish into the program's own groups. Being unswitchable and ahead of everything is a privilege of the
+#: program, not of whoever declares the group in a `pyproject.toml`: a point from any other distribution is an
+#: ordinary plugin whatever group it is in. A point that says nothing of its distribution (a test's stand-in) passes.
+PROGRAM_DISTRIBUTIONS: dict[str, frozenset[str]] = {
+    AGENT_PART_GROUP: frozenset({"zettcode-sdk"}),
+    TERMINAL_PART_GROUP: frozenset({"zettcode-app", "zettcode-commands", "zettcode-pets", "zettcode-presenters"}),
+}
+
+
+def part_group(point: EntryPoint) -> str | None:
+    """Return the program group ``point`` is a part of, or ``None`` when it is an ordinary plugin."""
+    group = getattr(point, "group", None)
+    allowed = PROGRAM_DISTRIBUTIONS.get(group) if group else None
+    if allowed is None:
+        return None
+    dist = _distribution(point)
+    return group if dist is None or dist in allowed else None
+
 
 def installed_entry_points() -> tuple[EntryPoint, ...]:
     """Return every plugin entry point installed in this environment.
@@ -74,9 +98,10 @@ def installed_entry_points() -> tuple[EntryPoint, ...]:
     """
     from importlib.metadata import entry_points
 
+    agent = sorted(entry_points(group=AGENT_PART_GROUP), key=lambda point: point.name)
     parts = sorted(entry_points(group=TERMINAL_PART_GROUP), key=lambda point: point.name)
     plugins = sorted(entry_points(group=PLUGIN_ENTRY_POINT_GROUP), key=lambda point: point.name)
-    return (*parts, *plugins)
+    return (*agent, *parts, *plugins)
 
 
 def installed_files(directory: Path) -> tuple[Path, ...]:
@@ -142,6 +167,7 @@ def load_plugins(
     builtins: Sequence[Plugin[Any]],
     shared: Mapping[str, object] | None = None,
     required: Sequence[str] = (),
+    agent: bool = True,
 ) -> Plugins:
     """Load the builtin plugins and every enabled distribution into one bundle.
 
@@ -151,9 +177,9 @@ def load_plugins(
         entry_points: Entry points to load; ``None`` reads the installed ones.
             Tests pass their own, so discovery can be exercised without
             installing a distribution.
-        builtins: Plugins compiled into the repository, which the engine does not ship: the caller passes
-            :data:`zettcode.sdk.builtins.AGENT_PLUGINS` for the program's agent, and ``()`` to load only what a
-            reader installed.
+        builtins: Plugins compiled into the repository, which the engine does not ship; ``()`` for none. The program's
+            agent is not passed here: it is found through the ``zettcode.agent`` entry-point group, unless ``agent`` is
+            false. A caller that cannot discover (a test) may pass :data:`zettcode.sdk.builtins.AGENT_PLUGINS`.
         shared: Objects the runtime hands over by name before any plugin activates (see
             :mod:`zettcode.engine.plugins.services`); a plugin reads them with ``container.service``, and they
             stay findable on the returned bundle. A plugin cannot provide a name that is taken here.
@@ -193,6 +219,8 @@ class _Candidate:
     error: BaseException | None = None
     #: Whether it came from the program's own entry-point group, which is ahead of every installed plugin.
     part: bool = False
+    #: Whether it is one of the plugins that compose the agent (``zettcode.agent``): a part that is also built in.
+    agent: bool = False
 
     @property
     def name(self) -> str:
@@ -213,6 +241,7 @@ def run(
     entry_points: Iterable[EntryPoint] | None,
     required: Sequence[str] = (),
     terminal: bool = False,
+    agent: bool = True,
 ) -> Plugins:
     """Feed the builtins, the enabled distributions and the single-file plugins to ``loader``, and return what it bundled.
 
@@ -241,8 +270,10 @@ def run(
     # which that switch is not about) and the plugins the program requires.
     points = tuple(entry_points) if entry_points is not None else installed_entry_points()
     # The parts of the program that need a screen are for a loader that has one.
-    points = tuple(point for point in points if terminal or getattr(point, "group", None) != TERMINAL_PART_GROUP)
-    parts = {point.name for point in points if getattr(point, "group", None) == TERMINAL_PART_GROUP}
+    points = tuple(point for point in points if terminal or part_group(point) != TERMINAL_PART_GROUP)
+    points = tuple(point for point in points if agent or part_group(point) != AGENT_PART_GROUP)
+    parts = {point.name for point in points if part_group(point) is not None}
+    agent_names = {point.name for point in points if part_group(point) == AGENT_PART_GROUP}
     # The configuration file's own list and the switch file's, merged for the one caller that loads. The switch
     # module cannot be imported here (it imports this one), so the union is written out; `off_names` is the same
     # rule for the front ends.
@@ -272,7 +303,9 @@ def run(
             sources[path.stem] = partial(_from_file, loader, path)
     held = {origin for origin in sources if origin in disabled or (not config.plugins_enabled and origin not in parts)}
     for origin in sources:
-        if origin not in held:
+        # A name the caller already passed as a built-in is that plugin; the discovered twin of it is the same part
+        # offered twice, not a second plugin to refuse as a duplicate.
+        if origin not in held and origin not in loader.builtins:
             candidates.extend(sources[origin]())
     # A name on that list can only reach a distribution or a file, unless the program needs it: the plugins it lists
     # as builtin loaded above, and the required ones, with what they need, are pulled in below. A line that names one
@@ -282,7 +315,9 @@ def run(
             "plugins.required",
             extra={"plugin": origin, "reason": "part of the program; [plugins] disable does not reach it"},
         )
-    protected = set(required)
+    # The plugins that compose the agent are protected like the required ones, but a failure of one is recorded and
+    # does not stop the call: that is what they were as compiled-in plugins.
+    protected = set(required) | agent_names
     while True:
         by_name = {candidate.name: candidate for candidate in candidates}
         wanted: set[str] = set()
@@ -294,7 +329,9 @@ def run(
             wanted.add(name)
             if name in by_name:
                 queue.extend(by_name[name].deps)
-        pulled = sorted(origin for origin in held if origin in wanted)
+        pulled = sorted(
+            origin for origin in held if origin in wanted and not (origin in parts and origin in loader.builtins)
+        )
         if not pulled:
             break
         for origin in pulled:
@@ -320,6 +357,13 @@ def run(
                 "plugins.name_taken",
                 extra={"plugin": name, "who": who, "reason": f"{owners[name]} already has the name {name!r}"},
             )
+    # A plugin of the program is the program's own whether or not it loads, and whether or not it is ever activated: one
+    # refused for a need that failed still goes on the list a switch is refused against.
+    loader.builtins.extend(c.origin for c in candidates if c.builtin and c.origin not in loader.builtins)
+    # Within the program's own groups the stated rank decides, then the name; the stable sort keeps everything else.
+    at = [i for i, c in enumerate(candidates) if c.agent]
+    for slot, candidate in zip(at, sorted((candidates[i] for i in at), key=_rank), strict=True):
+        candidates[slot] = candidate
     ordered, refused = graph.order([graph.Node(c.name, c.deps) for c in candidates])
     loaded: set[int] = set()
     for index in sorted(refused):
@@ -374,15 +418,22 @@ def _described(point: EntryPoint) -> str:
     return f"{point.name!r} ({dist or 'unknown distribution'}" + (f", {value})" if value else ")")
 
 
+def _rank(candidate: _Candidate) -> tuple[int, str]:
+    """Sort key of a part inside its group: its declared rank, then its name; a failure sorts first, by origin."""
+    return (candidate.plugin.rank if candidate.plugin is not None else -1, candidate.origin)
+
+
 def _from_point(loader: Loader, point: EntryPoint) -> list[_Candidate]:
     """Resolve one entry point into a candidate; a failure is a candidate that carries it."""
-    part = getattr(point, "group", None) == TERMINAL_PART_GROUP
+    group = part_group(point)
+    part = group is not None
+    agent = group == AGENT_PART_GROUP
     try:
-        return [_Candidate(_instantiate(point), point.name, part=part)]
+        return [_Candidate(_instantiate(point), point.name, builtin=agent, part=part, agent=agent)]
     except KeyboardInterrupt:
         raise
     except BaseException as error:
-        return [_Candidate(None, point.name, error=error, part=part)]
+        return [_Candidate(None, point.name, builtin=agent, error=error, part=part, agent=agent)]
 
 
 def _from_file(loader: Loader, path: Path) -> list[_Candidate]:

{zettcode_engine-0.4.0 → zettcode_engine-0.4.1}/src/zettcode/engine/plugins/plugin.py

@@ -93,6 +93,12 @@ class Plugin(PluginAgentMixin, Generic[_C], ABC):
     #: The names of the plugins this one needs. The loader activates a plugin after every plugin it lists, and
     #: leaves it out, reported, when one of them is absent, turned off, failed, or the lists go round in a circle.
     deps: ClassVar[tuple[str, ...]] = ()
+    #: Where a plugin stands among the others of its entry-point group when the loader has no ``deps`` to go by: parts
+    #: are activated by ``(rank, name)`` within their group, so a group whose extensions share a priority (and so
+    #: keep their registration order) is activated in a stated order and not in the order entry points happen to sort.
+    #: The program's to set: ``zettcode.sdk.builtins`` writes it for its own plugins, and a plugin of anyone else has
+    #: no use for it, since it is only read for the parts of the program.
+    rank: ClassVar[int] = 0
     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.

{zettcode_engine-0.4.0 → zettcode_engine-0.4.1}/src/zettcode/engine/plugins/switches.py

@@ -129,8 +129,9 @@ def catalog(
         # A part for a screen is listed by a process that has one. A bundle that holds none of it (the SDK, the
         # server) is not offering switches for things it never loads — unless one is switched off, which is the one
         # state in which a part is absent from a bundle that would have it.
-        if getattr(point, "group", None) == loader.TERMINAL_PART_GROUP and point.name not in off:
-            continue
+        if loader.part_group(point) is not None:
+            if point.name not in off:
+                continue
         installed.append(_installed(point.name, point.name, config, off=off))
     # A single-file plugin that is switched off is not in the bundle (the loader never imported it), so the folder is
     # what says it exists: it stays on the page, off, where it can be switched back on.

{zettcode_engine-0.4.0 → zettcode_engine-0.4.1}/src/zettcode/version.py

@@ -8,4 +8,4 @@ of the dependency graph: everything else may import `zettcode.version`, nothing
 from __future__ import annotations
 
 #: The version of the program and of every distribution built beside it.
-__version__ = "0.4.0"
+__version__ = "0.4.1"