Python SDK
A typed client for the Survey Guard API with safe retries built in. It is an unpublished preview: install it from a reviewed source checkout, not from PyPI.
Install
The SDK lives in the private CrowdminesAI/crowdmines-sdk repository, on the dev branch. Repository access is granted separately from your API key. It needs Python 3.11 or newer and has no third-party runtime dependencies.
git clone --branch dev https://github.com/CrowdminesAI/crowdmines-sdk.git
cd crowdmines-sdk
# Check out your reviewed commit for a repeatable installation.
python -m pip install ./python
Keep your GitHub credentials and your Crowdmines API key apart, and never put either in an installation URL.
Run a saved project
There is no default destination: pass the key and the base URL of the same environment. For a new survey, start with upload_spss as in the quickstart.
import os
from crowdmines import Client
# Read the key from the environment; never write it into source code.
client = Client(
api_key=os.environ["CM_API_KEY"],
base_url=os.environ["CM_API_BASE"],
)
project = {"id": os.environ["CM_PROJECT_ID"]}
config = client.get_configuration(project["id"])
print("Revision:", config["revision"])
print("Issues:", config["issues"])
# To save edits, pass the revision you read. A conflict means another
# update was saved first: read again and review before retrying.
# config = client.save_configuration(
# project["id"], expected_revision=config["revision"], draft=edited_draft)
# Persist the items and the key BEFORE the first submission.
# This starts processing and can consume credits / incur AI charges.
items = [{"item_id": "survey-a", "project_id": project["id"],
"configuration_revision": config["revision"]}]
batch = client.submit_batch(
items, idempotency_key=os.environ["CM_BATCH_REQUEST_ID"])
print("Batch ID:", batch["batch_id"])
# Polls until the batch finishes or the local deadline passes.
result = client.wait_for_batch(batch["batch_id"], timeout=300)
for item in result["items"]:
if item["status"] == "succeeded":
findings = client.get_result(item["run_id"]) # JSON, in memory
else:
print(item["item_id"], item["status"], item.get("error_code"))
Client methods
Uploads and datasets
| upload_spss(path) | Streams a .sav file and completes its upload. Returns dataset metadata. Does not create a project or start checks. |
|---|---|
| create_upload(filename, size_bytes) upload_bytes(intent, source, size_bytes) complete_upload(upload_id) | The same upload as separate steps, so you can persist upload state. Storage receives only the upload headers, never your API key. |
| cancel_upload(upload_id) | Cancels an unfinished upload. |
| get_dataset(dataset_id) | Reads dataset metadata. |
Projects and checks
| create_project(dataset_id, name=None) | Creates a project from an existing SPSS dataset. No automatic retries. |
|---|---|
| get_configuration(project_id) | Reads the draft, its issues and the current revision. |
| save_configuration(project_id, expected_revision=…, draft=…) | Saves setup against an explicit revision. A conflict needs your review. |
Batches
| submit_batch(items, idempotency_key=…) | Submits 1–10 distinct projects. Needs a key you have persisted and explicit configuration revisions. Can be billable. |
|---|---|
| get_batch(batch_id) | Reads batch and per-item status once. |
| wait_for_batch(batch_id, timeout=300, poll_interval=5, cancelled=None) | Polls until the batch finishes or the deadline passes. Returns partial failures for you to inspect. Stopping the poll does not cancel server work. |
Runs and results
| get_run(run_id) | Reads run progress. |
|---|---|
| get_result_link(run_id) | Returns a short-lived signed link to the full result. |
| get_result(run_id) | Loads the result JSON into memory. Call it again if a link expired; no new analysis starts. |
What the SDK retries
- Retried
- GET requests and batch submissions, on connection failures, truncated successful responses and HTTP 408, 429, 500, 502, 503 and 504.
- Never retried
- Uploads, project and configuration writes, HTTP 409, permission errors and invalid input.
- Defaults
- Two retries with exponential backoff, a 120-second request timeout and at most 60 seconds between attempts.
- Retry-After
- Always honored. If the server asks for a longer wait than the maximum, the SDK stops retrying instead of retrying early.
Keep the same batch items and the same idempotency key across retries, including after a process restart. The SDK never creates replacement paid runs, never resubmits failed items in a new batch and never resubmits a pending admission while polling.
Error types
ApiError- The API answered with an error. Read
statusandbody, and treat the body as sensitive. TransportError- The request did not complete. After a write the outcome may be unknown: check what exists before creating anything again.
PollTimeout- Local polling stopped. The job may still be running on the server.
Every method maps to one endpoint in the HTTP API reference.