Python SDK
==========

The Quantag Python SDK provides high-level access to the Quantag Quantum Virtual Machine (QVM) 
and optimization routines (QAOA) on different backends including Qiskit simulators and D-Wave.

Installation
------------

Install from PyPI:

.. code-block:: bash

   pip install quantag

Optional extras:

.. code-block:: bash

   pip install quantag[dwave]

Quick Start
-----------

.. code-block:: python

   from quantag import QVMBackend

   backend = QVMBackend()
   result = backend.run("H 0; CX 0 1; measure 0; measure 1;")
   print(result)

This executes a simple Bell-state circuit on the Quantag simulator.

Simulator
---------

The QVM backend provides a local quantum simulator compatible with OpenQASM input.

Example:

.. code-block:: python

   from quantag import QVMBackend

   qasm_code = """
   OPENQASM 2.0;
   include "qelib1.inc";
   qreg q[2];
   creg c[2];
   h q[0];
   cx q[0], q[1];
   measure q -> c;
   """

   backend = QVMBackend()
   result = backend.run(qasm_code, shots=1024)
   print(result.get_counts())

Optimizer (QAOA)
----------------

The SDK also provides a high-level QAOA solver for combinatorial optimization.

Portfolio optimization example:

.. code-block:: python

   from quantag import QAOASolver

   # Local portfolio definition (CSV with "returns" column)
   solver = QAOASolver(backend="dwave")   # or "qiskit"
   result = solver.solve("portfolio.csv", problem="portfolio")
   print(result)

- If backend="qiskit", QAOA is executed with Qiskit simulators (Sampler-based).  
- If backend="dwave", the problem is mapped to QUBO and submitted to D-Wave (if API token is provided).  
- If no token is provided or access is unavailable, a local `dimod.ExactSolver()` is used.  

Example with explicit D-Wave cloud access:

.. code-block:: python

   solver = QAOASolver(backend="dwave")
   result = solver.solve(
       "portfolio.csv",
       problem="portfolio",
       api_token="YOUR_DWAVE_API_KEY",
       solver="Advantage_system4.1"
   )
   print(result)


Data Sources
------------

One unique feature of the Quantag QAOA optimizer is **flexible data ingestion**. 
Optimization problems can be defined directly from real-world data without tedious preprocessing.

Currently supported:

- **CSV files** (recommended; lightweight and universal)
- **SQL databases** (PostgreSQL, MySQL, SQLite) via SQLAlchemy

Planned extensions:

- **JSON** and **Parquet** files
- **Cloud storage URIs** (AWS S3, Google Cloud Storage, Azure Blob)
- **REST APIs** returning JSON or CSV
- **Streaming sources** (Kafka, MQTT) for real-time optimization

Examples:

.. code-block:: python

   # From CSV
   solver.solve("portfolio.csv", problem="portfolio")

   # From PostgreSQL
   solver.solve(
       "postgresql://user:pass@localhost/mydb",
       problem="portfolio",
       table="portfolio_data"
   )

   # From a REST API (planned)
   solver.solve("https://api.example.com/portfolio.json", problem="portfolio")



Results
-------

- **Simulator** returns Qiskit-like counts dictionaries (e.g., {"00": 512, "11": 512}).  
- **QAOA** returns either a structured optimization result (Qiskit) or a `dimod.SampleSet` (D-Wave/local).  


QImage Module
=============

The ``quantag.qimage`` module provides **quantum-inspired image compression**
based on **Quantum Principal Component Analysis (QPCA)**.

Overview
--------

This module demonstrates how classical images can be represented as
quantum-like states (normalized amplitudes) and then analyzed using
QPCA methods. The algorithm works classically today, but follows the
same mathematical structure that can be deployed on future
**Quantum Processing Units (QPUs)**.

Main class
----------

.. autoclass:: quantag.qimage.QImageCompressor
   :members:

Example usage
-------------

.. code-block:: python

    from quantag import QImageCompressor
    from PIL import Image

    # Initialize compressor with 95% energy threshold
    compressor = QImageCompressor(energy_threshold=0.95)

    # Compress an image
    result = compressor.compress("example.png")

    print("Number of components kept (k):", result["k"])
    print("Mean Squared Error (MSE):", result["mse"])

    # Save outputs
    Image.fromarray(result["reconstructed"]).save("reconstructed.png")
    Image.fromarray(result["compressed"]).save("compressed.png")

    # Inspect overlay components
    for i, comp in enumerate(result["components"]):
        Image.fromarray(comp.astype("uint8")).save(f"component_{i}.png")

The ``compress()`` method returns:

- ``original``: the original grayscale data as NumPy array
- ``reconstructed``: full reconstruction from all components
- ``compressed``: compressed reconstruction (~95% variance preserved)
- ``mse``: mean squared error of compression
- ``components``: leading principal components reshaped as images
- ``k``: number of components retained

``QImageCompressor`` also provides a utility ``to_base64`` for embedding
results in web frontends.

``qimage`` is fully integrated into the ``quantag`` package and can be
used together with other modules such as QAOA optimization.


Roadmap
-------

Future extensions of the Python SDK will include:

- Support for Quantag’s QBIN binary circuit format.  
- Additional optimization problems (MaxCut, scheduling, etc.).  
- Hybrid quantum-classical routines.