zu-runtime 0.2.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+zu/__init__.py,sha256=JpeAJGFgcfYQyjDh2GQBLTNVMq1HLUyWyiECbOacHF0,7491
+zu/pipeline.py,sha256=1Ya7fDT5QFf_2NpNPyEVkLlcgHm4Zvy8TzrqjbHLt9g,4015
+zu_runtime-0.2.0.dist-info/METADATA,sha256=QZBtUDvQ6V5uQ5J4QX9aQ0EymYWsFJql33AalJAswsQ,4718
+zu_runtime-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+zu_runtime-0.2.0.dist-info/RECORD,,

zu_runtime-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any