Commutator Studios Python SDK

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), 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:

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.

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.

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!

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.

License

Copyright © 2026 Commutator Studios GmbH. All rights reserved.