Metadata-Version: 2.4
Name: qiskit-connector
Version: 0.0.2
Summary: Qiskit 2.x Connector for IBM Quantum Backends in Realtime RuntimeService
Home-page: https://github.com/schijioke-uche/qiskit-connector
Author: Dr. Jeffrey Chijioke-Uche
Author-email: "Dr. Jeffrey Chijioke-Uche" <jeffrey.chijioke-uche@ibm.com>
License: MIT License
        
        Copyright (c) 2025 Dr. Jeffrey Chijioke-Uche, IBM
        
        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.
        
Project-URL: Homepage, https://github.com/schijioke-uche/qiskit-connector
Project-URL: Source, https://github.com/schijioke-uche/qiskit-connector
Project-URL: Tracker, https://github.com/schijioke-uche/qiskit-connector/issues
Keywords: qiskit,quantum,ibm,connector
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Quantum Computing
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: python-dotenv>=0.21.0
Requires-Dist: qiskit-ibm-runtime>=0.37.0
Requires-Dist: qiskit>=2.0.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# qiskit-connector

**⚛️Qiskit 2.x Connector for IBM Quantum Backends in Realtime**

A Quantum helper package compatible with Qiskit v2.x which streamlines authentication, plan detection, and backend selection for Qiskit RuntimeService. This package performs the following:
- Loads environment variables from config file (e.g. `.env`) via `python-dotenv` to configure your IBM Quantum account and make the `backend` object available in your quantum code for reuse in real-time.
- Detects your active plan (Open, Standard, Premium, Dedicated) and sets up the correct channel/instance.
- Provides functions to save your account (`qiskit_save_connection`), verify QPU resources (`qpu_verify`, `is_verified`), and retrieve a ready-to-use backend (`connector()`).

###### 🐍 Package built and maintained by Dr. Jeffrey Chijioke-Uche, IBM Quantum Ambassador & Research Scientist.
###### 🐍 Package is globally available in Pypi: https://pypi.org/project/qiskit-connector
---

## 📋 Features & API

All of the following functions are available after you import the module:

```python
from qiskit_connector import (
    connector,
    plan_type,
    qpu_verify,
    is_verified
)
```

- **`qiskit_save_connection(plan_type: str)`**  
  Saves your IBM Quantum account into QiskitRuntimeService using the environment variables for the given plan (`"open"`, `"standard"`, `"premium"`, or `"dedicated"`).

- **`qpu_verify()`**  
  Lists available QPUs for your plan by querying `QiskitRuntimeService.backends()` or falling back to `paid_plans()` for paid plans.

- **`is_verified()`**  
  Verifies real‐time least-busy QPU for the active plan and prints details (name, qubit count, online date).

- **`connector() -> IBMBackend`**  
  **Main entry point**: Loads your saved account, picks the least busy QPU (or first available for open or paid plans), prints diagnostics, and returns an `IBMBackend` instance ready for circuit execution.

- **`plan_type() -> str`**  
  Returns either **"Open Plan"** or **"Paid Plan"** depending on your `.env` toggles.

---

## 🔧 Installation

```bash
pip install qiskit-connector
```

This will also pull in:

- `qiskit>=2.0.0`  
- `qiskit-ibm-runtime>=0.37.0`  
- `python-dotenv`  
- `requests`  

and any other Qiskit dependencies.

---

## 🗂️ Environment (.env) Setup
⚠️ Security Practice: Do not CHECK-IN `.env` into version control. Add it to your .gitignore.
During development, create a file named `.env` at your project root. The connector will automatically load it:

```dotenv

#------------------------------------------------------------------------------------------------
# This file is used to store environment variables for the Qiskit installation wizard: Update it.
# The "ibm_quantum" channel option is deprecated and will be sunset on 1 July 2025.
# After this date, ibm_cloud will be the only valid channel.
# For information on migrating to the new IBM Quantum Platform on the "ibm_cloud" channel,
# review the migration guide https://quantum.cloud.ibm.com/docs/migration-guides/classic-iqp-to-cloud-iqp .
#-----------------------------------------------------------------------------------------------------

# GENERAL PURPOSE USE:
#--------------------------------------------
IQP_API_TOKEN="<YOUR_API_TOKEN_OR_IBM_QUANTUM_API_KEY>"

# Default (Open plan) - free monthly 10mins Runtime.
OPEN_PLAN_CHANNEL="<PROVIDE CHANNEL NAME>"
OPEN_PLAN_INSTANCE="<PROVIDE INSTANCE AS CRN STRING>"   # Must be a CRN String.
OPEN_PLAN_NAME="open"

# Optional (Upgrade) - Standard Plan
STANDARD_PLAN_CHANNEL="<PROVIDE CHANNEL NAME>"
STANDARD_PLAN_INSTANCE="<PROVIDE INSTANCE NAME>"
STANDARD_PLAN_NAME="standard"
STANDARD_IQP_API_URL="https://auth.quantum-computing.ibm.com/api/users/loginWithToken"   #  Update URL
STANDARD_IQP_BACKEND_URL="https://api.quantum-computing.ibm.com/runtime/backends"        #  Update URL

# Optional (Upgrade) - Premium Plan
PREMIUM_PLAN_CHANNEL="<PROVIDE CHANNEL NAME>"
PREMIUM_PLAN_INSTANCE="<PROVIDE INSTANCE AS HUB/PROJECT/ASSET PATH>"
PREMIUM_PLAN_NAME="premium"
PREMIUM_IQP_API_URL="https://auth.quantum-computing.ibm.com/api/users/loginWithToken"  #  Update URL
PREMIUM_IQP_BACKEND_URL="https://api.quantum-computing.ibm.com/runtime/backends"       #  Update URL

# Optional (Upgrade) - Dedicated Plan
DEDICATED_PLAN_CHANNEL="<PROVIDE CHANNEL NAME>"
DEDICATED_PLAN_INSTANCE="<PROVIDE INSTANCE AS HUB/PROJECT/ASSET PATH>"
DEDICATED_PLAN_NAME="dedicated"
DEDICATED_IQP_API_URL="https://auth.quantum-computing.ibm.com/api/users/loginWithToken"  #  Update URL
DEDICATED_IQP_BACKEND_URL="https://api.quantum-computing.ibm.com/runtime/backends"       #  Update URL

# Toggle exactly one plan "on":
OPEN_PLAN="on"       # free plan
STANDARD_PLAN="off"
PREMIUM_PLAN="off"
DEDICATED_PLAN="off"
```

> **⚠️ Only one** of `OPEN_PLAN`, `STANDARD_PLAN`, `PREMIUM_PLAN`, or `DEDICATED_PLAN` may be set to **"on"** at a time.

---

## 📖 Quickstart Examples

### Open Plan (default free tier) and Paid Plan

```python

from qiskit_connector import connector, plan_type
from qiskit_ibm_runtime import SamplerV2 as Sampler, Session

current = plan_type()              # -> detects plan set in environment configuration.
qpu = connector()                  # -> instantiate quantum (QPU) device connected backends in realtime.

backend = qpu.name                 # This is your backend

if current == "Open Plan":          
    sampler = Sampler(mode=backend)                    # -> "Open Plan"  (session not supported)
    print("Your Plan:", current)                       # -> "Open Plan"
    print("Least busy QPU backend:", backend)          # -> e.g. "ibm_brisbane"
elif current == "Paid Plan":         
    with Session(backend=backend.name) as session:
      sampler = Sampler(mode=session)                  # -> "Paid Plan"  (supports session)
      print("Your Plan:", current)                     # -> "Paid Plan"
      print("Least busy QPU backend:", backend)        # -> e.g. "ibm_brisbane"
else:
    raise ValueError(f"Unknown plan type: {current} - Contact IBM Support")

# --- do other things below with backend, quantum circuit, sampler & transpilation ------

```


---

## 📜 Publisher
Dr. Jeffrey Chijioke-Uche, IBM Quantum Ambassador & Research Scientist 
