agentrust-telemetry 0.1.0a3__py3-none-any.whl

agentrust_telemetry/__init__.py

@@ -0,0 +1,80 @@
+"""AgentTrust governance telemetry reference SDK."""
+
+from .adapters import (
+    AgtGovernanceEventSink,
+    EventFactory,
+    agt_approval_request,
+    agt_approval_resolution,
+    agt_audit_action,
+    agt_audit_policy_decision,
+    agt_data_access_flow,
+    agt_data_classification,
+    agt_policy_decision,
+    agt_policy_decision_record,
+    cedar_policy_decision,
+    opa_decision_log,
+)
+from .client import EmitResult, TelemetryClient
+from .data_flow import ClassificationResult, DataClassifier, DataEndpoint, classified_data_flow
+from .context import ContextIds, active_context_ids
+from .errors import (
+    ContextMismatchError,
+    EventValidationError,
+    EvidenceError,
+    EvidencePersistenceError,
+    ProjectionError,
+    PropagationError,
+    TraceFinalizationError,
+)
+from .evidence import EvidenceAccumulator, EvidenceEntry, EvidenceSnapshot
+from .propagation import ExtractedContext, extract_context, inject_context
+from .otel import OTelLogEmitter, OTelMetricEmitter
+from .trace_adapter import TraceConfiguration, finalize_trace
+from .usage import CostObservation, UsageAccumulator, usage_record
+from .validation import SchemaValidator
+
+__all__ = [
+    "ContextIds",
+    "ContextMismatchError",
+    "CostObservation",
+    "ClassificationResult",
+    "DataClassifier",
+    "DataEndpoint",
+    "AgtGovernanceEventSink",
+    "EmitResult",
+    "EventValidationError",
+    "EventFactory",
+    "EvidenceAccumulator",
+    "EvidenceEntry",
+    "EvidenceError",
+    "EvidencePersistenceError",
+    "EvidenceSnapshot",
+    "ExtractedContext",
+    "ProjectionError",
+    "OTelLogEmitter",
+    "OTelMetricEmitter",
+    "PropagationError",
+    "SchemaValidator",
+    "TelemetryClient",
+    "TraceConfiguration",
+    "TraceFinalizationError",
+    "UsageAccumulator",
+    "active_context_ids",
+    "agt_approval_request",
+    "agt_approval_resolution",
+    "agt_audit_action",
+    "agt_audit_policy_decision",
+    "agt_data_access_flow",
+    "agt_data_classification",
+    "agt_policy_decision",
+    "agt_policy_decision_record",
+    "cedar_policy_decision",
+    "classified_data_flow",
+    "extract_context",
+    "inject_context",
+    "opa_decision_log",
+    "usage_record",
+    "finalize_trace",
+]
+
+__version__ = "0.1.0a3"

agentrust_telemetry/adapters/__init__.py

@@ -0,0 +1,28 @@
+"""Source adapters for normalized AgentTrust telemetry events."""
+
+from .base import EventFactory
+from .agt import AgtGovernanceEventSink, agt_policy_decision
+from .agt_approval import (
+    agt_approval_request,
+    agt_approval_resolution,
+    agt_policy_decision_record,
+)
+from .agt_audit import agt_audit_action, agt_audit_policy_decision
+from .agt_data import agt_data_access_flow, agt_data_classification
+from .cedar import cedar_policy_decision
+from .opa import opa_decision_log
+
+__all__ = [
+    "AgtGovernanceEventSink",
+    "EventFactory",
+    "agt_policy_decision",
+    "agt_policy_decision_record",
+    "agt_approval_request",
+    "agt_approval_resolution",
+    "agt_audit_action",
+    "agt_audit_policy_decision",
+    "agt_data_access_flow",
+    "agt_data_classification",
+    "cedar_policy_decision",
+    "opa_decision_log",
+]

agentrust_telemetry/adapters/agt.py

@@ -0,0 +1,207 @@
+"""Optional bridge from AGT governance events to AgentTrust telemetry."""
+
+from __future__ import annotations
+
+import math
+import re
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Callable, Iterable, Protocol, Sequence
+
+from .base import EventFactory
+
+
+_IDENTIFIER = re.compile(r"[A-Za-z0-9_.:-]{1,128}")
+_TIMESTAMP = re.compile(
+    r"^(?P<date>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(?P<fraction>\d{1,9}))?(?:Z|\+00:00)$"
+)
+
+
+class TelemetryEmitter(Protocol):
+    def emit(self, event: dict[str, Any]) -> Any: ...
+
+
+AgtEventMapper = Callable[[Any], Iterable[dict[str, Any]]]
+
+
+class AgtGovernanceEventSink:
+    """AGT-compatible batch sink without a mandatory AGT dependency.
+
+    Construct directly with the source runtime's result sentinels, or use
+    :meth:`from_agent_os` when ``agent-os`` is installed.
+    """
+
+    def __init__(
+        self,
+        client: TelemetryEmitter,
+        mapper: AgtEventMapper,
+        *,
+        success_result: Any,
+        failure_result: Any,
+    ) -> None:
+        self._client = client
+        self._mapper = mapper
+        self._success = success_result
+        self._failure = failure_result
+
+    @classmethod
+    def from_agent_os(
+        cls,
+        client: TelemetryEmitter,
+        mapper: AgtEventMapper,
+    ) -> "AgtGovernanceEventSink":
+        try:
+            from agent_os.event_sink import SinkExportResult
+        except ImportError as exc:
+            raise ImportError(
+                "AgtGovernanceEventSink.from_agent_os requires the agent-os package"
+            ) from exc
+        return cls(
+            client,
+            mapper,
+            success_result=SinkExportResult.SUCCESS,
+            failure_result=SinkExportResult.FAILURE,
+        )
+
+    def emit(self, events: Sequence[Any]) -> Any:
+        """Normalize then emit a batch, returning the configured AGT result."""
+        try:
+            normalized = [item for source in events for item in self._mapper(source)]
+            for event in normalized:
+                result = self._client.emit(event)
+                if not getattr(result, "accepted", False):
+                    return self._failure
+                if getattr(result, "projection_errors", ()):
+                    return self._failure
+            return self._success
+        except Exception:
+            return self._failure
+
+    def shutdown(self, timeout_ms: int = 5000) -> bool:
+        return True
+
+    def force_flush(self, timeout_ms: int = 30000) -> bool:
+        return True
+
+
+def agt_policy_decision(
+    factory: EventFactory,
+    source: Any,
+    *,
+    run_id: str,
+    policy_engine_version: str,
+    bundle_digest: dict[str, str],
+    resource_type: str | None = None,
+    enforcement_mode: str = "enforce",
+) -> dict[str, Any]:
+    """Normalize one AGT policy event without copying free-form source content."""
+    kind = _enum_value(_field(source, "kind"))
+    if kind not in {"policy_check", "policy_violation"}:
+        raise ValueError(f"AGT event kind is not a policy decision: {kind!r}")
+    decision = _decision(_field(source, "decision"))
+    agent_id = _required_string(_field(source, "agent_id"), "agent_id")
+    action_type = _required_string(_field(source, "action"), "action")
+    attributes = _field(source, "attributes", {})
+    if not isinstance(attributes, dict):
+        raise ValueError("AGT attributes must be an object")
+    resolved_resource_type = resource_type or attributes.get("resource_type")
+    resolved_resource_type = _required_string(resolved_resource_type, "resource_type")
+    event_id = _event_id(_field(source, "event_id"))
+    reason_codes = _reason_codes(attributes.get("reason_codes", []))
+    latency_ms = _field(source, "latency_ms", 0.0)
+    if (
+        not isinstance(latency_ms, (int, float))
+        or isinstance(latency_ms, bool)
+        or not math.isfinite(latency_ms)
+        or latency_ms < 0
+    ):
+        raise ValueError("AGT latency_ms must be a finite non-negative number")
+    policy: dict[str, Any] = {
+        "engine": "agt",
+        "engine_version": _required_string(policy_engine_version, "policy_engine_version"),
+        "bundle_digest": bundle_digest,
+    }
+    policy_name = _field(source, "policy_name")
+    if policy_name is not None:
+        policy["policy_id"] = _required_string(policy_name, "policy_name")
+    return factory.build(
+        "policy.decision",
+        run_id=run_id,
+        agent_id=agent_id,
+        event_id=event_id,
+        time_unix_nano=_timestamp_ns(_field(source, "occurred_at")),
+        trace_id=_field(source, "trace_id"),
+        span_id=_field(source, "span_id"),
+        decision=decision,
+        policy=policy,
+        action_type=action_type,
+        resource_type=resolved_resource_type,
+        enforcement_mode=enforcement_mode,
+        evaluation_duration_ns=round(latency_ms * 1_000_000),
+        reason_codes=reason_codes,
+    )
+
+
+def _field(source: Any, name: str, default: Any = None) -> Any:
+    if isinstance(source, dict):
+        return source.get(name, default)
+    return getattr(source, name, default)
+
+
+def _enum_value(value: Any) -> Any:
+    return value.value if isinstance(value, Enum) else value
+
+
+def _decision(value: Any) -> str:
+    normalized = _enum_value(value)
+    mapping = {
+        "allow": "allow",
+        "allowed": "allow",
+        "deny": "deny",
+        "denied": "deny",
+        "block": "deny",
+        "blocked": "deny",
+        "require_approval": "challenge",
+        "requires_approval": "challenge",
+        "review": "challenge",
+    }
+    if normalized not in mapping:
+        raise ValueError(f"unsupported AGT policy decision: {normalized!r}")
+    return mapping[normalized]
+
+
+def _required_string(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"AGT {field} must be a non-empty string")
+    return value
+
+
+def _reason_codes(values: Any) -> list[str]:
+    if not isinstance(values, list):
+        raise ValueError("AGT reason_codes must be an array")
+    if len(values) > 32 or any(
+        not isinstance(value, str) or _IDENTIFIER.fullmatch(value) is None
+        for value in values
+    ):
+        raise ValueError("AGT reason_codes must contain at most 32 identifiers")
+    if len(values) != len(set(values)):
+        raise ValueError("AGT reason_codes must be unique")
+    return list(values)
+
+
+def _event_id(value: Any) -> str:
+    try:
+        return str(uuid.UUID(_required_string(value, "event_id")))
+    except (ValueError, AttributeError) as exc:
+        raise ValueError("AGT event_id must be a UUID") from exc
+
+
+def _timestamp_ns(value: Any) -> int:
+    value = _required_string(value, "occurred_at")
+    match = _TIMESTAMP.fullmatch(value)
+    if match is None:
+        raise ValueError("AGT occurred_at must be an RFC 3339 UTC timestamp")
+    base = datetime.fromisoformat(match.group("date")).replace(tzinfo=timezone.utc)
+    fraction = (match.group("fraction") or "").ljust(9, "0")
+    return int(base.timestamp()) * 1_000_000_000 + int(fraction or "0")

agentrust_telemetry/adapters/agt_approval.py

@@ -0,0 +1,235 @@
+"""Adapters for AGT's action-bound approval protocol objects."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from .base import EventFactory
+
+
+_SOURCE_NAMESPACE = uuid.UUID("ea5a1737-5417-4eaa-8bb0-4fc40e4cb837")
+_DIGEST = re.compile(r"^(?P<algorithm>sha256):(?P<value>[0-9a-f]{64})$")
+
+
+def agt_policy_decision_record(
+    factory: EventFactory,
+    source: Any,
+    *,
+    run_id: str,
+    agent_id: str,
+    action_type: str,
+    resource_type: str,
+    policy_engine_version: str,
+    bundle_digest: dict[str, str],
+    evaluation_duration_ns: int = 0,
+    enforcement_mode: str = "enforce",
+    trace_id: str | None = None,
+    span_id: str | None = None,
+) -> dict[str, Any]:
+    """Map an AGT PolicyDecisionRecord that suspended for approval."""
+    verdict = _enum_value(_field(source, "verdict"))
+    if verdict != "require_approval":
+        raise ValueError("AGT PolicyDecisionRecord verdict must be require_approval")
+    source_id = _required_string(_field(source, "policy_decision_id"), "policy_decision_id")
+    return factory.build(
+        "policy.decision",
+        run_id=run_id,
+        agent_id=agent_id,
+        event_id=_source_event_id("policy", source_id),
+        time_unix_nano=_datetime_ns(_field(source, "decided_at"), "decided_at"),
+        trace_id=trace_id,
+        span_id=span_id,
+        decision="challenge",
+        policy={
+            "engine": "agt",
+            "engine_version": policy_engine_version,
+            "policy_id": _required_string(_field(source, "policy_rule_id"), "policy_rule_id"),
+            "bundle_digest": bundle_digest,
+        },
+        action_type=action_type,
+        resource_type=resource_type,
+        enforcement_mode=enforcement_mode,
+        evaluation_duration_ns=evaluation_duration_ns,
+        reason_codes=["agt.verdict:require_approval"],
+    )
+
+
+def agt_approval_request(
+    factory: EventFactory,
+    source: Any,
+    policy_decision: Any,
+    *,
+    run_id: str,
+    trace_id: str | None = None,
+    span_id: str | None = None,
+) -> dict[str, Any]:
+    """Map an AGT ApprovalRequest while preserving its policy and chain links."""
+    _verify_request_binding(source, policy_decision)
+    approval_id = _required_string(_field(source, "approval_request_id"), "approval_request_id")
+    policy_id = _required_string(_field(source, "policy_decision_id"), "policy_decision_id")
+    return factory.build(
+        "approval.requested",
+        run_id=run_id,
+        agent_id=_required_string(_field(source, "agent_id"), "agent_id"),
+        event_id=_source_event_id("approval.requested", approval_id),
+        time_unix_nano=_datetime_ns(_field(source, "requested_at"), "requested_at"),
+        trace_id=trace_id,
+        span_id=span_id,
+        approval_id=approval_id,
+        policy_event_id=_source_event_id("policy", policy_id),
+        chain_id=_required_string(_field(source, "approval_chain_id"), "approval_chain_id"),
+        chain_version=_required_string(
+            _field(source, "approval_chain_version"), "approval_chain_version"
+        ),
+        action_digest=_digest(_field(source, "action_digest"), "action_digest"),
+        actor_type="policy",
+        requested_at_unix_nano=_datetime_ns(_field(source, "requested_at"), "requested_at"),
+        expires_at_unix_nano=_datetime_ns(_field(source, "expires_at"), "expires_at"),
+        reason_codes=["agt.approval:requested"],
+    )
+
+
+def agt_approval_resolution(
+    factory: EventFactory,
+    resolution: Any,
+    request: Any,
+    *,
+    run_id: str,
+    trace_id: str | None = None,
+    span_id: str | None = None,
+) -> dict[str, Any]:
+    """Map a terminal AGT resolution after verifying its request binding."""
+    _verify_resolution_binding(resolution, request)
+    outcome = _enum_value(_field(resolution, "outcome"))
+    event_type = {
+        "allow": "approval.approved",
+        "deny": "approval.rejected",
+        "expired": "approval.expired",
+    }.get(outcome)
+    if event_type is None:
+        raise ValueError(f"unsupported AGT approval outcome: {outcome!r}")
+    approval_id = _required_string(
+        _field(resolution, "approval_request_id"), "approval_request_id"
+    )
+    resolved_at = _datetime_ns(_field(resolution, "resolved_at"), "resolved_at")
+    requested_at = _datetime_ns(_field(request, "requested_at"), "requested_at")
+    if resolved_at < requested_at:
+        raise ValueError("AGT approval resolution cannot predate its request")
+    final_digest = _field(resolution, "final_entry_digest")
+    optional_evidence = (
+        {"approval_evidence_digest": _digest(final_digest, "final_entry_digest")}
+        if final_digest is not None
+        else {}
+    )
+    policy_id = _required_string(_field(request, "policy_decision_id"), "policy_decision_id")
+    resolution_id = _required_string(
+        _field(resolution, "approval_resolution_id"), "approval_resolution_id"
+    )
+    return factory.build(
+        event_type,
+        run_id=run_id,
+        agent_id=_required_string(_field(request, "agent_id"), "agent_id"),
+        event_id=_source_event_id("approval.resolution", resolution_id),
+        time_unix_nano=resolved_at,
+        trace_id=trace_id,
+        span_id=span_id,
+        approval_id=approval_id,
+        policy_event_id=_source_event_id("policy", policy_id),
+        chain_id=_required_string(_field(request, "approval_chain_id"), "approval_chain_id"),
+        chain_version=_required_string(
+            _field(request, "approval_chain_version"), "approval_chain_version"
+        ),
+        resolution_id=resolution_id,
+        action_digest=_digest(_field(resolution, "action_digest"), "action_digest"),
+        actor_type="system",
+        requested_at_unix_nano=requested_at,
+        expires_at_unix_nano=_datetime_ns(_field(request, "expires_at"), "expires_at"),
+        reason_codes=[f"agt.outcome:{outcome}"],
+        **optional_evidence,
+    )
+
+
+def _verify_resolution_binding(resolution: Any, request: Any) -> None:
+    pairs = (
+        ("approval_request_id", "approval_request_id"),
+        ("action_digest", "action_digest"),
+        ("policy_version", "policy_version"),
+        ("approval_chain_version", "approval_chain_version"),
+    )
+    for resolution_field, request_field in pairs:
+        left = _required_string(
+            _enum_value(_field(resolution, resolution_field)), resolution_field
+        )
+        right = _required_string(
+            _enum_value(_field(request, request_field)), request_field
+        )
+        if left != right:
+            raise ValueError(
+                f"AGT resolution {resolution_field} does not match request {request_field}"
+            )
+
+
+def _verify_request_binding(request: Any, policy_decision: Any) -> None:
+    pairs = (
+        ("policy_decision_id", "policy_decision_id"),
+        ("action_digest", "action_digest"),
+        ("policy_version", "policy_version"),
+        ("approval_chain_id", "approval_chain_id"),
+        ("approval_chain_version", "approval_chain_version"),
+    )
+    for request_field, policy_field in pairs:
+        left = _required_string(
+            _enum_value(_field(request, request_field)), request_field
+        )
+        right = _required_string(
+            _enum_value(_field(policy_decision, policy_field)), policy_field
+        )
+        if left != right:
+            raise ValueError(
+                f"AGT request {request_field} does not match policy decision {policy_field}"
+            )
+
+
+def _source_event_id(kind: str, source_id: str) -> str:
+    return str(uuid.uuid5(_SOURCE_NAMESPACE, f"{kind}:{source_id}"))
+
+
+def _field(source: Any, name: str) -> Any:
+    if isinstance(source, dict):
+        return source.get(name)
+    return getattr(source, name, None)
+
+
+def _enum_value(value: Any) -> Any:
+    return value.value if isinstance(value, Enum) else value
+
+
+def _required_string(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"AGT {field} must be a non-empty string")
+    return value
+
+
+def _digest(value: Any, field: str) -> dict[str, str]:
+    value = _required_string(value, field)
+    match = _DIGEST.fullmatch(value)
+    if match is None:
+        raise ValueError(f"AGT {field} must use sha256:<lowercase-hex>")
+    return match.groupdict()
+
+
+def _datetime_ns(value: Any, field: str) -> int:
+    if not isinstance(value, datetime) or value.tzinfo is None:
+        raise ValueError(f"AGT {field} must be a timezone-aware datetime")
+    utc = value.astimezone(timezone.utc)
+    epoch = datetime(1970, 1, 1, tzinfo=timezone.utc)
+    delta = utc - epoch
+    return (
+        delta.days * 86_400_000_000_000
+        + delta.seconds * 1_000_000_000
+        + delta.microseconds * 1_000
+    )