agentnorm 0.1.0__py3-none-any.whl

agentnorm/__init__.py

@@ -0,0 +1,40 @@
+"""agentnorm - behavioural monitoring for AI agents.
+
+Agents are unvalidated models running in production. Evaluation grades their outputs
+offline; this watches how they *behave* at runtime and says when a run does not look like
+the ones before it.
+
+    from agentnorm import RunRecorder, Monitor
+
+    rec = RunRecorder(agent="triage", version="v3", principal="acme")
+    with rec.tool_call("search", {"q": q}, scope="acme") as call:
+        rows = search(q)
+        call.result_size = len(rows)
+
+    monitor = Monitor.fit(history)          # benign runs
+    verdict = monitor.score(rec.finish())
+    if verdict.flagged:
+        print(verdict.explain())
+
+Or instrument tools you already have, without restructuring the agent:
+
+    session = Session(agent="triage", version="v3", principal="acme")
+    tools = session.wrap({"search": search, "fetch": fetch})
+    ...
+    verdict = monitor.score(session.finish())
+
+No database, no framework, no context propagation required.
+"""
+from agentnorm.audit import AuditChain, AuditLog, verify_chain
+from agentnorm.detectors import DetectorSuite
+from agentnorm.integrations import Session, default_size_of
+from agentnorm.monitor import Alert, Monitor, Verdict
+from agentnorm.store import JsonlStore, Store
+from agentnorm.trace import Run, RunRecorder, ToolCall
+
+__version__ = "0.1.0"
+__all__ = [
+    "Alert", "AuditChain", "AuditLog", "DetectorSuite", "JsonlStore", "Monitor", "Run",
+    "RunRecorder", "Session", "Store", "ToolCall", "Verdict", "default_size_of",
+    "verify_chain",
+]

agentnorm/adapters/__init__.py

@@ -0,0 +1 @@
+"""Framework adapters. Each has optional dependencies, imported lazily."""

agentnorm/adapters/langchain.py

@@ -0,0 +1,140 @@
+"""LangChain / LangGraph adapter.
+
+LangChain reports tool starts and ends as separate callback events, often interleaved
+across concurrent tools, so the `with` block used elsewhere cannot express them. This
+handler tracks open calls by the framework's `run_id` and closes each one when its
+matching end or error arrives.
+
+**agentnorm does not depend on LangChain.** The base class is imported lazily and only if it
+is installed; without it the handler still works as a plain object, because LangChain
+duck-types handlers in the paths that matter. Keeping the dependency optional is
+deliberate: a monitoring library that drags in an agent framework is unusable by anyone
+running a different one, and half the point of agentnorm is comparing agents across
+frameworks on equal footing.
+
+    from agentnorm import Session
+    from agentnorm.adapters.langchain import agentnorm_callback
+
+    session = Session(agent="researcher", version="v2", principal="acme")
+    graph.invoke(state, config={"callbacks": [agentnorm_callback(session)]})
+
+    verdict = monitor.score(session.finish())
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+from uuid import UUID
+
+from agentnorm.integrations import Session, default_size_of
+from agentnorm.trace import RunRecorder, ToolCall
+
+
+def _base_class() -> type:
+    """LangChain's handler base if available, else `object`."""
+    try:  # pragma: no cover - depends on the host environment
+        from langchain_core.callbacks import BaseCallbackHandler
+
+        return BaseCallbackHandler
+    except Exception:  # noqa: BLE001 - any import failure means "not installed"
+        return object
+
+
+class AgentNormCallbackHandlerMixin:
+    """The recording logic, independent of whether LangChain is installed."""
+
+    # LangChain inspects these on handlers; supplied so a plain object still behaves.
+    raise_error: bool = False
+    run_inline: bool = False
+
+    def __init__(
+        self,
+        recorder: RunRecorder,
+        *,
+        size_of: Callable[[str, dict[str, Any], Any], int] | None = None,
+        scope_of: Callable[[str, dict[str, Any], Any], str | None] | None = None,
+    ) -> None:
+        self._rec = recorder
+        self._size_of = size_of or default_size_of
+        self._scope_of = scope_of
+        self._open: dict[str, ToolCall] = {}
+        self._args: dict[str, dict[str, Any]] = {}
+
+    # --- LangChain callback surface ------------------------------------------
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any] | None,
+        input_str: str,
+        *,
+        run_id: UUID | None = None,
+        inputs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        name = (serialized or {}).get("name") or kwargs.get("name") or "unknown_tool"
+        args = dict(inputs or {}) or {"input": input_str}
+        scope = ""
+        if self._scope_of is not None:
+            scope = self._scope_of(name, args, None) or ""
+        call = self._rec.start_call(name, args, scope=scope)
+        key = str(run_id)
+        self._open[key] = call
+        self._args[key] = args
+
+    def on_tool_end(self, output: Any, *, run_id: UUID | None = None, **kwargs: Any) -> None:
+        key = str(run_id)
+        call = self._open.pop(key, None)
+        if call is None:
+            # An end without a start means the handler was attached mid-run. Dropping it
+            # is correct: a call with no beginning has no duration and no arguments, and
+            # inventing them would corrupt the baseline it feeds.
+            return
+        args = self._args.pop(key, {})
+        size = int(self._size_of(call.tool, args, output))
+        if self._scope_of is not None and not call.scope:
+            call.scope = self._scope_of(call.tool, args, output) or ""
+        self._rec.complete_call(call, ok=True, result_size=size)
+
+    def on_tool_error(
+        self, error: BaseException, *, run_id: UUID | None = None, **kwargs: Any
+    ) -> None:
+        key = str(run_id)
+        call = self._open.pop(key, None)
+        self._args.pop(key, None)
+        if call is None:
+            return
+        self._rec.complete_call(
+            call, ok=False, error=f"{type(error).__name__}: {error}"
+        )
+
+    # --- results --------------------------------------------------------------
+
+    def finish(self):
+        """Close any calls the framework never ended, then return the run.
+
+        An agent killed mid-tool leaves an open call. Recording it as failed is more
+        honest than discarding it — a run that ends inside a tool is itself a signal.
+        """
+        for call in self._open.values():
+            self._rec.complete_call(call, ok=False, error="unterminated: run ended mid-call")
+        self._open.clear()
+        self._args.clear()
+        return self._rec.finish()
+
+
+def agentnorm_callback(
+    target: Session | RunRecorder,
+    *,
+    size_of: Callable[[str, dict[str, Any], Any], int] | None = None,
+    scope_of: Callable[[str, dict[str, Any], Any], str | None] | None = None,
+) -> Any:
+    """Build a LangChain callback handler recording into `target`.
+
+    Accepts a `Session` or a `RunRecorder`; call `.finish()` on whichever you passed.
+    """
+    recorder = target._rec if isinstance(target, Session) else target
+    base = _base_class()
+    handler_cls = type(
+        "AgentNormCallbackHandler", (AgentNormCallbackHandlerMixin, base), {}
+    )
+    return handler_cls(recorder, size_of=size_of, scope_of=scope_of)

agentnorm/audit.py

@@ -0,0 +1,332 @@
+"""Tamper-evident audit trail for agent actions.
+
+The EU AI Act's Article 12 obligations for high-risk systems take effect in August 2026:
+automatic logging of events relevant to traceability, tamper-evident, retained six months
+(twenty-four for biometric and law-enforcement systems), with penalties up to 3% of global
+turnover. What regulators and security teams have converged on needing is the ability to
+say *which agent accessed what data, under whose authority, and to reconstruct it later*.
+
+Behavioural monitoring already sees every one of those facts. It was throwing away the
+evidence.
+
+Records follow the IETF Agent Audit Trail draft (`draft-sharif-agent-audit-trail`), which
+matters for two reasons. Aligning with an emerging standard is a far better position than
+inventing a log format nobody else reads. And the draft has a field, `recording_component`,
+for exactly this situation - an entity that writes records *independently of the agent*,
+for gateways and middleware logging on the agent's behalf. Out-of-band recording is
+anticipated by the standard rather than bolted onto it.
+
+**What tamper-evident does and does not mean here.** Each record carries the SHA-256 of its
+predecessor's canonical form, so altering or removing any record breaks every hash after it
+and the break is detectable. That is integrity, not immutability: someone who can rewrite
+the whole file can recompute the whole chain. Detecting *that* requires anchoring the head
+hash somewhere the writer does not control - a WORM bucket, a countersigning service, a
+transparency log. `chain_head()` exists to be anchored; anchoring it is the deployment's
+job, and this module does not pretend to do it.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from agentnorm.trace import Run, ToolCall
+
+SPEC = "draft-sharif-agent-audit-trail-00"
+
+# Action types from the draft's controlled vocabulary.
+ACTION_TYPES = frozenset(
+    {"tool_call", "tool_response", "decision", "delegation", "escalation", "error", "lifecycle"}
+)
+OUTCOMES = frozenset({"success", "failure", "timeout", "denied", "escalated"})
+
+
+def canonical(record: dict[str, Any]) -> str:
+    """JSON Canonicalization Scheme (RFC 8785), to the extent audit records need it.
+
+    JCS exists so two parties hashing the same record agree on the bytes. Records here
+    contain only strings, integers, booleans, nulls and nested objects and arrays of
+    those - so sorted keys, no insignificant whitespace, and UTF-8 without ASCII escaping
+    is exactly JCS for this domain.
+
+    Floats are deliberately excluded rather than approximated: JCS mandates a specific
+    shortest-round-trip float serialisation, and getting that subtly wrong would produce
+    hashes that verify locally and fail against another implementation - the worst
+    possible failure mode for evidence.
+    """
+    _reject_floats(record)
+    return json.dumps(record, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _reject_floats(value: Any, path: str = "") -> None:
+    if isinstance(value, float):
+        raise TypeError(
+            f"float at {path or 'root'}: audit records must not contain floats, because "
+            "canonical float serialisation differs between implementations and would "
+            "break cross-verification. Encode as a string or an integer."
+        )
+    if isinstance(value, dict):
+        for k, v in value.items():
+            _reject_floats(v, f"{path}.{k}" if path else str(k))
+    elif isinstance(value, (list, tuple)):
+        for i, v in enumerate(value):
+            _reject_floats(v, f"{path}[{i}]")
+
+
+def digest(record: dict[str, Any]) -> str:
+    return hashlib.sha256(canonical(record).encode("utf-8")).hexdigest()
+
+
+@dataclass
+class AuditChain:
+    """Builds a hash-linked sequence of Agent Audit Trail records."""
+
+    recording_component: str = f"agentnorm/{SPEC}"
+    records: list[dict[str, Any]] = field(default_factory=list)
+    _prev_hash: str | None = None
+    _prev_id: str | None = None
+
+    def append(
+        self,
+        *,
+        agent_id: str,
+        agent_version: str,
+        session_id: str,
+        action_type: str,
+        action_detail: dict[str, Any],
+        outcome: str,
+        trust_level: str = "L2",
+        record_phase: str = "post_execution",
+        principal: str | None = None,
+        human_override: dict[str, Any] | None = None,
+        timestamp: datetime | None = None,
+    ) -> dict[str, Any]:
+        if action_type not in ACTION_TYPES:
+            raise ValueError(f"action_type {action_type!r} not in {sorted(ACTION_TYPES)}")
+        if outcome not in OUTCOMES:
+            raise ValueError(f"outcome {outcome!r} not in {sorted(OUTCOMES)}")
+
+        ts = (timestamp or datetime.now(timezone.utc)).astimezone(timezone.utc)
+        record: dict[str, Any] = {
+            "record_id": str(uuid.uuid4()),
+            "timestamp": ts.isoformat().replace("+00:00", "Z"),
+            "agent_id": agent_id,
+            "agent_version": agent_version,
+            "session_id": session_id,
+            "action_type": action_type,
+            "action_detail": action_detail,
+            "outcome": outcome,
+            "trust_level": trust_level,
+            "record_phase": record_phase,
+            "parent_record_id": self._prev_id,
+            "prev_hash": self._prev_hash,
+            "recording_component": self.recording_component,
+        }
+        # "under whose authority" - the regulator's question. Carried on every record
+        # rather than inferred from a session lookup that may not survive retention.
+        if principal:
+            record["principal"] = principal
+        if human_override:
+            record["human_override"] = human_override
+
+        self.records.append(record)
+        self._prev_id = record["record_id"]
+        self._prev_hash = digest(record)
+        return record
+
+    def chain_head(self) -> str | None:
+        """Hash of the latest record. Anchor this externally to detect wholesale rewrites."""
+        return self._prev_hash
+
+    def delegate(
+        self,
+        *,
+        agent_id: str,
+        agent_version: str,
+        session_id: str,
+        delegate_agent_id: str,
+        task_description: str,
+        delegate_trust_level: str = "L2",
+        constraints: list[str] | None = None,
+        principal: str | None = None,
+    ) -> dict[str, Any]:
+        """Record an agent handing work to another agent.
+
+        This is the record that makes a multi-agent chain reconstructable. Without it an
+        action is traceable to a system but not to a decision: four agents across two
+        protocols, none of which logged who asked whom to do what.
+
+        The task is recorded as a hash rather than as text, so the chain proves what was
+        delegated without the audit log becoming a copy of every prompt.
+        """
+        return self.append(
+            agent_id=agent_id,
+            agent_version=agent_version,
+            session_id=session_id,
+            action_type="delegation",
+            action_detail={
+                "delegate_agent_id": delegate_agent_id,
+                "delegate_trust_level": delegate_trust_level,
+                "task_description_hash": hashlib.sha256(
+                    task_description.encode("utf-8")
+                ).hexdigest(),
+                "constraints": constraints or [],
+            },
+            outcome="success",
+            principal=principal,
+        )
+
+
+def _call_detail(call: ToolCall) -> dict[str, Any]:
+    return {
+        "tool_name": call.tool,
+        "step": call.step,
+        "arguments": {k: _scalar(v) for k, v in call.args.items()},
+        "resource": call.resource,
+        "scope": call.scope,
+        "duration_ms": call.duration_ms,
+        "result_size": call.result_size,
+    }
+
+
+def _scalar(value: Any) -> Any:
+    """Audit values are strings, ints, bools or null - floats break canonicalisation."""
+    if isinstance(value, bool) or isinstance(value, int) or value is None:
+        return value
+    if isinstance(value, str):
+        return value[:2000]
+    return str(value)[:2000]
+
+
+def record_run(chain: AuditChain, run: Run, *, trust_level: str = "L2") -> list[dict[str, Any]]:
+    """Emit an audit record per tool call in a run, plus lifecycle bookends."""
+    out = [
+        chain.append(
+            agent_id=f"urn:agent:{run.agent}",
+            agent_version=run.version,
+            session_id=run.run_id,
+            action_type="lifecycle",
+            action_detail={"event": "run_started", "actor_kind": run.actor_kind},
+            outcome="success",
+            trust_level=trust_level,
+            record_phase="pre_execution",
+            principal=run.principal or None,
+            timestamp=run.started_at,
+        )
+    ]
+    for call in run.calls:
+        out.append(
+            chain.append(
+                agent_id=f"urn:agent:{run.agent}",
+                agent_version=run.version,
+                session_id=run.run_id,
+                action_type="tool_call",
+                action_detail=_call_detail(call),
+                outcome="success" if call.ok else "failure",
+                trust_level=trust_level,
+                principal=run.principal or None,
+                timestamp=call.started_at,
+            )
+        )
+    out.append(
+        chain.append(
+            agent_id=f"urn:agent:{run.agent}",
+            agent_version=run.version,
+            session_id=run.run_id,
+            action_type="lifecycle",
+            action_detail={"event": "run_finished", "calls": run.n_calls},
+            outcome="success",
+            trust_level=trust_level,
+            principal=run.principal or None,
+        )
+    )
+    return out
+
+
+@dataclass
+class VerificationResult:
+    ok: bool
+    records: int
+    first_broken_index: int | None = None
+    reason: str = ""
+
+    def __str__(self) -> str:
+        if self.ok:
+            return f"chain intact: {self.records} records verified"
+        return f"chain BROKEN at record {self.first_broken_index}: {self.reason}"
+
+
+def verify_chain(records: Iterable[dict[str, Any]]) -> VerificationResult:
+    """Recompute the chain and report the first record that does not agree.
+
+    Reporting *where* the chain breaks matters more than a boolean: the break points at
+    the earliest record that was altered or removed, which is the first thing an
+    investigator needs.
+    """
+    prev_hash: str | None = None
+    prev_id: str | None = None
+    count = 0
+
+    for i, record in enumerate(records):
+        count += 1
+        if record.get("prev_hash") != prev_hash:
+            return VerificationResult(
+                False, count, i,
+                f"prev_hash mismatch (expected {prev_hash!r}, found {record.get('prev_hash')!r})",
+            )
+        if record.get("parent_record_id") != prev_id:
+            return VerificationResult(
+                False, count, i, "parent_record_id does not match the preceding record"
+            )
+        try:
+            prev_hash = digest(record)
+        except TypeError as exc:
+            return VerificationResult(False, count, i, str(exc))
+        prev_id = record.get("record_id")
+
+    return VerificationResult(True, count)
+
+
+class AuditLog:
+    """Append-only audit log on disk, one JSON record per line."""
+
+    def __init__(self, path: str | Path, recording_component: str | None = None) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.chain = AuditChain(
+            recording_component=recording_component or f"agentnorm/{SPEC}"
+        )
+        # Resume an existing chain so restarts do not silently start a second one, which
+        # would verify cleanly on its own and hide the discontinuity.
+        existing = list(self.read())
+        if existing:
+            self.chain.records = existing
+            self.chain._prev_id = existing[-1].get("record_id")
+            self.chain._prev_hash = digest(existing[-1])
+
+    def write_run(self, run: Run, *, trust_level: str = "L2") -> int:
+        records = record_run(self.chain, run, trust_level=trust_level)
+        with self.path.open("a", encoding="utf-8") as fh:
+            for record in records:
+                fh.write(canonical(record) + "\n")
+        return len(records)
+
+    def read(self) -> Iterator[dict[str, Any]]:
+        if not self.path.is_file():
+            return
+        with self.path.open(encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if line:
+                    yield json.loads(line)
+
+    def verify(self) -> VerificationResult:
+        return verify_chain(self.read())
+
+    def chain_head(self) -> str | None:
+        return self.chain.chain_head()