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.
