Metadata-Version: 2.4
Name: commoncompute
Version: 0.1.2
Summary: Official Python SDK for Common Compute — the batch AI bill you shouldn't be paying.
Project-URL: Homepage, https://commoncompute.ai
Project-URL: Documentation, https://commoncompute.ai/docs
Project-URL: Source, https://github.com/Ikaikaalika/commoncomputeai
Project-URL: Changelog, https://commoncompute.ai/changelog
Author-email: Common Compute <support@commoncompute.ai>
License: MIT
License-File: LICENSE
Keywords: ai,apple-silicon,embeddings,inference,llm,openai-compatible
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx<1.0,>=0.24
Requires-Dist: pydantic<3.0,>=2.0
Provides-Extra: cli
Requires-Dist: rich>=13; extra == 'cli'
Requires-Dist: typer>=0.9; extra == 'cli'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: respx>=0.20; extra == 'test'
Description-Content-Type: text/markdown

# Common Compute — Python SDK

The official Python SDK + CLI for [Common Compute](https://commoncompute.ai) —
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.

```bash
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

```python
import commoncompute as cc

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

job = client.submit("coreml_embed", {"input": ["what is the neural engine?"]},
                    model_id="bge-base")
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
```

Prefer the OpenAI-style surface? `client.embeddings.create(input=[...],
model="bge-base")` returns vectors synchronously.

## Examples — live today

### 1. OCR / document extraction — vs AWS Textract

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

### 2. Embeddings in bulk

```python
for result in client.submit_many(
    "coreml_embed",
    [{"input": chunked(doc)} for doc in corpus],
    max_concurrent=16,
):
    save(result.output)              # results stream as they complete
```

### 3. Background removal

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

Also live: speech synthesis, image classification/detection/pose, barcode
reading, HEIC conversion — plus the generic `client.submit(workload_id,
payload)` for anything marked **live** in
[the catalog](https://commoncompute.ai/workloads).

### In preview

`client.translate(...)` and `client.video.transcode(...)` run on preview
capacity — functional, not yet GA.

### Not live yet

`client.transcription.*`, `client.rerank(...)`, `client.images.generate(...)`,
`client.chat.*`, and `client.build.ios_test(...)` target workloads still
marked *coming soon*: the API refuses them with a clear
`workload_not_available` error (HTTP 409) rather than queueing a job that
won't run. They activate automatically as those lanes go live — watch
[the catalog](https://commoncompute.ai/workloads).

## Price before execution, hard caps, dry runs

```python
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

```python
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):

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

## Account

```python
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

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

## CLI

```bash
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:

```python
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:

```python
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.
