Metadata-Version: 2.4
Name: qobserva
Version: 0.1.2
Summary: QObserva - Quantum program observability and benchmarking. One command to install and run everything.
Project-URL: Homepage, https://qobserva.com
Project-URL: Documentation, https://qobserva.com/docs.html
Project-URL: Repository, https://github.com/BuildersArk/qobserva
Project-URL: Issues, https://github.com/BuildersArk/qobserva/issues
Project-URL: Changelog, https://github.com/BuildersArk/qobserva/blob/main/CHANGELOG.md
Author-email: BuildersArk LLC <support@qobserva.com>
Maintainer-email: BuildersArk LLC <support@qobserva.com>
License: QOBSERVA COMMUNITY LICENSE
        
        Version 1.0 – March 2026
        Copyright (c) 2026 BuildersArk LLC
        
        This license governs the use of the QObserva software project and its
        associated components.
        
        This is a source-available license intended to allow individuals,
        researchers, and organizations to use, study, and evaluate QObserva
        while reserving certain commercial rights for BuildersArk LLC.
        
        This license is NOT an OSI-approved open source license.
        
        ------------------------------------------------------------------------
        
        1. Definitions
        
        1.1 "Licensor"
        "Licensor" means BuildersArk LLC.
        
        1.2 "Software"
        "Software" means the QObserva codebase and all related packages
        contained within this repository including, but not limited to:
          - qobserva
          - qobserva-agent
          - qobserva-collector
          - qobserva-local
          - documentation and configuration files.
        
        1.3 "You" / "Your"
        "You" means an individual or legal entity exercising permissions granted
        under this License.
        
        1.4 "Hosted Service"
        "Hosted Service" means making the Software or any substantial portion of
        its functionality available to third parties over a network including
        but not limited to:
          - Software-as-a-Service (SaaS)
          - cloud hosted platforms
          - managed services
          - remote monitoring or analytics platforms.
        
        1.5 "Competing Service"
        A Hosted Service that provides quantum observability, telemetry,
        monitoring, analytics, benchmarking, or other functionality materially
        similar to QObserva.
        
        1.6 "Derivative Work"
        Any modification, enhancement, translation, adaptation, or work based
        upon the Software.
        
        ------------------------------------------------------------------------
        
        2. Grant of Rights
        
        Subject to compliance with this License, Licensor grants You a
        worldwide, non-exclusive, non-transferable, royalty-free license to:
        
        2.1 Use
        Use the Software internally within Your organization for research,
        development, testing, evaluation, and production use.
        
        2.2 Modify
        Modify the Software and create Derivative Works for internal use.
        
        2.3 Redistribute Unmodified Copies
        Distribute unmodified copies of the Software provided that:
          - this License is included in full
          - all copyright notices remain intact
          - no attribution notices are removed.
        
        2.4 Community Contributions
        Submit improvements, bug fixes, or enhancements to the official QObserva
        repository maintained by BuildersArk LLC.
        
        ------------------------------------------------------------------------
        
        3. Restrictions
        
        Without a separate written commercial license from BuildersArk LLC, You
        may NOT:
        
        3.1 Provide as a Hosted Service
        Offer the Software or any Derivative Work as a Hosted Service where the
        primary value derives from the Software's functionality.
        
        3.2 Operate a Competing Service
        Operate or provide a Competing Service using the Software.
        
        3.3 Distribute Modified Versions
        Distribute Derivative Works or modified versions of the Software to
        third parties except when contributing them back to the official
        repository.
        
        3.4 Remove Notices
        Remove, obscure, or alter copyright notices, license notices, or
        attribution statements contained in the Software.
        
        3.5 Misrepresent Origin
        Misrepresent the origin of the Software. If modifications are
        distributed via contributions, they must clearly indicate that they are
        modifications.
        
        3.6 Trademark Usage
        Use the names QObserva, BuildersArk, or related trademarks, logos, or
        branding without written permission from the Licensor.
        
        Nothing in this License grants rights to Licensor trademarks except for
        factual statements such as: "Powered by QObserva".
        
        ------------------------------------------------------------------------
        
        4. Third-Party Components
        
        The Software may include or depend on third-party components licensed
        under separate open source or proprietary licenses.
        
        Those licenses apply independently of this License. Nothing in this
        License overrides the terms of third-party licenses.
        
        ------------------------------------------------------------------------
        
        5. No Warranty
        
        THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT
        WARRANTY OF ANY KIND.
        
        LICENSOR DISCLAIMS ALL WARRANTIES INCLUDING BUT NOT LIMITED TO:
          - MERCHANTABILITY
          - FITNESS FOR A PARTICULAR PURPOSE
          - NON-INFRINGEMENT.
        
        YOU ASSUME ALL RISKS ASSOCIATED WITH USE OF THE SOFTWARE.
        
        ------------------------------------------------------------------------
        
        6. Limitation of Liability
        
        TO THE MAXIMUM EXTENT PERMITTED BY LAW, LICENSOR SHALL NOT BE LIABLE FOR
        ANY DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE
        INCLUDING BUT NOT LIMITED TO:
          - DIRECT DAMAGES
          - INDIRECT DAMAGES
          - INCIDENTAL DAMAGES
          - SPECIAL DAMAGES
          - CONSEQUENTIAL DAMAGES.
        
        ------------------------------------------------------------------------
        
        7. Termination
        
        7.1 Breach
        This License terminates automatically if You materially breach its
        terms.
        
        7.2 Cure Period
        Licensor may provide written notice of breach and allow thirty (30) days
        to cure the violation.
        
        7.3 Effect of Termination
        Upon termination You must:
          - immediately cease use of the Software
          - destroy all copies of the Software in Your possession.
        
        Sections relating to restrictions, disclaimers, and liability survive
        termination.
        
        ------------------------------------------------------------------------
        
        8. Commercial Licensing
        
        Organizations wishing to:
          - operate QObserva as a Hosted Service
          - distribute modified versions commercially
          - build commercial products or services based on QObserva
        
        must obtain a separate commercial license from BuildersArk LLC.
        
        For commercial licensing inquiries contact:
        
          support@qobserva.com
        
        ------------------------------------------------------------------------
        
        9. Contributions
        
        Unless otherwise agreed in writing, any contribution intentionally
        submitted to the QObserva project grants BuildersArk LLC a perpetual,
        worldwide, royalty-free license to use, modify, distribute, sublicense,
        and commercialize such contributions as part of the QObserva project.
        
        ------------------------------------------------------------------------
        
        10. Governing Law
        
        This License shall be governed by and construed in accordance with the
        laws of the State of Texas, United States, without regard to
        conflict-of-law principles.
        
        ------------------------------------------------------------------------
        
        11. Future Licensing
        
        BuildersArk LLC reserves the right to offer the Software under different
        licensing terms, including commercial licenses or alternative community
        licenses, in the future.
License-File: LICENSE
Keywords: benchmarking,braket,cirq,dwave,monitoring,observability,pennylane,pyquil,qiskit,quantum,telemetry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: qobserva-agent>=0.1.0
Requires-Dist: qobserva-collector>=0.1.0
Requires-Dist: qobserva-local>=0.1.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: all-sdks
Requires-Dist: amazon-braket-sdk>=1.70.0; extra == 'all-sdks'
Requires-Dist: cirq>=1.0.0; extra == 'all-sdks'
Requires-Dist: dimod>=0.12.0; extra == 'all-sdks'
Requires-Dist: pennylane>=0.35.0; extra == 'all-sdks'
Requires-Dist: pyquil>=4.0.0; extra == 'all-sdks'
Requires-Dist: qiskit>=1.0.0; extra == 'all-sdks'
Provides-Extra: braket
Requires-Dist: amazon-braket-sdk>=1.70.0; extra == 'braket'
Provides-Extra: cirq
Requires-Dist: cirq>=1.0.0; extra == 'cirq'
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: dwave
Requires-Dist: dimod>=0.12.0; extra == 'dwave'
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.35.0; extra == 'pennylane'
Provides-Extra: pyquil
Requires-Dist: pyquil>=4.0.0; extra == 'pyquil'
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0.0; extra == 'qiskit'
Description-Content-Type: text/markdown

# QObserva

Quantum program observability and benchmarking. Local-first, security-first observability for quantum computing.

> ⚠️ **Beta:** QObserva is currently in beta. APIs may change.

## Quick Start

### Prerequisites

- **Python 3.10+** (see [Python Version Compatibility](#python-version-compatibility) for SDK-specific requirements)
- **Node.js** (for React dashboard)

**Recommendation:** For best compatibility with all SDKs, use **Python 3.12**.

### Installation

**From PyPI (recommended):**

```bash
pip install qobserva
```

For SDK adapters, install the agent with extras:

```bash
pip install qobserva-agent[qiskit]      # Qiskit
pip install qobserva-agent[all-sdks]    # All supported SDKs
```

**From source (development):**

```bash
git clone https://github.com/BuildersArk/qobserva.git
cd qobserva
pip install -e packages/qobserva_agent
pip install -e packages/qobserva_collector
pip install -e packages/qobserva_local
pip install -e packages/qobserva
# One-time: cd packages/qobserva_ui_react && npm install
```

### Start QObserva

```bash
qobserva up
```

Dashboard opens at **http://localhost:3000**

### Stop QObserva

```bash
qobserva down
```

## What is QObserva?

QObserva provides standardized telemetry, metrics, and visualizations for quantum program executions across all major Python quantum SDKs.

### Features

- **Decorator-first instrumentation**: `@observe_run()` decorator with a simple API
- **Multi-SDK support**: Qiskit, Braket, Cirq, PennyLane, pyQuil, D-Wave (all tested)
- **Professional React dashboard**: Modern dark-themed UI with diverse visualizations
  - Home dashboard with KPIs, trends, and run tables
  - Analytics dashboard with performance metrics and comparisons
  - Algorithm analytics for cross-SDK algorithm comparison
  - Run details with comprehensive quantum metrics
  - Compare runs side-by-side, search and filter, PDF report generation
- **Local-first**: Everything runs locally, no cloud required
- **Standardized schema**: Common event format across all SDKs
- **One-command setup**: `qobserva up` starts collector and dashboard
- **Energy metrics**: D-Wave optimization metrics (energy, approximation ratio)
- **Comprehensive metrics**: Entropy, top-K dominance, shot efficiency, runtime analysis

## Usage

### Instrument Your Code

**Always include the `sdk` tag for reliable adapter selection.**

```python
from qobserva import observe_run

@observe_run(
    project="my_project",
    tags={
        "sdk": "qiskit",       # Required
        "algorithm": "vqe"     # Optional but recommended
    },
    benchmark_id="vqe_h2_ground_state",
    benchmark_params={"energy": -1.137, "convergence_iterations": 10}
)
def my_quantum_algorithm():
    # Your quantum code here
    return execute_quantum_circuit()
```

**Supported SDK values:** `"qiskit"`, `"braket"`, `"cirq"`, `"pennylane"`, `"pyquil"`, `"dwave"`

Add an `"algorithm"` tag (e.g. `"vqe"`, `"grover"`, `"qaoa"`) to enable algorithm-specific dashboards and cross-SDK comparison.

### View Dashboard

Open http://localhost:3000 for:

- **Home**: Real-time run metrics, KPIs, success rate trends
- **Analytics**: Performance analysis and trends
- **Algorithms**: Algorithm-specific metrics and cross-SDK comparison (with algorithm tags)
- **Compare**: Side-by-side run comparison, search and filter

## Architecture

- **qobserva-agent**: Telemetry agent with decorators and adapters for all major quantum SDKs
- **qobserva-collector**: FastAPI service for ingestion, validation, and storage
- **qobserva-local**: One-command orchestrator for the local stack (includes React dashboard)
- **qobserva**: This meta-package and CLI (`qobserva up` / `qobserva down`)

The React dashboard is part of the local stack and runs automatically when you run `qobserva up`.

## SDK Support

```bash
pip install qobserva-agent[all-sdks]

# Or individual SDKs
pip install qobserva-agent[qiskit]
pip install qobserva-agent[braket]
pip install qobserva-agent[cirq]
pip install qobserva-agent[pennylane]
pip install qobserva-agent[pyquil]
pip install qobserva-agent[dwave]
```

### Python Version Compatibility

| SDK     | Python Version   | Notes |
|--------|------------------|--------|
| Qiskit | 3.10+            | 3.10–3.14 |
| Braket | 3.10 – 3.13      | **3.14+ not supported** (Braket uses Pydantic v1) |
| Cirq   | 3.10+            | 3.10–3.14 |
| PennyLane | 3.10+         | 3.10–3.14 |
| pyQuil | 3.10 – 3.12      | **3.13+ not supported** (PyQuil 4.x) |
| D-Wave | 3.10+            | 3.10–3.14 |

**Recommendations:** Use **Python 3.12** for all 6 SDKs; **Python 3.13** if you don’t need pyQuil.

## Project, Provider, and Backend

- **Project**: From `@observe_run(project="...")` — user-defined, for grouping runs.
- **Provider**: Extracted from the result (e.g. `ibm`, `aws_braket`, `local_sim`).
- **Backend**: Extracted from the result (e.g. `ibm_brisbane`, `default.qubit`).

Filter by these in the dashboard to compare providers and backends. Always set `tags={"sdk": "..."}` so adapter selection is correct.

## Documentation

- [Getting Started](https://github.com/BuildersArk/qobserva/blob/main/docs/GETTING_STARTED.md)
- [Testing Guide](https://github.com/BuildersArk/qobserva/blob/main/docs/TESTING_GUIDE.md)
- [API Reference](https://github.com/BuildersArk/qobserva/blob/main/docs/API_REFERENCE.md)
- [SDK Compatibility](https://github.com/BuildersArk/qobserva/blob/main/docs/SDK_COMPATIBILITY.md)
- [Troubleshooting](https://github.com/BuildersArk/qobserva/blob/main/docs/TROUBLESHOOTING.md)

## Links

- **Website**: [qobserva.com](https://qobserva.com)
- **Documentation**: [qobserva.com/docs.html](https://qobserva.com/docs.html)
- **GitHub**: [github.com/BuildersArk/qobserva](https://github.com/BuildersArk/qobserva)
- **Issues**: [github.com/BuildersArk/qobserva/issues](https://github.com/BuildersArk/qobserva/issues)

## Reporting Issues / Getting Help

If you encounter bugs, have questions, or would like to request features for the `qobserva` CLI / meta-package, please open an issue on GitHub:

- [https://github.com/BuildersArk/qobserva/issues](https://github.com/BuildersArk/qobserva/issues)

## License

The `qobserva` meta-package and CLI are provided under the
**QObserva Community License v1.0** (source-available). See the `LICENSE` file in this
package for full terms. Commercial hosting, distribution of modified versions, or
commercial products based on QObserva require a separate license from BuildersArk LLC.
