aigp-python 1.0.0__py3-none-any.whl

aigp/__init__.py

@@ -0,0 +1,128 @@
+"""
+AIGP — AI Governance Proof
+==========================
+
+Open standard for proving your AI agents used the approved
+policies, prompts, and tools — every single time.
+
+Quick Start::
+
+    pip install aigp-python sandarb
+
+    from aigp import configure, aigp
+    from sandarb import SandarbBackend
+
+    configure(
+        backend=SandarbBackend("https://api.sandarb.ai", token="..."),
+        agent_id="agent.my-bot-v1",
+    )
+
+    @aigp(policy="policy.trading-limits")
+    def process_trade(order: dict, governance=None):
+        if governance.denied:
+            return {"error": governance.denial_reason}
+        return execute(order)
+
+What AIGP does:
+  - Proves governance was delivered (Merkle proofs, cryptographic hashes)
+  - Emits standardized events (INJECT_SUCCESS, TOOL_INVOKED, A2A_CALL, ...)
+  - Transports via OpenTelemetry (dual-emit to governance store + observability)
+  - Stays vendor-neutral — any GovernanceBackend can plug in
+
+What AIGP does NOT do:
+  - Dictate how governance works — that's the backend's job
+  - Provide policies, prompts, or tools — those come from your governance server
+
+Website: https://open-aigp.org
+GitHub:  https://github.com/open-aigp/aigp
+"""
+
+# ── Core: what most developers need ──────────────────────────────────
+
+from aigp.decorators import (
+    configure,
+    aigp,
+    aigp_action,
+    a2a_traced,
+    audit_action,
+    GovernanceBackend,
+    GovernanceResult,
+    GovernanceError,
+    GovernedActionContext,
+    get_backend,
+    get_instrumentor,
+)
+
+# ── Events & Proof ────────────────────────────────────────────────────
+
+from aigp.instrumentor import AIGPInstrumentor
+from aigp.events import (
+    create_aigp_event,
+    compute_governance_hash,
+    compute_leaf_hash,
+    compute_merkle_governance_hash,
+    sign_event,
+    verify_event_signature,
+)
+
+# ── Context propagation (OTel integration) ────────────────────────────
+
+from aigp.attributes import AIGPAttributes
+from aigp.baggage import AIGPBaggage
+from aigp.tracestate import AIGPTraceState
+
+# ── OpenLineage integration ───────────────────────────────────────────
+
+from aigp.openlineage import (
+    build_governance_run_facet,
+    build_resource_input_facets,
+    build_openlineage_run_event,
+)
+
+# ── CloudEvents transport ─────────────────────────────────────────────
+
+from aigp.cloudevents import (
+    wrap_as_cloudevent,
+    unwrap_from_cloudevent,
+    build_ce_headers,
+    ce_type_from_event_type,
+    event_type_from_ce_type,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    # ── Start here ──
+    "configure",
+    "aigp",
+    "aigp_action",
+    "a2a_traced",
+    "audit_action",
+    "GovernanceBackend",
+    "GovernanceResult",
+    "GovernanceError",
+    "GovernedActionContext",
+    "get_backend",
+    "get_instrumentor",
+    # ── Events & Proof ──
+    "AIGPInstrumentor",
+    "create_aigp_event",
+    "compute_governance_hash",
+    "compute_leaf_hash",
+    "compute_merkle_governance_hash",
+    "sign_event",
+    "verify_event_signature",
+    # ── Context propagation ──
+    "AIGPAttributes",
+    "AIGPBaggage",
+    "AIGPTraceState",
+    # ── OpenLineage ──
+    "build_governance_run_facet",
+    "build_resource_input_facets",
+    "build_openlineage_run_event",
+    # ── CloudEvents ──
+    "wrap_as_cloudevent",
+    "unwrap_from_cloudevent",
+    "build_ce_headers",
+    "ce_type_from_event_type",
+    "event_type_from_ce_type",
+]

aigp/attributes.py

@@ -0,0 +1,129 @@
+"""
+AIGP Semantic Attributes for OpenTelemetry
+==========================================
+
+Defines the `aigp.*` namespace attributes as constants, organized by
+their OTel signal type (Resource vs Span vs Span Event).
+
+These follow OTel naming conventions:
+- Lowercase, dot-separated namespace hierarchy
+- Domain-first approach: aigp.{component}.{property}
+"""
+
+
+class AIGPAttributes:
+    """Constants for AIGP semantic attributes in the aigp.* namespace."""
+
+    # -------------------------------------------------------
+    # Resource Attributes (constant per agent process)
+    # -------------------------------------------------------
+    AGENT_ID = "aigp.agent.id"
+    AGENT_NAME = "aigp.agent.name"
+    ORG_ID = "aigp.org.id"
+    ORG_NAME = "aigp.org.name"
+
+    # -------------------------------------------------------
+    # Span Attributes: Core Governance
+    # -------------------------------------------------------
+    EVENT_ID = "aigp.event.id"
+    EVENT_TYPE = "aigp.event.type"
+    EVENT_CATEGORY = "aigp.event.category"
+    GOVERNANCE_HASH = "aigp.governance.hash"
+    GOVERNANCE_HASH_TYPE = "aigp.governance.hash_type"
+    DATA_CLASSIFICATION = "aigp.data.classification"
+    ENFORCEMENT_RESULT = "aigp.enforcement.result"
+    EVENT_SIGNATURE = "aigp.event.signature"
+    SIGNATURE_KEY_ID = "aigp.signature.key_id"
+    SEQUENCE_NUMBER = "aigp.sequence.number"
+    CAUSALITY_REF = "aigp.causality.ref"
+
+    # -------------------------------------------------------
+    # Span Attributes: Policy (singular — one policy per span)
+    # -------------------------------------------------------
+    POLICY_NAME = "aigp.policy.name"
+    POLICY_VERSION = "aigp.policy.version"
+    POLICY_ID = "aigp.policy.id"
+
+    # -------------------------------------------------------
+    # Span Attributes: Prompt (singular — one prompt per span)
+    # -------------------------------------------------------
+    PROMPT_NAME = "aigp.prompt.name"
+    PROMPT_VERSION = "aigp.prompt.version"
+    PROMPT_ID = "aigp.prompt.id"
+
+    # -------------------------------------------------------
+    # Span Attributes: Multi-Policy / Multi-Prompt / Multi-Tool
+    # Array-valued attributes for operations involving multiple
+    # governed resources simultaneously.
+    # -------------------------------------------------------
+    POLICIES_NAMES = "aigp.policies.names"
+    POLICIES_VERSIONS = "aigp.policies.versions"
+    PROMPTS_NAMES = "aigp.prompts.names"
+    PROMPTS_VERSIONS = "aigp.prompts.versions"
+    TOOLS_NAMES = "aigp.tools.names"
+    CONTEXTS_NAMES = "aigp.contexts.names"
+    LINEAGES_NAMES = "aigp.lineages.names"
+    MEMORIES_NAMES = "aigp.memories.names"
+    MODELS_NAMES = "aigp.models.names"
+
+    # -------------------------------------------------------
+    # Span Attributes: Merkle Tree Governance
+    # -------------------------------------------------------
+    MERKLE_LEAF_COUNT = "aigp.governance.merkle.leaf_count"
+
+    # -------------------------------------------------------
+    # Span Attributes: Denial and Violation
+    # -------------------------------------------------------
+    SEVERITY = "aigp.severity"
+    VIOLATION_TYPE = "aigp.violation.type"
+    DENIAL_REASON = "aigp.denial.reason"
+
+    # -------------------------------------------------------
+    # Span Event Names
+    # -------------------------------------------------------
+    EVENT_INJECT_SUCCESS = "aigp.inject.success"
+    EVENT_INJECT_DENIED = "aigp.inject.denied"
+    EVENT_PROMPT_USED = "aigp.prompt.used"
+    EVENT_PROMPT_DENIED = "aigp.prompt.denied"
+    EVENT_POLICY_VIOLATION = "aigp.policy.violation"
+    EVENT_GOVERNANCE_PROOF = "aigp.governance.proof"
+    EVENT_A2A_CALL = "aigp.a2a.call"
+    EVENT_MEMORY_READ = "aigp.memory.read"
+    EVENT_MEMORY_WRITTEN = "aigp.memory.written"
+    EVENT_TOOL_INVOKED = "aigp.tool.invoked"
+    EVENT_TOOL_DENIED = "aigp.tool.denied"
+    EVENT_CONTEXT_CAPTURED = "aigp.context.captured"
+    EVENT_LINEAGE_SNAPSHOT = "aigp.lineage.snapshot"
+    EVENT_INFERENCE_STARTED = "aigp.inference.started"
+    EVENT_INFERENCE_COMPLETED = "aigp.inference.completed"
+    EVENT_INFERENCE_BLOCKED = "aigp.inference.blocked"
+    EVENT_HUMAN_OVERRIDE = "aigp.human.override"
+    EVENT_HUMAN_APPROVAL = "aigp.human.approval"
+    EVENT_CLASSIFICATION_CHANGED = "aigp.classification.changed"
+    EVENT_MODEL_LOADED = "aigp.model.loaded"
+    EVENT_MODEL_SWITCHED = "aigp.model.switched"
+    EVENT_UNVERIFIED_BOUNDARY = "aigp.boundary.unverified"
+
+    # -------------------------------------------------------
+    # Enforcement result values
+    # -------------------------------------------------------
+    ENFORCEMENT_ALLOWED = "allowed"
+    ENFORCEMENT_DENIED = "denied"
+
+    # -------------------------------------------------------
+    # Data classification values
+    # -------------------------------------------------------
+    CLASSIFICATION_PUBLIC = "public"
+    CLASSIFICATION_INTERNAL = "internal"
+    CLASSIFICATION_CONFIDENTIAL = "confidential"
+    CLASSIFICATION_RESTRICTED = "restricted"
+
+    # -------------------------------------------------------
+    # Classification abbreviations for tracestate
+    # -------------------------------------------------------
+    CLASSIFICATION_ABBREV = {
+        "public": "pub",
+        "internal": "int",
+        "confidential": "con",
+        "restricted": "res",
+    }

aigp/baggage.py

@@ -0,0 +1,126 @@
+"""
+AIGP Baggage Propagation
+========================
+
+Manages OTel Baggage for propagating governance context across
+agent-to-agent calls.
+
+When Agent A calls Agent B, the governance context (active policy,
+data classification, org) travels via OTel Baggage in HTTP headers.
+
+Security: Sensitive data (governance_hash, denial_reason, raw content)
+MUST NOT be placed in Baggage as it leaks in HTTP headers.
+"""
+
+from opentelemetry import baggage, context
+from opentelemetry.context import Context
+from typing import Optional
+
+from aigp.attributes import AIGPAttributes
+
+
+class AIGPBaggage:
+    """
+    Manages AIGP governance context in OTel Baggage.
+
+    Baggage items are propagated automatically across service boundaries
+    when OTel instrumentation is active (HTTP, gRPC, etc.).
+    """
+
+    # Keys that are safe to propagate in Baggage (non-sensitive)
+    SAFE_KEYS = {
+        AIGPAttributes.POLICY_NAME,
+        AIGPAttributes.DATA_CLASSIFICATION,
+        AIGPAttributes.ORG_ID,
+    }
+
+    # Keys that MUST NOT be propagated (sensitive)
+    FORBIDDEN_KEYS = {
+        AIGPAttributes.GOVERNANCE_HASH,
+        AIGPAttributes.DENIAL_REASON,
+        AIGPAttributes.VIOLATION_TYPE,
+    }
+
+    @staticmethod
+    def inject(
+        policy_name: str = "",
+        data_classification: str = "",
+        org_id: str = "",
+        ctx: Optional[Context] = None,
+    ) -> Context:
+        """
+        Inject AIGP governance context into OTel Baggage.
+
+        Call this before making an agent-to-agent request so that the
+        receiving agent inherits governance context.
+
+        Args:
+            policy_name: Active governed policy (AGRN format).
+            data_classification: Data sensitivity level.
+            org_id: Organization identifier (AGRN format).
+            ctx: Optional OTel context. Defaults to current context.
+
+        Returns:
+            Updated OTel context with Baggage items.
+        """
+        current_ctx = ctx or context.get_current()
+
+        if policy_name:
+            current_ctx = baggage.set_baggage(
+                AIGPAttributes.POLICY_NAME, policy_name, context=current_ctx
+            )
+        if data_classification:
+            current_ctx = baggage.set_baggage(
+                AIGPAttributes.DATA_CLASSIFICATION, data_classification, context=current_ctx
+            )
+        if org_id:
+            current_ctx = baggage.set_baggage(
+                AIGPAttributes.ORG_ID, org_id, context=current_ctx
+            )
+
+        return current_ctx
+
+    @staticmethod
+    def extract(ctx: Optional[Context] = None) -> dict[str, str]:
+        """
+        Extract AIGP governance context from OTel Baggage.
+
+        Call this on the receiving side of an agent-to-agent call to
+        recover governance context set by the calling agent.
+
+        Args:
+            ctx: Optional OTel context. Defaults to current context.
+
+        Returns:
+            Dict of AIGP Baggage items found.
+        """
+        current_ctx = ctx or context.get_current()
+        result = {}
+
+        for key in AIGPBaggage.SAFE_KEYS:
+            value = baggage.get_baggage(key, context=current_ctx)
+            if value:
+                result[key] = value
+
+        return result
+
+    @staticmethod
+    def clear(ctx: Optional[Context] = None) -> Context:
+        """
+        Remove all AIGP Baggage items from context.
+
+        Useful when crossing trust boundaries where governance context
+        should not leak further.
+
+        Args:
+            ctx: Optional OTel context. Defaults to current context.
+
+        Returns:
+            Updated context with AIGP Baggage items removed.
+        """
+        current_ctx = ctx or context.get_current()
+
+        for key in AIGPBaggage.SAFE_KEYS:
+            current_ctx = baggage.remove_baggage(key, context=current_ctx)
+
+        return current_ctx

aigp/cloudevents.py

@@ -0,0 +1,264 @@
+"""
+AIGP CloudEvents Binding
+========================
+
+Wraps AIGP events in CloudEvents envelopes (structured mode) and
+unwraps CloudEvents back to raw AIGP events. Implements the binding
+defined in AIGP Specification Section 13.
+
+CloudEvents spec: https://cloudevents.io/
+AIGP binding:     Section 13 — Transport Bindings via CloudEvents
+
+Usage:
+    from aigp.cloudevents import wrap_as_cloudevent, unwrap_from_cloudevent
+
+    ce = wrap_as_cloudevent(aigp_event)
+    # -> {"specversion": "1.0", "type": "org.aigp.v1.inject_success", ...}
+
+    aigp_event = unwrap_from_cloudevent(ce)
+    # -> {"event_id": "...", "event_type": "INJECT_SUCCESS", ...}
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# CloudEvents spec version
+CE_SPECVERSION = "1.0"
+
+# AIGP type prefix (reverse-DNS, versioned)
+AIGP_TYPE_PREFIX = "org.aigp.v1."
+
+# AIGP source scheme
+AIGP_SOURCE_SCHEME = "aigp://"
+
+# AIGP JSON Schema URI
+AIGP_DATA_SCHEMA = "https://open-aigp.org/schema/aigp-event.schema.json"
+
+
+def wrap_as_cloudevent(
+    aigp_event: dict[str, Any],
+    *,
+    include_dataschema: bool = True,
+) -> dict[str, Any]:
+    """
+    Wrap an AIGP event in a CloudEvents structured-mode envelope.
+
+    Maps AIGP fields to CloudEvents context attributes and AIGP extension
+    attributes per Spec Section 13.
+
+    Args:
+        aigp_event: An AIGP event dict (from ``create_aigp_event`` or any
+            ``AIGPInstrumentor`` method).
+        include_dataschema: Whether to include the ``dataschema`` attribute
+            pointing to the AIGP JSON Schema. Default True.
+
+    Returns:
+        Dict conforming to CloudEvents JSON Format (structured mode).
+        The AIGP event is in the ``data`` field.
+
+    Raises:
+        ValueError: If required AIGP fields are missing.
+    """
+    event_id = aigp_event.get("event_id", "")
+    event_type = aigp_event.get("event_type", "")
+    agent_id = aigp_event.get("agent_id", "")
+
+    if not event_id or not event_type or not agent_id:
+        raise ValueError(
+            "AIGP event must have event_id, event_type, and agent_id "
+            "to wrap as CloudEvent"
+        )
+
+    # Build source URI: aigp://<org_id>/<agent_id>
+    org_id = aigp_event.get("org_id", "") or "default"
+    source = f"{AIGP_SOURCE_SCHEME}{org_id}/{agent_id}"
+
+    # Build type: org.aigp.v1.<lowercase_event_type>
+    ce_type = f"{AIGP_TYPE_PREFIX}{event_type.lower()}"
+
+    # Core context attributes
+    ce: dict[str, Any] = {
+        "specversion": CE_SPECVERSION,
+        "id": event_id,
+        "type": ce_type,
+        "source": source,
+    }
+
+    # Optional context attributes
+    event_time = aigp_event.get("event_time", "")
+    if event_time:
+        ce["time"] = event_time
+
+    ce["datacontenttype"] = "application/json"
+
+    if include_dataschema:
+        ce["dataschema"] = AIGP_DATA_SCHEMA
+
+    # Subject: primary governed resource (policy or prompt name)
+    policy_name = aigp_event.get("policy_name", "")
+    prompt_name = aigp_event.get("prompt_name", "")
+    subject = policy_name or prompt_name
+    if subject:
+        ce["subject"] = subject
+
+    # AIGP extension attributes (lowercase a-z0-9 only per CE spec)
+    ce["aigpagentid"] = agent_id
+
+    if org_id != "default":
+        ce["aigporgid"] = org_id
+
+    event_category = aigp_event.get("event_category", "")
+    if event_category:
+        ce["aigpcategory"] = event_category
+
+    data_classification = aigp_event.get("data_classification", "")
+    if data_classification:
+        ce["aigpclassification"] = data_classification
+
+    severity = aigp_event.get("severity", "")
+    if severity:
+        ce["aigpseverity"] = severity
+
+    hash_type = aigp_event.get("hash_type", "")
+    if hash_type:
+        ce["aigphashtype"] = hash_type
+
+    # Data payload: the full AIGP event
+    ce["data"] = aigp_event
+
+    return ce
+
+
+def unwrap_from_cloudevent(ce: dict[str, Any]) -> dict[str, Any]:
+    """
+    Extract the AIGP event from a CloudEvents structured-mode envelope.
+
+    Validates that the CloudEvents envelope has the expected structure
+    and returns the ``data`` payload.
+
+    Args:
+        ce: A CloudEvents dict in structured JSON format.
+
+    Returns:
+        The AIGP event dict from the ``data`` field.
+
+    Raises:
+        ValueError: If the envelope is not a valid AIGP CloudEvent.
+    """
+    specversion = ce.get("specversion", "")
+    if specversion != CE_SPECVERSION:
+        raise ValueError(
+            f"Unsupported CloudEvents specversion: {specversion!r} "
+            f"(expected {CE_SPECVERSION!r})"
+        )
+
+    ce_type = ce.get("type", "")
+    if not ce_type.startswith(AIGP_TYPE_PREFIX):
+        raise ValueError(
+            f"CloudEvents type {ce_type!r} does not start with "
+            f"{AIGP_TYPE_PREFIX!r} — not an AIGP event"
+        )
+
+    data = ce.get("data")
+    if data is None:
+        raise ValueError("CloudEvents envelope has no 'data' field")
+
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"CloudEvents 'data' must be a dict, got {type(data).__name__}"
+        )
+
+    return data
+
+
+def ce_type_from_event_type(event_type: str) -> str:
+    """
+    Convert an AIGP event_type to a CloudEvents type string.
+
+    Args:
+        event_type: AIGP event type (e.g., "INJECT_SUCCESS").
+
+    Returns:
+        CloudEvents type (e.g., "org.aigp.v1.inject_success").
+    """
+    return f"{AIGP_TYPE_PREFIX}{event_type.lower()}"
+
+
+def event_type_from_ce_type(ce_type: str) -> str:
+    """
+    Convert a CloudEvents type string back to an AIGP event_type.
+
+    Args:
+        ce_type: CloudEvents type (e.g., "org.aigp.v1.inject_success").
+
+    Returns:
+        AIGP event type (e.g., "INJECT_SUCCESS").
+
+    Raises:
+        ValueError: If the type does not have the AIGP prefix.
+    """
+    if not ce_type.startswith(AIGP_TYPE_PREFIX):
+        raise ValueError(
+            f"CloudEvents type {ce_type!r} does not start with "
+            f"{AIGP_TYPE_PREFIX!r}"
+        )
+    return ce_type[len(AIGP_TYPE_PREFIX):].upper()
+
+
+def build_ce_headers(
+    aigp_event: dict[str, Any],
+    *,
+    prefix: str = "ce-",
+) -> dict[str, str]:
+    """
+    Build CloudEvents binary-mode headers from an AIGP event.
+
+    For HTTP, use prefix="ce-" (default). For Kafka, use prefix="ce_".
+
+    Args:
+        aigp_event: An AIGP event dict.
+        prefix: Header prefix. "ce-" for HTTP, "ce_" for Kafka.
+
+    Returns:
+        Dict of header name -> header value strings.
+    """
+    event_id = aigp_event.get("event_id", "")
+    event_type = aigp_event.get("event_type", "")
+    agent_id = aigp_event.get("agent_id", "")
+    org_id = aigp_event.get("org_id", "") or "default"
+
+    headers: dict[str, str] = {
+        f"{prefix}specversion": CE_SPECVERSION,
+        f"{prefix}id": event_id,
+        f"{prefix}type": f"{AIGP_TYPE_PREFIX}{event_type.lower()}",
+        f"{prefix}source": f"{AIGP_SOURCE_SCHEME}{org_id}/{agent_id}",
+    }
+
+    event_time = aigp_event.get("event_time", "")
+    if event_time:
+        headers[f"{prefix}time"] = event_time
+
+    # AIGP extension attributes
+    headers[f"{prefix}aigpagentid"] = agent_id
+
+    if org_id != "default":
+        headers[f"{prefix}aigporgid"] = org_id
+
+    event_category = aigp_event.get("event_category", "")
+    if event_category:
+        headers[f"{prefix}aigpcategory"] = event_category
+
+    data_classification = aigp_event.get("data_classification", "")
+    if data_classification:
+        headers[f"{prefix}aigpclassification"] = data_classification
+
+    severity = aigp_event.get("severity", "")
+    if severity:
+        headers[f"{prefix}aigpseverity"] = severity
+
+    hash_type = aigp_event.get("hash_type", "")
+    if hash_type:
+        headers[f"{prefix}aigphashtype"] = hash_type
+
+    return headers