agentloop-profiler 0.1.0__py3-none-any.whl

agentloop/integrations/harbor/verifier.py

@@ -0,0 +1,118 @@
+"""External reward preservation and explicit, hashed acceptance criteria."""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Any
+
+from agentloop.interoperability.contracts import _validate_quality
+from agentloop.interoperability.validation import ImportValidationError, validate_json_tree
+from agentloop.interventions import canonical_json
+
+
+def _fail(field: str, reason: str) -> None:
+    raise ImportValidationError("invalid_verifier", field, reason)
+
+
+def reward_dimensions(value: Any) -> dict[str, int | float | None] | None:
+    if value is None:
+        return None
+    validate_json_tree(value)
+    if not isinstance(value, dict):
+        _fail("rewards", "reward dimensions must be an object or null")
+    for key, number in value.items():
+        if not isinstance(key, str) or not key.strip() or len(key.encode()) > 512:
+            _fail("rewards", "reward names must be bounded strings")
+        if number is not None and (type(number) not in {int, float} or not math.isfinite(number)):
+            _fail("rewards", "rewards must be finite numbers or null")
+    return dict(value)
+
+
+@dataclass(frozen=True)
+class ScoringContract:
+    _json: str
+
+    def to_dict(self) -> dict:
+        return json.loads(self._json)
+
+    @classmethod
+    def from_dict(cls, value: dict) -> ScoringContract:
+        validate_json_tree(value)
+        if not isinstance(value, dict) or set(value) - {
+            "schema_version",
+            "scorer_id",
+            "rule",
+            "thresholds",
+            "config_sha256",
+        }:
+            _fail("scoring", "unsupported scoring fields")
+        required = {"schema_version", "scorer_id", "rule", "thresholds"}
+        if not required <= set(value):
+            _fail("scoring", "versioned scorer identity, rule and thresholds are required")
+        config = {key: value[key] for key in required}
+        digest = sha256(canonical_json(config).encode()).hexdigest()
+        if value.get("config_sha256", digest) != digest:
+            _fail("scoring.config_sha256", "scoring hash does not match its definition")
+        config["config_sha256"] = digest
+        # Reuse the frozen receipt contract, including boolean/nonfinite rejection.
+        _validate_quality(
+            {
+                "execution_status": "unknown",
+                "verifier_status": "missing",
+                "verifier_dimensions": {},
+                "quality_pass": None,  # nosec B105
+                "quality_basis": "configured_thresholds",
+                "scoring_contract": config,
+                "verifier_isolation": "unknown",
+            }
+        )
+        return cls(canonical_json(config))
+
+    @classmethod
+    def all_gte(cls, scorer_id: str, thresholds: dict[str, float]) -> ScoringContract:
+        return cls.from_dict(
+            {
+                "schema_version": "1.0",
+                "scorer_id": scorer_id,
+                "rule": "all_gte",
+                "thresholds": thresholds,
+            }
+        )
+
+
+def external_outcome(
+    *,
+    execution_status: str,
+    verifier_status: str,
+    dimensions: dict | None,
+    isolation: str = "unknown",
+    scoring: ScoringContract | None = None,
+) -> dict:
+    rewards = reward_dimensions(dimensions)
+    config = scoring.to_dict() if scoring is not None else None
+    passed = None
+    if (
+        config is not None
+        and verifier_status == "available"
+        and rewards is not None
+        and all(rewards.get(key) is not None for key in config["thresholds"])
+    ):
+        passed = all(rewards[key] >= threshold for key, threshold in config["thresholds"].items())
+    result = {
+        "execution_status": execution_status,
+        "verifier_status": verifier_status,
+        "verifier_dimensions": rewards if rewards is not None else {},
+        "quality_pass": passed,
+        "quality_basis": "configured_thresholds"
+        if config is not None
+        else "external_uninterpreted_reward"
+        if verifier_status == "available" and rewards
+        else "unavailable",
+        "scoring_contract": config,
+        "verifier_isolation": isolation,
+    }
+    _validate_quality(result)
+    return result

agentloop/integrations/langgraph.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from functools import wraps
+from typing import Any, TypeVar
+
+from agentloop import trace_agent, trace_tool_call
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _merge_metadata(
+    metadata: dict[str, Any] | None, extra: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    merged = {"integration": "langgraph"}
+    if metadata:
+        merged.update(metadata)
+    if extra:
+        merged.update(extra)
+    return merged
+
+
+def trace_node(name: str | None = None, metadata: dict[str, Any] | None = None) -> Callable[[F], F]:
+    """Wrap a LangGraph node function as an AgentLoop node span.
+
+    This is dependency-free: it works for normal callables, async callables, or
+    LangGraph node functions without importing LangGraph inside AgentLoop.
+    """
+
+    def decorator(fn: F) -> F:
+        step_name = name or getattr(fn, "__name__", "langgraph_node")
+        step_metadata = _merge_metadata(metadata, {"node_name": step_name})
+
+        if inspect.iscoroutinefunction(fn):
+
+            @wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                with trace_tool_call(step_name, metadata=step_metadata):
+                    return await fn(*args, **kwargs)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            with trace_tool_call(step_name, metadata=step_metadata):
+                return fn(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def instrument_state_graph(graph: Any, metadata: dict[str, Any] | None = None) -> Any:
+    """Monkey-patch a LangGraph StateGraph-like builder so add_node auto-wraps nodes.
+
+    Usage:
+        builder = StateGraph(State)
+        instrument_state_graph(builder)
+        builder.add_node("retrieve", retrieve_fn)  # automatically traced
+
+    The function intentionally accepts `Any` so AgentLoop does not need LangGraph
+    as a dependency. It expects the object to expose an `add_node(name, action, ...)`
+    method and an empty `nodes` mapping or sequence. Call this before adding any
+    nodes; late instrumentation raises instead of silently producing partial traces.
+    """
+
+    if getattr(graph, "_agentloop_instrumented", False):
+        return graph
+    original_add_node = getattr(graph, "add_node", None)
+    if original_add_node is None or not callable(original_add_node):
+        raise TypeError("Expected a LangGraph-like object with callable add_node(...).")
+    nodes = getattr(graph, "nodes", None)
+    if not isinstance(nodes, Mapping | Sequence) or isinstance(nodes, str | bytes | bytearray):
+        raise TypeError("Expected a LangGraph-like builder with a nodes mapping or sequence.")
+    if nodes:
+        raise ValueError(
+            "Call instrument_state_graph() before add_node(); this builder already contains "
+            "nodes. Create a new builder and instrument it before adding nodes, or wrap node "
+            "functions with trace_node() explicitly before registering them."
+        )
+
+    @wraps(original_add_node)
+    def add_node(name: str, action: Any = None, *args: Any, **kwargs: Any) -> Any:
+        wrapped_action = action
+        if callable(action):
+            wrapped_action = trace_node(
+                str(name), _merge_metadata(metadata, {"auto_instrumented": True})
+            )(action)
+        return original_add_node(name, wrapped_action, *args, **kwargs)
+
+    setattr(graph, "add_node", add_node)
+    setattr(graph, "_agentloop_instrumented", True)
+    return graph
+
+
+class TracedRunnable:
+    """Small wrapper for compiled LangGraph apps/runnables.
+
+    It creates an AgentLoop trace around `.invoke(...)`, `.ainvoke(...)`, `.stream(...)`,
+    and `.astream(...)` while delegating every other attribute to the wrapped app.
+    """
+
+    def __init__(
+        self, app: Any, name: str = "langgraph_app", metadata: dict[str, Any] | None = None
+    ):
+        self.app = app
+        self.name = name
+        self.metadata = _merge_metadata(metadata, {"runnable": True})
+        self.last_trace = None
+
+    def __getattr__(self, item: str) -> Any:
+        return getattr(self.app, item)
+
+    def invoke(self, *args: Any, **kwargs: Any) -> Any:
+        with trace_agent(self.name, metadata=self.metadata) as trace:
+            result = self.app.invoke(*args, **kwargs)
+        self.last_trace = trace
+        return result
+
+    async def ainvoke(self, *args: Any, **kwargs: Any) -> Any:
+        with trace_agent(self.name, metadata=self.metadata) as trace:
+            result = await self.app.ainvoke(*args, **kwargs)
+        self.last_trace = trace
+        return result
+
+    def stream(self, *args: Any, **kwargs: Any) -> Any:
+        with trace_agent(self.name, metadata=self.metadata) as trace:
+            for item in self.app.stream(*args, **kwargs):
+                yield item
+        self.last_trace = trace
+
+    async def astream(self, *args: Any, **kwargs: Any) -> Any:
+        with trace_agent(self.name, metadata=self.metadata) as trace:
+            async for item in self.app.astream(*args, **kwargs):
+                yield item
+        self.last_trace = trace
+
+    def export_last_trace(self, path: str) -> None:
+        if self.last_trace is None:
+            raise RuntimeError("No trace recorded yet. Call invoke/ainvoke/stream/astream first.")
+        self.last_trace.export_json(path)
+
+
+def trace_runnable(
+    app: Any, name: str = "langgraph_app", metadata: dict[str, Any] | None = None
+) -> TracedRunnable:
+    """Wrap a compiled LangGraph app/runnable with AgentLoop tracing."""
+
+    return TracedRunnable(app=app, name=name, metadata=metadata)