weft-llm 1.0.0__tar.gz

weft_llm-1.0.0/.gitignore

@@ -0,0 +1,78 @@
+# The donor checkout, reachable for reading and lifting only.
+# Never a build input: see CLAUDE.md and docs/README.md.
+/donor
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.pyright/
+
+# `uv.lock` was here, filed between two caches. It is not a cache: `ci.yml` runs
+# `uv sync --frozen` in three of its four jobs, and every one of them died at that step
+# the first time CI ever ran. It is tracked now — the resolution CI installs and the
+# resolution a developer installs must be one artefact, which is the same argument
+# `docs/README.md` makes about single-sourcing anything two readers can disagree about.
+#
+# It constrains nobody downstream. A lockfile is not a dependency bound; what a consumer
+# resolves is decided by each distribution's `pyproject.toml`.
+
+# Session-local attempt counter for the guard_quality_gates.py PreToolUse hook — per-session
+# scratch, not a record anyone should read later. See the hook's module docstring.
+.claude/.gate-attempts.json
+
+# Secrets. `.env` holds live provider keys; only the documented, valueless
+# example is tracked. Listed before any tooling rule so a stray `git add -A`
+# cannot reach it.
+.env
+.env.*
+!.env.example
+
+# Corpus payload. Every subdirectory of /corpus is a materialised document set and
+# is deliberately untracked; `corpus/manifest.toml` and `scripts/fetch_corpus.py`
+# are the tracked artefact. `09` §4 V1 permits exactly this:
+# a corpus is "either redistributable or fetched by a pinned, checksummed script",
+# and the mRMR papers are published under publisher copyright, so committing them
+# would be redistribution this repository has no right to perform. The manifest
+# carries a sha256 per document, which is what makes the set reproducible without
+# the bytes being here. The pattern is a directory glob rather than a list of names
+# so that scaling the corpus up cannot silently start tracking a paper.
+/corpus/*/
+
+# Where a baseline run stages the corpus it indexes and writes the `weft.toml` it measures
+# through (`eval/run_baseline.py`). The staged copies are the same untracked papers one
+# directory over, and the configuration is reproduced by the harness rather than kept — what
+# is tracked is the run it produced, under `eval/baselines/`.
+/.baseline-run/
+
+# Working artefacts of a build session — a generated map of the codebase and a design
+# record produced while planning. Untracked on purpose: `docs/README.md` routes every
+# document this project owns, and a design that matters belongs in the `docs/` file
+# that owns its content, not in a root-level file nothing points at.
+/.phase2-*.md
+/.phase3-*.md
+/.phase4-*.md
+
+# Gate-session preparation: the Bring lists of `docs/05-grilling-sessions.md`, measured on the day
+# a session is about to run. Untracked for the same reason — the session's outcome belongs in
+# `docs/README.md`'s decision log and in the reference document the decision changes, never here.
+/.gate-brief-*.md
+
+# Claude Code local state
+.claude/settings.local.json
+
+.DS_Store
+
+# The build harness driving Phase 2, alongside its brief, findings and design record.
+/.phase2-build.js
+
+# Transient: harvested subagent findings, promoted into docs/lessons.md by implement-ll.
+# Never committed — its content belongs in the queue or nowhere.
+.claude/lessons-spool.md

weft_llm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Krysztopa
+
+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.

weft_llm-1.0.0/NOTICE

@@ -0,0 +1,24 @@
+Weft
+Copyright (c) 2026 Adam Krysztopa
+
+This product is licensed under the MIT License. See the LICENSE file at the root
+of this repository.
+
+--------------------------------------------------------------------------------
+Original work
+--------------------------------------------------------------------------------
+
+**Weft contains no source text from any other codebase.** Every line here is
+written for this project, against this project's contracts.
+
+This is a rule, not a description of the current state: no file may be copied or
+adapted from another project's source, and no third-party source text may be
+pasted into this repository. Where a prior system informed a design, what was
+carried across is understanding — an approach, an ordering, a measurement, a
+reason a guard exists — restated in this project's own words and implemented
+fresh. Copyright does not reach any of that, and nothing in this repository
+depends on a licence granted by anyone else.
+
+`docs/04-donor-inventory.md` records what was learned from prior work and what
+was deliberately not taken. It is a design record. Nothing in it authorises a
+copy, because copying is not permitted here at all.

weft_llm-1.0.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: weft-llm
+Version: 1.0.0
+Summary: First-party generation-support pack. Publishes the LLMProvider contract, the LLMError taxonomy, and the deterministic offline scripted provider.
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: weft-kernel<1.0.0,>=0.1.0

weft_llm-1.0.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "weft-llm"
+version = "1.0.0"
+description = "First-party generation-support pack. Publishes the LLMProvider contract, the LLMError taxonomy, and the deterministic offline scripted provider."
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+dependencies = ["weft-kernel>=0.1.0,<1.0.0"]
+
+# The one entry point a pack declares (`docs/02-extension-model.md` section 2).
+[project.entry-points."weft.packs"]
+llm = "weft_llm:register"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

weft_llm-1.0.0/src/weft_llm/__init__.py

@@ -0,0 +1,91 @@
+"""First-party generation-support pack. Publishes `LLMProvider` and registers no vendor.
+
+Task **2.30**: "the generation pack names no vendor, because a provider adapter is its own
+pack and the offline default is a deterministic scripted provider." This pack is the "own
+pack" a vendor's adapter registers *under* — `weft-openai` (a separate distribution)
+registers `openai` here the same way any stranger's `weft-anthropic` could, through the same
+public `weft.packs` entry point, with nothing extra for being first-party.
+
+Registers exactly one plugin itself: `scripted`, the deterministic offline default that
+keeps `poe ci-checks` and every fresh checkout running with no credential and no network —
+see `weft_llm.scripted`'s module docstring.
+
+**Task 2.10 completed the pack**: the `LLM` service (`weft_llm.client`), the retry wrapper
+(`weft_llm.retry`), the model-string vocabulary (`weft_llm.models`) and the role table the
+service resolves against (`weft_llm.roles`). `LLM` and `TokenSink` are exported here for a
+library caller, but neither carries a `version` and neither is registered under a name — the
+mechanical rule `.phase2-design.md` §3 states for a *service*, which is what keeps both out of
+`manual/contract-reference.md` and out of fitness function 9(c)'s left side. `NativeStructured`
+is exported for the opposite reason: it *is* a capability, derived by `isinstance` from what a
+provider implements, and the reference should say so.
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+from weft_kernel.discovery import PackRegistrar
+from weft_llm.client import LLMClient, NullSink, llm_service
+from weft_llm.contract import LLM, LLM_CONTRACT_VERSION, LLMProvider, NativeStructured, TokenSink
+from weft_llm.loop_guard import LoopGuardConfig, detect_generation_loop
+from weft_llm.models import ModelRef, find_runtime_match, model_ref
+from weft_llm.payload import (
+    Completion,
+    Conversation,
+    Message,
+    MessageRole,
+    OnFailure,
+    Rendered,
+    TokenChunk,
+    TokenUsage,
+)
+from weft_llm.retry import RetryPolicy, with_retry
+from weft_llm.roles import LLMRoles, RoleMapping, UnmappedLLMRoleError
+from weft_llm.scripted import NAME, ScriptedConfig, ScriptedProvider
+
+
+class Settings(BaseModel):
+    """`weft-llm` takes no pack settings — an empty model is still the required shape."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+def register(registrar: PackRegistrar, settings: Settings) -> None:
+    """Register `ScriptedProvider` as `"scripted"` for `LLMProvider`.
+
+    The only plugin this pack ships.
+    """
+    del settings
+    registrar.add(LLMProvider, NAME, ScriptedProvider)
+
+
+__all__ = [
+    "LLM",
+    "LLM_CONTRACT_VERSION",
+    "Completion",
+    "Conversation",
+    "LLMClient",
+    "LLMProvider",
+    "LLMRoles",
+    "LoopGuardConfig",
+    "Message",
+    "MessageRole",
+    "ModelRef",
+    "NativeStructured",
+    "NullSink",
+    "OnFailure",
+    "Rendered",
+    "RetryPolicy",
+    "RoleMapping",
+    "ScriptedConfig",
+    "ScriptedProvider",
+    "Settings",
+    "TokenChunk",
+    "TokenSink",
+    "TokenUsage",
+    "UnmappedLLMRoleError",
+    "detect_generation_loop",
+    "find_runtime_match",
+    "llm_service",
+    "model_ref",
+    "register",
+    "with_retry",
+]

weft_llm-1.0.0/src/weft_llm/client.py

@@ -0,0 +1,317 @@
+"""The `LLM` service — one code path from a role to an answer, with everything attached.
+
+Task **2.10**: the service `weft_llm.contract`'s own docstring promised "one task later",
+"alongside the retry and cascade machinery". It is the assembly point for four things a
+technique author must never write again: resolving a role to a provider and a model, retry,
+the registration seam, and streaming.
+
+**Streaming attaches here, and that discharges task 2.17 structurally.**
+`.phase2-design.md` decision 10 and §7: "the `LLM` client **always** calls `provider.stream(...)`,
+accumulates, and emits each chunk to `ctx.require(TokenSink)` tagged with the call's `role`.
+`complete()` still returns a decided `Outcome[Completion]`, decided at return and not when a
+stream is drained (G6)." One code path means "a generator that forgets to stream cannot exist,
+and a streaming twin has nowhere to live" — the donor kept ten `@register_strategy` and ten
+`@register_streaming_strategy` sites symmetric by hand, with no test asserting it, and
+`step-back`'s streaming twin silently became a different technique.
+
+**The cost of always streaming, named rather than discovered.** `LLMProvider.stream` yields
+text and nothing else, so a `Completion` built here carries `finish_reason=""` — the vendor's
+own word for why generation stopped does not survive. That is acceptable *because the taxonomy
+carries the same facts as classes*: a content-filter refusal is an `LLMContentFilterError` and
+a truncation is a provider's own concern, so nothing downstream has to string-match a finish
+reason to behave correctly. `LLMProvider.complete` remains the contract member a provider
+implements and a library caller may call directly; this client does not use it.
+
+**Every provider call goes through `weft_kernel.seam.wrap`.** The client runs a plugin outside
+`Runner`, which is exactly the case `weft_cli.ask` already set the precedent for: the span,
+the error attribution, the blocking-call guard and the transient strip are the seam's, and
+"if you find yourself writing a span by hand, stop."
+
+**Nothing but an `LLMError` escapes.** Anything else a provider lets out is wrapped in
+`LLMProviderFaultError` naming the provider — `.phase2-design.md` §7's first enforcement of
+"a taxonomy nobody catches is documentation". `CancelledError` is a `BaseException` and is
+untouched by every `except Exception` in this file, by construction.
+
+**Task 3.10 adds a fifth thing assembled here: the loop-breaker.** `weft_llm.loop_guard.
+detect_generation_loop` needs the whole answer accumulated so far on every call, and `complete`
+already builds exactly that (`parts`, joined) before emitting to the sink — the only place in
+this tree holding that shape on every token, which is why the guard attaches inside `complete`'s
+own accumulation loop rather than living in a `TokenSink` (`donor/study/08-salvage.md` §T1.12,
+lifted per `01` → Phase 3 **Lift**). A detected loop raises `LLMGenerationLoopError` — an
+`LLMPermanentError`, so it takes the same `except LLMError: raise` path a provider's own errors
+do — rather than quietly returning a truncated `Completion`; `weft_cli.cli.run_command` turns
+that raise into `TokenSink.close(reason=...)`, so a reader is told the stream was cut short
+rather than left to mistake it for one that finished cleanly.
+"""
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from typing import cast
+
+from weft_kernel.context import Context
+from weft_kernel.payload import NothingToProduce, Outcome, Produced
+from weft_kernel.registry import Registry, unwrap_factory
+from weft_kernel.seam import wrap
+from weft_llm.contract import LLM, LLMProvider, NativeStructured, TokenSink
+from weft_llm.errors import (
+    LLMError,
+    LLMGenerationLoopError,
+    LLMProviderFaultError,
+    NativeStructuredUnsupportedError,
+)
+from weft_llm.loop_guard import LoopGuardConfig, detect_generation_loop
+from weft_llm.models import ModelRef, find_runtime_match, model_ref
+from weft_llm.payload import Completion, Rendered, TokenChunk
+from weft_llm.retry import RetryPolicy, with_retry
+from weft_llm.roles import LLMRoles
+
+#: The contract name the seam stamps on every span and every attributed error raised through
+#: this client. Written once, here, rather than at each of the three call sites.
+_CONTRACT = "LLMProvider"
+
+
+class NullSink:
+    """A `TokenSink` that discards. The default, so no plugin ever needs a `try`.
+
+    `.phase2-design.md` §13 item 7 leaves `PrintingSink` to a Phase 3 sequencing call and
+    settles this half: "Phase 2 ships `NullSink` and the client-side emit path." Discarding is
+    not a fallback — a run nobody is watching genuinely has nowhere to put tokens, and the
+    alternative (no sink at all) would put a `try` in every caller.
+    """
+
+    async def emit(self, chunk: TokenChunk) -> None:
+        """Discards `chunk`. Deliberately not buffered — nothing would ever read the buffer."""
+        del chunk
+
+    async def close(self, *, reason: str | None = None) -> None:
+        """Nothing was opened. Present because the contract requires it of every sink."""
+        del reason
+
+
+class _Bound:
+    """One role's resolved answer: the provider to call, the model to name, who to blame."""
+
+    def __init__(self, *, provider: LLMProvider, raw: object, ref: ModelRef, distribution: str):
+        self.provider = provider
+        #: The instance *before* retry wrapped it, kept only so `close` reaches the real one
+        #: exactly once when two roles share a provider.
+        self.raw = raw
+        self.ref = ref
+        self.distribution = distribution
+
+
+class LLMClient:
+    """Resolves a role to a provider and a model at call time, and answers through it.
+
+    Satisfies `weft_llm.contract.LLM` structurally — this class never imports it as a base,
+    the same path every plugin in this tree takes with its own contract.
+
+    **Providers are built once per provider name, not once per role.** Two roles naming the
+    same provider with different models share one instance and one connection pool, which is
+    the shape `LLMProvider`'s own docstring argues for: "`model` is a per-call argument, not
+    constructor state … the same account, many models".
+    """
+
+    def __init__(
+        self,
+        *,
+        registry: Registry,
+        roles: LLMRoles,
+        retry: RetryPolicy | None = None,
+        loop_guard: LoopGuardConfig | None = None,
+    ) -> None:
+        self._registry = registry
+        self._roles = roles
+        self._retry = retry if retry is not None else RetryPolicy()
+        self._loop_guard = loop_guard if loop_guard is not None else LoopGuardConfig()
+        self._bound: dict[str, _Bound] = {}
+        #: Every provider name this deployment mapped — what makes a `provider/model` prefix
+        #: recognisable as a prefix rather than half of a model id. See `weft_llm.models`.
+        self._provider_names = frozenset(mapping.provider for mapping in roles.roles.values())
+
+    async def complete(self, rendered: Rendered, *, role: str, ctx: Context) -> Outcome[Completion]:
+        """Continue `rendered`'s conversation under `role`, streaming every chunk to the sink."""
+        bound = self._bind(role)
+        sink = ctx.require(TokenSink)
+
+        async def run() -> Outcome[Completion]:
+            parts: list[str] = []
+            try:
+                async for chunk in bound.provider.stream(
+                    rendered.conversation, model=bound.ref.model, ctx=ctx
+                ):
+                    parts.append(chunk)
+                    await sink.emit(TokenChunk(role=role, text=chunk))
+                    # Task 3.10: `parts` already holds the whole answer accumulated so far —
+                    # exactly the cumulative-text contract `weft_llm.loop_guard` requires — so
+                    # this is where the guard attaches rather than inside a `TokenSink`, which
+                    # only ever sees one chunk at a time. The chunk that revealed the loop has
+                    # already been emitted above, so a reader still sees it before the stream
+                    # stops; nothing after it is generated or shown.
+                    accumulated = "".join(parts)
+                    if detect_generation_loop(accumulated, config=self._loop_guard):
+                        raise self._loop_detected(bound, role, accumulated)
+            except LLMError:
+                raise
+            except Exception as fault:
+                raise self._fault(bound, role, fault) from fault
+            text = "".join(parts)
+            if not text:
+                # Never an empty `Produced` — the donor trap every contract in this tree
+                # documents. A model that answered with nothing did not answer.
+                return NothingToProduce(
+                    reason=(
+                        f"provider '{bound.ref.provider}' returned no text for role '{role}' "
+                        f"on model '{bound.ref.model or '(provider default)'}'"
+                    )
+                )
+            return Produced(value=Completion(text=text, model=bound.ref.model, finish_reason=""))
+
+        return await self._sealed(bound, role, run)()
+
+    async def complete_structured(
+        self, rendered: Rendered, schema: Mapping[str, object], *, role: str, ctx: Context
+    ) -> Outcome[Completion]:
+        """Tier 1 of the cascade: ask the vendor to answer *in* `schema` and check it itself.
+
+        Not streamed. A partial JSON document displayed as it arrives is noise to a reader and
+        unparseable to anything else, and the cascade's caller wants a typed value, not tokens.
+        """
+        bound = self._bind(role)
+        native = bound.provider
+        if not isinstance(native, NativeStructured):
+            raise NativeStructuredUnsupportedError(
+                f"provider '{bound.ref.provider}' (role '{role}') does not offer native "
+                f"structured output. Ask `native_structured_available('{role}')` first, or "
+                f"call the structured-output cascade, which steps down for you.",
+                provider=bound.ref.provider,
+                model=bound.ref.model,
+            )
+
+        async def run() -> Outcome[Completion]:
+            try:
+                return await native.complete_structured(
+                    rendered.conversation, schema, model=bound.ref.model, ctx=ctx
+                )
+            except LLMError:
+                raise
+            except Exception as fault:
+                raise self._fault(bound, role, fault) from fault
+
+        return await self._sealed(bound, role, run)()
+
+    async def native_structured_available(self, role: str) -> bool:
+        """Whether `role`'s provider satisfies `NativeStructured` — derived, never declared."""
+        return isinstance(self._bind(role).provider, NativeStructured)
+
+    async def close(self) -> None:
+        """Close every provider this client built, once each, in the order they were built."""
+        for bound in self._bound.values():
+            await bound.provider.close()
+
+    # --- resolution ---------------------------------------------------------------------
+
+    def _bind(self, role: str) -> _Bound:
+        """`role` → the provider instance and the model string a call under it uses.
+
+        Every refusal on this path is loud and names its options: an unmapped role names every
+        mapped role (`UnmappedLLMRoleError`), an unregistered provider names every registered
+        one (the registry's own `UnknownPluginError`), and a model a provider's declared
+        catalogue does not offer names the catalogue (`UnknownModelError`).
+        """
+        mapping = self._roles.resolve(role)
+        entry = self._registry.entry(LLMProvider, mapping.provider)
+        ref = model_ref(
+            provider=mapping.provider, requested=mapping.model, providers=self._provider_names
+        )
+        catalogue = _declared_catalogue(entry.factory)
+        if catalogue and ref.model:
+            ref = find_runtime_match(ref, catalogue)
+        cached = self._bound.get(mapping.provider)
+        if cached is not None:
+            return _Bound(
+                provider=cached.provider,
+                raw=cached.raw,
+                ref=ref,
+                distribution=cached.distribution,
+            )
+        raw = entry.factory(None)
+        bound = _Bound(
+            provider=with_retry(cast("LLMProvider", raw), self._retry),
+            raw=raw,
+            ref=ref,
+            distribution=entry.distribution,
+        )
+        self._bound[mapping.provider] = bound
+        return bound
+
+    def _sealed(
+        self, bound: _Bound, role: str, run: Callable[[], Awaitable[Outcome[Completion]]]
+    ) -> Callable[[], Awaitable[Outcome[Completion]]]:
+        """`run`, through the registration seam, attributed to the provider that will answer."""
+        return wrap(
+            run,
+            distribution=bound.distribution,
+            contract=_CONTRACT,
+            plugin=bound.ref.provider,
+            stage=f"llm:{role}",
+        )
+
+    def _fault(self, bound: _Bound, role: str, fault: Exception) -> LLMProviderFaultError:
+        return LLMProviderFaultError(
+            f"provider '{bound.ref.provider}' (role '{role}') raised "
+            f"{type(fault).__name__}: {fault}. That is not an LLMError, so nothing downstream "
+            f"could have caught it by class — it is a defect in the provider adapter, not a "
+            f"failure mode of the model.",
+            provider=bound.ref.provider,
+            model=bound.ref.model,
+        )
+
+    def _loop_detected(self, bound: _Bound, role: str, accumulated: str) -> LLMGenerationLoopError:
+        return LLMGenerationLoopError(
+            f"provider '{bound.ref.provider}' (role '{role}') was generating a repeating span "
+            f"and was stopped after {len(accumulated)} characters rather than left to keep "
+            f"filling the terminal. This is a loop-breaker for a model that got stuck, not a "
+            f"judgment about the content — retrying the identical prompt against the same "
+            f"model is likely to loop again; try a different prompt, role, or model.",
+            provider=bound.ref.provider,
+            model=bound.ref.model,
+        )
+
+
+def llm_service(
+    *,
+    registry: Registry,
+    roles: LLMRoles,
+    retry: RetryPolicy | None = None,
+    loop_guard: LoopGuardConfig | None = None,
+) -> LLMClient:
+    """Build the run's `LLM`. This pack's own constructor, per `.phase2-design.md` §7.
+
+    "Each pack builds its own service constructor … so a library caller is not forced through
+    the CLI." `weft_cli.run_services.build_services` calls this one and adds the result to the
+    run's `ServiceRegistry`; an embedding host application calls it directly with a role table
+    it built itself.
+    """
+    return LLMClient(registry=registry, roles=roles, retry=retry, loop_guard=loop_guard)
+
+
+def _declared_catalogue(factory: Callable[..., object]) -> Sequence[str]:
+    """A provider's declared `models`, read the documented way — through `unwrap_factory`.
+
+    `functools.partial` does not proxy attribute access, so a pack binding its settings at
+    registration (`partial(Provider, settings)` — `weft-store`'s shape) would otherwise
+    advertise nothing and the model check would silently never run.
+
+    A provider declaring nothing gets `()`, which turns the check off rather than refusing
+    every model: a name this code cannot check must be passed through, not guessed at.
+    """
+    declared = getattr(unwrap_factory(factory), "models", ())
+    if isinstance(declared, str) or not isinstance(declared, Sequence):
+        return ()
+    return [str(entry) for entry in cast("Sequence[object]", declared)]
+
+
+#: Stated so a reader of this module sees that the service Protocol is satisfied structurally,
+#: the same way a plugin satisfies its contract, and so a checker verifies it once here rather
+#: than at every `ServiceRegistry.add(LLM, ...)` call site.
+_: type[LLM] = LLMClient