aigp-agent-core 1.0.0__tar.gz

aigp_agent_core-1.0.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.eggs/
+
+# Node
+node_modules/
+dist/
+
+# Go
+bin/
+
+# Rust
+target/
+
+# .NET
+bin/
+obj/
+
+# Java
+*.class
+out/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets (never commit)
+.env
+*.pem
+*.key

aigp_agent_core-1.0.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: aigp-agent-core
+Version: 1.0.0
+Summary: AIGP Agent Governance Core — shared lifecycle for all framework adapters
+Requires-Python: >=3.11
+Requires-Dist: aigp-client>=3.0.0
+Provides-Extra: evidence
+Requires-Dist: amigo-bedrock>=0.2.0; extra == 'evidence'

aigp_agent_core-1.0.0/aigp_agent_core/__init__.py

@@ -0,0 +1,18 @@
+"""AIGP Agent Core — shared governance lifecycle for all framework adapters.
+
+Usage by adapter authors:
+    from aigp_agent_core import AgentGovernance
+
+    class MyFrameworkAdapter(AgentGovernance):
+        def on_my_framework_start(self, ...):
+            self.pre_invoke(agent_name, model_id, user_id)
+        def on_my_framework_end(self, ...):
+            self.post_invoke()
+"""
+
+__version__ = "1.0.0"
+
+from .governance import AgentGovernance
+from .stage_mapper import StageMapper
+
+__all__ = ["AgentGovernance", "StageMapper"]

aigp_agent_core-1.0.0/aigp_agent_core/governance.py

@@ -0,0 +1,183 @@
+"""Agent Governance — shared lifecycle that all framework adapters inherit."""
+
+import logging
+import time
+
+from aigp_client import (
+    AigpClient, TraceBuilder, SessionContext, TokenAccumulator,
+    ToolGovernance, DelegationToken, retry_on_rate_limit,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class GovernanceBlockedError(Exception):
+    """Raised when AIGP CHECK returns DENY."""
+    pass
+
+
+class AgentGovernance:
+    """Base class for governed agent adapters.
+
+    Handles the full AIGP lifecycle:
+    - pre_invoke: CHECK (is this agent allowed?)
+    - on_model_call: accumulate tokens
+    - on_tool_call: optional per-tool CHECK
+    - post_invoke: RECORD + TRACE + D-DNA evidence
+    - on_error: RECORD with ERROR status
+
+    Subclasses map framework-specific hooks to these methods.
+    """
+
+    def __init__(self, gov_url: str, app_id: str, hmac_secret: str, *,
+                 vault_url: str = "", evidence_bucket: str = "",
+                 consent_tier: str = "STANDARD", tool_policies: dict | None = None):
+        self._client = AigpClient(gov_url, app_id, hmac_secret)
+        self._app_id = app_id
+        self._session: SessionContext | None = None
+        self._tokens = TokenAccumulator()
+        self._trace: TraceBuilder | None = None
+        self._tools = ToolGovernance(self._client, tool_policies) if tool_policies else None
+        self._request_id = ""
+        self._model_id = ""
+        self._use_case = ""
+        self._t0 = 0.0
+        self._consent_tier = consent_tier
+
+        # Evidence writer (optional)
+        self._evidence = None
+        if vault_url and evidence_bucket:
+            try:
+                from amigo_bedrock import EvidenceWriter
+                self._evidence = EvidenceWriter(app_id, vault_url, evidence_bucket)
+            except ImportError:
+                logger.debug("amigo_bedrock not available, evidence writing disabled")
+
+    async def start(self) -> None:
+        """Start governance — register app and begin heartbeat."""
+        try:
+            await self._client.start_heartbeat(3600)
+            logger.info("AIGP governance started: %s", self._app_id)
+        except Exception as e:
+            logger.warning("AIGP start failed (non-fatal): %s", e)
+
+    def pre_invoke(self, agent_name: str, model_id: str, user_id: str = "",
+                   session: SessionContext | None = None) -> str:
+        """Call before agent execution. Sends CHECK. Returns request_id.
+
+        Raises GovernanceBlockedError if DENY.
+        """
+        import asyncio
+
+        self._t0 = time.time()
+        self._model_id = model_id
+        self._use_case = agent_name
+        self._tokens.reset()
+        self._session = session or SessionContext(user_id=user_id, consent_tier=self._consent_tier)
+        self._trace = TraceBuilder(request_id="")
+
+        if self._session.parent_session_id:
+            self._trace.link_parent(self._session.parent_session_id)
+
+        # S1: identity_session_initiation
+        self._trace.start(1)
+        self._trace.end(1, attributes={"user_id": user_id, "agent_name": agent_name})
+
+        # S3: request_registration (CHECK)
+        self._trace.start(3)
+        try:
+            decision = asyncio.get_event_loop().run_until_complete(
+                retry_on_rate_limit(lambda: self._client.check(use_case=agent_name, model_id=model_id))
+            )
+        except RuntimeError:
+            # No event loop — try sync
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                decision = pool.submit(lambda: __import__('asyncio').run(
+                    retry_on_rate_limit(lambda: self._client.check(use_case=agent_name, model_id=model_id))
+                )).result()
+
+        self._trace.end(3)
+
+        d = decision.get("decision", "ALLOW") if isinstance(decision, dict) else "ALLOW"
+        if d == "DENY":
+            raise GovernanceBlockedError(decision.get("reason", "Blocked by governance"))
+
+        self._request_id = decision.get("request_id", "") if isinstance(decision, dict) else ""
+        return self._request_id
+
+    def on_model_call(self, input_tokens: int = 0, output_tokens: int = 0, usage: dict | None = None) -> None:
+        """Call after each model invocation with token counts."""
+        if usage:
+            self._tokens.add_from_usage(usage)
+        else:
+            self._tokens.add(input_tokens, output_tokens)
+
+    async def on_tool_call(self, tool_name: str, params: dict = None, result: str = "",
+                           duration_ms: int = 0) -> dict:
+        """Call after a tool execution. Optionally CHECKs tool permission."""
+        decision = {"decision": "ALLOW"}
+        if self._tools:
+            decision = await self._tools.check_tool(tool_name, params)
+            if decision.get("decision") == "DENY":
+                raise GovernanceBlockedError(f"Tool '{tool_name}' denied: {decision.get('reason')}")
+
+        if self._trace:
+            self._trace.add_tool_span(tool_name, duration_ms, attributes={"classification": decision.get("classification", "")})
+
+        return decision
+
+    async def post_invoke(self, status: str = "SUCCESS") -> None:
+        """Call after agent session completes. Sends RECORD + TRACE + evidence."""
+        duration_ms = int((time.time() - self._t0) * 1000)
+
+        # RECORD
+        try:
+            await self._client.record(
+                use_case=self._use_case, model_id=self._model_id,
+                status=status, request_id=self._request_id,
+                input_tokens=self._tokens.total_input,
+                output_tokens=self._tokens.total_output,
+                duration_ms=duration_ms,
+                user_id=self._session.user_id if self._session else "",
+                session_id=self._session.session_id if self._session else "",
+            )
+        except Exception as e:
+            logger.warning("RECORD failed: %s", e)
+
+        # TRACE
+        if self._trace:
+            self._trace.start(14)
+            self._trace.end(14)
+            spans, summary = self._trace.build()
+            try:
+                await self._client.trace(
+                    trace_id=self._trace.trace_id,
+                    request_id=self._request_id,
+                    use_case=self._use_case,
+                    model_id=self._model_id,
+                    user_id=self._session.user_id if self._session else "",
+                    spans=spans, summary=summary,
+                    session_id=self._session.session_id if self._session else "",
+                )
+            except Exception as e:
+                logger.warning("TRACE failed: %s", e)
+
+        # Evidence
+        if self._evidence:
+            try:
+                from datetime import datetime, timezone
+                await self._evidence.write({
+                    "app_id": self._app_id, "request_id": self._request_id,
+                    "use_case": self._use_case, "model_id": self._model_id,
+                    "user_id": self._session.user_id if self._session else "",
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                    "duration_ms": duration_ms, "status": status,
+                    "tokens": self._tokens.to_dict(),
+                })
+            except Exception as e:
+                logger.warning("Evidence write failed: %s", e)
+
+    async def on_error(self, error: Exception) -> None:
+        """Call on agent error. Sends RECORD with ERROR status."""
+        await self.post_invoke(status="ERROR")

aigp_agent_core-1.0.0/aigp_agent_core/stage_mapper.py

@@ -0,0 +1,76 @@
+"""Stage Mapper — maps framework-specific events to AIGP 14+9 stages."""
+
+from aigp_client import STAGE_NAMES
+
+# Common mappings across frameworks
+COMMON_MAPPINGS = {
+    "agent_start": 1,       # identity_session_initiation
+    "consent_check": 2,     # consent_policy_determination
+    "pre_check": 3,         # request_registration
+    "prompt_build": 5,      # prompt_assembly
+    "context_retrieve": 7,  # context_retrieval
+    "model_select": 8,      # model_selection
+    "model_invoke": 9,      # runtime_invocation
+    "tool_auth": 10,        # tool_agent_authorization
+    "reasoning": 11,        # intermediate_reasoning
+    "output_gen": 12,       # output_generation
+    "output_release": 13,   # output_release
+    "record": 14,           # post_invocation_record
+    # Agentic
+    "agent_bind": 18,       # agent_identity_binding
+    "delegation": 19,       # delegation_scope_assignment
+    "input_attest": 20,     # input_attestation
+    "tool_runtime": 21,     # tool_authorization_runtime
+    "plan_govern": 22,      # execution_plan_governance
+    "autonomy_eval": 23,    # autonomy_boundary_evaluation
+    "inter_agent": 24,      # inter_agent_communication
+    "memory_gov": 25,       # memory_governance
+    "circuit_break": 26,    # circuit_breaker_evaluation
+}
+
+# Framework-specific mappings
+STRANDS_MAPPINGS = {
+    "Strands Agent": 1,
+    "Cycle": 11,
+    "Model invoke": 9,
+    "Tool": 21,
+}
+
+LANGCHAIN_MAPPINGS = {
+    "on_chain_start": 1,
+    "on_llm_start": 9,
+    "on_llm_end": 12,
+    "on_tool_start": 21,
+    "on_tool_end": 21,
+    "on_retriever_start": 7,
+    "on_chain_end": 13,
+}
+
+CREWAI_MAPPINGS = {
+    "task_start": 22,       # execution_plan_governance
+    "agent_start": 18,      # agent_identity_binding
+    "tool_use": 21,         # tool_authorization_runtime
+    "delegation": 19,       # delegation_scope_assignment
+    "task_end": 13,         # output_release
+}
+
+
+class StageMapper:
+    """Maps framework events to AIGP stage numbers."""
+
+    def __init__(self, framework: str = "common"):
+        if framework == "strands":
+            self._map = STRANDS_MAPPINGS
+        elif framework == "langchain":
+            self._map = LANGCHAIN_MAPPINGS
+        elif framework == "crewai":
+            self._map = CREWAI_MAPPINGS
+        else:
+            self._map = COMMON_MAPPINGS
+
+    def stage_for(self, event_name: str) -> int | None:
+        """Get AIGP stage number for a framework event. Returns None if unmapped."""
+        return self._map.get(event_name) or COMMON_MAPPINGS.get(event_name)
+
+    def stage_name(self, stage: int) -> str:
+        return STAGE_NAMES.get(stage, f"unknown_{stage}")

aigp_agent_core-1.0.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aigp-agent-core"
+version = "1.0.0"
+description = "AIGP Agent Governance Core — shared lifecycle for all framework adapters"
+requires-python = ">=3.11"
+dependencies = ["aigp-client>=3.0.0"]
+
+[project.optional-dependencies]
+evidence = ["amigo-bedrock>=0.2.0"]