Metadata-Version: 2.4
Name: agent-seal-xyz
Version: 0.3.0
Summary: Give your AI agent a signed, verifiable identity in one line.
Project-URL: Homepage, https://agent-seal.xyz
Project-URL: Repository, https://github.com/iPatan7/Dar-al-Adl-Home-of-justice-for-Autonmous-Agents
Project-URL: Verifier, https://agent-seal.xyz/verifier
License: MIT
Keywords: a2a,agent-accountability,agent-identity,agent-registry,ai-agent,dar-al-adl,ed25519,eu-ai-act
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Description-Content-Type: text/markdown

# agent-seal

[![Agent Seal Registry](https://img.shields.io/badge/Agent%20Seal-Registry-blue?style=flat-square)](https://agent-seal.xyz)
[![Verify agents](https://img.shields.io/badge/Verify-agent--seal.xyz%2Fverifier-green?style=flat-square)](https://agent-seal.xyz/verifier)
[![PyPI](https://img.shields.io/pypi/v/agent-seal-xyz?style=flat-square)](https://pypi.org/project/agent-seal-xyz/)

**Give your AI agent a signed, verifiable identity in one line.**

`agent-seal` registers your AI agent with the [Agent Seal Registry](https://agent-seal.xyz) — a court-grade, cryptographic identity system for autonomous agents. Keys are generated locally and never leave your machine; the registry only ever sees public keys and signatures.

## Quick start

```python
from agent_seal_xyz import seal

agent = seal(
    name="my-agent",
    architect="you@email.com",
    capabilities=["code-review"],
)
print(agent.sijil, agent.seal_url)
```

That's it. Your agent now has a public, cryptographically verifiable identity.

## Install

```bash
pip install agent-seal-xyz
```

## CLI

```bash
# Register
agent-seal register --name my-agent --architect you@email.com --capabilities code-review,pr-analysis

# Check status
agent-seal status <agent-id>

# Verify seal and card
agent-seal verify <agent-id>

# Attestation heartbeat — prove the agent is still the sealed agent
agent-seal attest --name my-agent --every 3600

# Check an action against a warrant *before* it runs (the gatekeeper)
agent-seal enforce --warrant chain.json --action "send payment from acct:acme/checking"

# Verify a signed decision receipt offline
agent-seal receipt verify receipt.json --trusted-key <hex>
```

## API

### `seal(name, architect, capabilities=None, *, model="unknown", private_key=None)`

Registers an agent and returns an `AgentRegistration` object.

| Attribute | Type | Description |
|---|---|---|
| `agent.sijil` | `int` | Sijil number in the registry |
| `agent.seal_url` | `str` | URL to the agent's SVG seal |
| `agent.badge_url` | `str` | URL to the embeddable badge |
| `agent.verify_url` | `str` | URL to verify the seal |
| `agent.agent_id` | `str` | UUID in the registry |
| `agent.public_key` | `str` | Hex-encoded Ed25519 public key |
| `agent.manifest_hash` | `str` | SHA-256 hash of the covenant |

### `AgentSealClient(registry_url="https://agent-seal.xyz")`

Lower-level client with `register()`, `status()`, `verify()`, and `attest()`
methods.

### `AgentSealClient.attest(...)` — Drift Monitoring

Sends a signed `agent:attest` heartbeat carrying the DNA sequence recomputed
from the covenant stored at registration (`~/.agent-seal/covenants/`). The
registry compares it to the sealed baseline and reports drift.

```python
from agent_seal_xyz import AgentSealClient

client = AgentSealClient()
result = client.attest(name="my-agent")
print(result["drift"]["decision"]["status"])   # healthy | authorized-evolution | unauthorized-drift
print(result["state"]["attestation"]["health"]) # fresh | drifted | ...
```

Keyword arguments: `agent_id`, `name`, `covenant_path`, `private_key` — one
of the first three is required. Health is public at
`GET /v1/public/agents/{id}/status` → `attestation.health`.

## Warrant Chains, Runtime Enforcement & Decision Receipts

Beyond identity, the SDK ships an offline authority layer — power-of-attorney as
code. A **keeper** issues a signed **warrant** delegating a scoped set of
capabilities to an agent; the agent can **attenuate** (never widen) that scope
down the chain. Every check is pure and offline — no network, no shared secret.

```python
from agent_seal_xyz import (
    issue_warrant, verify_chain,
    enforce_action, enforce_and_receipt, verify_receipt,
)

# 1. A keeper delegates a scoped, time-boxed warrant to an agent
result = issue_warrant(
    issuer={"id": "keeper:acme", "type": "keeper", "publicKey": keeper_pub},
    subject={"id": "agent:seal-1", "type": "agent", "publicKey": agent_pub},
    scope={"capabilities": ["payments.send"], "resources": ["acct:acme/*"]},
    not_after=not_after_iso,
    issuer_private_key=keeper_private_key,
)
chain = result["chain"]
verify_chain(chain).valid  # -> True

# 2. Gate an action *before* it runs
action = {"capability": "payments.send", "resource": "acct:acme/checking"}
decision = enforce_action(chain, action)
decision.allowed  # -> True   (False + code 'resource-out-of-scope' if outside the grant)

# 3. Mint a non-repudiable, signed proof of the decision
decision, receipt = enforce_and_receipt(
    chain, action, signing_key=enforcer_private_key, enforcer_id="gw:1",
)
verify_receipt(receipt, trusted_keys=[enforcer_pub]).valid  # -> True
```

`enforce_action` returns an `EnforceDecision` with `.allowed`, `.code`,
`.reason`, and a full per-gate audit trail in `.checks`. Warrants support
capability + resource scoping, spend budgets, caveats, expiry, and revocation
cascades. Decision receipts are Ed25519-signed and verify offline against a
trusted-key set.

## Key management

On first use, `agent-seal` generates an Ed25519 keypair and stores it at:

```
~/.agent-seal/keys/private.hex   (mode 0600)
~/.agent-seal/keys/public.hex    (mode 0600)
```

The private key never leaves your machine. To re-use an existing identity across environments (e.g., CI), pass `private_key=` as a hex string.

## Error handling

```python
from agent_seal_xyz import seal, AgentSealError, RateLimitError

try:
    agent = seal(name="my-agent", architect="you@email.com")
except RateLimitError as e:
    print(f"Rate limited. Retry in {e.retry_after}s.")
except AgentSealError as e:
    print(f"Registration failed: {e}")
```

Rate-limited requests (HTTP 429) are retried automatically up to 3 times, respecting the `Retry-After` header.

## What is Agent Seal?

[Agent Seal](https://agent-seal.xyz) is a public registry that gives AI agents cryptographic, human-accountable identities. Every registered agent receives a Sijil number, a signed covenant, and a public seal — verifiable by anyone at [agent-seal.xyz/verifier](https://agent-seal.xyz/verifier).

Built for the EU AI Act era: immutable audit trail, liability anchors, and EU AI Act readiness evidence out of the box.

---

[agent-seal.xyz](https://agent-seal.xyz) · [Verify an agent](https://agent-seal.xyz/verifier) · [Registry API](https://agent-seal.xyz/api)
