Metadata-Version: 2.4
Name: agentoath-shadowos
Version: 0.2.0
Summary: AgentOath trust protocol adapter for ShadowOS -- automatic trust receipts for AI agent operations.
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.com/integrate
Keywords: ai,agent,trust,shadowos,agentoath,identity
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
License-File: LICENSE
License-File: NOTICE
Requires-Dist: agentoath<3,>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# AgentOath ShadowOS Adapter

Trust receipts for an AI agent backend, wired in at the pipeline boundary.

This is a standalone adapter for the [AgentOath](https://agentoath.ai) trust
protocol. It depends on `agentoath` and on nothing else -- it contains no
ShadowOS code and does not import ShadowOS. It was written against a FastAPI
agent backend, and the shape it assumes is a common one: an agent that calls
tools, reads and writes memory, and answers over HTTP.

## Quick Start

```bash
pip install agentoath-shadowos
```

```python
from agentoath_shadowos import ShadowOSTrustAdapter

adapter = ShadowOSTrustAdapter.create(agent_name="MyAI Secretary")
adapter.save("agent_identity.json", password="...")

receipt = adapter.record_tool_call(
    tool="send_email",
    outcome="delivered",
    rating=9,
)
```

Reload a persisted identity rather than minting a new one -- a DID is derived
from its key, so creating a second identity means a second agent as far as the
protocol is concerned:

```python
adapter = ShadowOSTrustAdapter.load("agent_identity.json", password="...")
```

## The three pieces

| | |
|---|---|
| `ShadowOSTrustAdapter` | Owns the identity and turns operations into signed receipts |
| `TrustHooks` | `pre_*` / `post_*` pairs to bracket each stage of an agent pipeline |
| `AgentOathMiddleware` | ASGI middleware that adds trust headers to API responses |

## What to record, and what not to

Receipts are public and cannot be deleted. Record the operations somebody may
later need you to prove happened -- an approval, a decision, a promise made to
a customer. Do not record polling, cache hits, or debug traces: it turns the
Registry into a log system, which is not what it is for, and the noise is
permanent.

Recording must never break the operation it describes. Do the work first, then
record, and let recording fail silently:

```python
result = do_the_actual_work()
try:
    adapter.record_tool_call(tool="send_email", outcome="delivered", rating=9)
except Exception:
    pass          # a receipt that fails is not a request that failed
return result
```

## Privacy

The Registry rejects receipts whose metadata contains any of 28 blocked keys --
`prompt`, `email`, `raw`, `transcript`, `token` and similar -- and the match is
on underscore-separated words, so `prompt_hash` and `user_email` are rejected
too. Send a digest, or rename the field to something that is not about the
content. The full list and the reasoning are in the
[integration guide](https://agentoath.com/integrate).

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
