Metadata-Version: 2.4
Name: quantum-xai
Version: 0.4.0
Summary: Production-grade explainable quantum machine learning library
Author: Harsha P, B Manvitha Reddy
License-Expression: MIT
Keywords: xai,quantum,machine-learning,explainability
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scikit-learn>=1.2
Requires-Dist: matplotlib>=3.6
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.35; extra == "pennylane"
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0; extra == "qiskit"
Provides-Extra: quantum
Requires-Dist: pennylane>=0.35; extra == "quantum"
Requires-Dist: qiskit>=1.0; extra == "quantum"
Dynamic: license-file

﻿# quantum-xai

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

## Install

```bash
pip install quantum-xai
```

Optional quantum backends:

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

## Production Quickstart (Pipeline API)

```python
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:

```python
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

```bash
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

```bash
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/*
```
