quantum-xai

quantum-xai is a production-first Explainable Quantum ML library with a deterministic default backend and optional real-quantum adapters.

Install

pip install quantum-xai

Optional quantum backends:

pip install "quantum-xai[pennylane]"
pip install "quantum-xai[qiskit]"

Production Quickstart (Pipeline API)

from quantum_xai import ExplainerConfig, ModelConfig, QuantumXAIPipeline

pipeline = QuantumXAIPipeline(
    model_config=ModelConfig(n_features=4, backend="lightweight", random_state=42),
    explainer_config=ExplainerConfig(shap_n_samples=32, lime_n_samples=120),
)

result = pipeline.run(dataset="iris", n_samples=80, epochs=20, lr=0.08)
print(result.model_accuracy)
print(result.benchmark_metrics)

Multiclass

Use n_classes=3 with full Iris or Wine data:

from quantum_xai import ModelConfig, QuantumXAIPipeline

pipeline = QuantumXAIPipeline(ModelConfig(n_features=4, n_classes=3, random_state=42))
result = pipeline.run(dataset="iris", n_samples=90, epochs=20)
print(result.predictions[:5])

CLI

quantum-xai run --dataset iris --n-samples 80 --epochs 20
quantum-xai run --dataset iris --n-classes 3 --n-samples 90 --epochs 20
quantum-xai run --dataset iris --model-path model.json --explanations-path explanations.json

Public API

• QuantumXAIPipeline
• ModelConfig, ExplainerConfig, PipelineRunResult
• QuantumNeuralNetwork
• QuantumSHAPExplainer, QuantumGradientExplainer, QuantumLIMEExplainer, QuantumPerturbationExplainer
• QuantumXAIVisualizer
• QuantumDatasetLoader
• QuantumXAIBenchmark
• QuantumXAIResearch
• save_model, load_model, save_explanations, load_explanations
• QuantumXAIError, ValidationError, ConfigurationError, BackendUnavailableError, PersistenceError

Backend Selection

• backend="lightweight" (default): deterministic, hardware-free, CI-friendly.
• backend="pennylane": optional PennyLane-backed transform execution.
• backend="qiskit": optional Qiskit-backed transform execution.

If optional dependencies are missing, the library raises BackendUnavailableError with installation guidance.

Validation and Persistence

• Strong validation for shapes, labels, indices, and config values.
• Artifact persistence uses schema versioning (schema_version=1.0) and strict load checks.

Quality Commands

pip install -e ".[dev]"
quantum-xai run --dataset iris --n-samples 60 --epochs 5
ruff check .
black --check .
isort --check-only .
pytest
python -m build
twine check dist/*