agentrust-telemetry 0.1.0a3__py3-none-any.whl

agentrust_telemetry/adapters/agt_audit.py

@@ -0,0 +1,177 @@
+"""Strict adapters for Agent Mesh audit entries shipped by AGT core."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from .base import EventFactory
+
+
+_AUDIT_NAMESPACE = uuid.UUID("398428fd-2730-498f-8ed8-6b4290668171")
+_POLICY_EVENTS = {"policy_evaluation", "policy_violation"}
+_ACTION_EVENTS = {"tool_invocation", "tool_blocked", "action"}
+
+
+def agt_audit_policy_decision(
+    factory: EventFactory,
+    source: Any,
+    *,
+    run_id: str,
+    policy_engine_version: str,
+    bundle_digest: dict[str, str],
+    resource_type: str,
+    evaluation_duration_ns: int = 0,
+    enforcement_mode: str = "enforce",
+) -> dict[str, Any]:
+    """Map a policy-oriented Agent Mesh AuditEntry without copying its data."""
+    event_type = _required_string(_field(source, "event_type"), "event_type")
+    if event_type not in _POLICY_EVENTS:
+        raise ValueError(f"AGT audit event is not a policy event: {event_type!r}")
+    decision = _policy_decision(_field(source, "policy_decision"))
+    entry_id = _required_string(_field(source, "entry_id"), "entry_id")
+    policy: dict[str, Any] = {
+        "engine": "agt",
+        "engine_version": _required_string(policy_engine_version, "policy_engine_version"),
+        "bundle_digest": bundle_digest,
+    }
+    matched_rule = _field(source, "matched_rule")
+    if matched_rule is not None:
+        policy["policy_id"] = _required_string(matched_rule, "matched_rule")
+    return factory.build(
+        "policy.decision",
+        run_id=run_id,
+        agent_id=_required_string(_field(source, "agent_did"), "agent_did"),
+        event_id=_source_event_id("policy", entry_id),
+        time_unix_nano=_datetime_ns(_field(source, "timestamp"), "timestamp"),
+        trace_id=_optional_string(_field(source, "trace_id"), "trace_id"),
+        decision=decision,
+        policy=policy,
+        action_type=_required_string(_field(source, "action"), "action"),
+        resource_type=_required_string(resource_type, "resource_type"),
+        enforcement_mode=enforcement_mode,
+        evaluation_duration_ns=evaluation_duration_ns,
+        reason_codes=[f"agt.audit:{event_type}"],
+    )
+
+
+def agt_audit_action(
+    factory: EventFactory,
+    source: Any,
+    *,
+    run_id: str,
+    action_digest: dict[str, str],
+    action_kind: str,
+    operation: str,
+    duration_ns: int | None = None,
+) -> dict[str, Any]:
+    """Map an action audit row using a caller-computed full action digest."""
+    event_type = _required_string(_field(source, "event_type"), "event_type")
+    if event_type not in _ACTION_EVENTS:
+        raise ValueError(f"AGT audit event is not an action event: {event_type!r}")
+    entry_id = _required_string(_field(source, "entry_id"), "entry_id")
+    outcome = "denied" if event_type == "tool_blocked" else _action_outcome(
+        _field(source, "outcome")
+    )
+    resolved_duration = duration_ns
+    if resolved_duration is None:
+        resolved_duration = _audit_duration(source)
+    target: dict[str, str] | None = None
+    target_did = _field(source, "target_did")
+    if target_did is not None:
+        target = {"kind": "agent", "id": _required_string(target_did, "target_did")}
+    return factory.build(
+        "action.executed",
+        run_id=run_id,
+        agent_id=_required_string(_field(source, "agent_did"), "agent_did"),
+        event_id=_source_event_id("action", entry_id),
+        time_unix_nano=_datetime_ns(_field(source, "timestamp"), "timestamp"),
+        trace_id=_optional_string(_field(source, "trace_id"), "trace_id"),
+        action_id=entry_id,
+        action_kind=action_kind,
+        action_name=_required_string(_field(source, "action"), "action"),
+        operation=_required_string(operation, "operation"),
+        outcome=outcome,
+        duration_ns=resolved_duration,
+        action_digest=action_digest,
+        **({"target": target} if target else {}),
+    )
+
+
+def _policy_decision(value: Any) -> str:
+    mapping = {
+        "allow": "allow",
+        "allowed": "allow",
+        "deny": "deny",
+        "denied": "deny",
+        "require_approval": "challenge",
+        "requires_approval": "challenge",
+        "review": "challenge",
+        "not_applicable": "not_applicable",
+        "error": "error",
+    }
+    if value not in mapping:
+        raise ValueError(f"unsupported AGT audit policy decision: {value!r}")
+    return mapping[value]
+
+
+def _action_outcome(value: Any) -> str:
+    mapping = {
+        "success": "success",
+        "failure": "error",
+        "error": "error",
+        "denied": "denied",
+        "cancelled": "cancelled",
+        "timeout": "timeout",
+    }
+    if value not in mapping:
+        raise ValueError(f"unsupported AGT audit action outcome: {value!r}")
+    return mapping[value]
+
+
+def _audit_duration(source: Any) -> int:
+    issued = _field(source, "issued_at")
+    completed = _field(source, "completed_at")
+    if issued is None or completed is None:
+        raise ValueError(
+            "AGT action audit requires duration_ns or both issued_at and completed_at"
+        )
+    issued_ns = _datetime_ns(issued, "issued_at")
+    completed_ns = _datetime_ns(completed, "completed_at")
+    if completed_ns < issued_ns:
+        raise ValueError("AGT completed_at cannot predate issued_at")
+    return completed_ns - issued_ns
+
+
+def _source_event_id(kind: str, source_id: str) -> str:
+    return str(uuid.uuid5(_AUDIT_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 _required_string(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"AGT audit {field} must be a non-empty string")
+    return value
+
+
+def _optional_string(value: Any, field: str) -> str | None:
+    return None if value is None else _required_string(value, field)
+
+
+def _datetime_ns(value: Any, field: str) -> int:
+    if not isinstance(value, datetime) or value.tzinfo is None:
+        raise ValueError(f"AGT audit {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
+    )

agentrust_telemetry/adapters/agt_data.py

@@ -0,0 +1,105 @@
+"""AGT DataLabel and DataAccessDecision adapters."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from ..data_flow import (
+    ClassificationResult,
+    DataEndpoint,
+    classified_data_flow,
+)
+from .base import EventFactory
+
+
+_LEVELS = {
+    0: "public",
+    1: "internal",
+    2: "confidential",
+    3: "restricted",
+    4: "top_secret",
+}
+
+
+def agt_data_classification(source: Any) -> ClassificationResult:
+    """Map only AGT's ordered sensitivity tier; omit auxiliary label content."""
+    classification = _field(source, "classification")
+    raw = classification.value if isinstance(classification, Enum) else classification
+    if isinstance(raw, bool) or raw not in _LEVELS:
+        raise ValueError(f"unsupported AGT data classification: {raw!r}")
+    return ClassificationResult(
+        taxonomy="agt.data_classification.v1",
+        value=_LEVELS[raw],
+        producer="agt.data_label",
+    )
+
+
+def agt_data_access_flow(
+    factory: EventFactory,
+    decision: Any,
+    *,
+    run_id: str,
+    direction: str,
+    source: DataEndpoint,
+    destination: DataEndpoint,
+    purpose: str,
+    content_digest: dict[str, str] | None = None,
+    size_bytes: int | None = None,
+    token_count: int | None = None,
+    media_type: str | None = None,
+    transformation: str | None = None,
+    **envelope: Any,
+) -> dict[str, Any]:
+    """Map an AGT DataAccessDecision without copying labels or free-form reason."""
+    allowed = _field(decision, "allowed")
+    if not isinstance(allowed, bool):
+        raise ValueError("AGT data access allowed must be a boolean")
+    result = agt_data_classification(_field(decision, "data_label"))
+    agent_id = _field(decision, "agent_id")
+    if not isinstance(agent_id, str) or not agent_id:
+        raise ValueError("AGT data access agent_id must be a non-empty string")
+    class FixedClassifier:
+        def classify(self, value: Any) -> ClassificationResult:
+            return result
+
+    return classified_data_flow(
+        factory,
+        FixedClassifier(),
+        None,
+        run_id=run_id,
+        agent_id=agent_id,
+        time_unix_nano=_datetime_ns(_field(decision, "evaluated_at")),
+        direction=direction,
+        source=source,
+        destination=destination,
+        purpose=purpose,
+        policy_decision="allow" if allowed else "deny",
+        content_digest=content_digest,
+        size_bytes=size_bytes,
+        token_count=token_count,
+        media_type=media_type,
+        transformation=transformation,
+        **envelope,
+    )
+
+
+def _field(source: Any, name: str) -> Any:
+    if isinstance(source, dict):
+        return source.get(name)
+    return getattr(source, name, None)
+
+
+def _datetime_ns(value: Any) -> int:
+    from datetime import datetime, timezone
+
+    if not isinstance(value, datetime) or value.tzinfo is None:
+        raise ValueError("AGT data access evaluated_at 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
+    )

agentrust_telemetry/adapters/base.py

@@ -0,0 +1,90 @@
+"""Validated envelope construction shared by all adapters."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from copy import deepcopy
+from typing import Any, Callable
+
+from ..validation import SchemaValidator
+
+
+class EventFactory:
+    def __init__(
+        self,
+        validator: SchemaValidator,
+        *,
+        producer_name: str,
+        producer_version: str,
+        producer_instance_id: str | None = None,
+        clock_ns: Callable[[], int] = time.time_ns,
+        event_id_factory: Callable[[], uuid.UUID] = uuid.uuid4,
+    ) -> None:
+        self._validator = validator
+        self._producer = {
+            "name": producer_name,
+            "version": producer_version,
+            **({"instance_id": producer_instance_id} if producer_instance_id else {}),
+        }
+        self._clock_ns = clock_ns
+        self._event_id_factory = event_id_factory
+
+    def build(
+        self,
+        event_type: str,
+        *,
+        run_id: str,
+        agent_id: str | None = None,
+        workflow_id: str | None = None,
+        parent_agent_id: str | None = None,
+        task_id: str | None = None,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        event_id: str | None = None,
+        time_unix_nano: int | str | None = None,
+        **payload: Any,
+    ) -> dict[str, Any]:
+        reserved = {
+            "spec_version", "event_id", "event_type", "time_unix_nano", "run_id",
+            "producer", "agent_id", "workflow_id", "parent_agent_id", "task_id",
+            "trace_id", "span_id",
+        }
+        collision = sorted(reserved.intersection(payload))
+        if collision:
+            raise ValueError(f"payload cannot override envelope fields: {collision}")
+        timestamp = self._clock_ns() if time_unix_nano is None else time_unix_nano
+        event: dict[str, Any] = {
+            "spec_version": "0.1.0-alpha.3",
+            "event_id": event_id or str(self._event_id_factory()),
+            "event_type": event_type,
+            "time_unix_nano": _unix_nano(timestamp),
+            "run_id": run_id,
+            "producer": deepcopy(self._producer),
+            **{
+                key: _unix_nano(value) if key.endswith("_at_unix_nano") else value
+                for key, value in payload.items()
+            },
+        }
+        optional = {
+            "agent_id": agent_id,
+            "workflow_id": workflow_id,
+            "parent_agent_id": parent_agent_id,
+            "task_id": task_id,
+            "trace_id": trace_id,
+            "span_id": span_id,
+        }
+        event.update({key: value for key, value in optional.items() if value is not None})
+        self._validator.validate(event)
+        return event
+
+
+def _unix_nano(value: Any) -> str:
+    if isinstance(value, bool) or not isinstance(value, (int, str)):
+        raise TypeError("Unix nanosecond timestamps must be integers or decimal strings")
+    text = str(value)
+    if not text.isascii() or not text.isdecimal() or (len(text) > 1 and text.startswith("0")):
+        raise ValueError("Unix nanosecond timestamps must be canonical non-negative decimals")
+    if len(text) > 20:
+        raise ValueError("Unix nanosecond timestamps cannot exceed 20 digits")
+    return text

agentrust_telemetry/adapters/cedar.py

@@ -0,0 +1,66 @@
+"""Cedar authorization-response adapter with explicit safe fields."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable
+
+from .base import EventFactory
+
+
+def cedar_policy_decision(
+    factory: EventFactory,
+    *,
+    run_id: str,
+    agent_id: str,
+    decision: str,
+    cedar_version: str,
+    bundle_digest: dict[str, str],
+    action_type: str,
+    resource_type: str,
+    evaluation_duration_ns: int,
+    determining_policy_ids: Iterable[str] = (),
+    error_codes: Iterable[str] = (),
+    enforcement_mode: str = "enforce",
+    input_digest: dict[str, str] | None = None,
+    **envelope: Any,
+) -> dict[str, Any]:
+    normalized = decision.lower()
+    if normalized not in {"allow", "deny"}:
+        raise ValueError("Cedar decision must be Allow or Deny")
+    policy_ids = _identifiers(determining_policy_ids, "determining_policy_ids")
+    errors = _identifiers(error_codes, "error_codes")
+    if any(re.fullmatch(r"[A-Za-z0-9_.:-]{1,128}", value) is None for value in errors):
+        raise ValueError("Cedar error_codes must be identifiers, not error messages")
+    reason_codes = [*(f"cedar.policy:{value}" for value in policy_ids), *(f"cedar.error:{value}" for value in errors)]
+    if len(reason_codes) > 32:
+        raise ValueError("Cedar reasons and errors exceed the 32-code contract limit")
+    policy: dict[str, Any] = {
+        "engine": "cedar",
+        "engine_version": cedar_version,
+        "bundle_digest": bundle_digest,
+        **({"policy_id": policy_ids[0]} if len(policy_ids) == 1 else {}),
+        **({"input_digest": input_digest} if input_digest else {}),
+    }
+    return factory.build(
+        "policy.decision",
+        run_id=run_id,
+        agent_id=agent_id,
+        decision=normalized,
+        policy=policy,
+        action_type=action_type,
+        resource_type=resource_type,
+        enforcement_mode=enforcement_mode,
+        evaluation_duration_ns=evaluation_duration_ns,
+        reason_codes=reason_codes,
+        **envelope,
+    )
+
+
+def _identifiers(values: Iterable[str], field: str) -> list[str]:
+    if isinstance(values, (str, bytes)):
+        raise ValueError(f"Cedar {field} must be an iterable of strings, not a string")
+    normalized = sorted(set(values))
+    if any(not isinstance(value, str) or not value for value in normalized):
+        raise ValueError(f"Cedar {field} must contain non-empty strings")
+    return normalized

agentrust_telemetry/adapters/opa.py

@@ -0,0 +1,102 @@
+"""Open Policy Agent decision-log adapter."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+from .base import EventFactory
+
+
+DecisionMapper = Callable[[Any], str]
+_OPA_EVENT_NAMESPACE = uuid.UUID("881f86d8-7573-4d35-98cb-c00b934cc04f")
+_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$"
+)
+
+
+def opa_decision_log(
+    factory: EventFactory,
+    decision_log: dict[str, Any],
+    *,
+    run_id: str,
+    agent_id: str,
+    action_type: str,
+    resource_type: str,
+    bundle_digest: dict[str, str],
+    opa_version: str | None = None,
+    enforcement_mode: str = "enforce",
+    result_mapper: DecisionMapper | None = None,
+) -> dict[str, Any]:
+    source_id = decision_log.get("decision_id")
+    if not isinstance(source_id, str) or not source_id:
+        raise ValueError("OPA decision log requires a non-empty decision_id")
+    mapper = result_mapper or _boolean_decision
+    decision = mapper(decision_log.get("result"))
+    if decision not in {"allow", "deny", "challenge", "not_applicable", "error"}:
+        raise ValueError(f"OPA result mapper returned unsupported decision: {decision!r}")
+    labels = decision_log.get("labels", {})
+    if not isinstance(labels, dict):
+        raise ValueError("OPA labels must be an object")
+    version = opa_version or labels.get("version")
+    if not isinstance(version, str) or not version:
+        raise ValueError("OPA version is required explicitly or in labels.version")
+    metrics = decision_log.get("metrics", {})
+    if not isinstance(metrics, dict):
+        raise ValueError("OPA metrics must be an object")
+    duration = metrics.get("timer_rego_query_eval_ns", 0)
+    if not isinstance(duration, int) or isinstance(duration, bool) or duration < 0:
+        raise ValueError("OPA timer_rego_query_eval_ns must be a non-negative integer")
+    path = decision_log.get("path")
+    policy: dict[str, Any] = {
+        "engine": "opa",
+        "engine_version": version,
+        "bundle_digest": bundle_digest,
+        **({"policy_id": path.lstrip("/")} if isinstance(path, str) and path else {}),
+    }
+    ids = decision_log.get("ids", [])
+    if not isinstance(ids, list) or any(not isinstance(value, str) or not value for value in ids):
+        raise ValueError("OPA ids must be an array of non-empty strings")
+    if len(ids) > 32:
+        raise ValueError("OPA ids exceed the 32-code contract limit")
+    return factory.build(
+        "policy.decision",
+        run_id=run_id,
+        agent_id=agent_id,
+        event_id=str(uuid.uuid5(_OPA_EVENT_NAMESPACE, source_id)),
+        time_unix_nano=_timestamp_ns(decision_log["timestamp"])
+        if "timestamp" in decision_log
+        else None,
+        trace_id=decision_log.get("trace_id"),
+        span_id=decision_log.get("span_id"),
+        decision=decision,
+        policy=policy,
+        action_type=action_type,
+        resource_type=resource_type,
+        enforcement_mode=enforcement_mode,
+        evaluation_duration_ns=duration,
+        reason_codes=[f"opa.rule:{value}" for value in ids],
+    )
+
+
+def _boolean_decision(result: Any) -> str:
+    if result is True:
+        return "allow"
+    if result is False:
+        return "deny"
+    if result is None:
+        return "not_applicable"
+    raise ValueError("OPA non-boolean result requires an explicit result_mapper")
+
+
+def _timestamp_ns(value: Any) -> int:
+    if not isinstance(value, str):
+        raise ValueError("OPA timestamp must be an RFC 3339 UTC string")
+    match = _TIMESTAMP.fullmatch(value)
+    if match is None:
+        raise ValueError("OPA timestamp must use RFC 3339 UTC form ending in Z")
+    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/client.py

@@ -0,0 +1,113 @@
+"""Validated, caller-owned telemetry emission."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any, Callable, Protocol
+
+from .context import ContextIds, active_context_ids, current_span
+from .errors import ContextMismatchError
+from .projection import log_record, span_attributes
+from .validation import SchemaValidator
+
+
+class SpanLike(Protocol):
+    def add_event(self, name: str, attributes: dict[str, Any], timestamp: int) -> None: ...
+    def get_span_context(self) -> Any: ...
+
+
+class LogEmitter(Protocol):
+    def emit(self, record: dict[str, Any]) -> None: ...
+
+
+class EvidenceSink(Protocol):
+    def append(self, event: dict[str, Any]) -> Any: ...
+
+
+class MetricEmitter(Protocol):
+    def emit(self, event: dict[str, Any]) -> bool: ...
+
+
+@dataclass(frozen=True)
+class EmitResult:
+    accepted: bool
+    span_event_emitted: bool
+    log_emitted: bool
+    context: ContextIds | None
+    projection_errors: tuple[str, ...] = ()
+    evidence_persisted: bool = False
+    metrics_emitted: bool = False
+
+
+class TelemetryClient:
+    def __init__(
+        self,
+        validator: SchemaValidator,
+        *,
+        span_resolver: Callable[[], SpanLike | None] | None = None,
+        log_emitter: LogEmitter | None = None,
+        evidence_sink: EvidenceSink | None = None,
+        metric_emitter: MetricEmitter | None = None,
+    ):
+        self._validator = validator
+        self._span_resolver = span_resolver
+        self._log_emitter = log_emitter
+        self._evidence_sink = evidence_sink
+        self._metric_emitter = metric_emitter
+
+    def emit(self, event: dict[str, Any]) -> EmitResult:
+        self._validator.validate(event)
+        resolver = self._span_resolver or current_span
+        span = resolver()
+        context = active_context_ids(lambda: span)
+        if context:
+            if event.get("trace_id") not in (None, context.trace_id):
+                raise ContextMismatchError("event trace_id disagrees with active span")
+            if event.get("span_id") not in (None, context.span_id):
+                raise ContextMismatchError("event span_id disagrees with active span")
+
+        evidence_persisted = False
+        if self._evidence_sink is not None:
+            # Evidence is accepted after correlation validation and before any
+            # best-effort operational projection.
+            self._evidence_sink.append(deepcopy(event))
+            evidence_persisted = True
+
+        errors: list[str] = []
+        span_emitted = False
+        if span is not None and context is not None:
+            try:
+                span.add_event(
+                    event["event_type"],
+                    attributes=span_attributes(event),
+                    timestamp=int(event["time_unix_nano"]),
+                )
+                span_emitted = True
+            except Exception as exc:  # exporter implementations are external
+                errors.append(f"span projection failed: {type(exc).__name__}: {exc}")
+
+        log_emitted = False
+        if self._log_emitter is not None:
+            try:
+                self._log_emitter.emit(log_record(event, context))
+                log_emitted = True
+            except Exception as exc:  # exporter implementations are external
+                errors.append(f"log projection failed: {type(exc).__name__}: {exc}")
+
+        metrics_emitted = False
+        if self._metric_emitter is not None:
+            try:
+                metrics_emitted = self._metric_emitter.emit(deepcopy(event))
+            except Exception as exc:
+                errors.append(f"metric projection failed: {type(exc).__name__}: {exc}")
+
+        return EmitResult(
+            True,
+            span_emitted,
+            log_emitted,
+            context,
+            tuple(errors),
+            evidence_persisted,
+            metrics_emitted,
+        )

agentrust_telemetry/context.py

@@ -0,0 +1,30 @@
+"""Optional OpenTelemetry context integration without global configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True)
+class ContextIds:
+    trace_id: str
+    span_id: str
+
+
+def current_span() -> Any | None:
+    try:
+        from opentelemetry import trace
+    except ImportError:
+        return None
+    return trace.get_current_span()
+
+
+def active_context_ids(span_resolver: Callable[[], Any | None] = current_span) -> ContextIds | None:
+    span = span_resolver()
+    if span is None:
+        return None
+    context = span.get_span_context()
+    if not getattr(context, "is_valid", False):
+        return None
+    return ContextIds(trace_id=f"{context.trace_id:032x}", span_id=f"{context.span_id:016x}")