zu-runtime 0.2.0__tar.gz

zu_runtime-0.2.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Test / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Zu runtime artifacts
+*.db
+zu.db
+zu.yaml.local
+zu_review.jsonl
+*.review.jsonl
+# Per-agent cost telemetry ledger — machine-local run history, not source.
+cost.jsonl
+# A recorded replay path is learned per-run and machine-local — regenerated on
+# every successful run, not source. The agent ships; its track does not.
+track.json
+# …except the flagship example ships its track on purpose, as a demo of the
+# record/replay convergence (committed; re-runs show as ordinary modifications).
+!examples/agents/vet-appointment/track.json
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Claude Code local session state
+.claude/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Microsoft Office temp/lock files
+~$*
+
+# Internal design / strategy docs — kept local, never in the public repo
+*.docx
+*.pdf
+# BUILD.md is the internal build-sequence / deferred-gaps ledger — kept local.
+# (ARCHITECTURE.md is public: an onboarding agent needs the structural map.)
+docs/BUILD.md
+
+# Local secret — API key for live validation, never commit
+zu_demo_key.md
+*_key.md
+
+# Local PyPI publish token — never commit
+/pypi
+
+# Local Discord credentials (bot token / app secrets) — never commit
+/discord

zu_runtime-0.2.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: zu-runtime
+Version: 0.2.0
+Summary: An opinionated, backend-agnostic runtime for agents that work in production — deterministic, auditable, injection-resistant. Import as `zu`.
+Project-URL: Homepage, https://github.com/k3-mt/zu
+Project-URL: Repository, https://github.com/k3-mt/zu
+License-Expression: Apache-2.0
+Keywords: agents,ai-agents,event-sourcing,llm,runtime,sandbox,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: zu-backends==0.2.0
+Requires-Dist: zu-checks==0.2.0
+Requires-Dist: zu-cli==0.2.0
+Requires-Dist: zu-providers==0.2.0
+Requires-Dist: zu-tools==0.2.0
+Provides-Extra: all
+Requires-Dist: zu-backends[docker]==0.2.0; extra == 'all'
+Requires-Dist: zu-cli[mcp]==0.2.0; extra == 'all'
+Requires-Dist: zu-cli[serve]==0.2.0; extra == 'all'
+Requires-Dist: zu-cli[test]==0.2.0; extra == 'all'
+Requires-Dist: zu-providers[anthropic]==0.2.0; extra == 'all'
+Requires-Dist: zu-providers[openai]==0.2.0; extra == 'all'
+Requires-Dist: zu-tools==0.2.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: zu-providers[anthropic]==0.2.0; extra == 'anthropic'
+Provides-Extra: demo
+Requires-Dist: zu-tools==0.2.0; extra == 'demo'
+Provides-Extra: docker
+Requires-Dist: zu-backends[docker]==0.2.0; extra == 'docker'
+Provides-Extra: mcp
+Requires-Dist: zu-cli[mcp]==0.2.0; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: zu-providers[openai]==0.2.0; extra == 'openai'
+Provides-Extra: serve
+Requires-Dist: zu-cli[serve]==0.2.0; extra == 'serve'
+Provides-Extra: test
+Requires-Dist: zu-cli[test]==0.2.0; extra == 'test'
+Provides-Extra: web
+Requires-Dist: zu-tools==0.2.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# Zu
+
+**An opinionated, backend-agnostic runtime for agents that work in production** —
+deterministic, auditable, and injection-resistant by construction.
+
+New here? One line:
+
+```bash
+pip install 'zu-runtime[all]'       # everything: web tools, both model SDKs, server, Docker, MCP
+```
+
+Prefer a lean install? `pip install zu-runtime` gives you `import zu`, the `zu`
+command, the **web tools** (http_fetch/html_parse/render_dom), the model-provider adapters,
+detectors, validators, and a SQLite event sink. Add the heavy/situational bits as extras:
+
+```bash
+pip install 'zu-runtime[anthropic]' # + the Anthropic SDK to call a real model (also: [openai])
+pip install 'zu-runtime[serve]'     # + the HTTP server (zu serve)
+pip install 'zu-runtime[docker]'    # + the Docker sandbox (tier-2 browser)
+pip install 'zu-runtime[mcp]'       # + the MCP server (zu mcp)
+```
+
+The `zu-*` packages are also standalone on PyPI, but you rarely install them individually —
+that's for plugin authors depending on just `zu-core`.
+
+## Embed it
+
+```python
+import zu
+
+result = zu.run(
+    {"query": "Extract the product name and price.",
+     "target": "https://example.com/product/123",
+     "output_schema": {"type": "object",
+                       "properties": {"name": {"type": "string"}, "price": {"type": "string"}},
+                       "required": ["name", "price"]}},
+    config={"provider": {"name": "anthropic", "model": "claude-sonnet-4-6",
+                         "api_key_env": "ANTHROPIC_API_KEY"},
+            "plugins": {"tools": ["http_fetch", "html_parse", "render_dom"],
+                        "detectors": ["empty", "error", "js-shell", "bot-wall"],
+                        "validators": ["schema", "grounding"]}},
+)
+print(result.status, result.value)
+```
+
+Swapping the model is a one-line edit to the `provider` block — Anthropic,
+OpenRouter, OpenAI, or a local model (Ollama / vLLM) — because the runtime only
+ever speaks to a `ModelProvider` port. Credentials are named by environment
+variable (`api_key_env`), never passed in code or config.
+
+## Run it from the command line, or as a service
+
+```bash
+zu run agent.yaml             # one-shot
+zu run agent.yaml --every 5m  # scheduled worker
+zu serve -c agent.yaml                     # HTTP: POST /run  (needs the [serve] extra)
+```
+
+## What it is
+
+A small, stable core (the loop, registry, contracts, event bus) surrounded by
+six swappable ports. Every capability that can vary is a plugin behind a port,
+so the production system is reached by adding adapters — never by reopening the
+core. Full source, architecture, and examples:
+**https://github.com/k3-mt/zu**
+
+Apache-2.0.

zu_runtime-0.2.0/README.md

@@ -0,0 +1,67 @@
+# Zu
+
+**An opinionated, backend-agnostic runtime for agents that work in production** —
+deterministic, auditable, and injection-resistant by construction.
+
+New here? One line:
+
+```bash
+pip install 'zu-runtime[all]'       # everything: web tools, both model SDKs, server, Docker, MCP
+```
+
+Prefer a lean install? `pip install zu-runtime` gives you `import zu`, the `zu`
+command, the **web tools** (http_fetch/html_parse/render_dom), the model-provider adapters,
+detectors, validators, and a SQLite event sink. Add the heavy/situational bits as extras:
+
+```bash
+pip install 'zu-runtime[anthropic]' # + the Anthropic SDK to call a real model (also: [openai])
+pip install 'zu-runtime[serve]'     # + the HTTP server (zu serve)
+pip install 'zu-runtime[docker]'    # + the Docker sandbox (tier-2 browser)
+pip install 'zu-runtime[mcp]'       # + the MCP server (zu mcp)
+```
+
+The `zu-*` packages are also standalone on PyPI, but you rarely install them individually —
+that's for plugin authors depending on just `zu-core`.
+
+## Embed it
+
+```python
+import zu
+
+result = zu.run(
+    {"query": "Extract the product name and price.",
+     "target": "https://example.com/product/123",
+     "output_schema": {"type": "object",
+                       "properties": {"name": {"type": "string"}, "price": {"type": "string"}},
+                       "required": ["name", "price"]}},
+    config={"provider": {"name": "anthropic", "model": "claude-sonnet-4-6",
+                         "api_key_env": "ANTHROPIC_API_KEY"},
+            "plugins": {"tools": ["http_fetch", "html_parse", "render_dom"],
+                        "detectors": ["empty", "error", "js-shell", "bot-wall"],
+                        "validators": ["schema", "grounding"]}},
+)
+print(result.status, result.value)
+```
+
+Swapping the model is a one-line edit to the `provider` block — Anthropic,
+OpenRouter, OpenAI, or a local model (Ollama / vLLM) — because the runtime only
+ever speaks to a `ModelProvider` port. Credentials are named by environment
+variable (`api_key_env`), never passed in code or config.
+
+## Run it from the command line, or as a service
+
+```bash
+zu run agent.yaml             # one-shot
+zu run agent.yaml --every 5m  # scheduled worker
+zu serve -c agent.yaml                     # HTTP: POST /run  (needs the [serve] extra)
+```
+
+## What it is
+
+A small, stable core (the loop, registry, contracts, event bus) surrounded by
+six swappable ports. Every capability that can vary is a plugin behind a port,
+so the production system is reached by adding adapters — never by reopening the
+core. Full source, architecture, and examples:
+**https://github.com/k3-mt/zu**
+
+Apache-2.0.

zu_runtime-0.2.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "zu-runtime"
+version = "0.2.0"
+description = "An opinionated, backend-agnostic runtime for agents that work in production — deterministic, auditable, injection-resistant. Import as `zu`."
+requires-python = ">=3.11"
+license = "Apache-2.0"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+readme = "README.md"
+keywords = ["agents", "llm", "ai-agents", "runtime", "web-scraping", "sandbox", "event-sourcing"]
+# The runnable base: `import zu`, the `zu` command, the web tools
+# (http_fetch/html_parse/render_dom — the common case, so they ship in the base), the
+# model-provider adapters, detectors, validators, and the sqlite event sink. The
+# heavy/situational bits below are opt-in extras (the real model SDKs, the HTTP server,
+# the Docker sandbox, MCP); every plugin is also installable standalone (pip install
+# zu-tools, …) so a plugin author can depend on just what they need (the ecosystem).
+dependencies = [
+    "zu-cli==0.2.0",
+    "zu-providers==0.2.0",
+    "zu-checks==0.2.0",
+    "zu-backends==0.2.0",
+    "zu-tools==0.2.0",       # web tools — the common case, so it ships in the base
+]
+
+[project.optional-dependencies]
+# The web tools now ship in the BASE; [web]/[demo] remain as no-op back-compat
+# aliases so an existing `pip install 'zu-runtime[web]'` / `[demo]` still resolves.
+web = ["zu-tools==0.2.0"]
+demo = ["zu-tools==0.2.0"]
+# Real model SDKs (the adapters ship in the base; these add the vendor client).
+anthropic = ["zu-providers[anthropic]==0.2.0"]
+openai = ["zu-providers[openai]==0.2.0"]
+# The HTTP server (`zu serve`) and the Docker sandbox client (tier-2 browser).
+serve = ["zu-cli[serve]==0.2.0"]
+docker = ["zu-backends[docker]==0.2.0"]
+# The MCP server (`zu mcp`) — integrate with coding agents (Claude Code, Cursor).
+mcp = ["zu-cli[mcp]==0.2.0"]
+# The plugin-test gate + adversarial red team (`zu test-plugin`) — a contributor
+# / CI tool for proving a plugin cooperates and withstands attack.
+test = ["zu-cli[test]==0.2.0"]
+# Everything: web tools, both model SDKs, the server, the Docker sandbox, MCP,
+# and the test gate.
+all = [
+    "zu-tools==0.2.0",
+    "zu-providers[anthropic]==0.2.0",
+    "zu-providers[openai]==0.2.0",
+    "zu-cli[serve]==0.2.0",
+    "zu-cli[mcp]==0.2.0",
+    "zu-cli[test]==0.2.0",
+    "zu-backends[docker]==0.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/k3-mt/zu"
+Repository = "https://github.com/k3-mt/zu"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zu"]

zu_runtime-0.2.0/src/zu/__init__.py

@@ -0,0 +1,203 @@
+"""Zu — the embed facade. ``import zu`` and run an agent in one line.
+
+This is the batteries-included entry point for *using* Zu from your own code.
+It wires the same path the CLI and the HTTP server use — config in, a typed
+``Result`` out — so embedding, ``zu run``, and ``zu serve`` are one runtime, not
+three.
+
+    import zu
+
+    # a self-contained agent: one agent.yaml, or a bundle dir (agent.yaml + tools/)
+    result = zu.run_agent("agent.yaml")        # or zu.run_agent("my-agent/")
+
+    # the programmatic form — a config plus a task (config + many tasks):
+    result = zu.run(
+        {"query": "Extract the title and price.", "target": "https://example.com",
+         "output_schema": {"type": "object", "properties": {"title": {"type": "string"}}}},
+        config={"provider": {"name": "anthropic", "model": "claude-sonnet-4-6",
+                             "api_key_env": "ANTHROPIC_API_KEY"},
+                "plugins": {"tools": ["http_fetch", "html_parse"], "validators": ["schema"]}},
+    )
+
+    print(result.status, result.value)
+
+    # a reusable, configured runner (load config once, run many tasks)
+    agent = zu.Zu(config="zu.yaml")
+    r1 = agent.run({"query": "..."})
+    r2, events = agent.run_with_events({"query": "..."})   # also get the event log
+
+Credentials are never passed here: config names the *environment variable*
+holding a key (``api_key_env``), resolved inside the adapter at call time.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from zu_cli.config import (
+    ConfigError,
+    RunConfig,
+    assemble,
+    coerce_config,
+    coerce_task,
+)
+from zu_core.contracts import Budget, Event, Result, Status, TaskSpec
+from zu_core.loop import run_task
+from zu_core.registry import (
+    backend,
+    detector,
+    provider,
+    sink,
+    tool,
+    validator,
+)
+
+from .pipeline import Pipeline, PipelineResult
+
+__version__ = "0.1.0"
+
+# In-process plugin registration decorators, re-exported from the core registry
+# so the documented ``@zu.tool`` / ``@zu.detector`` / … surface (see
+# the architecture docs and AGENTS.md) actually resolves on ``import zu``. They
+# register onto the process-wide REGISTRY the loop reads, so a decorator-
+# registered plugin is visible to ``zu.run`` and ``zu plugins`` alike.
+__all__ = [
+    "Zu",
+    "Pipeline",
+    "PipelineResult",
+    "run_agent",
+    "run_agent_with_events",
+    "run",
+    "arun",
+    "run_with_events",
+    "ConfigError",
+    "RunConfig",
+    "TaskSpec",
+    "Result",
+    "Status",
+    "Budget",
+    "Event",
+    "create_app",
+    "tool",
+    "detector",
+    "validator",
+    "provider",
+    "backend",
+    "sink",
+    "__version__",
+]
+
+
+# Config/task coercion is shared with the CLI surfaces (see zu_cli.config). The
+# embed facade accepts a str task as a *path* (``allow_paths=True``): you're
+# running in-process on your own host, so reading a task file you point at — the
+# same affordance as ``zu run`` — is intended.
+
+
+class Zu:
+    """A configured runner. Load a config once, run many tasks against it.
+
+    ``config`` is a path, a dict, a ``RunConfig``, or None (``./zu.yaml``). The
+    config is parsed eagerly so a bad config fails here, not on the first run.
+    """
+
+    def __init__(self, config: Any = None) -> None:
+        self.config: RunConfig = coerce_config(config)
+
+    async def arun_with_events(self, task: Any) -> tuple[Result, list[Event]]:
+        """Async: run one task, returning the Result and the run's event log."""
+        spec = coerce_task(task, self.config.budget, allow_paths=True)
+        provider, registry, bus, providers = assemble(self.config)
+        # The same observability hook the CLI uses: an embedded agent queues a
+        # blocked attempt to the review queue too (no console trace by default).
+        from zu_cli.observe import attach_observability
+
+        attach_observability(bus, self.config.observability)
+        try:
+            result = await run_task(
+                spec, provider, registry, bus,
+                providers=providers, containment=self.config.containment,
+                max_observation_chars=self.config.max_observation_chars,
+                observation_strategy=self.config.observation_strategy,
+                max_context_chars=self.config.max_context_chars,
+            )
+            events = await bus.query()
+            return result, events
+        finally:
+            # ``assemble`` builds a fresh bus (and its canonical/trace sinks) per
+            # run; release them here so a long-lived, reused ``Zu`` instance does
+            # not leak one sqlite connection per ``run()``.
+            await bus.aclose()
+
+    async def arun(self, task: Any) -> Result:
+        """Async: run one task, returning just the Result."""
+        result, _ = await self.arun_with_events(task)
+        return result
+
+    def run_with_events(self, task: Any) -> tuple[Result, list[Event]]:
+        """Run one task synchronously, returning the Result and the event log."""
+        return asyncio.run(self.arun_with_events(task))
+
+    def run(self, task: Any) -> Result:
+        """Run one task synchronously, returning just the Result."""
+        return asyncio.run(self.arun(task))
+
+
+def run_agent(source: Any = None) -> Result:
+    """Run a self-contained agent to a Result — the embed equivalent of
+    ``zu run``. ``source`` is an ``agent.yaml`` path, a **bundle directory**
+    (agent.yaml + a tools/ package, auto-loaded), a dict, or None (``./agent.yaml``
+    or ``./``)."""
+    result, _ = run_agent_with_events(source)
+    return result
+
+
+def run_agent_with_events(source: Any = None) -> tuple[Result, list[Event]]:
+    """Run a self-contained agent, returning the Result *and* its event log."""
+    return asyncio.run(_arun_agent(source))
+
+
+async def _arun_agent(source: Any) -> tuple[Result, list[Event]]:
+    from zu_cli.config import load_agent
+    from zu_cli.observe import attach_observability
+
+    spec, cfg = load_agent(source)
+    provider, registry, bus, providers = assemble(cfg)
+    attach_observability(bus, cfg.observability)
+    try:
+        result = await run_task(
+            spec, provider, registry, bus,
+            providers=providers, containment=cfg.containment,
+            max_observation_chars=cfg.max_observation_chars,
+            observation_strategy=cfg.observation_strategy,
+            max_context_chars=cfg.max_context_chars,
+        )
+        return result, await bus.query()
+    finally:
+        await bus.aclose()
+
+
+def run(task: Any, config: Any = None) -> Result:
+    """Run one task against a config — the programmatic form (config + many tasks).
+    ``task`` and ``config`` may each be a path, a dict, the typed object, or None.
+    For a single self-contained ``agent.yaml``/bundle, use :func:`run_agent`."""
+    return Zu(config).run(task)
+
+
+async def arun(task: Any, config: Any = None) -> Result:
+    """Async one-shot — the coroutine behind :func:`run`."""
+    return await Zu(config).arun(task)
+
+
+def run_with_events(task: Any, config: Any = None) -> tuple[Result, list[Event]]:
+    """Run one task to a Result *and* its event log (the queryable provenance)."""
+    return Zu(config).run_with_events(task)
+
+
+def create_app(config: Any = None, **kwargs: Any) -> Any:
+    """The ASGI app for ``zu serve``. Re-exported here so an embedder can mount
+    Zu in their own ASGI stack. Needs the 'serve' extra (FastAPI)."""
+    from zu_cli.server import create_app as _create_app
+
+    return _create_app(config, **kwargs)

zu_runtime-0.2.0/src/zu/pipeline.py

@@ -0,0 +1,92 @@
+"""``zu.Pipeline`` — the config-driven wrapper over the core orchestration.
+
+The orchestration itself (shared-trace chaining, gating, resume) lives in
+``zu_core.pipeline`` — pure, SDK-free core logic over ``run_task``. This wrapper
+adds the ergonomics that match ``zu.run``: a YAML/dict **config** (one provider
+block, the plugins, the sink) and **dict phase specs**. It assembles the config
+once and shares the resulting bus across every phase.
+
+    pipe = zu.Pipeline(config="zu.yaml")
+    pipe.phase("extract",   {"query": "...", "output_schema": {...}})
+    pipe.phase("summarize", lambda prev: {"query": f"...{prev.value['name']}...", "output_schema": {...}})
+    result = pipe.run()          # PipelineResult: status, value, phases, events, id
+
+A phase's task is a dict, or a callable ``(prev_result) -> dict`` that consumes
+the previous phase's validated value. Point the config at the ``scripted``
+provider to run the whole pipeline offline (no model, no network).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import Any
+from uuid import UUID, uuid4
+
+from zu_cli.config import assemble, coerce_config, coerce_task
+from zu_core.contracts import Result, TaskSpec
+from zu_core.pipeline import Phase, PipelineResult, run_pipeline
+
+__all__ = ["Pipeline", "PipelineResult"]
+
+# A phase's task: a static spec dict, or a builder that consumes the prior result.
+PhaseTask = dict | Callable[[Result | None], dict]
+
+
+class Pipeline:
+    """A deterministic sequence of phases sharing one trace, log, and budget gate.
+
+    ``config`` is a path, dict, ``RunConfig``, or None (``./zu.yaml``) — the same
+    as ``zu.run``. ``pipeline_id`` defaults to a fresh id; pass a stable one (with
+    a durable ``event_sink`` in the config) to make the pipeline resumable across
+    process restarts.
+    """
+
+    def __init__(self, config: Any = None, *, pipeline_id: UUID | str | None = None) -> None:
+        self.config = coerce_config(config)
+        self._id = _as_uuid(pipeline_id) if pipeline_id is not None else uuid4()
+        self._phases: list[tuple[str, PhaseTask]] = []
+
+    @property
+    def id(self) -> UUID:
+        return self._id
+
+    def phase(self, name: str, task: PhaseTask) -> Pipeline:
+        """Append a phase. ``task`` is a spec dict or ``(prev_result) -> dict``.
+        Returns self, so calls chain. Names must be unique (they key resume)."""
+        if any(n == name for n, _ in self._phases):
+            raise ValueError(f"duplicate phase name: {name!r}")
+        self._phases.append((name, task))
+        return self
+
+    async def arun(self) -> PipelineResult:
+        cfg = self.config
+        provider, registry, bus, providers = assemble(cfg)
+        try:
+            phases = [Phase(name, self._build(task)) for name, task in self._phases]
+            return await run_pipeline(
+                phases, provider, registry, bus,
+                providers=providers, containment=cfg.containment, pipeline_id=self._id,
+                max_observation_chars=cfg.max_observation_chars,
+                observation_strategy=cfg.observation_strategy,
+                max_context_chars=cfg.max_context_chars,
+            )
+        finally:
+            # ``assemble`` built the bus + its sink(s); release them after the run.
+            await bus.aclose()
+
+    def run(self) -> PipelineResult:
+        """Run the pipeline synchronously."""
+        return asyncio.run(self.arun())
+
+    def _build(self, task: PhaseTask) -> Callable[[Result | None], TaskSpec]:
+        """Turn a dict / callable phase task into a core TaskSpec builder, coercing
+        the dict and inheriting the config's default budget."""
+        def build(prev: Result | None) -> TaskSpec:
+            task_dict = task(prev) if callable(task) else dict(task)
+            return coerce_task(task_dict, self.config.budget, allow_paths=True)
+        return build
+
+
+def _as_uuid(value: UUID | str) -> UUID:
+    return value if isinstance(value, UUID) else UUID(str(value))

zu_runtime-0.2.0/tests/test_facade.py

@@ -0,0 +1,106 @@
+"""The embed facade: `import zu` and run an agent in one line.
+
+Proves the library entry point works offline (scripted provider, no key, no
+network) from plain dicts and from files, returns the typed Result, exposes the
+event log, and reuses one config across many runs via the Zu class.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+import zu
+from zu import ConfigError, Status
+
+
+def _cfg(answer: dict) -> dict:
+    return {
+        "provider": {"name": "scripted", "script": [{"text": json.dumps(answer), "finish": "stop"}]},
+        "plugins": {"validators": ["schema"]},
+    }
+
+
+_TASK = {
+    "query": "extract the product",
+    "output_schema": {
+        "type": "object",
+        "properties": {"name": {"type": "string"}, "price": {"type": "string"}},
+        "required": ["name", "price"],
+    },
+}
+
+
+def test_run_from_dicts_returns_typed_result():
+    result = zu.run(_TASK, config=_cfg({"name": "Acme", "price": "$9"}))
+    assert result.status is Status.SUCCESS
+    assert result.value == {"name": "Acme", "price": "$9"}
+
+
+def test_run_with_events_exposes_the_log():
+    result, events = zu.run_with_events(_TASK, config=_cfg({"name": "Acme", "price": "$9"}))
+    assert result.status is Status.SUCCESS
+    assert events[-1].type == "harness.task.completed"
+    assert any(e.type == "harness.task.started" for e in events)
+
+
+def test_zu_class_reuses_one_config_for_many_runs():
+    agent = zu.Zu(config=_cfg({"name": "Acme", "price": "$9"}))
+    r1 = agent.run(_TASK)
+    r2 = agent.run({**_TASK, "query": "again"})
+    assert r1.status is Status.SUCCESS and r2.status is Status.SUCCESS
+
+
+async def test_async_entry_point():
+    result = await zu.arun(_TASK, config=_cfg({"name": "Acme", "price": "$9"}))
+    assert result.status is Status.SUCCESS
+
+
+def test_run_from_files(tmp_path):
+    cfg = tmp_path / "zu.yaml"
+    cfg.write_text(
+        "provider:\n  name: scripted\n"
+        '  script: [{ text: \'{"name":"Acme","price":"$9"}\', finish: stop }]\n'
+        "plugins:\n  validators: [schema]\n",
+        encoding="utf-8",
+    )
+    task = tmp_path / "task.yaml"
+    task.write_text(
+        "query: extract\noutput_schema:\n  type: object\n"
+        "  properties: { name: { type: string }, price: { type: string } }\n"
+        "  required: [name, price]\n",
+        encoding="utf-8",
+    )
+    result = zu.run(str(task), config=str(cfg))
+    assert result.status is Status.SUCCESS
+
+
+def test_task_inherits_config_budget():
+    agent = zu.Zu(config={**_cfg({"name": "A", "price": "$1"}), "budget": {"max_steps": 3}})
+    assert agent.config.budget.max_steps == 3
+
+
+def test_bad_config_type_is_a_clean_error():
+    with pytest.raises(ConfigError):
+        zu.run(_TASK, config=12345)  # not a path/dict/RunConfig
+
+
+def test_bad_task_is_a_clean_error():
+    with pytest.raises(ConfigError):
+        zu.run({"no_query": True}, config=_cfg({"x": "y"}))
+
+
+def test_registration_decorators_are_exported():
+    """The documented ``@zu.tool`` / ``@zu.detector`` / … surface resolves on the
+    facade and registers onto the process-wide registry the loop reads."""
+    from zu_core.registry import REGISTRY
+
+    for name in ("tool", "detector", "validator", "provider", "backend", "sink"):
+        assert callable(getattr(zu, name)), f"zu.{name} is not exported"
+
+    @zu.tool
+    class _FacadeProbeTool:
+        name = "facade_probe_tool"
+
+    assert "facade_probe_tool" in REGISTRY.names("tools")

zu_runtime-0.2.0/tests/test_pipeline.py

@@ -0,0 +1,128 @@
+"""Multi-phase pipelines — the event-sourced way to chain agent runs.
+
+A pipeline lifts a single run's guarantees to the whole sequence: every phase
+shares ONE trace and ONE event log, advances only on a validated success, and a
+re-run resumes from the log instead of repeating finished work. All offline
+(scripted model), so deterministic and keyless.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+import zu
+from zu_core.contracts import Status
+
+
+def _cfg(*moves, sink: str | None = None) -> dict:
+    # validators off: these tests exercise pipeline ORCHESTRATION (trace, gating,
+    # resume) on tool-less scripted phases; schema/grounding are covered in
+    # zu-checks. "Validated success" still gates — a clean finalise is SUCCESS.
+    cfg: dict = {"provider": {"name": "scripted", "script": list(moves)},
+                 "plugins": {"validators": []}}
+    if sink is not None:
+        cfg["event_sink"] = {"driver": "sqlite", "path": sink}
+    return cfg
+
+
+async def test_two_phase_pipeline_passes_value_forward() -> None:
+    seen: dict = {}
+    pipe = zu.Pipeline(config=_cfg(
+        {"text": '{"name": "AeroPress", "price": "$39"}', "finish": "stop"},
+        {"text": '{"blurb": "great press"}', "finish": "stop"},
+    ))
+    pipe.phase("extract", {"query": "extract name and price"})
+
+    def blurb(prev):
+        seen["prev"] = prev.value                       # phase 2 consumes phase 1
+        return {"query": f"write a blurb for {prev.value['name']}"}
+
+    pipe.phase("blurb", blurb)
+    res = await pipe.arun()
+
+    assert res.status is Status.SUCCESS
+    assert res.value == {"blurb": "great press"}                 # final phase's value
+    assert seen["prev"] == {"name": "AeroPress", "price": "$39"}  # data flowed forward
+    assert res.phases["extract"].value == {"name": "AeroPress", "price": "$39"}
+
+
+async def test_pipeline_stops_on_a_failed_phase() -> None:
+    ran: list[str] = []
+    pipe = zu.Pipeline(config=_cfg(
+        {"text": '{"ok": true}', "finish": "stop"},
+        {"text": "truncated", "finish": "length"},      # phase 2 fails (terminal)
+    ))
+    pipe.phase("one", {"query": "q1"})
+    pipe.phase("two", {"query": "q2"})
+
+    def three(prev):
+        ran.append("three")
+        return {"query": "q3"}
+
+    pipe.phase("three", three)
+    res = await pipe.arun()
+
+    assert res.status is not Status.SUCCESS              # the pipeline failed
+    assert res.failed_phase == "two"
+    assert "three" not in ran                            # phase 3 never built or ran
+    assert "three" not in res.phases
+
+
+async def test_pipeline_is_one_replayable_trace() -> None:
+    pipe = zu.Pipeline(config=_cfg(
+        {"text": '{"a": 1}', "finish": "stop"},
+        {"text": '{"b": 2}', "finish": "stop"},
+    ))
+    pipe.phase("p1", {"query": "q"}).phase("p2", {"query": "q"})
+    res = await pipe.arun()
+
+    assert res.events                                    # the whole pipeline log
+    assert all(e.trace_id == pipe.id for e in res.events)   # ONE correlation id
+    assert len({e.task_id for e in res.events}) >= 3        # pipeline + 2 phase task_ids
+    types = {e.type for e in res.events}
+    assert "harness.pipeline.started" in types
+    assert "harness.pipeline.completed" in types
+    done = {e.payload.get("phase") for e in res.events
+            if e.type == "harness.pipeline.phase.completed"}
+    assert done == {"p1", "p2"}
+
+
+async def test_pipeline_resumes_from_the_log(tmp_path) -> None:
+    db = str(tmp_path / "pipe.db")
+    pid = uuid4()
+
+    # Run 1: phase A succeeds, phase B truncates (fails) → pipeline stops; A is on
+    # the durable log, B is not.
+    p1 = zu.Pipeline(
+        config=_cfg({"text": '{"v": "A"}', "finish": "stop"},
+                    {"text": "x", "finish": "length"}, sink=db),
+        pipeline_id=pid,
+    )
+    p1.phase("A", {"query": "qa"}).phase("B", {"query": "qb"})
+    r1 = await p1.arun()
+    assert r1.status is not Status.SUCCESS and r1.failed_phase == "B"
+
+    # Run 2 (resume): same id + same sink. A is found complete in the log and
+    # SKIPPED (its task builder never runs); B re-runs and now succeeds.
+    rebuilt: list[str] = []
+
+    def build_a(prev):
+        rebuilt.append("A")
+        return {"query": "qa"}
+
+    p2 = zu.Pipeline(
+        config=_cfg({"text": '{"v": "B-ok"}', "finish": "stop"}, sink=db),
+        pipeline_id=pid,
+    )
+    p2.phase("A", build_a).phase("B", {"query": "qb"})
+    r2 = await p2.arun()
+
+    assert r2.status is Status.SUCCESS
+    assert r2.value == {"v": "B-ok"}
+    assert "A" not in rebuilt                            # A skipped — not re-executed
+    assert r2.phases["A"].value == {"v": "A"}            # A's value reused from the log
+    assert any(e.type == "harness.pipeline.phase.skipped" for e in r2.events)
+    # A was started exactly once across both runs (run 1), never re-run.
+    a_starts = [e for e in r2.events
+                if e.type == "harness.task.started" and e.payload.get("query") == "qa"]
+    assert len(a_starts) == 1