> For the complete documentation index, see [llms.txt](https://rawctx.gitbook.io/rawctx-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rawctx.gitbook.io/rawctx-docs/documentation/python-sdk.md). # Python SDK The Python SDK exposes the same package, answer evidence, reconciliation, and trust workflows as the CLI. ## Package context ```python import rawctx result = rawctx.search( "customer metrics", registry="https://api.rawctx.dev", sort="similarity", ) package = rawctx.info( "@scope/name@1.2.3", registry="https://api.rawctx.dev", ) model = rawctx.load( "@scope/name@1.2.3", registry="https://api.rawctx.dev", ) prompt = rawctx.to_prompt( "@scope/name@1.2.3", datasets=["customers", "orders"], max_tokens=2000, registry="https://api.rawctx.dev", ) ``` ## Answer evidence Use `rawctx.log_answer()` for the concise text or caller-hash path, or `RawctxClient` when a workflow needs multiple operations and explicit resource lifetime. When text is supplied without an explicit hash, the service derives the workspace's active SHA-256 or HMAC commitment. ```python import rawctx with rawctx.RawctxClient() as client: log = client.create_answer_log( application_key="support_assistant", question_hash="sha256:235d0f0faf774748394fbb5dec9c41c51ac23b1cc6c344bc06864e7d34442516", answer_hash="sha256:f564d7fd469050a37898846611c9a6031be9bad19907812ec0d605b3e614b6f8", source_refs=[ { "source_name": "support-policy", "source_hash": "sha256:7777777777777777777777777777777777777777777777777777777777777777", } ], ) proof = client.proof_answer(log["id"]) ``` ## Run EZKL and queue verification Install the optional EZKL runtime once: ```bash pip install 'rawctx[ezkl]' ``` Prepare the model circuit, settings, proving key, verification key, and the workspace-compatible SRS once. Record their locations in `rawctx.ezkl.json` at the application's working directory. Relative paths are resolved from the configuration file: ```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" } ``` Set `RAWCTX_EZKL_CONFIG` when this file is not in the working directory. Do not generate `kzg.srs` with `ezkl.get_srs()` or `ezkl.gen_srs()`. The file must be the exact SRS bundle supplied for the workspace's `kzg_srs_v1` worker. The SDK validates its pinned hash before proving. The prepared settings must use `Public` input and output visibility. Configure the deployment credentials in the process environment: ```ini RAWCTX_REGISTRY=https:// RAWCTX_TOKEN= ``` ```python import rawctx with rawctx.RawctxClient() as client: result = client.run_ezkl_and_log( application_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"]) ``` You do not pass an artifact path on each call. The helper loads the project config, generates a witness and proof in a private temporary directory, verifies the proof locally, derives the answer text from the single rescaled public output, and removes the temporary files. It then creates the answer log and queues an `ezkl_v1` job. A locally valid proof is not yet server-verified: the returned job is normally `queued`, and the worker must finish with `adapter_verified`. The first integrated contract supports exactly one public rescaled input and one public rescaled output. `input_data` is numeric EZKL input, not arbitrary natural-language text. The ONNX model and SRS are hashed locally but are not uploaded; proof/settings/VK and exposed rescaled values are stored in private job metadata. The helper performs answer-log creation and job creation as two writes. Use a stable `idempotency_key` for retries because a rejected job can leave the log recorded. Regenerated proofs can also produce distinct job requests. Workspace size, backend, and budget policy still apply. ## Runtime credentials Do not run `rawctx login` in a production server or container. A workspace administrator should sign in to the workspace Hub in a browser, open **Settings > Access & team > API tokens**, and create a dedicated token for the deployment. Give it a recognizable name and the shortest practical expiration, then copy the token when it is shown and store it in the deployment platform's secret manager. Configure the workspace registry and the UI-issued token in the deployed server's process environment: ```ini RAWCTX_REGISTRY=https:// RAWCTX_TOKEN= ``` The no-argument client automatically reads both values: ```python import rawctx with rawctx.RawctxClient() as client: client.create_answer_log( application_key="support_assistant", # ... ) ``` If the application needs to select or validate the values explicitly, pass them to the client constructor: ```python import os import rawctx client = rawctx.RawctxClient( registry=os.environ["RAWCTX_REGISTRY"], token=os.environ["RAWCTX_TOKEN"], ) ``` The token is shown only when it is created. Rotate or revoke it from the same UI and update the secret manager when ownership, exposure, or expiration changes. Current UI-issued API tokens are workspace/user scoped rather than bound to one `application_key`; use a separate token per deployment and do not reuse an administrator's interactive CLI token. For developer or operator CLI use, the no-argument client can also use the authenticated workspace registry stored by `rawctx login`. `AsyncRawctxClient.create_answer_log()` provides the async answer-log creation path. `AsyncRawctxClient.run_ezkl_and_log()` runs the same integrated EZKL workflow in a worker thread. `AsyncRawctxClient.create_ezkl_answer_log()` remains available when an application already owns the generated artifacts. This hash-only example works only when the workspace permits caller-generated SHA-256 commitments. For a workspace that requires the service to derive the active tenant HMAC, pass `question_text` and `answer_text` without explicit hashes as shown in Get started. Text submission and text storage remain separate workspace decisions. ## Public error types Catch typed exceptions instead of parsing messages: ```python from rawctx import AuthRequiredError, RawctxError, ValidationError try: # rawctx operation pass except AuthRequiredError: # prompt for login or supply CI credentials raise except ValidationError as exc: # report an invalid local artifact print(exc) except RawctxError as exc: # common rawctx fallback print(exc) ``` See Errors and troubleshooting for the error taxonomy. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://rawctx.gitbook.io/rawctx-docs/documentation/python-sdk.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.