Metadata-Version: 2.4
Name: tracevity
Version: 0.5.0
Summary: Deterministic local reconstruction inspection and release gating for AI-agent traces.
Author: Independent Product Lab
License-Expression: Apache-2.0
Project-URL: Homepage, https://tracevity.com/
Project-URL: Documentation, https://tracevity.com/cli/
Project-URL: Inspector, https://tracevity.com/inspect/
Project-URL: Gate, https://tracevity.com/gate/
Project-URL: Methodology, https://tracevity.com/methodology/
Project-URL: Feedback, https://github.com/independent-product-lab/tracevity-feedback/issues
Project-URL: Issues, https://github.com/independent-product-lab/tracevity-feedback/issues
Project-URL: Security, https://github.com/independent-product-lab/tracevity-feedback/security/advisories/new
Keywords: ai agents,audit trail,opentelemetry,reconstruction,traceability
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Logging
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE-CLI
Requires-Dist: opentelemetry-proto==1.44.0
Requires-Dist: protobuf==6.33.6
Dynamic: license-file

# Tracevity CLI

**A trace tells you what was recorded. Tracevity tells you what you can reconstruct from it.**

This is the release README for the authorized `0.5.0` Public Beta distribution. Its presence in the
source tree does not establish that PyPI or the canonical documentation domain currently serves the
release; the install and documentation links below become observed release facts only after exact
package and provider readbacks.

Tracevity is a deterministic, local tool for evaluating the evidentiary sufficiency of AI-agent
activity traces. **Inspect** evaluates one selected execution against named reconstruction
requirements. **Gate** compares an accepted baseline with a release or migration candidate and
reports requirement-level reconstruction regressions.

Tracevity is not a telemetry collector, hosted trace viewer, generic semantic-convention checker,
or certification service. Your trace and correlated evidence remain on the machine or CI runner
where the command executes.

## Install

Use an isolated tool environment when possible:

```bash
pipx install tracevity==0.5.0
```

or:

```bash
uv tool install tracevity==0.5.0
```

Conventional installation is also supported:

```bash
python -m pip install tracevity==0.5.0
```

Tracevity 0.5.0 supports CPython 3.11, 3.12, 3.13, and 3.14. Its operational dependency closure is
limited to pinned OTLP protobuf definitions and protobuf itself.

`tracevity --version`, the current Inspector engine, and the current Gate engine all identify
version `0.5.0`. Current reports use additive Reconstruction Report v0.2 and Gate Report v0.2
contracts. Historical v0.1 reports remain readable; their historical engine identities are not
rewritten. Exact packaged engine and resource bytes contribute to report build identity, so changes
remain visible and sealed reports are never treated as interchangeable without an exact
compatibility check.

## Quickstart

Download, verify, and extract the safe synthetic example bundle from
[tracevity.com/cli](https://tracevity.com/cli/), then run these commands from the extracted bundle
directory. No production trace is needed.

```bash
tracevity --version

tracevity traces list --manifest inspect/manifest.json

tracevity inspect \
  --manifest inspect/manifest.json \
  --requirements inspect/requirements.json \
  --out reconstruction-report.json

tracevity gate \
  --suite gate/tracevity-gate.json \
  --out tracevity-gate-report.json
```

`traces list` returns bounded structural information for explicit target selection. It does not
print prompts, outputs, tool arguments, tool results, or arbitrary captured attributes.

## Capture and destination evidence

Start the bounded loopback receiver before running an OTLP HTTP/protobuf exporter:

```bash
tracevity capture otlp \
  --listen 127.0.0.1:4318 \
  --out trace.otlp.pb \
  --receipt capture-receipt.json
```

The receiver accepts only `/v1/traces` on IPv4 loopback, enforces request, byte, span, and idle-time
bounds, combines valid batches, and never uploads or prints captured values.

Tracevity ships one deliberately narrow, read-only destination adapter:

```bash
tracevity evidence github issue-comment \
  --repo OWNER/REPOSITORY \
  --comment-id COMMENT_ID \
  --out github-evidence.json
```

It reads exactly one existing issue or pull-request comment from `api.github.com`. Public comments
can be read without authentication. For private repositories or higher rate limits, set
`TRACEVITY_GITHUB_TOKEN` in the environment; command-line tokens and custom API origins are not
accepted. The envelope stores a body SHA-256, not the comment body. Provider API retrieval is
external-system evidence with unverified record authenticity; HTTPS, ETags, and request IDs are not
cryptographic proof.

Render either report locally as inert HTML and/or Markdown:

```bash
tracevity report render reconstruction-report.json \
  --html reconstruction-report.html \
  --markdown reconstruction-report.md
```

## Supported trace declarations

The Inspector accepts OTLP trace protobuf for four exact declared representations:

| Declaration                      | Supported version                          | Evidence binding                 |
| -------------------------------- | ------------------------------------------ | -------------------------------- |
| OpenTelemetry GenAI              | `67dff024110be5bd9f318006e733f4078e0f4c97` | `binding-otel-genai-to-otlp`     |
| OpenInference                    | `0.1.33`                                   | `binding-openinference-to-otlp`  |
| MLflow native tracing            | `3.15.2`                                   | `binding-mlflow-native-to-otlp`  |
| MLflow GenAI-transformed tracing | `3.15.2`                                   | `binding-mlflow-native-to-genai` |

OTLP logs and metrics are recognized but unsupported as primary trace inputs. A structurally valid
OTLP payload does not prove producer identity, complete capture, or semantic sufficiency.

## Gate exits

| Exit | Meaning                                                                    |
| ---: | -------------------------------------------------------------------------- |
|  `0` | No policy-blocking reconstruction regression                               |
|  `2` | Blocking reconstruction regression                                         |
|  `3` | Required result became indeterminate, or a sealed baseline is incomparable |
|  `4` | Invalid suite, policy, baseline, manifest, evidence, or input              |
|  `5` | Unsupported signal, dialect, version, or representation                    |
| `70` | Internal invariant or prohibited-network failure                           |

Gate compares reconstruction consequences for named requirements, not raw span counts or field
sets. Replayable baseline and candidate inputs run through the same current Inspector. An
incompatible sealed report yields `INCOMPARABLE_REQUIRES_REBASE`; it is never silently accepted.

## Privacy, network, and semantic limits

`inspect`, `gate`, `traces list`, and `report render` make no network requests. `capture otlp` opens
only the loopback listener the operator requests. The GitHub evidence adapter makes one explicit,
bounded outbound read to the official GitHub REST API. No command contacts a Tracevity service,
emits Tracevity analytics, calls a model, uploads a trace, creates an account, performs an update
check, sends a crash report, or keeps a hidden input cache. Trace contents remain local and are
never executed.

Keep these boundaries explicit:

```text
tool success != external settlement
agent identity != initiating principal
valid OTLP != sufficient reconstruction
recorded rationale != hidden reasoning
Gate pass != certification
```

Tracevity reports what supplied evidence establishes for a named use case. An exactly correlated
provider record can corroborate destination state without becoming cryptographically authenticated.
Tracevity does not reveal true latent motivation, prove omitted evidence never existed, certify an
arbitrary producer, or turn a tool-reported result into independently verified external state.

## Documentation and feedback

- [CLI documentation](https://tracevity.com/cli/)
- [Inspector](https://tracevity.com/inspect/)
- [Gate](https://tracevity.com/gate/)
- [Methodology](https://tracevity.com/methodology/)
- [Bug reports and corrections](https://github.com/independent-product-lab/tracevity-feedback/issues)
- [Private security report](https://github.com/independent-product-lab/tracevity-feedback/security/advisories/new)

Never post production traces, prompts, outputs, credentials, secrets, customer data, or private logs
to a public issue.

## License

Files included in the public Python distribution and its bundled public runtime resources are
licensed under Apache-2.0. See `LICENSE-CLI` in the distribution. That scoped license does not
relicense the private Tracevity monorepo or material not included in the wheel/source distribution.
