Metadata-Version: 2.4
Name: rawctx
Version: 0.3.43
Summary: Python SDK and CLI for AI answer evidence, reconciliation, OTel links, and verifiable proof receipts
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.7
Requires-Dist: cryptography>=43.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.11.0
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: ruamel.yaml>=0.18.6

# rawctx

Tamper-proof receipts for your AI's answers.

When an AI answer is challenged, rawctx records what it said, which sources it
used, and a verifiable receipt. It keeps answer evidence and proof review
separate from the agent and observability stack you already run.

## Install

```bash
pip install rawctx
rawctx login
```

You can also mint a no-signup, hash-only browser receipt from the
[rawctx Hub](https://hub.rawctx.dev/). The browser path sends cryptographic
fingerprints instead of the question and answer text.

## Log an answer

```python
import rawctx

receipt = rawctx.log_answer(
    "What is the refund policy?",
    "Customers can request a refund within 30 days.",
)

print(receipt)
```

Hash-centered storage is the default. Workspace settings can enable raw question
and answer text storage, while hashes remain available when text storage is off.

## Queue EZKL verification

Set the workspace endpoint and a UI-issued deployment token in the process
environment:

```ini
RAWCTX_REGISTRY=https://<workspace-api-host>
RAWCTX_TOKEN=<workspace-api-token>
```

After EZKL has generated the proof artifacts, one SDK call creates the answer
log and queues server-side verification:

```python
import rawctx

with rawctx.RawctxClient() as client:
    result = client.create_ezkl_answer_log(
        application_key="ezkl_test",
        input_text="2",
        output_text="2",
        model_path="identity.onnx",
        proof_path="proof.json",
        settings_path="settings.json",
        verification_key_path="vk.key",
        srs_path="kzg.srs",
        idempotency_key="ezkl:identity:run-001",
        backend_version="23.0.5",
    )

print(result["log_id"])
print(result["job_id"], result["proof_job"]["status"])
```

The helper validates the first rescaled public input and output and hashes the
artifacts locally. It queues verification rather than running it locally; the
proof is verified only when the worker reports `adapter_verified`. `srs_path`
is hashed but not uploaded. Use a stable `idempotency_key` for retries because
answer-log and job creation are separate writes.

## What rawctx records

- **Answer record:** application, environment, question and answer text or
  hashes, idempotency key, policy flags, and status.
- **Source evidence:** `source_refs` for documents, registered audio or video
  evidence, answer segments, and purpose-bound retrieval events.
- **Model-run lineage:** model metadata, input and output hashes, configuration
  hashes, trace IDs, and inference commitments.
- **Lifecycle and proof:** correction, void, and redaction events plus Merkle
  inclusion, signed tree-head binding, external anchors, witness receipts, and
  explicit proof status.

rawctx does not generate answers, orchestrate workflows, or replace LangSmith,
Langfuse, or another OpenTelemetry runtime. It records the evidence object that
connects an answer to the sources and trace information needed for review.

## Connect OpenTelemetry evidence

`rawctx.ingest_otel_trace_bundle()` wraps public-safe fields from an existing
OpenTelemetry trace into an answer-audit record. Keep trace ownership in your
current observability system and submit only the identifiers, hashes, and
references needed for answer review.

Do not send observability API keys, private trace URLs, raw tool outputs, or
other secrets to rawctx.

## Check answer-log completeness

Independent reconciliation compares a short-period external reference set with
rawctx answer-audit logs. It detects missing, unexpected, late, duplicate, and
unanchored records without becoming an inline decision gate.

```bash
rawctx reconcile run reconciliation.json --json
rawctx reconcile findings RUN_ID --json
rawctx reconcile proof RUN_ID --output reconciliation-proof.json
rawctx trust verify reconciliation-proof.json --online
```

Use a business-system export, provider usage export, or auditor-controlled
extract that cannot be rewritten in lockstep with the answer logs. Persisted
findings and proofs are commitment-oriented; do not place secrets, raw customer
exports, raw PII, or private system URLs in payload metadata.

## Review proof state

Proof status distinguishes externally anchored records from pending or
local-only evidence. It describes the receipt's verification state; it does not
claim that the submitted answer or upstream trace content is true.

```bash
rawctx trust proof answer ANSWER_LOG_ID --output proof.json
rawctx trust verify proof.json --online --json
```

## Public documentation

- [rawctx Hub](https://hub.rawctx.dev/)
- [Answer Audit](https://hub.rawctx.dev/docs/answer-audit)
- [Independent Reconciliation](https://hub.rawctx.dev/docs/reconciliation)
- [OpenTelemetry integrations](https://hub.rawctx.dev/docs/integrations)
