zu-core 0.2.0__py3-none-any.whl

zu_core/__init__.py

@@ -0,0 +1,142 @@
+"""Zu core — the small, stable runtime: contracts, ports, registry, loop, bus.
+
+Depends only on the standard library and Pydantic. It contains no model SDK,
+no domain branching, and no knowledge of any specific tool or provider.
+"""
+
+from __future__ import annotations
+
+from . import events
+from .bus import EventBus, SubscriberFailure
+from .codec import IdentityCodec, KeyProvider, PayloadCodec, decode_payload, encode_payload
+from .content import Action, Audio, Content, ContentPart, Image, Observation, Text
+from .contracts import Budget, Event, Result, Status, TaskSpec
+from .eventstore import ALLOWED_EVENT_FILTERS, event_matches, validate_filter
+from .ports import (
+    CAP_FS_READ,
+    CAP_FS_WRITE,
+    CAP_NET,
+    CAP_SANDBOX,
+    CAP_SUBPROCESS,
+    EGRESS_OPEN,
+    INTERFACE_ATTR,
+    INTERFACE_VERSION,
+    Capabilities,
+    Detector,
+    EventSink,
+    Finish,
+    ModelProvider,
+    ModelRequest,
+    ModelResponse,
+    Policy,
+    RunContext,
+    SandboxBackend,
+    Scope,
+    Severity,
+    Tool,
+    ToolCall,
+    ToolSpec,
+    Trigger,
+    TriggerEvent,
+    Validator,
+    Verdict,
+    declared_envelope,
+)
+from .projections import SessionState, SessionStore
+from .registry import (
+    REGISTRY,
+    IncompatibleInterfaceError,
+    LoadFailure,
+    Registry,
+    backend,
+    check_interface,
+    detector,
+    policy,
+    provider,
+    sink,
+    tool,
+    trigger,
+    validator,
+)
+from .security import SecurityBlock
+from .sinks import MemoryEventSink
+from .view import RENDER_KEYS, scope_event, scope_payload
+
+__all__ = [
+    # contracts
+    "Budget",
+    "Event",
+    "Result",
+    "Status",
+    "TaskSpec",
+    # multimodal content (the policy currency)
+    "Content",
+    "ContentPart",
+    "Text",
+    "Image",
+    "Audio",
+    "Observation",
+    "Action",
+    # event bus + taxonomy + projections + sinks + codec
+    "EventBus",
+    "SubscriberFailure",
+    "SessionStore",
+    "SessionState",
+    "MemoryEventSink",
+    "events",
+    "ALLOWED_EVENT_FILTERS",
+    "event_matches",
+    "validate_filter",
+    "IdentityCodec",
+    "PayloadCodec",
+    "KeyProvider",
+    "encode_payload",
+    "decode_payload",
+    "SecurityBlock",
+    "scope_event",
+    "scope_payload",
+    "RENDER_KEYS",
+    # ports
+    "CAP_NET",
+    "CAP_SANDBOX",
+    "CAP_FS_READ",
+    "CAP_FS_WRITE",
+    "CAP_SUBPROCESS",
+    "EGRESS_OPEN",
+    "INTERFACE_VERSION",
+    "INTERFACE_ATTR",
+    "declared_envelope",
+    "Capabilities",
+    "Detector",
+    "EventSink",
+    "Finish",
+    "ModelProvider",
+    "ModelRequest",
+    "ModelResponse",
+    "Policy",
+    "RunContext",
+    "SandboxBackend",
+    "Scope",
+    "Severity",
+    "Tool",
+    "ToolCall",
+    "ToolSpec",
+    "Trigger",
+    "TriggerEvent",
+    "Validator",
+    "Verdict",
+    # registry
+    "REGISTRY",
+    "LoadFailure",
+    "IncompatibleInterfaceError",
+    "check_interface",
+    "Registry",
+    "backend",
+    "detector",
+    "policy",
+    "provider",
+    "sink",
+    "tool",
+    "trigger",
+    "validator",
+]

zu_core/bus.py

@@ -0,0 +1,129 @@
+"""The event bus — one source of truth, projected to destinations (step 3).
+
+There is exactly **one canonical event store** (an ``EventSink``) — the single
+source of truth for a run. The bus, on every publish:
+
+  1. **appends to the canonical store first** — durability before any side
+     effect. If that write fails, the failure propagates: you cannot have a run
+     whose source of truth is missing a record.
+  2. **then fans out to destinations** — projections (derived read models like
+     the session store) and secondary sinks (a shipper to OTel, a central log).
+     Each destination is isolated: one that raises does not stop the others,
+     and its failure is recorded (bounded) rather than disappearing.
+
+The canonical store defaults to an in-memory sink and is swapped for a durable
+one (SQLite, Postgres, the hosted central log) by configuration — same port,
+same semantics. Reads (`query`/`stream`/`count`) delegate to the canonical
+store, so there is never a second, divergent copy of the log in the bus.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections import deque
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import NamedTuple
+
+from .contracts import Event
+from .ports import EventSink
+from .sinks import MemoryEventSink
+
+log = logging.getLogger("zu.bus")
+
+Subscriber = Callable[[Event], "Awaitable[None] | None"]
+
+
+class SubscriberFailure(NamedTuple):
+    """A destination that raised while handling an event — recorded, not lost."""
+
+    subscriber: Subscriber
+    event: Event
+    error: Exception
+
+
+class EventBus:
+    def __init__(
+        self,
+        sink: EventSink | None = None,
+        *,
+        max_recorded_failures: int = 1000,
+    ) -> None:
+        # The single source of truth. Defaults to in-memory; configure a durable
+        # sink for production. Never accompanied by a second in-bus copy.
+        self.sink: EventSink = sink if sink is not None else MemoryEventSink()
+        self._subscribers: list[Subscriber] = []
+        # Secondary sinks attached via ``add_destination`` — tracked so ``aclose``
+        # can release their resources (e.g. a sqlite connection) too.
+        self._destinations: list[EventSink] = []
+        # Bounded so a long-lived bus can't leak memory via recorded failures.
+        self.subscriber_failures: deque[SubscriberFailure] = deque(
+            maxlen=max_recorded_failures
+        )
+
+    def subscribe(self, fn: Subscriber) -> None:
+        """Register a destination: a projection or any per-event handler."""
+        self._subscribers.append(fn)
+
+    def add_destination(self, sink: EventSink) -> None:
+        """Project the stream to a secondary sink (e.g. a shipper), isolated.
+
+        The secondary sink is a destination, not the source of truth: its
+        failures are isolated like any other subscriber's, never propagated.
+        """
+
+        async def _ship(event: Event) -> None:
+            await sink.append(event)
+
+        self._destinations.append(sink)
+        self.subscribe(_ship)
+
+    async def aclose(self) -> None:
+        """Release the canonical store and every secondary destination that holds
+        a resource (e.g. a sqlite connection). ``close`` is an optional capability
+        on a sink — a sink without one (the in-memory default, the per-append
+        jsonl sink) is simply skipped. Each close is isolated so one failure does
+        not strand the others. Idempotent: safe to call more than once.
+
+        The embed facade assembles a fresh bus per run, so calling this in a
+        ``finally`` is what keeps a long-lived ``Zu`` instance from leaking one
+        connection per ``run()``."""
+        for sink in [self.sink, *self._destinations]:
+            closer = getattr(sink, "close", None)
+            if closer is None:
+                continue
+            try:
+                result = closer()
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as exc:  # noqa: BLE001 - one close failure must not strand the rest
+                log.warning("sink %r failed to close: %s", sink, exc)
+
+    async def publish(self, event: Event) -> None:
+        # 1. canonical store first; a failure here propagates (source of truth).
+        await self.sink.append(event)
+
+        # 2. fan out to destinations, isolating any crash.
+        for fn in self._subscribers:
+            try:
+                result = fn(event)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as exc:  # noqa: BLE001 - one crash must not stop the rest
+                self.subscriber_failures.append(SubscriberFailure(fn, event, exc))
+                log.warning("destination %r failed on %s: %s", fn, event.type, exc)
+
+    # --- reads delegate to the single source of truth ---------------------
+
+    async def query(
+        self, flt: dict | None = None, *, limit: int | None = None, after_seq: int = 0
+    ) -> list[Event]:
+        return await self.sink.query(flt, limit=limit, after_seq=after_seq)
+
+    def stream(
+        self, flt: dict | None = None, *, batch_size: int = 500
+    ) -> AsyncIterator[Event]:
+        return self.sink.stream(flt, batch_size=batch_size)
+
+    async def count(self, flt: dict | None = None) -> int:
+        return await self.sink.count(flt)

zu_core/codec.py

@@ -0,0 +1,98 @@
+"""Payload codec seam — the encryption-at-rest boundary for durable sinks.
+
+Encryption-at-rest is deferred as a *cipher* but not as a *format*: an
+append-only log is the worst place to retrofit encryption (you accumulate
+immutable plaintext), so the on-disk envelope is fixed now and the cipher is
+swappable later. Every stored payload blob begins with a one-byte **version
+tag** identifying the codec that wrote it, so a log can hold rows written by
+different codecs (e.g. plaintext rows from before encryption was enabled) and
+still be read back — the durable sink decodes each row by its own tag.
+
+Default is `IdentityCodec` (plaintext, zero dependencies). A real AES-256-GCM
+codec ships behind zu-backends' optional ``[encryption]`` extra. The AES codec
+binds the row's indexed columns as associated data (AAD), so a ciphertext can't
+be moved to — or have its index columns edited on — a different row. The default
+`IdentityCodec` is plaintext and provides *no* integrity: it accepts the ``aad``
+argument for interface parity but cannot bind it (there is no authentication tag
+over plaintext), so the move-resistance guarantee applies only once a cipher is
+configured. Managed keys (KMS / envelope encryption / rotation) are a future
+stage; the codec asks for a key, so swapping an env-var key for a KMS provider
+later is a contained change with no on-disk format impact.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PayloadCodec(Protocol):
+    version: int  # 0-255; the tag byte written as the first byte of each blob
+
+    def encode_body(self, plaintext: str, aad: bytes) -> bytes: ...
+
+    def decode_body(self, body: bytes, aad: bytes) -> str: ...
+
+
+@runtime_checkable
+class KeyProvider(Protocol):
+    """Supplies symmetric data keys *by id*, so a codec can rotate keys and a
+    deployment can source them from the KMS/secret store of its choice (AWS KMS,
+    GCP KMS, Vault, an HSM, …) — the choice belongs to whoever runs Zu, never
+    baked in here. The codec never holds a long-lived master key: it asks the
+    provider for the *current* key id when writing, and for a specific key id
+    (read back off the stored blob) when decrypting an older row.
+
+    Key rotation is the answer to AES-GCM's nonce-scaling bound too: a fresh
+    random 96-bit nonce is safe to ~2^32 events under one key, so rotating the
+    data key (a new ``current_key_id``) resets that budget while old rows keep
+    decrypting under their own key id. Implement this against a KMS to get
+    managed keys with no on-disk format change."""
+
+    @property
+    def current_key_id(self) -> str: ...
+
+    def key(self, key_id: str) -> bytes: ...
+
+
+class IdentityCodec:
+    """Plaintext. The default: no dependencies, fully queryable on disk.
+
+    ``aad`` is accepted for interface parity with authenticated codecs but is
+    intentionally unused: plaintext carries no authentication tag, so there is
+    nothing to bind it to. The AAD row-binding guarantee is a property of the
+    AES codec only — see the module docstring.
+    """
+
+    version = 0
+
+    def encode_body(self, plaintext: str, aad: bytes) -> bytes:
+        return plaintext.encode("utf-8")
+
+    def decode_body(self, body: bytes, aad: bytes) -> str:
+        return body.decode("utf-8")
+
+
+def encode_payload(codec: PayloadCodec, plaintext: str, aad: bytes = b"") -> bytes:
+    """Tag-then-body: [version byte][codec-specific body]."""
+    if not 0 <= codec.version <= 255:
+        raise ValueError(f"codec.version must be a byte (0-255), got {codec.version}")
+    return bytes([codec.version]) + codec.encode_body(plaintext, aad)
+
+
+def decode_payload(
+    blob: bytes, aad: bytes, registry: Mapping[int, PayloadCodec]
+) -> str:
+    """Dispatch on the leading version byte so mixed-codec logs read back."""
+    if not blob:
+        raise ValueError("empty payload blob")
+    version = blob[0]
+    codec = registry.get(version)
+    if codec is None:
+        raise ValueError(
+            f"no codec registered for payload version {version}; "
+            "cannot decode (was this row written with an encryption codec "
+            "that is not installed/configured?)"
+        )
+    return codec.decode_body(blob[1:], aad)

zu_core/content.py

@@ -0,0 +1,138 @@
+"""Typed multimodal content — the modality-agnostic currency of the loop.
+
+The policy port (today an LLM, tomorrow a world model or an embodied
+controller) consumes an :class:`Observation` and emits an :class:`Action`. For
+that single seam to serve every modality, the *observation* must carry typed
+content — text, image, audio, sensor — rather than a bare string, and the
+*action* must be typed rather than a guessed-at dict. These models are that
+currency (Engineering Design §8.2, §9).
+
+Design notes that are load-bearing:
+
+* **Frozen value objects.** A piece of content is a fact about what was
+  observed; it is never mutated in place. Like :class:`Event`, the envelope is
+  frozen.
+* **Discriminated union.** ``Observation.content`` is a list of a closed set of
+  parts, tagged by ``kind`` so Pydantic can round-trip it from JSON on the event
+  log without ambiguity. New modalities are added here (a new ``Content``
+  subclass + a new ``kind``), never by smuggling an untyped blob through.
+* **Binary is base64 on the wire.** :class:`Image`/:class:`Audio` carry raw
+  ``bytes`` in memory but serialise as base64 in JSON mode, so an observation is
+  safe to journal or hand to the codec without a decode error. Media payloads
+  are large; what lands on the event log is the caller's choice (a reference or
+  a scoped copy), but the contract itself never crashes a ``model_dump``.
+* **Additive, not a rewrite.** Tools still return plain dicts and the
+  interpreter loop still speaks ``ModelRequest``/``ModelResponse``. These types
+  are the seam the perception-reduction tools (the Action Surface), the
+  HuggingFace task-model adapter, and the generalised Policy port build on; they
+  do not disturb the existing contracts.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Content(BaseModel):
+    """Frozen base for one piece of observed content.
+
+    A concrete part declares a ``kind`` discriminator so a heterogeneous
+    ``list[Content]`` round-trips from JSON unambiguously.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+
+class Text(Content):
+    kind: Literal["text"] = "text"
+    text: str
+
+
+class Image(Content):
+    # base64 in/out in JSON mode so a binary payload never breaks model_dump(mode="json").
+    model_config = ConfigDict(frozen=True, ser_json_bytes="base64", val_json_bytes="base64")
+
+    kind: Literal["image"] = "image"
+    data: bytes
+    mime: str = "image/png"
+
+
+class Audio(Content):
+    model_config = ConfigDict(frozen=True, ser_json_bytes="base64", val_json_bytes="base64")
+
+    kind: Literal["audio"] = "audio"
+    data: bytes
+    mime: str = "audio/wav"
+
+
+# The closed set of content parts, tagged by ``kind``. Extend it by adding a
+# ``Content`` subclass with a new ``kind`` literal and listing it here — the one
+# place modality support is declared.
+ContentPart = Annotated[Text | Image | Audio, Field(discriminator="kind")]
+
+
+class Observation(BaseModel):
+    """The typed input side of the policy — heavy perceptual input, one shape.
+
+    The :class:`Observation` is what a perception-reduction step (the Action
+    Surface, a UI-element detector, a lidar reducer) fills compactly, and what
+    the policy reads to choose its next :class:`Action`.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    content: list[ContentPart] = Field(default_factory=list)
+
+    @classmethod
+    def from_text(cls, text: str) -> Observation:
+        """Build a text-only observation — the common case and the bridge from
+        the loop's existing string/dict observations."""
+        return cls(content=[Text(text=text)])
+
+    def text(self) -> str:
+        """The concatenated text of every :class:`Text` part (newline-joined).
+
+        How a text policy, a grounding validator, or a text-classifier detector
+        reads an observation without caring which other modalities ride along.
+        """
+        return "\n".join(p.text for p in self.content if isinstance(p, Text))
+
+    def parts(self, kind: str) -> list[ContentPart]:
+        """Every part of a given ``kind`` (``"text"`` | ``"image"`` | ``"audio"``)."""
+        return [p for p in self.content if p.kind == kind]
+
+
+class Action(BaseModel):
+    """The typed output side of the policy.
+
+    An LLM policy returns a ``tool_call`` (or final ``text``); a world-model or
+    embodied controller returns a ``command`` carrying a control action. The
+    harness, bus, detectors, validation, and envelope are unchanged across all
+    three — which is the whole point of typing the action rather than the policy
+    (Engineering Design §9.2).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    kind: Literal["text", "tool_call", "command"]
+    payload: dict = Field(default_factory=dict)
+
+    @classmethod
+    def text(cls, text: str) -> Action:
+        """A final-answer action."""
+        return cls(kind="text", payload={"text": text})
+
+    @classmethod
+    def tool_call(cls, name: str, args: dict | None = None) -> Action:
+        """A request to invoke a tool by name — the LLM-policy shape. The
+        payload mirrors :class:`zu_core.ports.ToolCall` (``name`` + ``args``) so
+        a Policy adapter can bridge the two without a lossy translation."""
+        return cls(kind="tool_call", payload={"name": name, "args": args or {}})
+
+    @classmethod
+    def command(cls, **payload: object) -> Action:
+        """A low-level control action — the world-model / embodied-controller
+        shape (e.g. ``Action.command(actuator="gait", vector=[...])``)."""
+        return cls(kind="command", payload=dict(payload))

zu_core/contracts.py

@@ -0,0 +1,83 @@
+"""The typed boundaries everything in Zu speaks through.
+
+These three frozen/validated Pydantic models — TaskSpec, Result, Event — are
+the gates every part of the runtime passes through. They are deliberately
+strict: a malformed task or a mis-namespaced event must be refused at the
+boundary, not swallowed.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import Enum
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class Status(str, Enum):
+    SUCCESS = "success"
+    ESCALATE = "escalate"
+    TERMINAL = "terminal"
+
+
+class Budget(BaseModel):
+    max_steps: int = 20
+    max_tokens: int = 200_000
+    wall_time_s: int = 120
+    max_tool_calls: int = 32  # per single model response — caps a runaway turn
+
+
+class TaskSpec(BaseModel):
+    """The typed input to a run."""
+
+    task_id: UUID = Field(default_factory=uuid4)
+    query: str
+    target: str | None = None
+    output_schema: dict = Field(default_factory=dict)  # JSON schema the result must satisfy
+    budget: Budget = Field(default_factory=Budget)
+    max_tier: int = 2
+
+
+class Result(BaseModel):
+    """The typed output of a run."""
+
+    status: Status
+    value: dict | None = None
+    reason: str | None = None  # detector name, on escalate/terminal
+
+
+class Event(BaseModel):
+    """The append-only record envelope.
+
+    Frozen at the envelope level: no field may be *reassigned* once an event is
+    built. The durable record is immutable in the strongest sense — a sink
+    serialises the event to JSON at ``append`` time, so what lands in the
+    canonical store can never change afterward.
+
+    One boundary to know: ``frozen`` does not deep-freeze the ``payload`` dict's
+    *contents* (``event.payload[k] = ...`` is not blocked). Deep-freezing every
+    payload was rejected deliberately — payloads carry large fetched HTML on the
+    hot path and copying/freezing them per event is too costly. The invariant is
+    therefore: **treat a published event's payload as read-only.** Do not mutate
+    it in place; the canonical on-disk copy is already immutable regardless.
+    """
+
+    model_config = {"frozen": True}
+
+    event_id: UUID = Field(default_factory=uuid4)
+    trace_id: UUID
+    task_id: UUID
+    parent_id: UUID | None = None
+    type: str
+    ts: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    source: str
+    payload: dict = Field(default_factory=dict)
+    schema_version: int = 1
+
+    @field_validator("type")
+    @classmethod
+    def _namespace(cls, v: str) -> str:
+        if not (v.startswith("harness.") or v.startswith("data.")):
+            raise ValueError("event type must start with 'harness.' or 'data.'")
+        return v