commoncompute 0.1.1

Official Python SDK for Common Compute — the batch AI bill you shouldn't be paying.

Common Compute — Python SDK

The official Python SDK + CLI for Common Compute — batch AI compute without the AWS tax, on Apple Silicon hardware AWS can't offer.

One SDK call replaces the IAM roles, compute environments, and job definitions. Every job returns its price and ETA before it runs, and you're only billed for successful jobs — each with a verifiable receipt.

pip install commoncompute          # core: httpx + pydantic only
pip install "commoncompute[cli]"   # + the `cc` command line
cc login                           # opens the browser — no key to copy-paste

cc login (or commoncompute.connect() from a script or notebook) opens an approval page in your browser; click Approve and a fresh API key is saved to ~/.config/commoncompute/credentials, where the SDK finds it automatically. Prefer explicit config? export CC_API_KEY=cc_live_... works everywhere and takes precedence.

The 10-minute path

import commoncompute as cc

client = cc.Client()   # CC_API_KEY, or ~/.commoncompute/config

job = client.transcription.create("s3://my-bucket/meeting.mp3", timestamps=True)
print(job.job_id, job.locked_price_usd, job.eta_seconds)   # price known BEFORE it runs

result = client.result(job)          # waits, downloads, attaches the receipt
print(result.output)
print(result.receipt)                # signed proof of what ran, where, for how much

Examples

1. OCR / document extraction — vs AWS Textract

job = client.ocr.extract("https://example.com/contracts.pdf", structured=True)
result = client.result(job)          # blocks + bounding boxes as JSON

2. Transcription in bulk

jobs = client.transcription.create_many(
    [f"s3://recordings/call-{i}.mp3" for i in range(200)],
    language="en",
    max_concurrent=16,
)

3. Reranking — sharpen RAG retrieval

job = client.rerank("what is the neural engine?", documents, top_n=5)
top = client.result(job).output

4. Translation

job = client.translate(catalog_descriptions, target_lang="de")

5. Background removal

job = client.images.remove_background("product-shot.png")

Also available: client.video.transcode(...), client.build.ios_test(...), client.images.generate(...), client.embeddings.create(...), and the generic client.submit(workload_id, payload) for anything in the catalog.

Price before execution, hard caps, dry runs

quote = client.ocr.extract("scan.pdf", dry_run=True)     # price + ETA, no job
job = client.ocr.extract("scan.pdf", max_spend_usd=1.0)  # refused if it would exceed

Batches that stream back

for result in client.submit_many("vision_bgremove", images, max_concurrent=8):
    save(result.output)              # results stream as they complete

Receipts

Every successful job carries a receipt (job_id, cost, provider id, timestamps, input/output hashes, signature):

client.receipts.list()
csv_blob = client.receipts.export(format="csv")

Account

client.account.balance()         # card-on-file billing state (cash only)
client.account.spend(days=30)    # spend summary by workload
client.account.tier()            # your volume tier + the next threshold

Per-task prices step down automatically as your monthly usage grows — your current rate is always the one a quote returns.

Async

async with cc.AsyncClient() as client:
    job = await client.jobs.submit(workload_id="coreml_embed", payload={"input": ["hi"]})

CLI

cc login                          # stores the key locally
cc estimate vision_ocr --units 5  # price + ETA, no execution
cc submit coreml_embed --payload '{"input":["hi"]}' --wait
cc jobs list
cc jobs status <id>               # via: cc jobs get <id>
cc balance
cc receipts export --format csv --out receipts.csv

Migrating from OpenAI (optional)

Existing OpenAI-based pipelines (embeddings, chat, transcription) can point at Common Compute by swapping two env vars — or:

from commoncompute.compat import openai   # sets OPENAI_BASE_URL / OPENAI_API_KEY
client = openai.OpenAI()

This is a migration path, not the recommended interface: the native client returns locked prices, ETAs, and receipts that the OpenAI wire format can't express.

Errors

Typed, always:

try:
    client.ocr.extract("scan.pdf", max_spend_usd=0.01)
except cc.InsufficientFundsError:      # quote exceeded the cap / no card
    ...
except cc.UnsupportedFormatError:      # wrong file type for the workload
    ...
except cc.JobTimeoutError:             # wait() expired; job still running
    ...
except cc.NetworkError:                # no HTTP response after retries
    ...
except cc.CommonComputeError as e:     # everything raises from this
    print(e.request_id)

Configuration

Setting	Env var	Fallback
API key	CC_API_KEY	~/.commoncompute/config, then ~/.config/commoncompute/credentials
Base URL	CC_BASE_URL	https://api.commoncompute.ai
Org id	CC_ORG	default workspace

Python 3.9+. Core dependencies: httpx, pydantic. MIT license.