Metadata-Version: 2.4
Name: rawctx
Version: 0.3.50
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
Provides-Extra: ezkl
Requires-Dist: ezkl==23.0.5; extra == "ezkl"
Provides-Extra: aws-kms
Requires-Dist: boto3<2,>=1.38.0; extra == "aws-kms"

# rawctx

Tamper-evident records and receipts for submitted AI answers.

When an AI answer is challenged, rawctx records the submitted answer and source
references, then creates a receipt that can be checked for later changes. It
keeps answer evidence and proof review separate from the agent and observability
stack you already run.

The receipt binds the values submitted to rawctx. It does not prove that the
model used a referenced source, that an answer is factually correct, or that a
source export is complete and truthful.

## 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.",
    project_key="support-assistant",
)

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.

## Select a project and environment

Projects separate applications or services inside one workspace. Environments
belong to a project and are used for filtering and deployment-specific
credentials.

```bash
rawctx projects list
rawctx projects create support-assistant \
  --display-name "Support assistant" \
  --default-environment production
rawctx environments create staging --project support-assistant
rawctx projects use support-assistant --environment production
rawctx credential create production-writer \
  --project support-assistant \
  --scope answer_audit:create
```

`credential create` prints the plaintext project token once. Store it in a
secret manager. Use `rawctx credential revoke CREDENTIAL_ID --project PROJECT`
to revoke it.

Applications can select context explicitly or through environment variables:

```python
with rawctx.RawctxClient(
    project="support-assistant",
    environment="production",
) as client:
    client.create_answer_log(question_text="Question", answer_text="Answer")
```

```ini
RAWCTX_PROJECT=support-assistant
RAWCTX_ENVIRONMENT=production
```

Use `project_key` in new code. `application_key` is deprecated but remains
available for older integrations. Existing flat answer and reconciliation API
endpoints still send it. If a `project_key` call omits the environment, the
server uses the Project's default.

## Queue EZKL verification

Install the optional prover runtime and prepare `rawctx.ezkl.json` once with
the ONNX model, compiled circuit, settings, PK, VK, and workspace-compatible
SRS paths:

```bash
pip install 'rawctx[ezkl]'
```

```json
{
  "schema": "rawctx.ezkl.project.v1",
  "model_path": "ezkl/model.onnx",
  "compiled_circuit_path": "ezkl/network.compiled",
  "settings_path": "ezkl/settings.json",
  "proving_key_path": "ezkl/pk.key",
  "verification_key_path": "ezkl/vk.key",
  "srs_path": "ezkl/kzg.srs",
  "srs_ref": "kzg_srs_v1"
}
```

Paths are relative to `rawctx.ezkl.json`. Set `RAWCTX_EZKL_CONFIG` when the
file is stored elsewhere.

Set the workspace endpoint and a Project credential in the process environment.
Use a workspace login token only for Project and credential administration:

```ini
RAWCTX_REGISTRY=https://<workspace-api-host>
RAWCTX_TOKEN=<project-credential>
RAWCTX_PROJECT=ezkl-test
```

At runtime, no artifact path is passed. The SDK generates and locally verifies
the proof, creates the answer log, and queues server verification:

```python
import rawctx

with rawctx.RawctxClient() as client:
    result = client.run_ezkl_and_log(
        project_key="ezkl-test",
        input_data=[[2.0]],
        idempotency_key="ezkl:identity:run-001",
    )

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

The helper supports a single public rescaled numeric input and output. Local
verification is followed by an asynchronous server job, so `queued` is not the
final result; wait for `adapter_verified`. The SRS must match the workspace's
pinned `kzg_srs_v1` bundle and must not be regenerated with EZKL. Use a stable
`idempotency_key` 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 orchestrate model or agent inference and does not replace
LangSmith, Langfuse, or another OpenTelemetry runtime. Its optional EZKL helper
only runs the proof lifecycle for an already prepared ONNX circuit. rawctx
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.

For the usual workflow, upload a CSV or JSON file in **Logs > Reconciliation**.
The Hub checks the file, creates a review request, and waits for a different
Project manager to approve it. After approval, the Hub signs the received
content with its AWS KMS ML-DSA key and starts the run.

The basic CSV needs `decision_id` and `decided_at`. It may also contain
`outcome`, `answer_hash`, `model_ref_hash`, `config_hash`, `context_hash`,
`external_record_id`, and `metadata`.

```csv
decision_id,decided_at
mod-123,2026-08-12T09:13:00Z
```

JSON may be a record array or an object with a `reference_records` array. The
server derives the period from the uploaded `decided_at` values. The Hub accepts
up to 10,000 records, a period of at most seven days, and files up to 16 MiB.

This is a **Hub-managed attestation**. It binds the file and normalized records
from the time the Hub receives them through review and submission. It does not
show that the customer source system created the file, or that the file includes
every source-system record.

### Advanced: customer-managed source signature

Use the signed manifest flow when the source export job must sign before the
file reaches the Hub. This CSV format is stricter: all four columns must be
present, although the last two values may be empty.

```csv
decision_id,decided_at,outcome,external_record_id
mod-123,2026-08-12T09:13:00Z,blocked,row-987
```

```bash
pip install 'rawctx[aws-kms]'

rawctx reconcile prepare moderation.csv \
  --output source-manifest.json \
  --source-key moderation-daily-export \
  --period-start 2026-08-12T00:00:00Z \
  --period-end 2026-08-13T00:00:00Z \
  --project-key moderation-agent \
  --environment production \
  --export-id moderation-2026-08-12 \
  --producer-principal source:moderation-exporter \
  --signature-key-id moderation-prod-v1 \
  --aws-kms-key-id arn:aws:kms:ap-northeast-2:111122223333:key/KEY_ID

rawctx reconcile submit-for-review source-manifest.json --json
```

The customer-managed manifest binds the CSV hash, scope, options, metadata, and
every record before upload. The server verifies the ML-DSA signature with the
registered customer source key. A different Project manager reviews it in
**Logs > Reconciliation**; approval submits the run automatically. CSV input
accepts UTF-8 with or without a BOM, preserves duplicates, requires
timezone-aware timestamps, and rejects more than 10,000 records or a period
longer than seven days.

ECDSA P-256 is available through `--private-key` for development and
compatibility. It is not the post-quantum production path. Existing signed v1
JSON requests may still use `rawctx reconcile run reconciliation.json`.

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

For a customer-managed signature, the review API checks ML-DSA online when a
request is created and approved. The run receipt records that result. A
portable proof does not carry a portable KMS public key, so both local and
registry proof verification report the source signature as
`SIGNATURE_UNVERIFIED` instead of repeating the KMS check.

Hub-managed receipts have the same offline limit. The verifier reports
`reconciliation_hub_attestation_signature_verification_unsupported` and
`SIGNATURE_UNVERIFIED`; it does not treat the earlier online Hub KMS check as a
new offline verification.

Use an export from a business system, provider, or auditor that answer-log
operators cannot edit at the same time. Findings and proofs store commitments;
do not place secrets, raw customer exports, personal data, 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
```

## Export a portable evidence package

For the advanced customer-managed flow, keep the exact reconciliation request
as `source-manifest.json`, including its `source_provenance` and
`reference_records`. Export the matching rawctx records as JSONL, then package
them with the proof:

```bash
rawctx trust package create \
  --proof reconciliation-proof.json \
  --source-manifest source-manifest.json \
  --rawctx-export rawctx-export.jsonl \
  --output evidence.zip \
  --json

rawctx trust package verify evidence.zip --json
```

Package verification is offline. It checks the archive manifest, every file
hash, and the proof bundle. The source manifest and rawctx export are included
for review, but their inclusion does not prove that the source export is
complete or truthful.

## 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)
