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

pip install rawctx
rawctx login

You can also mint a no-signup, hash-only browser receipt from the rawctx Hub. The browser path sends cryptographic fingerprints instead of the question and answer text.

Log an answer

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.

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:

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

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:

pip install 'rawctx[ezkl]'

{
  "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:

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:

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.

Prepare and sign a closed-period CSV in the source export job. The header is fixed; the last two values may be empty.

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

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 manifest binds the CSV hash, scope, options, metadata, and every record. The server verifies the ML-DSA signature with the registered KMS 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.

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

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.

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.

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

Export a portable evidence package

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:

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
• Answer Audit
• Independent Reconciliation
• OpenTelemetry integrations