Metadata-Version: 2.4
Name: agentoath
Version: 0.2.0
Summary: The open protocol for AI agent identity, trust, and notarization.
Author-email: AgentOath Protocol Team <team@agentoath.ai>
License: Apache-2.0
Project-URL: Homepage, https://agentoath.ai
Project-URL: Repository, https://github.com/AgentOath/agentoath
Project-URL: Documentation, https://agentoath.ai/docs
Keywords: ai,agent,trust,identity,notarization,ed25519,protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=41.0
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"

# AgentOath Python SDK

The open protocol for AI agent identity, trust, and notarization.

## Installation

```bash
pip install agentoath
```

## Quick Start

```python
from agentoath import TrustAgent, TrustReceipt

# Create a new Agent identity
agent = TrustAgent.create(
    name="My AI Assistant",
    capabilities=["chat", "search"],
    platform="custom",
)

# Save identity to disk
agent.save("my_agent.json")

# Load identity from disk
agent = TrustAgent.load("my_agent.json")

# Sign a trust receipt after an interaction
receipt = agent.sign_receipt(
    to_agent="did:trust:agent:bbb...",
    action="collaboration",
    rating=9,
    description="Built a great report",
)

# Verify a receipt
is_valid = receipt.verify_from_signature(other_agent.public_key)

# Calculate trust score
score = agent.calculate_trust_score(receipts)
print(f"Trust Score: {score.overall}")
```

## CLI

The SDK includes a command-line tool:

```bash
# Generate a new Agent keypair
agentoath init --name "My Agent" --capabilities "chat,search"

# Display Agent info
agentoath info

# Sign a receipt
agentoath sign-receipt --to did:trust:agent:bbb... --rating 9

# Verify a receipt
agentoath verify-receipt receipt.json --from-key-file agent_key.json

# Compute trust score
agentoath trust-score --receipts receipts.json --target-did did:trust:agent:bbb...
```

## Registry Client

Connect to an AgentOath Registry server:

```python
from agentoath import TrustAgent
from agentoath.registry_client import RegistryClient

agent = TrustAgent.create(name="My Agent")
client = RegistryClient("https://registry.agentoath.ai")

# Register with the Registry
resp = client.register(agent)
print(resp.data["identity_certificate"])

# Publish a receipt
receipt = agent.sign_receipt(to_agent="did:trust:agent:bbb...", rating=9)
client.publish_receipt(receipt)

# Query trust score
score = client.query_trust_score("did:trust:agent:bbb...")
print(score.data)
```

The client supports offline mode -- when the Registry is unreachable, it returns graceful fallback responses instead of crashing.

## API Reference

### TrustAgent

| Method | Description |
|--------|-------------|
| `TrustAgent.create(name, capabilities, platform)` | Create a new Agent with a fresh keypair |
| `TrustAgent.load(path, password)` | Load an Agent from a key file |
| `agent.save(path, password)` | Save the Agent's identity to disk |
| `agent.sign_receipt(to_agent, action, rating)` | Sign a Trust Receipt |
| `agent.counter_sign_receipt(receipt)` | Add a counter-signature |
| `agent.verify_receipt(receipt, from_public_key)` | Verify a receipt's signature |
| `agent.calculate_trust_score(receipts)` | Compute trust score |
| `agent.did` | The Agent's DID |
| `agent.public_key_formatted` | Public key as `ed25519:{base64}` |

### TrustReceipt

| Method | Description |
|--------|-------------|
| `TrustReceipt.create(from_agent_did, from_private_key, to_agent_did)` | Create and sign a receipt |
| `TrustReceipt.from_dict(data)` | Create from a dictionary |
| `receipt.counter_sign(to_private_key)` | Add counter-signature |
| `receipt.verify_from_signature(public_key)` | Verify initiator's signature |
| `receipt.verify_counter_signature(public_key)` | Verify counter-signature |
| `TrustReceipt.verify(receipt_dict, from_public_key)` | Static verification |

### RegistryClient

| Method | Description |
|--------|-------------|
| `client.register(agent)` | Register an Agent |
| `client.get_agent(did)` | Look up an Agent by DID |
| `client.get_agent_card(did)` | Get Agent's public profile |
| `client.search_agents(name, platform, capability)` | Search for Agents |
| `client.publish_receipt(receipt)` | Publish a signed receipt |
| `client.get_receipts(agent_did)` | Get receipts for an Agent |
| `client.verify_receipt(receipt, from_public_key)` | Online verification |
| `client.query_trust_score(agent_did)` | Query trust score |

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=agentoath --cov-report=term-missing
```

## Links

- Website: [agentoath.ai](https://agentoath.ai)
- GitHub: [github.com/AgentOath/agentoath](https://github.com/AgentOath/agentoath)
- Architecture: [docs/architecture.md](https://github.com/AgentOath/agentoath/blob/main/docs/architecture.md)

## License

Apache 2.0
