penguiflow 1.0.3__py3-none-any.whl → 2.1.0__py3-none-any.whl

penguiflow/errors.py

@@ -0,0 +1,113 @@
+"""Traceable exception surface for PenguiFlow."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+
+
+class FlowErrorCode(str, Enum):
+    """Stable error codes surfaced by the runtime."""
+
+    NODE_TIMEOUT = "NODE_TIMEOUT"
+    NODE_EXCEPTION = "NODE_EXCEPTION"
+    TRACE_CANCELLED = "TRACE_CANCELLED"
+    DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED"
+    HOP_BUDGET_EXHAUSTED = "HOP_BUDGET_EXHAUSTED"
+    TOKEN_BUDGET_EXHAUSTED = "TOKEN_BUDGET_EXHAUSTED"
+
+
+class FlowError(Exception):
+    """Wraps runtime failures with trace metadata for downstream handling."""
+
+    __slots__ = (
+        "trace_id",
+        "node_name",
+        "node_id",
+        "code",
+        "message",
+        "original_exc",
+        "metadata",
+        "exception_type",
+    )
+
+    def __init__(
+        self,
+        *,
+        trace_id: str | None,
+        node_name: str | None,
+        code: FlowErrorCode | str,
+        message: str,
+        original_exc: BaseException | None = None,
+        node_id: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.trace_id = trace_id
+        self.node_name = node_name
+        self.node_id = node_id
+        self.code = code.value if isinstance(code, FlowErrorCode) else str(code)
+        self.message = message
+        self.original_exc = original_exc
+        self.metadata = dict(metadata or {})
+        self.exception_type = (
+            type(original_exc).__name__ if original_exc is not None else None
+        )
+
+    def __str__(self) -> str:  # pragma: no cover - debug helper
+        trace = f" trace={self.trace_id}" if self.trace_id else ""
+        node = f" node={self.node_name}" if self.node_name else ""
+        return f"[{self.code}] {self.message}{trace}{node}".strip()
+
+    def unwrap(self) -> BaseException | None:
+        """Return the wrapped exception, if any."""
+
+        return self.original_exc
+
+    def to_payload(self) -> dict[str, Any]:
+        """Return a JSON-serialisable representation of the error."""
+
+        payload: dict[str, Any] = {
+            "code": self.code,
+            "message": self.message,
+        }
+        if self.trace_id is not None:
+            payload["trace_id"] = self.trace_id
+        if self.node_name is not None:
+            payload["node_name"] = self.node_name
+        if self.node_id is not None:
+            payload["node_id"] = self.node_id
+        if self.exception_type is not None:
+            payload["exception_type"] = self.exception_type
+        if self.metadata:
+            payload["metadata"] = dict(self.metadata)
+        return payload
+
+    @classmethod
+    def from_exception(
+        cls,
+        *,
+        trace_id: str | None,
+        node_name: str | None,
+        node_id: str | None,
+        exc: BaseException,
+        code: FlowErrorCode,
+        message: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> FlowError:
+        """Build a ``FlowError`` from an underlying exception."""
+
+        error_message = message or str(exc) or exc.__class__.__name__
+        return cls(
+            trace_id=trace_id,
+            node_name=node_name,
+            node_id=node_id,
+            code=code,
+            message=error_message,
+            original_exc=exc,
+            metadata=metadata,
+        )
+
+
+__all__ = ["FlowError", "FlowErrorCode"]

penguiflow/metrics.py

@@ -0,0 +1,105 @@
+"""Observability primitives for PenguiFlow."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class FlowEvent:
+    """Structured runtime event emitted around node execution."""
+
+    event_type: str
+    ts: float
+    node_name: str | None
+    node_id: str | None
+    trace_id: str | None
+    attempt: int
+    latency_ms: float | None
+    queue_depth_in: int
+    queue_depth_out: int
+    outgoing_edges: int
+    queue_maxsize: int
+    trace_pending: int | None
+    trace_inflight: int
+    trace_cancelled: bool
+    extra: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "extra", MappingProxyType(dict(self.extra)))
+
+    @property
+    def queue_depth(self) -> int:
+        """Return the combined depth of incoming and outgoing queues."""
+
+        return self.queue_depth_in + self.queue_depth_out
+
+    def to_payload(self) -> dict[str, Any]:
+        """Render a dictionary payload suitable for structured logging."""
+
+        payload: dict[str, Any] = {
+            "ts": self.ts,
+            "event": self.event_type,
+            "node_name": self.node_name,
+            "node_id": self.node_id,
+            "trace_id": self.trace_id,
+            "latency_ms": self.latency_ms,
+            "q_depth_in": self.queue_depth_in,
+            "q_depth_out": self.queue_depth_out,
+            "q_depth_total": self.queue_depth,
+            "outgoing": self.outgoing_edges,
+            "queue_maxsize": self.queue_maxsize,
+            "attempt": self.attempt,
+            "trace_inflight": self.trace_inflight,
+            "trace_cancelled": self.trace_cancelled,
+        }
+        if self.trace_pending is not None:
+            payload["trace_pending"] = self.trace_pending
+        if self.extra:
+            payload.update(self.extra)
+        return payload
+
+    def metric_samples(self) -> dict[str, float]:
+        """Derive numeric metrics for integrations such as MLflow."""
+
+        metrics: dict[str, float] = {
+            "queue_depth_in": float(self.queue_depth_in),
+            "queue_depth_out": float(self.queue_depth_out),
+            "queue_depth_total": float(self.queue_depth),
+            "attempt": float(self.attempt),
+            "trace_inflight": float(self.trace_inflight),
+            "trace_cancelled": 1.0 if self.trace_cancelled else 0.0,
+        }
+        if self.trace_pending is not None:
+            metrics["trace_pending"] = float(self.trace_pending)
+        if self.latency_ms is not None:
+            metrics["latency_ms"] = self.latency_ms
+        if (latency := self.extra.get("latency_ms")) is not None:
+            # Allow extra payloads to inject a latency override for retries.
+            try:
+                metrics["latency_ms"] = float(latency)
+            except (TypeError, ValueError):  # pragma: no cover - defensive
+                pass
+        return metrics
+
+    def tag_values(self) -> dict[str, str]:
+        """Return string tags describing the event."""
+
+        tags: dict[str, str] = {"event_type": self.event_type}
+        if self.node_name is not None:
+            tags["node_name"] = self.node_name
+        if self.node_id is not None:
+            tags["node_id"] = self.node_id
+        if self.trace_id is not None:
+            tags["trace_id"] = self.trace_id
+        if self.extra:
+            for key, value in self.extra.items():
+                if isinstance(value, str | int | float | bool):
+                    tags[key] = str(value)
+        return tags
+
+
+__all__ = ["FlowEvent"]

penguiflow/middlewares.py

@@ -1,17 +1,16 @@
-"""Middleware hooks for PenguiFlow.
-
-Instrumentation arrives in Phase 3.
-"""
+"""Middleware hooks for PenguiFlow."""
 
 from __future__ import annotations
 
 from typing import Protocol
 
+from .metrics import FlowEvent
+
 
 class Middleware(Protocol):
-    """Base middleware signature."""
+    """Base middleware signature receiving :class:`FlowEvent` objects."""
 
-    async def __call__(self, event: str, payload: dict[str, object]) -> None: ...
+    async def __call__(self, event: FlowEvent) -> None: ...
 
 
-__all__ = ["Middleware"]
+__all__ = ["Middleware", "FlowEvent"]

penguiflow/patterns.py

@@ -11,6 +11,7 @@ from pydantic import BaseModel
 from pydantic.type_adapter import TypeAdapter
 
 from .node import Node, NodePolicy
+from .policies import PolicyLike, RoutingRequest, evaluate_policy
 from .types import Message
 
 PayloadT = TypeVar("PayloadT")
@@ -47,6 +48,8 @@ async def map_concurrent(
 def predicate_router(
     name: str,
     predicate: Callable[[Any], Sequence[Node | str] | Node | str | None],
+    *,
+    policy: PolicyLike | None = None,
 ) -> Node:
     """Create a node that routes messages based on predicate outputs."""
 
@@ -56,15 +59,36 @@ def predicate_router(
             return
 
         normalized = _normalize_targets(ctx, targets)
-        if normalized:
-            await ctx.emit(msg, to=normalized)
+        if not normalized:
+            return
 
-    return Node(router, name=name, policy=NodePolicy(validate="none"))
+        selected = normalized
+        if policy is not None:
+            request = RoutingRequest(
+                message=msg,
+                context=ctx,
+                node=router_node,
+                proposed=tuple(normalized),
+                trace_id=getattr(msg, "trace_id", None),
+            )
+            decision = await evaluate_policy(policy, request)
+            if decision is None:
+                return
+            selected = _normalize_targets(ctx, decision)
+            if not selected:
+                return
+
+        await ctx.emit(msg, to=selected)
+
+    router_node = Node(router, name=name, policy=NodePolicy(validate="none"))
+    return router_node
 
 
 def union_router(
     name: str,
     union_model: type[BaseModel],
+    *,
+    policy: PolicyLike | None = None,
 ) -> Node:
     """Route based on a discriminated union Pydantic model."""
 
@@ -77,9 +101,27 @@ def union_router(
         normalized = _normalize_targets(ctx, target)
         if not normalized:
             raise KeyError(f"No successor matches '{target}'")
-        await ctx.emit(validated, to=normalized)
 
-    return Node(router, name=name, policy=NodePolicy(validate="none"))
+        selected = normalized
+        if policy is not None:
+            request = RoutingRequest(
+                message=validated,
+                context=ctx,
+                node=router_node,
+                proposed=tuple(normalized),
+                trace_id=getattr(validated, "trace_id", None),
+            )
+            decision = await evaluate_policy(policy, request)
+            if decision is None:
+                return
+            selected = _normalize_targets(ctx, decision)
+            if not selected:
+                return
+
+        await ctx.emit(validated, to=selected)
+
+    router_node = Node(router, name=name, policy=NodePolicy(validate="none"))
+    return router_node
 
 
 def join_k(name: str, k: int) -> Node:

penguiflow/policies.py

@@ -0,0 +1,149 @@
+"""Policy helpers for dynamic routing decisions."""
+
+from __future__ import annotations
+
+import inspect
+import json
+import os
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol, TypeAlias, cast
+
+from .node import Node
+
+if TYPE_CHECKING:  # pragma: no cover - import cycle guard
+    from .core import Context
+else:  # pragma: no cover - runtime fallback
+    class Context:  # type: ignore[too-many-ancestors]
+        """Placeholder context type for runtime annotations."""
+
+        pass
+
+RoutingDecisionType: TypeAlias = None | Node | str | Sequence[Node | str]
+
+
+@dataclass(slots=True)
+class RoutingRequest:
+    """Information provided to routing policies."""
+
+    message: Any
+    context: Context
+    node: Node
+    proposed: tuple[Node, ...]
+    trace_id: str | None
+
+    @property
+    def node_name(self) -> str:
+        return self.node.name or self.node.node_id
+
+    @property
+    def proposed_names(self) -> tuple[str, ...]:
+        names: list[str] = []
+        for candidate in self.proposed:
+            names.append(candidate.name or candidate.node_id)
+        return tuple(names)
+
+
+class RoutingPolicy(Protocol):
+    """Protocol for routing policies used by router nodes."""
+
+    def select(
+        self, request: RoutingRequest
+    ) -> RoutingDecisionType | Awaitable[RoutingDecisionType]:
+        """Return the desired routing targets for *request*."""
+
+
+PolicyCallable = Callable[
+    [RoutingRequest], RoutingDecisionType | Awaitable[RoutingDecisionType]
+]
+PolicyLike = RoutingPolicy | PolicyCallable
+
+
+async def evaluate_policy(
+    policy: PolicyLike,
+    request: RoutingRequest,
+) -> RoutingDecisionType:
+    """Evaluate *policy* for the given *request* supporting sync/async returns."""
+
+    if hasattr(policy, "select"):
+        selector = cast(RoutingPolicy, policy).select
+        candidate = selector(request)
+    else:
+        candidate = cast(PolicyCallable, policy)(request)
+
+    if inspect.isawaitable(candidate):
+        return await candidate
+    return candidate
+
+
+KeyFn = Callable[[RoutingRequest], str | None]
+
+
+class DictRoutingPolicy:
+    """Routing policy driven by a mapping loaded from config."""
+
+    def __init__(
+        self,
+        mapping: Mapping[str, RoutingDecisionType],
+        *,
+        default: RoutingDecisionType = None,
+        key_getter: KeyFn | None = None,
+    ) -> None:
+        self._mapping: dict[str, RoutingDecisionType] = dict(mapping)
+        self._default = default
+        self._key_getter = key_getter or (lambda request: request.trace_id)
+
+    def select(self, request: RoutingRequest) -> RoutingDecisionType:
+        key = self._key_getter(request)
+        if key is None:
+            return self._default
+        return self._mapping.get(key, self._default)
+
+    def update_mapping(self, mapping: Mapping[str, RoutingDecisionType]) -> None:
+        self._mapping = dict(mapping)
+
+    def set_default(self, decision: RoutingDecisionType) -> None:
+        self._default = decision
+
+    @classmethod
+    def from_json(cls, payload: str, **kwargs: Any) -> DictRoutingPolicy:
+        data = json.loads(payload)
+        if not isinstance(data, Mapping):
+            raise TypeError("JSON payload must decode to a mapping")
+        return cls(data, **kwargs)
+
+    @classmethod
+    def from_json_file(cls, path: str, **kwargs: Any) -> DictRoutingPolicy:
+        with open(path, encoding="utf-8") as fh:
+            return cls.from_json(fh.read(), **kwargs)
+
+    @classmethod
+    def from_env(
+        cls,
+        env_var: str,
+        *,
+        loader: Callable[[str], Mapping[str, RoutingDecisionType]] | None = None,
+        default: RoutingDecisionType = None,
+        key_getter: KeyFn | None = None,
+    ) -> DictRoutingPolicy:
+        raw = os.getenv(env_var)
+        if raw is None:
+            raise KeyError(f"Environment variable '{env_var}' not set")
+        if loader is None:
+            data = json.loads(raw)
+        else:
+            data = loader(raw)
+        if not isinstance(data, Mapping):
+            raise TypeError("Policy loader must return a mapping")
+        return cls(data, default=default, key_getter=key_getter)
+
+
+__all__ = [
+    "DictRoutingPolicy",
+    "PolicyCallable",
+    "PolicyLike",
+    "RoutingDecisionType",
+    "RoutingPolicy",
+    "RoutingRequest",
+    "evaluate_policy",
+]