commoncompute 0.1.0__tar.gz

commoncompute-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+node_modules/
+.npm/
+dist/
+coverage/
+.wrangler/
+.pytest_cache/
+__pycache__/
+*.pyc
+*.db
+.DS_Store
+.env
+.env.*
+!.env.example
+.dev.vars
+.local-test-key
+Cargo.lock
+.vercel
+
+# Build artifacts — these are generated and must never be tracked.
+# (Web deploys rebuild from source via `wrangler pages deploy out`.)
+.next/
+apps/web/out/
+*.tsbuildinfo
+
+# Xcode build output (provider app)
+apps/provider/build/
+
+# Per-app local Claude scratch dirs
+apps/web/.claude/
+
+# Playwright E2E artifacts (apps/web)
+apps/web/playwright-report/
+apps/web/test-results/
+apps/web/.playwright/
+
+# Local scratch — never tracked (internal notes, draft reviews)
+tmp/
+.venv

commoncompute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Common Compute, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commoncompute-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: commoncompute
+Version: 0.1.0
+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.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
+
+```python
+job = client.ocr.extract("https://example.com/contracts.pdf", structured=True)
+result = client.result(job)          # blocks + bounding boxes as JSON
+```
+
+### 2. Transcription in bulk
+
+```python
+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
+
+```python
+job = client.rerank("what is the neural engine?", documents, top_n=5)
+top = client.result(job).output
+```
+
+### 4. Translation
+
+```python
+job = client.translate(catalog_descriptions, target_lang="de")
+```
+
+### 5. Background removal
+
+```python
+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](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.

commoncompute-0.1.0/README.md

@@ -0,0 +1,175 @@
+# 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.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
+
+```python
+job = client.ocr.extract("https://example.com/contracts.pdf", structured=True)
+result = client.result(job)          # blocks + bounding boxes as JSON
+```
+
+### 2. Transcription in bulk
+
+```python
+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
+
+```python
+job = client.rerank("what is the neural engine?", documents, top_n=5)
+top = client.result(job).output
+```
+
+### 4. Translation
+
+```python
+job = client.translate(catalog_descriptions, target_lang="de")
+```
+
+### 5. Background removal
+
+```python
+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](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.

commoncompute-0.1.0/commoncompute/__init__.py

@@ -0,0 +1,86 @@
+"""Common Compute — official Python SDK.
+
+Thin, typed wrapper around the Common Compute HTTP API. Ships an OpenAI-
+compatible path for drop-in migration plus first-class helpers for the
+native job API. See https://commoncompute.ai/docs for the full reference.
+
+Quickstart::
+
+    import commoncompute as cc
+
+    client = cc.Client(api_key="cc_live_...")
+    print(client.balance())
+
+    # OpenAI-compatible chat
+    reply = client.chat.create(
+        model="qwen-2.5-7b-instruct",
+        messages=[{"role": "user", "content": "hi"}],
+    )
+    print(reply["choices"][0]["message"]["content"])
+
+    # Native job submission
+    job = client.jobs.submit(
+        workload_id="coreml_embed",
+        payload={"inputs": ["hello world"]},
+    )
+    result = client.jobs.wait(job["id"])
+
+Streaming chat::
+
+    for chunk in client.chat.stream(model="qwen-2.5-7b-instruct",
+                                    messages=[{"role": "user", "content": "hi"}]):
+        delta = chunk["choices"][0].get("delta", {}).get("content", "")
+        print(delta, end="", flush=True)
+"""
+
+# MUST come before any submodule imports — _transport.py reads
+# `commoncompute.__version__` at import time for the User-Agent header,
+# and the previous ordering (`__version__` defined at the bottom) made
+# every clean install of the SDK fail with a circular ImportError.
+__version__ = "0.1.0"
+
+from .client import Client, AsyncClient
+from .errors import (
+    CommonComputeError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    InsufficientFundsError,
+    InsufficientCreditsError,  # legacy alias of InsufficientFundsError
+    BadRequestError,
+    ValidationError,
+    UnsupportedFormatError,
+    NetworkError,
+    JobTimeoutError,
+    APIError,
+)
+from .models import Job, Quote, Receipt, TaskResult, AccountTier, SpendSummary
+from .connect import connect, login
+from . import aws_batch  # noqa: E402  (intentional re-export)
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "connect",
+    "login",
+    "CommonComputeError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "InsufficientFundsError",
+    "InsufficientCreditsError",
+    "BadRequestError",
+    "ValidationError",
+    "UnsupportedFormatError",
+    "NetworkError",
+    "JobTimeoutError",
+    "APIError",
+    "Job",
+    "Quote",
+    "Receipt",
+    "TaskResult",
+    "AccountTier",
+    "SpendSummary",
+    "aws_batch",
+    "__version__",
+]

commoncompute-0.1.0/commoncompute/_generated_workloads.py

@@ -0,0 +1,60 @@
+# @generated by packages/workloads/codegen/emit-sdk-workloads.ts — DO NOT EDIT.
+# Regenerate:  npx tsx packages/workloads/codegen/emit-sdk-workloads.ts
+# Source of truth: packages/workloads (the shared catalog). CI fails if this
+# file drifts from the catalog (see tests/unit/workloads-parity.test.ts).
+from __future__ import annotations
+
+# Every workload id in the catalog. Used to decide whether a jobDefinition head
+# names a workload directly vs. a model.
+KNOWN_WORKLOAD_IDS: frozenset[str] = frozenset({
+    "coreml_embed",
+    "whisper_ane",
+    "whisper_subtitle",
+    "accelerate_denoise",
+    "pyannote_diarize",
+    "audio_classify",
+    "avspeech_tts",
+    "apple_translate",
+    "bge_rerank",
+    "nl_langdetect",
+    "nl_ner",
+    "nl_sentiment",
+    "vision_ocr",
+    "vision_bgremove",
+    "vision_aesthetics",
+    "vision_face",
+    "vision_detect",
+    "vision_pose",
+    "vision_barcode",
+    "vision_segment",
+    "coreml_upscale",
+    "vt_transcode",
+    "videotoolbox_heic",
+    "av_thumbnail",
+    "vision_scene",
+    "mlx_image",
+    "xcode_build",
+    "xctest_runner",
+    "mlx_small_rag",
+    "mlx_llm",
+    "mlx_llm_long_ctx",
+    "coreml_vision",
+    "sd_mlx",
+    "mlx_finetune",
+    "pytorch_mps",
+    "blender_metal",
+    "cpu_bench",
+})
+
+# (regex source, workload_id), highest priority first. Compile with re.IGNORECASE.
+IMAGE_PATTERNS: tuple[tuple[str, str], ...] = (
+    ("whisper", "whisper_ane"),
+    ("(embed|sentence-transformer|bge|e5-)", "coreml_embed"),
+    ("(stable-diffusion|sdxl|sd-|sd_)", "sd_mlx"),
+    ("(flux|mlx-image)", "mlx_image"),
+    ("(llama|mistral|qwen|mlx-llm|chat-llm)", "mlx_llm"),
+    ("(ffmpeg|transcode|videotoolbox|vt[-_])", "vt_transcode"),
+    ("(ocr|tesseract|textract)", "vision_ocr"),
+    ("(blender|cycles)", "blender_metal"),
+    ("(pytorch|torch)", "pytorch_mps"),
+)