Metadata-Version: 2.4
Name: commutator-sdk
Version: 0.1.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
recommendation = client.recommend(
    execution_id="your_execution_id",
    plan_only=True,
    target_dd=True
)

print(f"Recommended Backend: {recommendation['recommendedBackend']}")
print(f"Expected Fidelity: {recommendation['expectedFidelity']}")
```

---

## 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.
