Metadata-Version: 2.5
Name: agentrust-trace
Version: 0.11.0
Summary: TRACE v0.2: hardware-attested governance records for AI agents
Project-URL: Homepage, https://github.com/agentrust-io/trace-spec
Project-URL: Repository, https://github.com/agentrust-io/trace-spec
Project-URL: Issues, https://github.com/agentrust-io/trace-spec/issues
Project-URL: Changelog, https://github.com/agentrust-io/trace-spec/blob/main/CHANGELOG.md
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-governance,attestation,confidential-computing,eat,rats,tee,trace
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: pydantic>=2.13.5
Requires-Dist: referencing>=0.28
Requires-Dist: rfc3986-validator>=0.1.1
Requires-Dist: rfc8785>=0.1.4
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest>=9.1.1; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-jsonschema; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/icon.svg" width="96" height="96" alt="TRACE"/>
</p>

# TRACE: Trust, Runtime Attestation, and Compliance Evidence

Community updates and contributor highlights: [AgenTrust on LinkedIn](https://www.linkedin.com/company/agentrust-io/).

<p align="center">
  <a href="https://trace.agentrust-io.com">
    <img src="https://img.shields.io/badge/%F0%9F%93%96_Full_Documentation-trace.agentrust--io.com-8251EE?style=for-the-badge&logoColor=white" alt="Full Documentation" height="40">
  </a>
</p>

<p align="center">
  <a href="spec/trace-v0.2.md">Specification</a> &nbsp;|&nbsp;
  <a href="schema/trace-claim.json">Schema</a> &nbsp;|&nbsp;
  <a href="examples/">Examples</a> &nbsp;|&nbsp;
  <a href="https://github.com/agentrust-io/trace-tests">Test Suite</a> &nbsp;|&nbsp;
  <a href="https://github.com/agentrust-io/cmcp">Reference Impl</a>
</p>

[![Specification: Community Specification License 1.0](https://img.shields.io/badge/Specification-Community_Specification_License_1.0-blue.svg)](Governance/COMMUNITY-SPECIFICATION-LICENSE.md)
[![Code: Apache 2.0](https://img.shields.io/badge/Code-Apache_2.0-lightgrey.svg)](LICENSE)
[![Spec](https://img.shields.io/badge/Spec-v0.2-0ea5e9)](spec/trace-v0.2.md)
[![PyPI](https://img.shields.io/pypi/v/agentrust-trace)](https://pypi.org/project/agentrust-trace/)
[![CI](https://github.com/agentrust-io/trace-spec/actions/workflows/ci.yml/badge.svg)](https://github.com/agentrust-io/trace-spec/actions/workflows/ci.yml)
[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat)](https://discord.gg/grgzFEHgkj)

<p align="center">
  <strong>TRACE Specification is an <a href="https://www.linuxfoundation.org/">LF Project</a></strong>, hosted at the Linux Foundation as its own series, "TRACE Specification, a Series of LF Projects, LLC".
</p>

> **Developer Preview.** Launched at Confidential Computing Summit, 23 June 2026. Spec v0.2 is current. See [LIMITATIONS.md](LIMITATIONS.md) before relying on it in production.

An open specification for portable, signed runtime evidence about AI agent runs. TRACE defines the format, anchoring protocol, and verification rules for a record of what an agent ran, where, under which policy, touching which data, and calling which tools, signed so any third party can check it offline. A v0.2 signature proves who produced a record and that it has not changed; hardware provenance needs attestation verified against a trusted root, which the proposed [v0.3 runtime evidence profile](docs/rfcs/runtime-evidence-profile.md) adds.

A TRACE Trust Record answers: _what ran, where, under which policy, touching which data, calling which tools_, in a form any third party can check offline without asking the operator.

## What a Trust Record claims

Each question maps to a field in the record. The signature shows who made each claim and that it has not changed; whether a claim is true needs evidence the verifier checks independently, as [LIMITATIONS.md](LIMITATIONS.md) describes.

| Question | TRACE claim |
|---|---|
| What model ran? | `model.model_id` + `model.weights_digest` |
| Where did it run? | `runtime.platform` + `runtime.measurement` |
| Under which policy? | `policy.bundle_hash` + `policy.enforcement_mode` |
| What data did it touch? | `data_class` |
| Which tools were called? | `tool_transcript.hash` + `tool_transcript.call_count` |
| Is the record independently anchored? | `transparency` (SCITT receipt URI) |

## Quick start

```bash
pip install agentrust-trace
```

```python
import time
from agentrust_trace import generate_key, sign_record

key = generate_key()

record = {
    "eat_profile": "tag:agentrust-io.com,2026:trace-v0.2",
    "iat": int(time.time()),
    "subject": "spiffe://trust.example.org/agent/payments-processor",
    "model": {"provider": "example-provider", "model_id": "example-model-1"},
    "runtime": {"platform": "software-only", "measurement": "sha256:" + "0" * 64},
    "policy": {"bundle_hash": "sha256:" + "b" * 64, "enforcement_mode": "enforce"},
    "data_class": "confidential",
    "build_provenance": {"slsa_level": 1, "digest": "sha256:" + "e" * 64},
    "appraisal": {"status": "none", "verifier": "https://verifier.example.org"},
}

signed = sign_record(record, key)
```
See the [Quickstart guide](https://trace.agentrust-io.com/docs/quickstart/) for key persistence, validation, and anchoring the record to a transparency log.

## Resources

| | |
|---|---|
| 📖 Full documentation | [trace.agentrust-io.com](https://trace.agentrust-io.com) |
| 📄 Specification | [spec/trace-v0.2.md](spec/trace-v0.2.md) |
| 🔍 Schema | [schema/trace-claim.json](schema/trace-claim.json) |
| 📦 PyPI | [agentrust-trace](https://pypi.org/project/agentrust-trace/) |
| 🧪 Test suite | [trace-tests](https://github.com/agentrust-io/trace-tests) |
| 🗂 Registry | [trace-registry](https://github.com/agentrust-io/trace-registry) |
| 🔗 Reference implementation | [cmcp](https://github.com/agentrust-io/cmcp) |
| 💬 Discussions | [GitHub Discussions](https://github.com/orgs/agentrust-io/discussions) |
| 📋 Changelog | [CHANGELOG.md](CHANGELOG.md) |

## Standards alignment

Hosted at the Linux Foundation as its own series, "TRACE Specification, a Series of LF Projects, LLC", under [LF Projects policies](https://lfprojects.org/policies/). The Linux Foundation [announced the contribution](https://www.linuxfoundation.org/press/linux-foundation-welcomes-trace-to-advance-verifiable-runtime-evidence-for-ai-workloads) on 25 August 2026, developed with AMD, Intel, Microsoft, OPAQUE and TII. Builds on [RFC 9711 (EAT)](https://www.rfc-editor.org/rfc/rfc9711), [RFC 9334 (RATS)](https://www.rfc-editor.org/rfc/rfc9334), and SCITT draft-22.

## Frequently asked questions

### What is TRACE?

TRACE (Trust, Runtime Attestation, and Compliance Evidence) is an open specification for hardware-attested AI agent governance records. It defines the record format, the anchoring protocol, and the verification rules for cryptographic evidence that an AI agent ran under a specific policy, in a verified hardware environment, on a given data class, invoking identified tools.

### What does a TRACE Trust Record prove?

A single signed Trust Record answers, in a form any third party can verify without trusting the operator: what model ran, where it ran, under which policy, what data class it touched, which tools were called, and whether the record is independently anchored to a SCITT transparency ledger.

### What standards is TRACE built on?

TRACE builds on open IETF and IRTF standards: RFC 9711 (CBOR Web Token / EAT) for the claim envelope, RFC 9334 (RATS) for the attester, verifier, and relying-party roles, and the SCITT draft for transparency-ledger anchoring.

### How do I create and verify a Trust Record?

Install the library with `pip install agentrust-trace`, sign a record with `sign_record(record, key)`, and check one with `verify_record(record, public_key_or_jwk=trusted_key)`, both imported from `agentrust_trace`. `verify_record` checks the profile URI, the schema, the signature over the RFC 8785 canonical form, and freshness; it checks revocation only when you pass it a revocation source, and it performs no attestation verification. The library does not anchor a record to a transparency ledger: `transparency` is a string member holding the SCITT receipt URI, which a producer fills in once its ledger returns one. The Quickstart page carries a runnable version of both steps.

### How does TRACE relate to AGT and cMCP?

TRACE is the evidence format. AGT and cMCP produce and consume Trust Records, so you can connect them into an end-to-end agent governance pipeline. See the integration guides for details.

### What is the current status of TRACE?

The current specification is TRACE v0.2, published with a conformance test suite. See the Limitations page for scope boundaries before relying on it in production.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and [GOVERNANCE.md](GOVERNANCE.md). All contributors must agree to the [ANTITRUST.md](ANTITRUST.md) policy.
