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.

Install from source
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.

Saved-project workflow
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"))
Submitting a batch can consume credits and add AI charges. Review the draft, its issues and the AI settings first.

Client methods

Uploads and datasets

Uploads and datasets methods
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

Projects and checks methods
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

Batches methods
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

Runs and results methods
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 status and body, 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.