ziro-core 0.2.6__py3-none-any.whl

ziro/__init__.py

@@ -0,0 +1,63 @@
+"""Ziro — the public, semver'd Python SDK.
+
+``import ziro`` is the ONLY supported, documented surface. Everything under
+``app.*`` is internal and may change without a major-version bump. The SDK is a
+thin facade over the F12 ``TurnRunner`` shared turn core: it resolves a profile,
+builds the graph, and drives turns through the one resume loop the CLI also uses.
+
+Imports are **lazy** (PEP 562 module ``__getattr__``): ``import ziro`` pulls no
+torch / graph stack — those load only when you touch ``ziro.Ziro`` (i.e. when you
+actually build an agent). This keeps the SDK cheap to import in a host app.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+__all__ = [
+    "Ziro",
+    "CapabilitiesHandle",
+    "TurnResult",
+    "StreamEvent",
+    "create_agent",
+    "Agent",
+    "AgentSpec",
+    "ToolConfig",
+    "Guardrails",
+    "PluginConfig",
+]
+
+try:
+    # Written at build time by hatch-vcs from the git tag (see pyproject.toml).
+    from ziro._version import __version__
+except ImportError:  # raw source tree with no tag / no VCS metadata
+    __version__ = "0.0.0+unknown"
+
+if TYPE_CHECKING:  # for type-checkers / IDEs only — no runtime import cost
+    from ziro.agent import Agent, Ziro, create_agent
+    from ziro.capabilities.handle import CapabilitiesHandle
+    from ziro.spec import AgentSpec, Guardrails, PluginConfig, ToolConfig
+    from ziro.types import StreamEvent, TurnResult
+
+
+def __getattr__(name: str):
+    if name in ("Ziro", "Agent", "create_agent"):
+        from ziro import agent
+
+        return getattr(agent, name)
+    if name in ("AgentSpec", "ToolConfig", "Guardrails", "PluginConfig"):
+        from ziro import spec
+
+        return getattr(spec, name)
+    if name == "CapabilitiesHandle":
+        from ziro.capabilities.handle import CapabilitiesHandle
+
+        return CapabilitiesHandle
+    if name in ("TurnResult", "StreamEvent"):
+        from ziro import types
+
+        return getattr(types, name)
+    raise AttributeError(f"module 'ziro' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

ziro/_hf_bootstrap.py

@@ -0,0 +1,78 @@
+"""F24 — HuggingFace offline bootstrap (runs before any transformers/hub import).
+
+``huggingface_hub`` reads ``HF_HUB_OFFLINE`` into a module constant **once, at
+import time**, and it is imported very early (via
+``langchain_core.language_models.base`` → ``transformers``). Setting the env var any
+later has no effect (verified during implementation). The only chokepoint that runs
+before that import is ``app/__init__.py``, which calls :func:`configure_hf_offline`
+here.
+
+Going offline removes ~9 s of HuggingFace Hub revision/etag checks per launch (a
+cached-model construct drops from ~9.2 s to ~0.3 s) **and** pins the embedding space
+to the cached revision the FAISS index was built against. To stay correct on a fresh
+machine, we only go offline when the model is **already cached** (a pure filesystem
+check, no import) — otherwise the one-time download still runs. This module imports
+nothing but :mod:`os` so it can run before the heavy import web.
+"""
+
+from __future__ import annotations
+
+import os
+
+_EMB_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+
+def _hub_cache_dir() -> str:
+    """The HuggingFace hub cache directory, honouring the standard env overrides."""
+    cache = os.environ.get("HUGGINGFACE_HUB_CACHE")
+    if cache:
+        return cache
+    home = os.environ.get("HF_HOME") or os.path.join(
+        os.path.expanduser("~"), ".cache", "huggingface"
+    )
+    return os.path.join(home, "hub")
+
+
+def _embeddings_cached(model: str = _EMB_MODEL) -> bool:
+    """True iff a usable snapshot of ``model`` is already in the hub cache.
+
+    A usable snapshot carries ``config.json``; checking for it (rather than just the
+    snapshots dir) guards against a half-populated cache.
+    """
+    folder = "models--" + model.replace("/", "--")
+    snapshots = os.path.join(_hub_cache_dir(), folder, "snapshots")
+    if not os.path.isdir(snapshots):
+        return False
+    try:
+        for snap in os.listdir(snapshots):
+            if os.path.exists(os.path.join(snapshots, snap, "config.json")):
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def configure_hf_offline() -> bool:
+    """Set ``HF_HUB_OFFLINE``/``TRANSFORMERS_OFFLINE`` when safe. Returns True iff
+    offline is in effect. MUST run before any ``huggingface_hub`` import.
+
+    Precedence: ``ZIRO_NO_ENV_MUTATION=1`` disables all host-env mutation (for
+    embedders — ``import ziro`` must not silently touch the host process env);
+    an explicit operator ``HF_HUB_OFFLINE`` is never overridden;
+    ``ZIRO_EMBEDDINGS_OFFLINE=1`` forces offline regardless of cache; otherwise
+    we go offline only when the embeddings model is already cached.
+    """
+    if os.environ.get("ZIRO_NO_ENV_MUTATION") == "1":
+        # Never write to the host env. Report the current offline state, but leave
+        # it to the operator to set HF_HUB_OFFLINE explicitly when embedding Ziro.
+        explicit_ro = os.environ.get("HF_HUB_OFFLINE")
+        return explicit_ro not in (None, "0", "", "false", "False")
+    explicit = os.environ.get("HF_HUB_OFFLINE")
+    if explicit is not None:  # respect an operator's explicit choice, either way
+        return explicit not in ("0", "", "false", "False")
+    forced = os.environ.get("ZIRO_EMBEDDINGS_OFFLINE", "") in ("1", "true", "True")
+    if forced or _embeddings_cached():
+        os.environ["HF_HUB_OFFLINE"] = "1"
+        os.environ["TRANSFORMERS_OFFLINE"] = "1"
+        return True
+    return False

ziro/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.6'
+__version_tuple__ = version_tuple = (0, 2, 6)
+
+__commit_id__ = commit_id = None

ziro/agent.py

@@ -0,0 +1,511 @@
+"""``Agent`` — the public facade over the F12 ``TurnRunner`` shared turn core.
+
+No new turn logic: resolve a profile (by ``agent=`` YAML id, or an injected
+``AgentSpec`` via ``create_agent``), open the store/checkpointer, build the
+graph, and drive turns through ``TurnRunner.run_turn`` — the same path the TUI
+and ``-p`` use. Sync methods bridge to the async core on a private daemon
+loop; async methods await it directly.
+
+**One-loop rule (replan C5).** A single ``Agent`` instance is either driven all-sync
+(``chat``/``stream``/``open``/``close``) or all-async (``achat``/``astream`` under
+``async with``) — never mixed. The sync API funnels *everything* (open, turn,
+close) through one private loop; the async API stays on the caller's loop. Mixing
+them would use the async ``AsyncSqliteSaver`` checkpointer across two event loops,
+which raises. A guard below fails loudly instead of corrupting state.
+
+**Torch-free import.** Heavy imports (``TurnRunner``, the graph stack → torch) are
+done inside methods, so ``import ziro`` / ``import ziro.agent`` pull no torch until
+you actually construct (with a ``user=``) or drive an ``Agent``.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+import warnings
+from contextlib import AsyncExitStack
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncIterator,
+    Callable,
+    Iterator,
+    Optional,
+    Sequence,
+    Union,
+    cast,
+)
+
+from ziro.capabilities.handle import CapabilitiesHandle
+from ziro.spec import AgentSpec, Guardrails, PluginConfig, ToolConfig
+from ziro.types import StreamEvent
+
+if TYPE_CHECKING:
+    from langchain_core.tools import BaseTool
+    from langgraph.checkpoint.base import BaseCheckpointSaver
+    from langgraph.store.base import BaseStore
+
+    from ziro.compaction.models import CompactionConfig
+    from ziro.hooks.models import HooksConfig, HookSpec
+    from ziro.llm.adapter import LLMAdapter
+    from ziro.memory.models import MemoryConfig
+    from ziro.permissions.models import PermissionPolicy
+    from ziro.runtime.runner import TurnResult, TurnRunner
+    from ziro.graph.interrupts import InterruptRequest, InterruptResponse
+    from ziro.subagents.models import SpawnPolicy
+
+    InterruptHandler = Callable[[InterruptRequest], InterruptResponse]
+
+
+class Agent:
+    """A reusable agent session over an ``AgentSpec`` (code-first) or a YAML
+    agent id. ``user`` binds at construction OR on the first turn
+    (``agent.chat("hi", user="alice")``); one instance = one user.
+
+    ``use_agent()`` switches to a YAML-registry agent even on a spec-driven
+    instance (that is what the underlying switch does).
+
+    Args:
+        spec: an ``AgentSpec`` (code-first, via ``create_agent``), or ``None``
+            for the YAML-registry path (``agent=``/``model=``).
+        user: user id (scopes long-term memory). May be omitted here and
+            supplied on the first ``chat``/``turn``/``stream`` call instead.
+        agent: agent id to run (None → the manifest/picker default, non-interactive).
+        flavour: reserved (F22); passing it now raises NotImplementedError.
+        thread: resume a thread by id (None → a fresh thread).
+        model: OpenRouter model override (None → the agent's meta / env default).
+        provider: reserved (set the provider in the agent's meta.yaml for now).
+        reasoning_effort: high|medium|low|off (None → env / meta default).
+        on_interrupt: called for a mid-turn HITL interrupt (permission ``ask`` /
+            handoff / clarify). Default = fail-closed deny (the ``chat_once`` posture).
+    """
+
+    def __init__(
+        self,
+        spec: AgentSpec | None = None,
+        *,
+        user: Optional[str] = None,
+        agent: Optional[str] = None,
+        flavour: Optional[str] = None,
+        thread: Optional[str] = None,
+        model: Optional[str] = None,
+        provider: Optional[str] = None,
+        reasoning_effort: Optional[str] = None,
+        on_interrupt: "Optional[InterruptHandler]" = None,
+    ) -> None:
+        if flavour is not None:
+            raise NotImplementedError("flavour selection lands in F22; pass agent=… for now")
+        if provider is not None:
+            raise NotImplementedError(
+                "per-instance provider override is not wired yet: set `provider:` in "
+                "the agent's meta.yaml (or build a custom LLMAdapter and pass llm=)"
+            )
+        if spec is not None and (agent is not None or model is not None):
+            raise ValueError("pass either spec= (code-first) or agent=/model= (YAML), not both")
+        self._spec = spec
+        self._agent_arg = agent
+        self._model_arg = model
+        self._effort_arg = reasoning_effort
+        self._thread_arg = thread
+        self._user = user
+        self._runner: "TurnRunner | None" = None
+        self._on_interrupt = on_interrupt
+        self._stack: Optional[AsyncExitStack] = None
+        self._opened = False
+        # A private daemon loop so the SYNC API can drive the async core without the
+        # caller being on an event loop (the TUI's pattern).
+        self._loop = asyncio.new_event_loop()
+        self._loop_thread = threading.Thread(
+            target=self._loop.run_forever, name="ziro-sdk", daemon=True
+        )
+        self._loop_thread.start()
+        # The loop the session was opened on — the one-loop guard compares against it.
+        self._session_loop: Optional[asyncio.AbstractEventLoop] = None
+        if user is not None:
+            self._ensure_runner()
+
+    # ---- runner construction (lazy — this is where torch loads) -----------
+
+    def _ensure_runner(self) -> "TurnRunner":
+        if self._runner is not None:
+            return self._runner
+        if self._user is None:
+            raise RuntimeError(
+                "no user bound: pass user= to the constructor or to the first "
+                "chat/turn/stream call"
+            )
+        from ziro.runtime.runner import TurnRunner  # lazy: pulls the graph stack (torch)
+
+        extra: dict = {}
+        effort = self._effort_arg
+        if self._spec is not None:
+            from ziro.memory.models import MemoryConfig
+            from ziro.profiles.spec_profile import SpecProfile
+
+            spec = self._spec
+            extra["profile"] = SpecProfile(spec)
+            if spec.llm is not None and not isinstance(spec.llm, str):
+                extra["llm"] = spec.llm
+            if spec.memory is not None and not isinstance(spec.memory, MemoryConfig):
+                extra["store"] = spec.memory
+            if spec.checkpointer is not None:
+                extra["checkpointer"] = spec.checkpointer
+            effort = effort or spec.reasoning_effort
+        self._runner = TurnRunner(
+            self._user,
+            agent=self._agent_arg,
+            thread_id=self._thread_arg,
+            interactive=False,
+            model=self._model_arg,
+            reasoning_effort=effort,
+            **extra,
+        )
+        return self._runner
+
+    def _bind_user(self, user: Optional[str]) -> None:
+        if user is not None:
+            if self._user is None:
+                self._user = user
+            elif user != self._user:
+                raise RuntimeError(
+                    f"this Agent instance is bound to user '{self._user}'; "
+                    "create another instance (or a gateway session) for a second user"
+                )
+        self._ensure_runner()
+
+    # ---- interrupt renderer ------------------------------------------------
+
+    def _renderer(self) -> "InterruptHandler":
+        if self._on_interrupt is not None:
+            return self._on_interrupt
+        from ziro.graph.interrupts import render_non_interactive  # fail-closed deny
+
+        return render_non_interactive
+
+    # ---- lifecycle ---------------------------------------------------------
+
+    def _submit(self, coro: Any) -> Any:
+        """Run a coroutine on the private loop from a sync caller and block."""
+        return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
+
+    def _check_loop(self) -> None:
+        """One-loop guard: a turn must run on the same loop that opened the session."""
+        if not self._opened:
+            return
+        try:
+            running = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        if self._session_loop is not None and running is not self._session_loop:
+            raise RuntimeError(
+                "Agent was opened on a different event loop. Use one instance either "
+                "all-sync (chat/stream) or all-async (async with … achat/astream), "
+                "never both."
+            )
+
+    async def _aopen(self) -> "Agent":
+        if not self._opened:
+            runner = self._ensure_runner()
+            self._session_loop = asyncio.get_running_loop()
+            self._stack = AsyncExitStack()
+            await self._stack.enter_async_context(runner.session())
+            self._opened = True
+        return self
+
+    async def _aclose(self) -> None:
+        if self._stack is not None:
+            await self._stack.aclose()
+            self._stack = None
+        self._opened = False
+        self._session_loop = None
+
+    def open(self) -> "Agent":
+        """Sync open: build the graph + open store/checkpointer on the private loop."""
+        self._submit(self._aopen())
+        return self
+
+    def close(self) -> None:
+        if self._opened:
+            self._submit(self._aclose())
+        self._loop.call_soon_threadsafe(self._loop.stop)
+
+    def __enter__(self) -> "Agent":
+        return self.open()
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> "Agent":
+        return await self._aopen()
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self._aclose()
+        self._loop.call_soon_threadsafe(self._loop.stop)
+
+    # ---- turn API (all delegate to TurnRunner) -----------------------------
+
+    async def achat(
+        self, message: str, *, attach: Optional[list[str]] = None, user: Optional[str] = None
+    ) -> str:
+        result = await self.aturn(message, attach=attach, user=user)
+        return result.reply
+
+    def chat(
+        self, message: str, *, attach: Optional[list[str]] = None, user: Optional[str] = None
+    ) -> str:
+        return self._submit(self.achat(message, attach=attach, user=user))
+
+    async def aturn(
+        self, message: str, *, attach: Optional[list[str]] = None, user: Optional[str] = None
+    ) -> "TurnResult":
+        """Full ``TurnResult`` (guardrail flags, interrupts, raw state).
+        ``to_json()`` is the exact chat_once contract."""
+        self._bind_user(user)
+        await self._aopen()
+        self._check_loop()
+        runner = self._ensure_runner()
+        human, _ = runner.make_human(message, attach)
+        return await runner.run_turn(human, renderer=self._renderer())
+
+    def turn(
+        self, message: str, *, attach: Optional[list[str]] = None, user: Optional[str] = None
+    ) -> "TurnResult":
+        return self._submit(self.aturn(message, attach=attach, user=user))
+
+    async def astream(
+        self, message: str, *, attach: Optional[list[str]] = None, user: Optional[str] = None
+    ) -> AsyncIterator[StreamEvent]:
+        """Stream the turn's incremental token/state events, then complete."""
+        self._bind_user(user)
+        await self._aopen()
+        self._check_loop()
+        runner = self._ensure_runner()
+        human, _ = runner.make_human(message, attach)
+        queue: "asyncio.Queue[Optional[StreamEvent]]" = asyncio.Queue()
+
+        def _sink(event: StreamEvent) -> None:
+            queue.put_nowait(event)
+
+        async def _drive() -> None:
+            try:
+                await runner.run_turn(human, renderer=self._renderer(), on_event=_sink)
+            finally:
+                queue.put_nowait(None)  # sentinel: turn done
+
+        task = asyncio.ensure_future(_drive())
+        try:
+            while True:
+                event = await queue.get()
+                if event is None:
+                    break
+                yield event
+        finally:
+            await task
+
+    def stream(
+        self, message: str, *, attach: Optional[list[str]] = None, user: Optional[str] = None
+    ) -> Iterator[StreamEvent]:
+        """Sync stream: drain the async stream over the private loop."""
+        agen = self.astream(message, attach=attach, user=user)
+        while True:
+            try:
+                yield self._submit(agen.__anext__())
+            except StopAsyncIteration:
+                break
+
+    # ---- session control -----------------------------------------------------
+
+    @property
+    def thread_id(self) -> str:
+        return self._ensure_runner().thread_id
+
+    @property
+    def agent_id(self) -> str:
+        return self._ensure_runner().profile.agent_id
+
+    def use_agent(self, agent_id: str) -> None:
+        """Switch agent (fresh thread, rebuilt graph) — TurnRunner.switch_agent."""
+        self._submit(self._ensure_runner().switch_agent(agent_id))
+
+    def use_model(self, model: str) -> None:
+        """Override the model and rebuild — TurnRunner.switch_model.
+
+        No-op on a spec-driven agent whose spec injected an ``LLMAdapter``
+        object as ``llm``: the injected adapter keeps winning on rebuild
+        (``_build_llm``'s short-circuit), so this call has no effect —
+        construct a new ``Agent`` with a different spec instead.
+        """
+        self._submit(self._ensure_runner().switch_model(model))
+
+    def use_thread(self, thread_id: str) -> None:
+        """Resume a thread by id (no rebuild) — TurnRunner.switch_thread."""
+        self._ensure_runner().switch_thread(thread_id)
+
+    def use_flavour(self, name: str) -> None:
+        """STUB (F22): apply a capability-preset bundle + swap the default agent."""
+        raise NotImplementedError("flavour switching lands in F22")
+
+    # ---- capability handle (stub interface; F21 fills it) ------------------
+
+    @property
+    def capabilities(self) -> CapabilitiesHandle:
+        return CapabilitiesHandle(self._ensure_runner())
+
+    # ---- embedding: mount as a sub-graph in a host LangGraph / FastAPI app --
+
+    @property
+    def graph(self) -> Any:
+        """The live compiled LangGraph (a Runnable) — includes THIS session's
+        checkpointer. Requires the session to be open. For mounting inside a host
+        graph that owns its own persistence, prefer ``as_runnable()``.
+
+        ``plugin_gate`` is pre-bound at build from this agent's resolved plugin
+        policy (``SpecProfile``/``AgentProfile`` → off-by-default for a code-first
+        agent) — the host must **not** supply it; a host-supplied ``thread_id`` /
+        ``user_id`` / ``agent_id`` still merges in normally alongside it."""
+        if not self._opened:
+            self.open()
+        from ziro.plugins.discovery import _resolve_plugin_gate
+
+        r = self._ensure_runner()
+        assert r.graph is not None  # self.open() above ran session(), which builds it
+        gate = _resolve_plugin_gate(r.profile)
+        return r.graph.with_config({"configurable": {"plugin_gate": gate}})
+
+    def as_runnable(self) -> Any:
+        """A compiled LangGraph Runnable with **no checkpointer**, for composition
+        into a host graph that provides its own persistence (avoids a
+        nested-checkpointer conflict). The host must supply the ``configurable``
+        keys the graph reads: ``thread_id`` / ``user_id`` / ``agent_id``.
+        ``plugin_gate`` is pre-bound at build from this agent's resolved plugin
+        policy — the host does not (and must not) supply it, so an embedded
+        code-first agent stays hermetic (zero plugins unless ``plugins=`` asked
+        for them) regardless of what configurable keys the host passes."""
+        if not self._opened:
+            self.open()
+        from ziro.graph.graph import build_graph
+        from ziro.plugins.discovery import _resolve_plugin_gate
+
+        r = self._ensure_runner()
+        assert r._store is not None  # open() ran session(), which sets the store
+        gate = _resolve_plugin_gate(r.profile)
+        graph = build_graph(
+            r._build_llm(), r._store, None, registry=r._registry, profile=r.profile
+        )
+        return graph.with_config({"configurable": {"plugin_gate": gate}})
+
+
+def _normalize_plugins(
+    plugins: "Union[PluginConfig, bool, Sequence[str], None]",
+) -> "PluginConfig | None":
+    """Normalize the ``plugins=`` shorthand to a ``PluginConfig``, mirroring how
+    ``tools=`` normalizes to ``ToolConfig``. ``None`` stays None so ``SpecProfile``
+    can apply the SDK's default-off surface default."""
+    if plugins is None or isinstance(plugins, PluginConfig):
+        return plugins
+    if isinstance(plugins, bool):
+        return PluginConfig(enabled=plugins)
+    if isinstance(plugins, (str, bytes)):
+        raise TypeError(
+            "plugins= expects a sequence of plugin ids (e.g. ['cc/x']), not a bare "
+            f"str/bytes; got {plugins!r}. Wrap it in a list: plugins=[{plugins!r}]"
+        )
+    allow = tuple(plugins)
+    if not allow:
+        # An empty sequence means "no plugins" — must stay distinguishable from
+        # plugins=True (all installed) and must NOT produce enabled=True with an
+        # empty allow, since the gate treats empty allow as "no allowlist, all pass".
+        return PluginConfig(enabled=False)
+    return PluginConfig(enabled=True, allow=allow)
+
+
+def create_agent(
+    *,
+    spec: AgentSpec | None = None,
+    llm: "Union[LLMAdapter, str, None]" = None,
+    system_prompt: Optional[str] = None,
+    soul_prompt: Optional[str] = None,
+    tools: "Union[ToolConfig, Sequence[Union[str, BaseTool]], None]" = None,
+    guardrails: Optional[Guardrails] = None,
+    memory: "Union[BaseStore, MemoryConfig, None]" = None,
+    checkpointer: "Optional[BaseCheckpointSaver]" = None,
+    compaction: "Optional[CompactionConfig]" = None,
+    permissions: "Optional[PermissionPolicy]" = None,
+    subagents: "Union[SpawnPolicy, Sequence[str], None]" = None,
+    mcp_servers: Optional[dict] = None,
+    hooks: "Union[HooksConfig, Sequence[HookSpec], None]" = None,
+    reasoning_effort: Optional[str] = None,
+    plugins: "Union[PluginConfig, bool, Sequence[str], None]" = None,
+    name: str = "custom",
+    description: str = "",
+    user: Optional[str] = None,
+    thread: Optional[str] = None,
+    on_interrupt: "Optional[InterruptHandler]" = None,
+) -> Agent:
+    """Build an :class:`Agent` from pluggable objects. Everything omitted keeps
+    today's defaults (env model, sqlite store/checkpointer, library policies).
+    ``create_agent(spec=spec)`` accepts a prebuilt :class:`AgentSpec` directly
+    (mutually exclusive with the per-field kwargs)."""
+    field_kwargs = (
+        llm, system_prompt, soul_prompt, tools, guardrails, memory, checkpointer,
+        compaction, permissions, subagents, mcp_servers, hooks, reasoning_effort,
+        plugins,
+    )
+    if spec is not None:
+        if any(v is not None for v in field_kwargs) or name != "custom" or description:
+            raise ValueError("pass either spec= or per-field kwargs, not both")
+    else:
+        if tools is None:
+            tool_cfg = ToolConfig()
+        elif isinstance(tools, ToolConfig):
+            tool_cfg = tools
+        else:
+            tool_cfg = ToolConfig(core=tuple(tools))
+        spawn = subagents
+        if spawn is not None and not hasattr(spawn, "allowed_children"):
+            from ziro.subagents.models import SpawnPolicy
+
+            spawn = SpawnPolicy(allowed_children=list(spawn))
+        hooks_cfg = hooks
+        if hooks_cfg is not None and not hasattr(hooks_cfg, "hooks"):
+            from ziro.hooks.models import HooksConfig
+
+            hooks_cfg = HooksConfig(hooks=list(hooks_cfg))
+        spec = AgentSpec(
+            name=name, description=description, llm=llm,
+            system_prompt=system_prompt, soul_prompt=soul_prompt,
+            tools=tool_cfg, guardrails=guardrails, memory=memory,
+            checkpointer=checkpointer, compaction=compaction,
+            permissions=permissions, subagents=cast("SpawnPolicy | None", spawn),
+            mcp_servers=mcp_servers, hooks=cast("HooksConfig | None", hooks_cfg),
+            reasoning_effort=reasoning_effort,
+            plugins=_normalize_plugins(plugins),
+        )
+    return Agent(spec, user=user, thread=thread, on_interrupt=on_interrupt)
+
+
+class Ziro(Agent):
+    """Deprecated F20 facade name — use :func:`create_agent` / :class:`Agent`.
+    Survives one release."""
+
+    def __init__(
+        self,
+        *,
+        user: str,
+        agent: Optional[str] = None,
+        flavour: Optional[str] = None,
+        thread: Optional[str] = None,
+        model: Optional[str] = None,
+        provider: Optional[str] = None,
+        reasoning_effort: Optional[str] = None,
+        on_interrupt: "Optional[InterruptHandler]" = None,
+    ) -> None:
+        warnings.warn(
+            "ziro.Ziro is deprecated; use ziro.create_agent(...) / ziro.Agent",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(
+            user=user, agent=agent, flavour=flavour, thread=thread, model=model,
+            provider=provider, reasoning_effort=reasoning_effort,
+            on_interrupt=on_interrupt,
+        )