Metadata-Version: 2.4
Name: qcoder
Version: 0.3.0a1
Summary: Quantum circuit analysis and structured feature extraction tools.
Author-email: Quantum Ready Solutions <support@qcoder.ai>
Maintainer-email: Quantum Ready Solutions <support@qcoder.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://qcoder.ai
Project-URL: Documentation, https://qcoder.ai/manual/
Project-URL: Repository, https://github.com/QuantumReadySolutions/qCoder
Project-URL: Issues, https://github.com/QuantumReadySolutions/qCoder/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0; extra == "qiskit"
Provides-Extra: cirq
Requires-Dist: cirq-core>=1.4; extra == "cirq"
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.44; extra == "pennylane"
Dynamic: license-file

# qCoder

**qCoder** helps developers **inspect quantum circuits before they run them.** It reads **OpenQASM** circuits, extracts **repeatable structural features**, and emits **structured JSON** (single file) or **JSONL** (batches)—useful for **notebooks**, **CI**, **pull-request review**, and **AI coding assistants** when you attach or paste deterministic context next to circuit text.

**CLI:** **`qcoder analyze`**, **`qcoder batch`**, **`qcoder context`**, and **`qcoder review`**. Optional **Qiskit / Cirq / PennyLane** intake (structure/export only, no simulator or hardware execution): **`pip install "qcoder[qiskit]"`**, **`pip install "qcoder[cirq]"`**, **`pip install "qcoder[pennylane]"`**.

**Company / legal:** Quantum Ready Solutions. **Product docs:** [qcoder.ai](https://qcoder.ai) · [manual](https://qcoder.ai/manual/). **Source:** [github.com/QuantumReadySolutions/qCoder](https://github.com/QuantumReadySolutions/qCoder). **Support:** [support@qcoder.ai](mailto:support@qcoder.ai).

## What qCoder analyzes

qCoder summarizes **circuit structure** from declarations in your source files. Pair its JSON output with simulator or hardware run data whenever you need **execution evidence**.

## Package layout (supported public surface)

For **this release**, treat the **supported surface** as:

- **`qcoder analyze`** — single-circuit extraction (human or `--json`).
- **`qcoder batch`** — directory batch to **JSONL**.
- **Optional `--guidance`** on `analyze` / `batch` — deterministic heuristic starting points (shots and simulator/MPS settings) derived from circuit structure.
- **`qcoder context`** — deterministic preflight context artifacts (**JSON + Markdown**), including optional `--guidance` and optional `--full-features` glossary appendix.
- **`qcoder review`** — deterministic post-run review artifacts (**JSON + Markdown**) from user-provided counts.
- **Counts intake normalization** — `qcoder.counts.v0` and `qiskit_counts` normalization into the same deterministic review path.
- **`qcoder[qiskit]`** — optional `QuantumCircuit` intake into the **same extractor** as OpenQASM.
- **`qcoder[cirq]`** — optional Cirq `Circuit` intake into the **same extractor** as OpenQASM.
- **`qcoder[pennylane]`** — optional PennyLane circuit intake into the **same extractor** as OpenQASM.
- **Documented feature output** — see [qcoder.ai — Feature reference](https://qcoder.ai/manual/feature-reference/) and `engines/feature_extraction/features/schema_v0.py`; JSON carries a **`schema_version`** alongside named fields.

Other modules under **`src/qcoder`** may exist for prototyping (extra tooling or engines outside the commands above). Unless documented here, **`docs/`**, or **qcoder.ai**, they do **not** share the same stability expectations as the commands and artifact formats listed above.

Brief notes live in **`docs/architecture.md`**.

## Install

```bash
pip install qcoder
```

Pre-release lines on PyPI use segments such as **`0.3.0a1`**.

Optional Qiskit adapter:

```bash
pip install "qcoder[qiskit]"
```

Optional Cirq adapter:

```bash
pip install "qcoder[cirq]"
```

Optional PennyLane adapter:

```bash
pip install "qcoder[pennylane]"
```

Requires **Python 3.11+**. Runtime dependency: **NumPy**.

Machine-readable JSON from **`qcoder analyze --json`** includes a derived **`feature_map`** object (`name → value`) for easier reading. The canonical circuit feature bundle remains the nested **`features`** object (`schema_version`, **`feature_names`**, **`features`**).

Optional **`--guidance`** adds heuristic shot-count and simulator/MPS starting-point suggestions derived from structural features. These suggestions are transparent, non-guaranteed starting points only; qCoder performs no backend execution and includes no telemetry/upload in this flow.

`qcoder context` and `qcoder review` generate deterministic local artifacts (JSON + Markdown) intended for user-controlled AI-assisted planning/review workflows. "LLM-ready/RAG-ready" in this project means users can attach or paste these artifacts manually; qCoder itself performs no retrieval, embeddings, network calls, or telemetry/upload in this flow.

The optional Qiskit, Cirq, and PennyLane adapters are structure/export intake paths only. qCoder does not execute simulators or hardware backends in these flows.

## CLI quickstart

```bash
qcoder analyze path/to/circuit.qasm
qcoder analyze path/to/circuit.qasm --json
qcoder analyze path/to/circuit.qasm --json --guidance
qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md preflight.context.md --guidance
qcoder batch circuits --out batch.features.jsonl --pattern "*.qasm"
qcoder batch circuits --out batch.features.jsonl --pattern "*.qasm" --guidance
qcoder review --counts-json counts.json --format qiskit_counts --preflight-json preflight.context.json --out-json execution.review.json --out-md execution.review.md
```

**Batch:** JSONL records are written to **`--out`**. Status lines (for example record counts) may go to **stderr**, so prefer **`--out`** over shell stdout redirection for the JSONL stream.

## Develop / test (from a clone)

If you use **pyenv**, select the intended Python before creating the venv (for example `pyenv local 3.11.x` or `pyenv shell 3.11.x`) so `python -m venv` uses that interpreter.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[qiskit]"
pip install pytest
pytest -q
```

## License

Licensed under the **Apache License 2.0**. See `LICENSE` and `NOTICE`.
