Metadata-Version: 2.4
Name: arsia-protocol
Version: 1.0.0.post1
Summary: ARSIA Protocol SDK — EdDSA signing, message types, compliance profiles for autonomous AI agent infrastructure
Project-URL: Homepage, https://arsiaprotocol.org
Project-URL: Documentation, https://arsiaprotocol.org
Project-URL: Repository, https://github.com/arsialabs/arsia-protocol-sdk
Project-URL: Specification, https://github.com/arsialabs/arsia-protocol
Project-URL: Changelog, https://github.com/arsialabs/arsia-protocol-sdk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/arsialabs/arsia-protocol-sdk/issues
Author-email: Kirk Patrick <kirk@arsialabs.ai>, Greici Savoldi <greici@arsialabs.ai>
License-Expression: BUSL-1.1
License-File: LICENSE
License-File: NOTICE
Keywords: agents,ai-agents,arsia,arsia-protocol,audit,autonomous-agents,compliance,dora,ed25519,eddsa,eu-ai-act,gdpr,jcs,mifid
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Legal Industry
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: cryptography>=43.0
Requires-Dist: jsonschema>=4.21.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: rfc8785>=0.1.4
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: click>=8.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: types-jsonschema>=4.21.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Description-Content-Type: text/markdown

# arsia-protocol — Python SDK

[![PyPI](https://img.shields.io/pypi/v/arsia-protocol)](https://pypi.org/project/arsia-protocol/)
[![Python](https://img.shields.io/pypi/pyversions/arsia-protocol)](https://pypi.org/project/arsia-protocol/)
[![License](https://img.shields.io/badge/license-BSL_1.1-blue)](https://github.com/arsialabs/arsia-protocol-sdk/blob/main/LICENSE.md)
[![Typed](https://img.shields.io/badge/typed-mypy%20%7C%20pyright-brightgreen)](https://github.com/arsialabs/arsia-protocol-sdk)

Reference Python implementation of the
[ARSIA Protocol](https://github.com/arsialabs/arsia-protocol): the
compliance-enforced communication layer for autonomous AI agents. The SDK
builds, signs, verifies, and validates ARSIA message envelopes. It is
**transport-agnostic** — you choose HTTP, WebSocket, gRPC, MCP, A2A,
stdio, or anything else.

Fully typed — works with mypy, pyright, and IDE autocompletion out of the box.

## Install

```bash
pip install arsia-protocol                # core SDK
pip install "arsia-protocol[cli]"         # plus the `arsia` CLI
pip install "arsia-protocol[dev]"         # development (tests, mypy, ruff)
```

## Quickstart

```python
from arsia_protocol import (
    create_request, generate_ed25519_keypair, sign_message, verify_message,
)

# 1. Generate an Ed25519 keypair (developer convenience — use an HSM / KMS
#    in production).
priv, pub = generate_ed25519_keypair()
kid = "agent:acme.bot#k1"

# 2. Build a signed request envelope.
envelope = create_request(
    from_agent="agent:acme.bot",
    to_agent="agent:other.svc",
    payload_type="com.arsiaprotocol.echo",
    capabilities=["com.arsiaprotocol.echo"],
    args={"msg": "hello"},
)
signed = sign_message(envelope, priv, kid)

# 3. On the recipient side — verify the signature.
assert verify_message(signed, pub) is True
```

### Validate against schema + semantics

```python
from arsia_protocol import validate_schema, validate_semantic

l1_errors = validate_schema(signed)       # L1: JSON Schema (Draft 2020-12)
l2_errors = validate_semantic(signed)     # L2: timestamps, kid match, etc.
assert l1_errors == [] and l2_errors == []
```

### Apply a compliance profile

```python
from arsia_protocol import apply_profile

# The envelope must declare compliance.profile — apply_profile reads it
# from there and inherits the profile's defaults (retention, jurisdiction, …).
envelope["compliance"] = {"profile": "GDPR-STANDARD"}
enriched = apply_profile(envelope)         # strict=False by default
```

## Key Concepts

### verify vs. validate

| Function | What it checks | Question it answers |
|----------|---------------|---------------------|
| `verify_message(envelope, pub_key)` | Ed25519/ES256 signature | "Was this signed by the claimed sender?" |
| `validate_schema(envelope)` | JSON Schema (Draft 2020-12) | "Does this match the ARSIA envelope structure?" |
| `validate_semantic(envelope)` | Cross-field rules (timestamps, kid prefix, capabilities) | "Is this envelope internally consistent?" |
| `validate_envelope(envelope)` | Both schema + semantic (convenience) | "Is this well-formed and consistent?" |

A typical receiver calls both: `verify_message()` to trust the sender, then
`validate_envelope()` to trust the content.

### build_* vs. create_* naming

- **`create_*`** (7 functions) — envelope-level factories that produce a
  complete, signable ARSIA envelope: `create_request`, `create_response`,
  `create_error`, `create_event`, `create_pending_approval`,
  `create_approval_decision`, `create_rollback_request`.

- **`build_*`** (49 functions) — sub-component builders that produce parts of
  envelopes: audit records, error details, JWKs, state operation arguments,
  discovery documents, etc.

Rule of thumb: if it returns a complete envelope ready to sign, it's `create_*`.
If it returns a component or record, it's `build_*`.

## `arsia` CLI

```bash
pip install "arsia-protocol[cli]"

arsia keygen --kid agent:acme.bot#k1        # generate Ed25519 key material
arsia verify envelope.json --jwk sender.jwk # verify a signed envelope
arsia canonicalize doc.json                 # emit RFC 8785 canonical bytes
arsia inspect envelope.json                 # pretty-print with diagnostics
arsia schemas                               # list bundled JSON Schemas
arsia vectors                               # list bundled test vectors
arsia profiles GDPR-STANDARD                # print a compliance profile
```

## What the SDK does NOT do

- **Transport** (HTTP, WebSocket, MCP, A2A) — that's `arsiactl`, not the SDK.
- **Agent execution**, planning, tool use — that's the agent framework.
- **Audit trail storage** — the SDK builds audit records; it does not persist them.
- **OAuth2 issuance** — the SDK validates tokens, does not issue them.
- **Payload interpretation** — the SDK signs and verifies envelopes; it never inspects payload content beyond routing-relevant fields.

## Documentation

| Resource | Description |
|----------|-------------|
| [Learning Path](https://github.com/arsialabs/arsia-protocol-sdk/blob/main/python/docs/learning-path.md) | Step-by-step guide from install to production |
| [Concepts](https://github.com/arsialabs/arsia-protocol-sdk/blob/main/python/docs/concepts.md) | Mental model: envelopes, lifecycle, naming, profiles |
| [Cookbook](https://github.com/arsialabs/arsia-protocol-sdk/blob/main/python/docs/cookbook.md) | 22 copy-pasteable recipes for common tasks |
| [Examples](https://github.com/arsialabs/arsia-protocol-sdk/tree/main/python/examples) | 14 runnable scripts (10 basic + 4 regulated use cases) |
| [API Reference](https://github.com/arsialabs/arsia-protocol-sdk/tree/main/python/docs/api) | Full API documentation (run `mkdocs serve`) |

## Development

```bash
cd python
pip install -e ".[dev]"
pytest tests/ -v
mypy src/arsia_protocol/
ruff check src/
ruff format src/
```

## Links

- **Specification:** <https://github.com/arsialabs/arsia-protocol>
- **Repository:** <https://github.com/arsialabs/arsia-protocol-sdk>
- **Website:** <https://arsiaprotocol.org>
- **Issues:** <https://github.com/arsialabs/arsia-protocol-sdk/issues>
- **Changelog:** [CHANGELOG.md](https://github.com/arsialabs/arsia-protocol-sdk/blob/main/CHANGELOG.md)

---

ARSIA Protocol ([arsiaprotocol.org](https://arsiaprotocol.org)) ·
by [Arsia Labs](https://arsialabs.ai) · BSL 1.1
