imperial-a2a 1.0.1__tar.gz

imperial_a2a-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Lambert / NanoEmpire AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imperial_a2a-1.0.1/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: imperial-a2a
+Version: 1.0.1
+Summary: Agent-to-Agent (A2A) task routing system with audit trails, policy engine, reputation tracking, and gateway
+Home-page: https://github.com/robertlambertnano/empire
+Author: Robert Lambert
+Author-email: Robert Lambert / NanoEmpire AI <roblambert9@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Robert Lambert / NanoEmpire AI
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://neuralempireai.com
+Project-URL: Repository, https://github.com/roblambert9/nano-empire-ai
+Project-URL: Documentation, https://github.com/roblambert9/nano-empire-ai/blob/master/docs/x402-integration-guide.md
+Project-URL: Bug Tracker, https://github.com/roblambert9/nano-empire-ai/issues
+Keywords: a2a,agent,routing,audit,policy,reputation,gateway,lifecycle
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: croniter>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: aiohttp>=3.8.0; extra == "dev"
+Requires-Dist: uvicorn>=0.27.0; extra == "dev"
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8.0; extra == "async"
+Provides-Extra: gateway
+Requires-Dist: uvicorn>=0.27.0; extra == "gateway"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Empire A2A (Agent-to-Agent) Task Routing System
+
+A production-grade Agent-to-Agent (A2A) task routing system with persistent storage, audit trails, policy enforcement, reputation tracking, cross-node transport, task composition, scheduling, caching, multi-tenant isolation, and external SDK/observability.
+
+## Features
+
+- **Capability-Based Routing**: Route tasks to agents based on capabilities, load, cost, latency, affinity, or round-robin
+- **Persistent Storage**: SQLite-backed task storage with WAL mode for concurrent access
+- **Tamper-Evident Audit Trails**: SHA-256 chained audit logs with integrity verification
+- **Full Lifecycle Tracking**: 10-state task machine with persistence hooks and timeout recovery
+- **Policy Engine**: Hot-reloadable YAML policies with ALLOW/DENY/REQUIRE rules and budget caps
+- **Reputation System**: Exponential decay scoring with sliding window metrics and p50/p95 latency tracking
+- **Mesh Transport**: Cross-node HTTP transport via Tailscale with retry/backoff and circuit breaking
+- **Task Composition**: DAG decomposition with topological sort and 6 aggregation strategies
+- **Scheduler**: Cron expression parser with shortcuts (@hourly, @daily, etc.) and jitter support
+- **Result Cache**: Hash-based cache with per-capability TTLs and automatic invalidation
+- **Multi-Tenant Isolation**: Workspace-based isolation with explicit cross-workspace allowlists
+- **Client SDK**: Sync and async clients with HMAC request signing
+- **Observability**: Prometheus metrics endpoint and deep health checks
+- **Gateway Service**: FastAPI REST/WebSocket service with HMAC authentication and rate limiting
+
+## Installation
+
+```bash
+pip install imperial-a2a
+```
+
+For development dependencies:
+```bash
+pip install imperial-a2a[dev]
+```
+
+For async client:
+```bash
+pip install imperial-a2a[async]
+```
+
+For full gateway:
+```bash
+pip install imperial-a2a[gateway]
+```
+
+## Quick Start
+
+```python
+from imperial_a2a import (
+    get_a2a_router,
+    get_lifecycle,
+    get_audit_trail,
+    get_policy_engine,
+    get_reputation_engine,
+    get_task_store,
+    A2AClient,
+    sign_request
+)
+
+# Initialize components
+router = get_a2a_router()
+lifecycle = get_lifecycle()
+audit = get_audit_trail()
+policy = get_policy_engine()
+reputation = get_reputation_engine()
+store = get_task_store()
+
+# Register an agent capability
+router.register_agent_capability(
+    agent_id="agent-001",
+    capability=AgentCapability(
+        agent_id="agent-001",
+        capability_id="text-summarization",
+        description="Summarizes text documents",
+        input_schema={"type": "object", "properties": {"text": {"type": "string"}}},
+        output_schema={"type": "object", "properties": {"summary": {"type": "string"}}},
+        cost_per_task=0.001,
+        avg_latency_ms=500,
+        max_concurrent=5
+    )
+)
+
+# Submit a task via client
+client = A2AClient(gateway_url="http://localhost:8000")
+result = client.submit_task(
+    capability_id="text-summarization",
+    input_data={"text": "Long document to summarize..."},
+    priority=TaskPriority.NORMAL
+)
+
+# Check task status
+status = client.get_task_status(result.task_id)
+```
+
+## Running the Gateway
+
+```bash
+uvicorn imperial_a2a.gateway:create_gateway --host 0.0.0.0 --port 8000
+```
+
+## Configuration
+
+The policy engine loads YAML configuration from `empire/config/a2a_policy.yaml` by default:
+
+```yaml
+version: 1
+rules:
+  - effect: DENY
+    scope: GLOBAL
+    when:
+      agent_id: "blocked-agent-001"
+    description: "Block specific agent"
+  - effect: REQUIRE
+    scope: CAPABILITY
+    when:
+      capability_id: "high-risk-operation"
+    then:
+      - effect: DENY
+        when:
+          reputation_score: {"<": 0.5}
+        description: "Require good reputation for high-risk ops"
+budgets:
+  - agent_id: "agent-001"
+    capability_id: "premium-service"
+    daily_limit: 100.0
+    description: "Daily budget for premium service"
+```
+
+## API Endpoints
+
+### Gateway (`/`)
+- `POST /tasks` - Submit a new task
+- `GET /tasks/{task_id}` - Get task status
+- `GET /tasks` - List tasks with filters
+- `POST /tasks/{task_id}/cancel` - Cancel a task
+- `GET /agents/{agent_id}` - Get agent info
+- `GET /capabilities` - List capabilities
+- `GET /health` - Basic health check
+- `GET /health/deep` - Deep health check (503 if unhealthy)
+- `GET /metrics` - Prometheus metrics
+- `WS /ws/{client_id}` - WebSocket for real-time updates
+
+### Observability
+- Prometheus metrics available at `/metrics` endpoint
+- Deep health checks at `/health/deep`
+- Structured JSON logging available via `setup_structured_logging()`
+
+## Testing
+
+Run the test suite:
+```bash
+pytest empire/tests/ -v
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Empire Integration
+
+This A2A system is designed to integrate with the Nano Empire AI operating system. It exposes metrics and health endpoints that can be scraped by the empire observability system.
+
+For integration with the empire dashboard, see `empire/viz/empire_dashboard.py` which includes A2A-specific health checks and metrics.

imperial_a2a-1.0.1/README.md

@@ -0,0 +1,160 @@
+# Empire A2A (Agent-to-Agent) Task Routing System
+
+A production-grade Agent-to-Agent (A2A) task routing system with persistent storage, audit trails, policy enforcement, reputation tracking, cross-node transport, task composition, scheduling, caching, multi-tenant isolation, and external SDK/observability.
+
+## Features
+
+- **Capability-Based Routing**: Route tasks to agents based on capabilities, load, cost, latency, affinity, or round-robin
+- **Persistent Storage**: SQLite-backed task storage with WAL mode for concurrent access
+- **Tamper-Evident Audit Trails**: SHA-256 chained audit logs with integrity verification
+- **Full Lifecycle Tracking**: 10-state task machine with persistence hooks and timeout recovery
+- **Policy Engine**: Hot-reloadable YAML policies with ALLOW/DENY/REQUIRE rules and budget caps
+- **Reputation System**: Exponential decay scoring with sliding window metrics and p50/p95 latency tracking
+- **Mesh Transport**: Cross-node HTTP transport via Tailscale with retry/backoff and circuit breaking
+- **Task Composition**: DAG decomposition with topological sort and 6 aggregation strategies
+- **Scheduler**: Cron expression parser with shortcuts (@hourly, @daily, etc.) and jitter support
+- **Result Cache**: Hash-based cache with per-capability TTLs and automatic invalidation
+- **Multi-Tenant Isolation**: Workspace-based isolation with explicit cross-workspace allowlists
+- **Client SDK**: Sync and async clients with HMAC request signing
+- **Observability**: Prometheus metrics endpoint and deep health checks
+- **Gateway Service**: FastAPI REST/WebSocket service with HMAC authentication and rate limiting
+
+## Installation
+
+```bash
+pip install imperial-a2a
+```
+
+For development dependencies:
+```bash
+pip install imperial-a2a[dev]
+```
+
+For async client:
+```bash
+pip install imperial-a2a[async]
+```
+
+For full gateway:
+```bash
+pip install imperial-a2a[gateway]
+```
+
+## Quick Start
+
+```python
+from imperial_a2a import (
+    get_a2a_router,
+    get_lifecycle,
+    get_audit_trail,
+    get_policy_engine,
+    get_reputation_engine,
+    get_task_store,
+    A2AClient,
+    sign_request
+)
+
+# Initialize components
+router = get_a2a_router()
+lifecycle = get_lifecycle()
+audit = get_audit_trail()
+policy = get_policy_engine()
+reputation = get_reputation_engine()
+store = get_task_store()
+
+# Register an agent capability
+router.register_agent_capability(
+    agent_id="agent-001",
+    capability=AgentCapability(
+        agent_id="agent-001",
+        capability_id="text-summarization",
+        description="Summarizes text documents",
+        input_schema={"type": "object", "properties": {"text": {"type": "string"}}},
+        output_schema={"type": "object", "properties": {"summary": {"type": "string"}}},
+        cost_per_task=0.001,
+        avg_latency_ms=500,
+        max_concurrent=5
+    )
+)
+
+# Submit a task via client
+client = A2AClient(gateway_url="http://localhost:8000")
+result = client.submit_task(
+    capability_id="text-summarization",
+    input_data={"text": "Long document to summarize..."},
+    priority=TaskPriority.NORMAL
+)
+
+# Check task status
+status = client.get_task_status(result.task_id)
+```
+
+## Running the Gateway
+
+```bash
+uvicorn imperial_a2a.gateway:create_gateway --host 0.0.0.0 --port 8000
+```
+
+## Configuration
+
+The policy engine loads YAML configuration from `empire/config/a2a_policy.yaml` by default:
+
+```yaml
+version: 1
+rules:
+  - effect: DENY
+    scope: GLOBAL
+    when:
+      agent_id: "blocked-agent-001"
+    description: "Block specific agent"
+  - effect: REQUIRE
+    scope: CAPABILITY
+    when:
+      capability_id: "high-risk-operation"
+    then:
+      - effect: DENY
+        when:
+          reputation_score: {"<": 0.5}
+        description: "Require good reputation for high-risk ops"
+budgets:
+  - agent_id: "agent-001"
+    capability_id: "premium-service"
+    daily_limit: 100.0
+    description: "Daily budget for premium service"
+```
+
+## API Endpoints
+
+### Gateway (`/`)
+- `POST /tasks` - Submit a new task
+- `GET /tasks/{task_id}` - Get task status
+- `GET /tasks` - List tasks with filters
+- `POST /tasks/{task_id}/cancel` - Cancel a task
+- `GET /agents/{agent_id}` - Get agent info
+- `GET /capabilities` - List capabilities
+- `GET /health` - Basic health check
+- `GET /health/deep` - Deep health check (503 if unhealthy)
+- `GET /metrics` - Prometheus metrics
+- `WS /ws/{client_id}` - WebSocket for real-time updates
+
+### Observability
+- Prometheus metrics available at `/metrics` endpoint
+- Deep health checks at `/health/deep`
+- Structured JSON logging available via `setup_structured_logging()`
+
+## Testing
+
+Run the test suite:
+```bash
+pytest empire/tests/ -v
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Empire Integration
+
+This A2A system is designed to integrate with the Nano Empire AI operating system. It exposes metrics and health endpoints that can be scraped by the empire observability system.
+
+For integration with the empire dashboard, see `empire/viz/empire_dashboard.py` which includes A2A-specific health checks and metrics.