Metadata-Version: 2.4
Name: commutator-sdk
Version: 0.2.1
Summary: Commutator Studios Python SDK
Author: Commutator Studios
Project-URL: Homepage, https://commutatorstudios.com
Keywords: quantum,sdk,optimization,physics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.0

# Commutator Studios Python SDK

<div align="center">
  <img src="https://img.shields.io/pypi/v/commutator-sdk?color=blue&label=PyPI" alt="PyPI Version">
  <img src="https://img.shields.io/pypi/pyversions/commutator-sdk" alt="Python Versions">
  <img src="https://img.shields.io/badge/License-Proprietary-red" alt="License">
</div>

<br>

**Commutator SDK** is the official Python client for the Commutator Studios quantum ecosystem. It provides a seamless, developer-friendly interface to integrate quantum workloads, optimization engines, and identity management natively into your Python tech stack.

By connecting to the **Centralized API Gateway ([commutator.app](https://commutator.app))**, this SDK handles authentication, rate-limiting, and billing checks automatically, allowing you to focus on building quantum-accelerated applications.

---

## Features

* **Quantum Fleet Management**: Discover, list, and check the status of available quantum backends (e.g., `ibm_berlin`, `ibmq_qasm_simulator`).
* **Hardware & Algorithmic Recommendations**: Interface directly with `cs-optimizer` to get smart recommendations for hardware and optimization levels (e.g., VQE) before you run your circuits.
* **Job Execution & Polling**: Submit quantum circuits, execute jobs on actual quantum hardware, and download results natively into Python objects.
* **Standardized Error Handling**: Detailed, structured exceptions (`APIError`, `ValidationError`, `AuthenticationError`) for predictable and easy debugging.
* **...and more!**

---

## Installation

The SDK requires **Python 3.11+**. You can install it directly from PyPI using pip:

```bash
pip install commutator-sdk
```

---

## Quick Start

Here is a simple example showing how to authenticate, create a job, execute a circuit, and fetch the results.

### 1. Authentication

You can authenticate using your API Key or Username/Password.
```python
from commutator.client import CommutatorClient

# Initialize the client (Environment is auto-detected)
client = CommutatorClient(api_key="your_api_key_here")
```

### 2. Submitting a Quantum Job

Submit your quantum circuit JSON and execute it on a selected backend.

```python
import json

# 1. Create the Job
job = client.create_job(
    name="My First VQE Run",
    algorithm="VQE",
    file_path="circuit.json"
)
job_id = job["id"]
print(f"Job created successfully: {job_id}")

# 2. Execute the Job
client.execute_job(
    job_id=job_id,
    backend="ibm_berlin",
    optimization_level=3
)
print("Job dispatched to the quantum backend!")
```

### 3. Optimizer Recommendations

Not sure which backend or optimization level to use? Ask the Recommendation Engine!

```python
recommendations = client.optimizer.recommend(
    job_id="your_job_id",
    target_backends=["ibm_kingston", "ibm_brisbane"]  # Optional: omit to evaluate all fleet backends
)

print(f"Recommended Backend: {recommendations[0]['provider']}")
```

---

## Error Handling & Exception Reference

When executing quantum simulation jobs, the SDK automatically inspects the API response `errorCode` and raises typed Python exceptions providing human-readable diagnostic remedies:

```python
from commutator.client import CommutatorClient
from commutator.exceptions import (
    SimulationOOMError,
    SimulationTimeoutError,
    ProviderAuthenticationError,
    JobFailedError
)

client = CommutatorClient(api_key="your_api_key")

try:
    job_details = client.jobs.get(job_id="5bacd027-267d-4c8e-94c4-5348c48880b3")
except SimulationOOMError as e:
    print(f"❌ Memory Error [{e.error_code}]: {e.message}")
    print(f"💡 Actionable Remedy: {e.remedy}")
except SimulationTimeoutError as e:
    print(f"⏱️ Job Timed Out [{e.error_code}]: {e.message}")
    print(f"💡 Actionable Remedy: {e.remedy}")
except JobFailedError as e:
    print(f"⚠️ Job Execution Failed [{e.error_code}]: {e.message}")
```

### Supported Exception Mapping

| API `errorCode` Enum | Raised SDK Exception Class | Python Import Path |
| :--- | :--- | :--- |
| `SIMULATION_OOM` | `SimulationOOMError` | `from commutator.exceptions import SimulationOOMError` |
| `SIMULATION_TIMEOUT` | `SimulationTimeoutError` | `from commutator.exceptions import SimulationTimeoutError` |
| `PROVIDER_AUTH_FAILED` | `ProviderAuthenticationError` | `from commutator.exceptions import ProviderAuthenticationError` |
| `OPTIMIZATION_DIVERGED` | `OptimizationDivergedError` | `from commutator.exceptions import OptimizationDivergedError` |
| *Fallback / System Faults* | `JobFailedError` | `from commutator.exceptions import JobFailedError` |

---

## Advanced Usage

For comprehensive documentation, including detailed API reference, Identity Management (`list_api_keys`, `get_audit_logs`), and advanced configuration options, please refer to the official [Commutator Studios Documentation](https://commutator.app/docs/sdk).

## License

Copyright © 2026 Commutator Studios GmbH. All rights reserved.
