kevros-agent-framework 0.1.1__tar.gz

kevros_agent_framework-0.1.1/.gitignore

@@ -0,0 +1,266 @@
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+
+# Virtual environments
+venv/
+env/
+.venv/
+.env/
+**/venv/
+**/env/
+
+# Logs (generated at runtime)
+logs/*.log
+logs/*.out
+logs/*.jsonl
+logs/*.bak*
+!logs/.gitkeep
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Backups
+*.bak
+*.tmp
+
+# OS
+.DS_Store
+Thumbs.db
+*:Zone.Identifier
+
+# Runtime state (regenerated)
+run/aar/
+run/*.css
+run/*.js
+
+# Temporary
+temp/
+tmp/
+nohup.out
+
+# Demo logs
+demo_logs/*.log
+adapter_logs/*.log
+*.json.json
+
+# Security: Prevent committing private keys
+logs/keyprobe/
+*.raw
+**/ml_dsa_*
+
+# Secrets and keys (added by prod_one_click_fix)
+.env
+.keys/
+keys/
+
+# A2A Gateway runtime data (API key store, payment ledger — NEVER commit)
+a2a_gateway/data/
+
+# Backups and archives
+backups/
+logs/archive/
+
+# Production artifacts and vaults
+taskhawk_production/
+taskhawk_vault/
+vault/
+kernel/
+
+# WASM artifacts
+wasm_kernel/
+wasm_kernel.zip
+
+# Evidence and audit files
+taskhawk_evidence_*.json
+commit_audit_*.md
+
+# Runtime generated
+run/*.json
+run/*.npy
+!run/.keep
+
+# Temporary docker compose files (keep only main, prod, and autogen)
+docker-compose.override.yml
+docker-compose.artifact_stable.yml
+docker-compose.enforcer_module.yml
+docker-compose.fix_enforcer_cmd.yml
+docker-compose.fixpkg.yml
+docker-compose.fixrun.yml
+docker-compose.healthfix.yml
+docker-compose.prod.hotfix.yml
+docker-compose.runtime.stable.yml
+docker-compose.verify.yml
+*.pyd
+run/
+logs/
+**/node_modules/
+frontend/dist/
+backend/__pycache__/
+sdk/**/__pycache__/
+formal/states/
+formal/tla2tools.jar
+*.st
+*.fp
+
+# --- local secrets ---
+.secrets/
+secrets/
+*.key
+*.pem
+*.hex
+
+# --- backups / junk ---
+*.bak
+*.bak.*
+*.swp
+*.tmp
+
+# --- large artifacts ---
+dist/images/
+*.tar
+*.tgz
+*.zip
+publish/
+
+# Extra safety
+**/.keys/
+
+# Frontend build artifacts (do not commit)
+frontend/*.tsbuildinfo
+frontend/vite.config.d.ts
+frontend/vite.config.js
+
+# Git hooks are tracked (shared across team)
+# .githooks/ is NOT ignored - it's version-controlled
+
+# Managed app build artifacts (root-level only, allow marketplace plans)
+mainTemplate.json
+!marketplace/**/plans/**/mainTemplate.json
+!marketplace-commercial/**/plans/**/mainTemplate.json
+!marketplace-gov/**/plans/**/mainTemplate.json
+
+# Marketplace distribution zips (built by packaging scripts)
+**/dist/*.zip
+
+# local per-worktree overrides
+.env.local
+.vs/
+
+# RTL verification artifacts (untracked)
+RTL-KAT/
+
+# Marketing and documentation (untracked)
+website-content/
+/agents/
+*.pptx
+webflow.md
+/wsl_ram_reset.ps1
+
+# Business documents and proposals (confidential, not for code repo)
+proposals/
+patents/
+*.docx
+!correspondence_federal/TaskHawk_CAISI_RFI_Response_*.docx
+!TaskHawk_CAISI_RFI_Response_*.docx
+*_ORIGINAL_BACKUP.docx
+*.xlsx
+!NISTIR-8596-Comments_*.xlsx
+csv/
+
+# Rust build artifacts
+**/target/
+
+# C++ build artifacts
+cpp_enforcer/out/
+cpp_enforcer/build/
+cpp_enforcer/_codeql_build_dir/
+**/CMakeFiles/
+**/cmake-build-*/
+
+# External repositories (cloned locally, not submodules)
+github-mcp-server/
+enforcer-cpp/build/
+
+# Binary documents (not source code)
+*.pbix
+*.pdf
+!website/public/research/*.pdf
+
+# Data exports (regenerable from Azure/compliance tools)
+ControlsExport*.csv
+GroupsExport*.csv
+PolicyComplianceExport*.csv
+
+# Build output (regenerable)
+dist/
+dist-gov/
+
+# Scratch markers (accidental empty files)
+/=
+/reading
+/transferring
+
+# Benchmark and analysis output
+analyze_*/
+benchmarks/
+compliance_report_*.txt
+
+# Session artifacts (notes, dumps)
+resume_session.md
+interesting.md
+think_on_this.md
+
+# Traceability generated artifacts (regenerable via tools/generate_traceability_matrix.py)
+TRACEABILITY_MATRIX.csv
+TRACEABILITY_MATRIX.json
+
+# Windsurf (not used)
+.windsurf/
+
+# Local exploration / scratch
+potential/
+
+# Benchmark dataset cache (downloaded from HuggingFace, regenerable)
+data/benchmark_cache/
+
+# Federal contracting documents (confidential, not for code repo)
+Federal/
+
+# Cost analysis (business document)
+cost-analysis.csv
+
+# MCP server artifacts (external, packaged separately)
+quick_xfer/
+
+# Azure Marketplace UI definition (generated artifacts)
+createUiDefinition.json
+!marketplace/**/plans/**/createUiDefinition.json
+!marketplace-commercial/**/plans/**/createUiDefinition.json
+!marketplace-gov/**/plans/**/createUiDefinition.json
+viewDefinition.json
+!marketplace/**/plans/**/viewDefinition.json
+!marketplace-commercial/**/plans/**/viewDefinition.json
+!marketplace-gov/**/plans/**/viewDefinition.json
+
+# PyPI recovery codes (NEVER commit)
+PyPI-Recovery-Codes-*
+
+# MCP registry auth tokens (NEVER commit)
+.mcpregistry_*
+
+# CDP API keys (NEVER commit)
+cdp_api_key*.json
+
+# mcp-publisher binary (downloaded tool, not source)
+mcp-publisher
+
+# Revenue loop runtime artifacts
+tools/.revenue_loop_state.json
+tools/revenue_loop.log

kevros_agent_framework-0.1.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: kevros-agent-framework
+Version: 0.1.1
+Summary: Kevros Governance Middleware for Microsoft Agent Framework — cryptographic authorization, intent binding, and hash-chained provenance for AI agents.
+Project-URL: Homepage, https://taskhawktech.com
+Project-URL: Governance Gateway, https://governance.taskhawktech.com
+Project-URL: Agent Card, https://governance.taskhawktech.com/.well-known/agent.json
+Author-email: TaskHawk Systems <governance@taskhawktech.com>
+License: BSL-1.1
+Requires-Python: >=3.10
+Requires-Dist: agent-framework>=1.0.0b251001
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: opentelemetry-semantic-conventions-ai==0.4.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: embedded
+Requires-Dist: kevros>=0.3.1; extra == 'embedded'
+Description-Content-Type: text/markdown
+
+# Kevros Governance Middleware for Microsoft Agent Framework
+
+Cryptographic authorization, intent binding, and hash-chained provenance for AI agents built on the [Microsoft Agent Framework](https://github.com/microsoft/agent-framework).
+
+## Install
+
+```bash
+pip install kevros-agent-framework
+```
+
+## Quick Start
+
+```python
+from kevros_agent_framework import (
+    KevrosGovernanceMiddleware,
+    KevrosFunctionMiddleware,
+    KevrosConfig,
+    KevrosGovernanceClient,
+)
+from agent_framework import Agent
+
+# Configure -- API key auto-provisions on first use if omitted
+config = KevrosConfig(api_key="kvrs_...")
+client = KevrosGovernanceClient(config)
+
+# Attach both middleware types, sharing a single client
+agent = Agent(
+    client=chat_client,
+    name="governed-assistant",
+    instructions="You are a helpful assistant.",
+    middleware=[
+        KevrosGovernanceMiddleware(config=config, client=client),
+        KevrosFunctionMiddleware(config=config, client=client),
+    ],
+)
+```
+
+## What It Does
+
+Every agent invocation and tool call is cryptographically governed:
+
+- **Precision decisioning** -- Each agent run is verified against governance policy (ALLOW / CLAMP / DENY) with an HMAC-signed release token
+- **Intent binding** -- Each function call gets a cryptographic intent-to-command binding before execution
+- **Hash-chained provenance** -- Every decision is logged to an append-only, tamper-evident ledger
+
+## Comparison with Purview Policy Middleware
+
+| Aspect | Purview | Kevros |
+|--------|---------|--------|
+| Purpose | Content-level DLP (redact PII, block topics) | Cryptographic authorization + audit evidence |
+| Proof | None (rule-based decision) | HMAC release tokens, hash-chained provenance |
+| Scope | Message content filtering | Action authorization, intent binding, provenance |
+| Relationship | Complementary | Complementary |
+
+Use both: Purview for content safety, Kevros for authorization and evidence.
+
+## Links
+
+- [Kevros Governance Gateway](https://governance.taskhawktech.com)
+- [Agent Card](https://governance.taskhawktech.com/.well-known/agent.json)
+- [Website](https://taskhawktech.com)
+
+## License
+
+BSL-1.1 -- See LICENSE for details.

kevros_agent_framework-0.1.1/README.md

@@ -0,0 +1,65 @@
+# Kevros Governance Middleware for Microsoft Agent Framework
+
+Cryptographic authorization, intent binding, and hash-chained provenance for AI agents built on the [Microsoft Agent Framework](https://github.com/microsoft/agent-framework).
+
+## Install
+
+```bash
+pip install kevros-agent-framework
+```
+
+## Quick Start
+
+```python
+from kevros_agent_framework import (
+    KevrosGovernanceMiddleware,
+    KevrosFunctionMiddleware,
+    KevrosConfig,
+    KevrosGovernanceClient,
+)
+from agent_framework import Agent
+
+# Configure -- API key auto-provisions on first use if omitted
+config = KevrosConfig(api_key="kvrs_...")
+client = KevrosGovernanceClient(config)
+
+# Attach both middleware types, sharing a single client
+agent = Agent(
+    client=chat_client,
+    name="governed-assistant",
+    instructions="You are a helpful assistant.",
+    middleware=[
+        KevrosGovernanceMiddleware(config=config, client=client),
+        KevrosFunctionMiddleware(config=config, client=client),
+    ],
+)
+```
+
+## What It Does
+
+Every agent invocation and tool call is cryptographically governed:
+
+- **Precision decisioning** -- Each agent run is verified against governance policy (ALLOW / CLAMP / DENY) with an HMAC-signed release token
+- **Intent binding** -- Each function call gets a cryptographic intent-to-command binding before execution
+- **Hash-chained provenance** -- Every decision is logged to an append-only, tamper-evident ledger
+
+## Comparison with Purview Policy Middleware
+
+| Aspect | Purview | Kevros |
+|--------|---------|--------|
+| Purpose | Content-level DLP (redact PII, block topics) | Cryptographic authorization + audit evidence |
+| Proof | None (rule-based decision) | HMAC release tokens, hash-chained provenance |
+| Scope | Message content filtering | Action authorization, intent binding, provenance |
+| Relationship | Complementary | Complementary |
+
+Use both: Purview for content safety, Kevros for authorization and evidence.
+
+## Links
+
+- [Kevros Governance Gateway](https://governance.taskhawktech.com)
+- [Agent Card](https://governance.taskhawktech.com/.well-known/agent.json)
+- [Website](https://taskhawktech.com)
+
+## License
+
+BSL-1.1 -- See LICENSE for details.

kevros_agent_framework-0.1.1/kevros_agent_framework/__init__.py

@@ -0,0 +1,44 @@
+"""
+Kevros Governance Middleware for Microsoft Agent Framework.
+
+    pip install kevros-agent-framework
+
+Two modes:
+    Remote (default): pip install kevros-agent-framework
+    Embedded:         pip install kevros-agent-framework[embedded]
+"""
+
+from .config import KevrosConfig
+from .client import KevrosGovernanceClient
+from .models import (
+    Decision, IntentType, IntentSource, OutcomeStatus,
+    VerifyRequest, VerifyResponse,
+    AttestRequest, AttestResponse,
+    BindIntentRequest, BindIntentResponse,
+    VerifyOutcomeRequest, VerifyOutcomeResponse,
+)
+
+from .middleware import KevrosGovernanceMiddleware, GovernanceDeniedException
+from .function_middleware import KevrosFunctionMiddleware
+
+# Embedded provider requires gateway internals (pip install kevros-agent-framework[embedded])
+try:
+    from .embedded import EmbeddedGovernanceProvider
+except ImportError:
+    EmbeddedGovernanceProvider = None  # type: ignore[assignment,misc]
+
+__all__ = [
+    "KevrosConfig",
+    "KevrosGovernanceClient",
+    "KevrosGovernanceMiddleware",
+    "KevrosFunctionMiddleware",
+    "GovernanceDeniedException",
+    "EmbeddedGovernanceProvider",
+    "Decision", "IntentType", "IntentSource", "OutcomeStatus",
+    "VerifyRequest", "VerifyResponse",
+    "AttestRequest", "AttestResponse",
+    "BindIntentRequest", "BindIntentResponse",
+    "VerifyOutcomeRequest", "VerifyOutcomeResponse",
+]
+
+__version__ = "0.1.0"

kevros_agent_framework-0.1.1/kevros_agent_framework/client.py

@@ -0,0 +1,146 @@
+"""
+Remote governance provider -- HTTP client for the Kevros A2A Gateway.
+
+Implements GovernanceProvider protocol. Handles auto-signup, retry,
+and connection lifecycle. Safe to share across middleware instances.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Optional
+
+import httpx
+
+from .config import KevrosConfig
+from .models import (
+    AttestRequest, AttestResponse,
+    BindIntentRequest, BindIntentResponse,
+    SignupRequest, SignupResponse,
+    VerifyRequest, VerifyResponse,
+    VerifyOutcomeRequest, VerifyOutcomeResponse,
+)
+
+logger = logging.getLogger("kevros.middleware")
+
+
+class KevrosGovernanceClient:
+    """
+    HTTP client for Kevros A2A Governance Gateway.
+
+    Implements GovernanceProvider protocol.
+    Use as async context manager for proper lifecycle:
+
+        async with KevrosGovernanceClient(config) as client:
+            result = await client.verify(req)
+    """
+
+    def __init__(self, config: KevrosConfig) -> None:
+        self._config = config
+        self._api_key: Optional[str] = config.api_key or os.environ.get("KEVROS_API_KEY")
+        self._signup_lock = asyncio.Lock()
+        self._http = httpx.AsyncClient(
+            base_url=config.gateway_url,
+            timeout=config.timeout_seconds,
+            headers={"Content-Type": "application/json"},
+        )
+
+    async def __aenter__(self) -> KevrosGovernanceClient:
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()
+
+    async def _ensure_api_key(self) -> str:
+        """Get or create API key via auto-signup. Thread-safe."""
+        if self._api_key:
+            return self._api_key
+
+        async with self._signup_lock:
+            # Double-check after acquiring lock
+            if self._api_key:
+                return self._api_key
+
+            agent_id = self._config.agent_id or "agent-framework-agent"
+            signup_req = SignupRequest(
+                agent_id=agent_id,
+                operator_email=self._config.operator_email or "",
+                operator_name=self._config.operator_name or "",
+            )
+            resp = await self._http.post(
+                "/signup",
+                json=signup_req.model_dump(exclude_none=True),
+            )
+            resp.raise_for_status()
+            signup_resp = SignupResponse.model_validate(resp.json())
+            self._api_key = signup_resp.api_key
+            logger.info(
+                "Kevros auto-signup complete: agent_id=%s tier=%s limit=%d",
+                agent_id, signup_resp.tier, signup_resp.monthly_limit,
+            )
+            return self._api_key
+
+    async def _request_with_retry(
+        self, method: str, path: str, json_body: dict
+    ) -> httpx.Response:
+        """Make an authenticated request with retry logic."""
+        api_key = await self._ensure_api_key()
+        headers = {"X-API-Key": api_key}
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(1 + self._config.max_retries):
+            try:
+                resp = await self._http.request(
+                    method, path, json=json_body, headers=headers,
+                )
+                resp.raise_for_status()
+                return resp
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPStatusError) as exc:
+                last_exc = exc
+                # Don't retry on 4xx client errors (except 429)
+                if isinstance(exc, httpx.HTTPStatusError) and 400 <= exc.response.status_code < 500 and exc.response.status_code != 429:
+                    raise
+                if attempt < self._config.max_retries:
+                    await asyncio.sleep(self._config.retry_backoff_seconds * (attempt + 1))
+
+        raise last_exc  # type: ignore[misc]
+
+    async def verify(self, request: VerifyRequest) -> VerifyResponse:
+        resp = await self._request_with_retry(
+            "POST", "/governance/verify",
+            request.model_dump(exclude_none=True),
+        )
+        return VerifyResponse.model_validate(resp.json())
+
+    async def attest(self, request: AttestRequest) -> AttestResponse:
+        resp = await self._request_with_retry(
+            "POST", "/governance/attest",
+            request.model_dump(exclude_none=True),
+        )
+        return AttestResponse.model_validate(resp.json())
+
+    async def bind_intent(self, request: BindIntentRequest) -> BindIntentResponse:
+        resp = await self._request_with_retry(
+            "POST", "/governance/bind",
+            request.model_dump(exclude_none=True),
+        )
+        return BindIntentResponse.model_validate(resp.json())
+
+    async def verify_outcome(self, request: VerifyOutcomeRequest) -> VerifyOutcomeResponse:
+        resp = await self._request_with_retry(
+            "POST", "/governance/verify-outcome",
+            request.model_dump(exclude_none=True),
+        )
+        return VerifyOutcomeResponse.model_validate(resp.json())
+
+    async def health(self) -> bool:
+        try:
+            resp = await self._http.get("/governance/health")
+            return resp.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    async def close(self) -> None:
+        await self._http.aclose()

kevros_agent_framework-0.1.1/kevros_agent_framework/config.py

@@ -0,0 +1,35 @@
+"""Kevros middleware configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class KevrosConfig:
+    """Immutable configuration for Kevros governance middleware."""
+
+    # Gateway connection
+    gateway_url: str = "https://governance.taskhawktech.com"
+    api_key: Optional[str] = None  # kvrs_... key. If None, auto-signup on first use.
+
+    # Behavior
+    fail_closed: bool = True       # Block agent on gateway errors
+    log_decisions: bool = True     # Log governance decisions to stderr
+    timeout_seconds: float = 5.0   # HTTP timeout per request
+    max_retries: int = 1           # Retries before declaring gateway unreachable (0 = no retry)
+    retry_backoff_seconds: float = 0.5  # Backoff between retries
+
+    # Intent binding
+    bind_intents: bool = True      # Enable function middleware intent binding
+    record_outcomes: bool = True   # Record function results as outcomes
+
+    # Agent identity
+    agent_id: Optional[str] = None          # Override agent ID (defaults to agent name)
+    agent_namespace: Optional[str] = None   # Organizational namespace
+    operator_name: Optional[str] = None     # Legal entity name for signup
+    operator_email: Optional[str] = None    # Contact email for signup
+
+    # Mode
+    embedded: bool = False         # If True, use local GatewayServices instead of HTTP