minima-cli 0.4.9__py3-none-any.whl

minima_harness/ai/provider_quirks.py

@@ -0,0 +1,37 @@
+"""Per-provider request quirks for the OpenAI-compatible provider, as DATA not control flow.
+
+Most OpenAI-compatible hosts speak the identical wire protocol, but a few diverge on small
+request details — e.g. OpenAI's GPT-5 / o-series reject ``max_tokens`` and require
+``max_completion_tokens``. Encoding those as a lookup table (rather than a growing chain of
+``if model.provider == ...`` branches in :mod:`~minima_harness.ai.providers.openai_compat`)
+keeps the single hand-rolled provider lean and makes the next quirk a one-line data entry.
+
+This is the Python-appropriate analogue of OpenCode's per-provider "compatibility lowering":
+a small table, not a class hierarchy. It is the single place provider param drift is encoded.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderQuirks:
+    """How one provider's chat-completions request differs from the OpenAI baseline."""
+
+    # Name of the max-output-tokens param. OpenAI's GPT-5/o-series need max_completion_tokens;
+    # every other OpenAI-compatible host (groq, openrouter, deepseek, …) uses the classic name.
+    token_param: str = "max_tokens"
+
+
+_DEFAULT = ProviderQuirks()
+
+# Keyed by harness provider id. Only providers that DIVERGE from the baseline appear here.
+_QUIRKS: dict[str, ProviderQuirks] = {
+    "openai": ProviderQuirks(token_param="max_completion_tokens"),
+}
+
+
+def quirks_for(provider: str) -> ProviderQuirks:
+    """Quirks for ``provider`` (the baseline OpenAI-compatible behavior if it has none)."""
+    return _QUIRKS.get(provider, _DEFAULT)

minima_harness/ai/providers/__init__.py

@@ -0,0 +1,75 @@
+"""Provider registry entry point.
+
+Real providers self-register on import. Their modules are imported defensively so a
+missing optional SDK only skips that provider (logged at debug) rather than breaking
+``import minima_harness``. The faux provider registers on demand via
+:func:`register_faux_provider`.
+
+Always available:
+  - openai-completions  (raw httpx; httpx is a core dep)
+Conditionally (need the ``harness`` extra: ``anthropic`` + ``google-genai``):
+  - anthropic-messages
+  - google-generative-ai
+"""
+
+from __future__ import annotations
+
+import logging
+
+from minima_harness.ai.providers.base import (
+    Provider,
+    get_provider,
+    register_provider,
+    registered_apis,
+    unregister_provider,
+)
+from minima_harness.ai.providers.faux import register_faux_provider
+
+_log = logging.getLogger("minima_harness.ai.providers")
+
+_REGISTERED = False
+
+
+def ensure_providers_registered() -> None:
+    """Idempotently import the real provider modules so they self-register.
+
+    Called lazily from :func:`minima_harness.ai.stream` to keep ``import minima_harness``
+    side-effect-free.
+    """
+    global _REGISTERED
+    if _REGISTERED:
+        return
+    _REGISTERED = True
+
+    try:
+        from minima_harness.ai.providers import openai_compat  # noqa: F401
+
+        register_provider(
+            openai_compat.OpenAICompatProvider.api_id, openai_compat.OpenAICompatProvider()
+        )
+    except Exception as exc:  # noqa: BLE001 - httpx should always be present
+        _log.debug("openai-completions provider not registered: %s", exc)
+
+    for mod, api, cls in (
+        ("anthropic", "anthropic-messages", "AnthropicProvider"),
+        ("google", "google-generative-ai", "GoogleProvider"),
+    ):
+        try:
+            imported = __import__(f"minima_harness.ai.providers.{mod}", fromlist=[cls])
+            provider_cls = getattr(imported, cls)
+            register_provider(api, provider_cls())
+        except ImportError as exc:
+            _log.debug("%s provider skipped (SDK not installed): %s", api, exc)
+        except Exception as exc:  # noqa: BLE001
+            _log.warning("%s provider failed to register: %s", api, exc)
+
+
+__all__ = [
+    "Provider",
+    "ensure_providers_registered",
+    "get_provider",
+    "register_faux_provider",
+    "register_provider",
+    "registered_apis",
+    "unregister_provider",
+]

minima_harness/ai/providers/_common.py

@@ -0,0 +1,48 @@
+"""Shared helpers for provider implementations."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+
+def resolve_api_key(options: dict[str, Any] | None, *env_vars: str) -> str | None:
+    """Options value wins, then the first set environment variable."""
+    if options and options.get("api_key"):
+        return str(options["api_key"])
+    for var in env_vars:
+        value = os.environ.get(var)
+        if value:
+            return value
+    return None
+
+
+def to_json_schema(model_cls: type[BaseModel]) -> dict[str, Any]:
+    """A provider-agnostic JSON Schema for a pydantic parameter model.
+
+    Strips pydantic-only ``title`` noise and rewrites ``anyOf``/``const`` enum patterns
+    (from ``Literal``) to plain ``enum`` lists so Google's constrained schema dialect
+    accepts them.
+    """
+    schema = model_cls.model_json_schema()
+    schema.pop("title", None)
+    _clean_schema(schema)
+    return schema
+
+
+def _clean_schema(node: Any) -> None:
+    if isinstance(node, dict):
+        node.pop("title", None)
+        # Literal -> pydantic emits {"anyOf":[{"const": v}, ...]}; flatten to {"enum":[...]}.
+        any_of = node.get("anyOf")
+        if isinstance(any_of, list) and all(isinstance(a, dict) and "const" in a for a in any_of):
+            node["enum"] = [a["const"] for a in any_of]
+            node.pop("anyOf", None)
+        for value in node.values():
+            _clean_schema(value)
+    elif isinstance(node, list):
+        for item in node:
+            _clean_schema(item)

minima_harness/ai/providers/anthropic.py

@@ -0,0 +1,290 @@
+"""Anthropic Messages API provider (wraps the ``anthropic`` SDK, async).
+
+Reuses minima's optional ``reasoner-anthropic`` / ``harness`` extra. Maps the SDK's raw
+stream events onto PI's event taxonomy and assembles the final AssistantMessage with
+realized token usage (input from ``message_start``, output from ``message_delta``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from minima_harness.ai.compat import normalize_for_target
+from minima_harness.ai.events import (
+    DoneEvent,
+    ErrorEvent,
+    StartEvent,
+    TextDeltaEvent,
+    TextEndEvent,
+    TextStartEvent,
+    ThinkingDeltaEvent,
+    ThinkingEndEvent,
+    ThinkingStartEvent,
+    ToolCall,
+    ToolCallDeltaEvent,
+    ToolCallEndEvent,
+    ToolCallStartEvent,
+)
+from minima_harness.ai.providers._common import resolve_api_key, to_json_schema
+from minima_harness.ai.types import (
+    AssistantMessage,
+    ImageContent,
+    Message,
+    TextContent,
+    ThinkingContent,
+)
+from minima_harness.ai.usage import attach_cost
+
+if TYPE_CHECKING:
+    from anthropic import AsyncAnthropic
+
+    from minima_harness.ai.events import Event
+    from minima_harness.ai.types import Context, Model
+
+_STOP_MAP = {
+    "end_turn": "stop",
+    "stop_sequence": "stop",
+    "max_tokens": "length",
+    "tool_use": "toolUse",
+}
+
+
+class AnthropicProvider:
+    api_id = "anthropic-messages"
+
+    def __init__(self, client: AsyncAnthropic | None = None) -> None:
+        self._client = client
+
+    def _build_client(self, options: dict[str, Any]) -> AsyncAnthropic:
+        if self._client is not None:
+            return self._client
+        from anthropic import AsyncAnthropic
+
+        api_key = resolve_api_key(options, "ANTHROPIC_API_KEY", "ANTHROPIC_OAUTH_TOKEN")
+        return AsyncAnthropic(api_key=api_key, timeout=options.get("timeout", 60.0))
+
+    async def stream(
+        self,
+        model: Model,
+        context: Context,
+        *,
+        options: dict[str, Any] | None = None,
+        signal: object | None = None,
+    ) -> AsyncIterator[Event]:
+        options = options or {}
+        client = self._build_client(options)
+        kwargs = _build_kwargs(model, context, options)
+        assistant = AssistantMessage(content=[], model=model.id, stop_reason="stop")
+        text_buf: dict[int, list[str]] = {}
+        think_buf: dict[int, list[str]] = {}
+        sig_buf: dict[int, list[str]] = {}  # signature_delta chunks per thinking block
+        tools_acc: dict[int, dict[str, str]] = {}
+        in_tokens = out_tokens = cache_read = cache_write = 0
+
+        yield StartEvent(partial=assistant)
+        try:
+            async with client.messages.stream(**kwargs) as s:
+                async for ev in s:
+                    etype = getattr(ev, "type", "")
+
+                    if etype == "message_start":
+                        usage = getattr(getattr(ev, "message", None), "usage", None)
+                        if usage is not None:
+                            in_tokens = getattr(usage, "input_tokens", 0) or 0
+                            cache_read = getattr(usage, "cache_read_input_tokens", 0) or 0
+                            cache_write = getattr(usage, "cache_creation_input_tokens", 0) or 0
+
+                    elif etype == "content_block_start":
+                        idx = getattr(ev, "index", 0)
+                        block = getattr(ev, "content_block", None)
+                        btype = getattr(block, "type", "")
+                        if btype == "text":
+                            yield TextStartEvent(content_index=idx)
+                        elif btype == "thinking":
+                            yield ThinkingStartEvent(content_index=idx)
+                        elif btype == "tool_use":
+                            tools_acc[idx] = {
+                                "id": getattr(block, "id", "") or f"call_{idx}",
+                                "name": getattr(block, "name", ""),
+                                "args": "",
+                            }
+                            yield ToolCallStartEvent(content_index=idx)
+
+                    elif etype == "content_block_delta":
+                        idx = getattr(ev, "index", 0)
+                        delta = getattr(ev, "delta", None)
+                        dtype = getattr(delta, "type", "")
+                        if dtype == "text_delta":
+                            txt = getattr(delta, "text", "") or ""
+                            text_buf.setdefault(idx, []).append(txt)
+                            yield TextDeltaEvent(delta=txt, content_index=idx)
+                        elif dtype == "thinking_delta":
+                            txt = getattr(delta, "thinking", "") or ""
+                            think_buf.setdefault(idx, []).append(txt)
+                            yield ThinkingDeltaEvent(delta=txt, content_index=idx)
+                        elif dtype == "signature_delta":
+                            # Anthropic signs each thinking block; capture it so it can be echoed
+                            # back when the block is replayed (required, or the API 400s).
+                            sig = getattr(delta, "signature", "") or ""
+                            sig_buf.setdefault(idx, []).append(sig)
+                        elif dtype == "input_json_delta":
+                            partial = getattr(delta, "partial_json", "") or ""
+                            if idx in tools_acc:
+                                tools_acc[idx]["args"] += partial
+                            yield ToolCallDeltaEvent(delta=partial, content_index=idx)
+
+                    elif etype == "content_block_stop":
+                        idx = getattr(ev, "index", 0)
+                        if idx in tools_acc:
+                            slot = tools_acc[idx]
+                            import json
+
+                            try:
+                                args = json.loads(slot["args"]) if slot["args"].strip() else {}
+                            except json.JSONDecodeError:
+                                args = {"_raw": slot["args"]}
+                            call = ToolCall(id=slot["id"], name=slot["name"], arguments=args)
+                            assistant.content.append(call)
+                            yield ToolCallEndEvent(tool_call=call, content_index=idx)
+                        elif idx in think_buf:
+                            thinking = "".join(think_buf[idx])
+                            signature = "".join(sig_buf.get(idx, []))
+                            assistant.content.append(
+                                ThinkingContent(thinking=thinking, signature=signature)
+                            )
+                            yield ThinkingEndEvent(content=thinking, content_index=idx)
+                        elif idx in text_buf:
+                            text = "".join(text_buf[idx])
+                            assistant.content.append(TextContent(text=text))
+                            yield TextEndEvent(content=text, content_index=idx)
+
+                    elif etype == "message_delta":
+                        delta = getattr(ev, "delta", None)
+                        stop = getattr(delta, "stop_reason", None)
+                        if stop:
+                            assistant.stop_reason = _STOP_MAP.get(stop, "stop")  # type: ignore[assignment]
+                        usage = getattr(ev, "usage", None)
+                        if usage is not None:
+                            out_tokens = getattr(usage, "output_tokens", 0) or 0
+        except Exception as exc:  # noqa: BLE001
+            err = AssistantMessage(
+                content=[TextContent(text="")], stop_reason="error", error_message=str(exc)
+            )
+            err.model = model.id
+            yield ErrorEvent(reason="error", error=err)
+            return
+
+        if not assistant.content:
+            assistant.content.append(TextContent(text=""))
+        assistant.usage.input = in_tokens
+        assistant.usage.output = out_tokens
+        assistant.usage.cache_read = cache_read
+        assistant.usage.cache_write = cache_write
+        attach_cost(model, assistant.usage)
+        yield DoneEvent(reason=assistant.stop_reason, message=assistant)
+
+
+_EPHEMERAL = {"type": "ephemeral"}
+
+
+def _build_kwargs(model: Model, context: Context, options: dict[str, Any]) -> dict[str, Any]:
+    # Prompt caching is ON by default (the agent re-sends a large stable prefix —
+    # system prompt + tool schemas + conversation history — every turn). cache_control
+    # breakpoints mark the longest prefix to cache: Anthropic reads it at ~0.1x next turn.
+    # Callers with unique one-shot prompts (e.g. the LLM judge) pass prompt_cache=False to
+    # avoid a pointless cache write. Below the per-model min-cacheable size the API simply
+    # ignores the breakpoint, so this is always safe.
+    cache = bool(options.get("prompt_cache", True))
+    messages = normalize_for_target(context.messages, "anthropic-messages")
+    wire = [_to_wire(m) for m in messages]
+    kwargs: dict[str, Any] = {
+        "model": model.id,
+        "max_tokens": options.get("max_tokens", model.max_tokens),
+        "messages": wire,
+    }
+    if context.system_prompt:
+        if cache:
+            kwargs["system"] = [
+                {"type": "text", "text": context.system_prompt, "cache_control": _EPHEMERAL}
+            ]
+        else:
+            kwargs["system"] = context.system_prompt
+    if context.tools:
+        tools = [
+            {
+                "name": t.name,
+                "description": t.description,
+                "input_schema": to_json_schema(t.parameters),
+            }
+            for t in context.tools
+        ]
+        if cache and tools:
+            # A breakpoint on the LAST tool caches the whole (stable) tool array.
+            tools[-1] = {**tools[-1], "cache_control": _EPHEMERAL}
+        kwargs["tools"] = tools
+    if cache and wire:
+        _mark_last_block(wire[-1])
+    # Thinking is opt-in via options to avoid surprise token spend.
+    if options.get("thinking") and model.reasoning:
+        budget = options.get("thinking_budget", 1024)
+        kwargs["thinking"] = {"type": "enabled", "budget_tokens": int(budget)}
+    return kwargs
+
+
+def _mark_last_block(wire_msg: dict[str, Any]) -> None:
+    """Add a cache_control breakpoint to the last content block of a wire message.
+
+    Caches the conversation prefix incrementally: each turn extends the cached prefix, so
+    the prior history is re-read at ~0.1x rather than re-charged at the full input rate.
+    """
+    content = wire_msg.get("content")
+    if isinstance(content, list) and content and isinstance(content[-1], dict):
+        content[-1] = {**content[-1], "cache_control": _EPHEMERAL}
+
+
+def _to_wire(m: Message) -> dict[str, Any]:
+    if m.role == "toolResult":
+        return {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": m.tool_call_id,
+                    "content": _flatten_text(m),
+                    "is_error": m.is_error,
+                }
+            ],
+        }
+    blocks = m.content if not isinstance(m.content, str) else [TextContent(text=m.content)]
+    content: list[dict[str, Any]] = []
+    for b in blocks:
+        if isinstance(b, TextContent):
+            content.append({"type": "text", "text": b.text})
+        elif isinstance(b, ImageContent):
+            content.append(
+                {
+                    "type": "image",
+                    "source": {"type": "base64", "media_type": b.mime_type, "data": b.data},
+                }
+            )
+        elif isinstance(b, ThinkingContent):
+            # A thinking block can only be replayed WITH its signature — Anthropic 400s on
+            # "thinking.signature: Field required" otherwise. We only have a signature for blocks
+            # this provider produced; drop any unsigned thinking (e.g. from another provider or an
+            # older session) rather than send an invalid block.
+            if b.signature:
+                content.append(
+                    {"type": "thinking", "thinking": b.thinking, "signature": b.signature}
+                )
+        elif isinstance(b, ToolCall):
+            content.append(
+                {"type": "tool_use", "id": b.id, "name": b.name, "input": b.arguments or {}}
+            )
+    return {"role": m.role, "content": content}
+
+
+def _flatten_text(m: Message) -> str:
+    if isinstance(m.content, str):
+        return m.content
+    return "".join(b.text for b in m.content if isinstance(b, TextContent))

minima_harness/ai/providers/base.py

@@ -0,0 +1,65 @@
+"""Provider protocol and the provider registry.
+
+A provider owns the ``stream()`` implementation for one ``api`` id (e.g.
+``anthropic-messages``). Real providers register themselves at import time in
+Phase 1; the faux provider registers on demand for hermetic tests.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from minima_harness.ai.events import Event
+
+if TYPE_CHECKING:
+    from minima_harness.ai.types import Context, Model
+
+
+@runtime_checkable
+class Provider(Protocol):
+    """A streaming provider bound to one ``Model.api`` id."""
+
+    api_id: str
+
+    def stream(
+        self,
+        model: Model,
+        context: Context,
+        *,
+        options: dict | None = None,
+        signal: object | None = None,
+    ) -> AsyncIterator[Event]:
+        """Yield streaming events, ending with ``DoneEvent`` or ``ErrorEvent``.
+
+        Implementations are async generator functions (``async def`` with ``yield``), so
+        the declared signature is a plain ``def`` returning ``AsyncIterator`` — calling it
+        returns the iterator directly, no ``await``.
+        """
+        ...
+
+
+# api id -> provider instance. Instances are reused; stateful providers (faux) expose
+# per-test handles rather than mutating this singleton.
+_REGISTRY: dict[str, Provider] = {}
+
+
+def register_provider(api: str, provider: Provider) -> None:
+    """Register (or replace) the provider for an ``api`` id."""
+    _REGISTRY[api] = provider
+
+
+def unregister_provider(api: str) -> None:
+    _REGISTRY.pop(api, None)
+
+
+def get_provider(api: str) -> Provider:
+    try:
+        return _REGISTRY[api]
+    except KeyError:
+        available = ", ".join(sorted(_REGISTRY)) or "<none>"
+        raise KeyError(f"no provider registered for api {api!r} (available: {available})") from None
+
+
+def registered_apis() -> list[str]:
+    return sorted(_REGISTRY)

minima_harness/ai/providers/faux.py

@@ -0,0 +1,173 @@
+"""In-memory provider for hermetic tests and demos.
+
+Minimal port of PI's ``registerFauxProvider``. Opt-in; not registered by default.
+One deterministic scripted flow per registration.
+Usage is estimated at roughly 1 token per 4 characters when not provided on the message.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
+
+from minima_harness.ai.events import (
+    DoneEvent,
+    ErrorEvent,
+    StartEvent,
+    TextDeltaEvent,
+    TextEndEvent,
+    TextStartEvent,
+    ThinkingDeltaEvent,
+    ThinkingEndEvent,
+    ThinkingStartEvent,
+    ToolCallEndEvent,
+    ToolCallStartEvent,
+)
+from minima_harness.ai.providers.base import Provider, register_provider, unregister_provider
+from minima_harness.ai.types import (
+    AssistantMessage,
+    Modality,
+    Model,
+    ModelCost,
+    TextContent,
+    ThinkingContent,
+    ToolCall,
+)
+from minima_harness.ai.usage import attach_cost
+
+if TYPE_CHECKING:
+    from minima_harness.ai.events import Event
+
+
+_FAUX_MODEL = Model(
+    id="faux",
+    provider="faux",
+    api="faux",
+    name="Faux (test)",
+    cost=ModelCost(input=0.0, output=0.0),
+    context_window=8192,
+    max_tokens=4096,
+    input=(Modality.text,),
+    reasoning=False,
+)
+
+# Roughly 1 token per 4 characters, per PI's faux provider.
+_CHARS_PER_TOKEN = 4
+
+
+def _estimate_usage(msg: AssistantMessage) -> None:
+    if msg.usage.input or msg.usage.output:
+        return
+    char_len = sum(
+        len(b.text) if isinstance(b, TextContent) else len(getattr(b, "thinking", ""))
+        for b in msg.content
+        if not isinstance(b, str)
+    )
+    msg.usage.output = max(1, char_len // _CHARS_PER_TOKEN)
+
+
+class FauxProviderState:
+    """Observable per-registration state."""
+
+    def __init__(self) -> None:
+        self.call_count = 0
+        self.responses: deque[AssistantMessage] = deque()
+
+    @property
+    def pending_response_count(self) -> int:
+        return len(self.responses)
+
+
+class FauxRegistration:
+    """Handle returned by :func:`register_faux_provider`."""
+
+    def __init__(self, *, models: list[Model] | None = None) -> None:
+        self.models = models or [_FAUX_MODEL]
+        self.state = FauxProviderState()
+        self._provider = _FauxProvider(self.state, self.models)
+
+    def get_model(self, model_id: str | None = None) -> Model:
+        if model_id is None:
+            return self.models[0]
+        for m in self.models:
+            if m.id == model_id:
+                return m
+        raise KeyError(model_id)
+
+    def set_responses(self, messages: list[AssistantMessage]) -> None:
+        self.state.responses = deque(messages)
+
+    def append_responses(self, messages: list[AssistantMessage]) -> None:
+        self.state.responses.extend(messages)
+
+    def register(self) -> FauxRegistration:
+        register_provider("faux", self._provider)
+        return self
+
+    def unregister(self) -> None:
+        unregister_provider("faux")
+
+    def __enter__(self) -> FauxRegistration:
+        register_provider("faux", self._provider)
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        unregister_provider("faux")
+
+
+class _FauxProvider(Provider):
+    def __init__(self, state: FauxProviderState, models: list[Model]) -> None:
+        self.api_id = "faux"
+        self.state = state
+        self.models = models
+
+    async def stream(
+        self,
+        model: Model,
+        context: object,
+        *,
+        options: dict | None = None,
+        signal: object | None = None,
+    ) -> AsyncIterator[Event]:
+        self.state.call_count += 1
+        if not self.state.responses:
+            err = AssistantMessage(
+                content=[TextContent(text="")],
+                stop_reason="error",
+                error_message="No more faux responses queued",
+            )
+            err.model = model.id
+            yield ErrorEvent(reason="error", error=err)
+            return
+
+        msg = self.state.responses.popleft()
+        msg.model = model.id
+        _estimate_usage(msg)
+        attach_cost(model, msg.usage)
+
+        yield StartEvent(partial=msg)
+        for index, block in enumerate(msg.content):
+            if isinstance(block, TextContent):
+                yield TextStartEvent(content_index=index)
+                if block.text:
+                    yield TextDeltaEvent(delta=block.text, content_index=index)
+                yield TextEndEvent(content=block.text, content_index=index)
+            elif isinstance(block, ThinkingContent):
+                yield ThinkingStartEvent(content_index=index)
+                if block.thinking:
+                    yield ThinkingDeltaEvent(delta=block.thinking, content_index=index)
+                yield ThinkingEndEvent(content=block.thinking, content_index=index)
+            elif isinstance(block, ToolCall):
+                yield ToolCallStartEvent(content_index=index)
+                yield ToolCallEndEvent(tool_call=block, content_index=index)
+        yield DoneEvent(reason=msg.stop_reason, message=msg)
+
+
+def register_faux_provider(*, models: list[Model] | None = None) -> FauxRegistration:
+    """Register a temporary in-memory provider for tests/demos.
+
+    Remember to call ``.unregister()`` (or use the provider as a context manager) so the
+    faux api id does not leak across tests.
+    """
+    return FauxRegistration(models=models).register()