Metadata-Version: 2.4
Name: qcoder
Version: 0.4.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 you **plan and review quantum circuit runs** using **local, deterministic artifacts** (JSON and Markdown): preflight context from circuit **structure**, then post-run review from **counts you provide**. It does **not** call an LLM, send telemetry, upload data, run a simulator or hardware, perform retrieval, or create embeddings.

Stable structural **feature vectors** (`schema_version`, `feature_names`, `features`) and a readable **`feature_map`** sit underneath; they power the guidance and profile layers but are not the whole story for day-one use.

**CLI:** **`qcoder analyze`**, **`qcoder batch`**, **`qcoder context`**, **`qcoder review`**. Optional **`qcoder[qiskit]`**, **`qcoder[cirq]`**, **`qcoder[pennylane]`** — Python-only **structure/export intake** into the same extractor as OpenQASM (no simulator or hardware execution inside qCoder).

**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).

---

## First 5 minutes: preflight → review

**1. Install** (Python **3.11+**; runtime dependency **NumPy**):

```bash
pip install qcoder
```

Pre-release lines on PyPI may look like **`0.4.0a1`**.

**2. Create a small Bell circuit** as `bell.qasm` (OpenQASM 2), or use the copy in **[`examples/circuits/bell.qasm`](examples/circuits/bell.qasm)** from a clone:

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

**3. Build preflight context** (heuristic resource guidance + optional structural taxonomy profiles):

```bash
qcoder context bell.qasm \
  --out-json preflight.context.json \
  --out-md preflight.context.md \
  --guidance --profiles
```

From the repo root you can instead run:

```bash
qcoder context examples/circuits/bell.qasm \
  --out-json preflight.context.json \
  --out-md preflight.context.md \
  --guidance --profiles
```

**4. Review with sample counts** (illustrative counts only—not produced by qCoder). From a **clone**, use the fixture **[`examples/fixtures/bell_counts_qiskit.json`](examples/fixtures/bell_counts_qiskit.json)**:

```bash
qcoder review \
  --counts-json examples/fixtures/bell_counts_qiskit.json \
  --format qiskit_counts \
  --preflight-json preflight.context.json \
  --out-json execution.review.json \
  --out-md execution.review.md
```

If you only have **`pip install`** and no **`examples/`** tree, write the same payload to a file and pass that path:

```bash
printf '%s\n' '{"00": 5, "11": 3}' > counts.json
qcoder review \
  --counts-json counts.json \
  --format qiskit_counts \
  --preflight-json preflight.context.json \
  --out-json execution.review.json \
  --out-md execution.review.md
```

In real use, **`counts.json`** comes from **your** simulator or hardware pipeline; qCoder only reads the file you pass in.

**Examples:** **[`examples/README.md`](examples/README.md)** (Bell QASM + illustrative counts for clones).

---

## What qCoder analyzes

qCoder summarizes **circuit structure** from OpenQASM (and optional framework export paths). Pair its JSON with **your** 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.
- **Optional `--profiles`** on **`qcoder context`** and on **`qcoder analyze --json`** — deterministic derived structural taxonomy from `feature_map` (additive, non-canonical). For **`analyze`**, use **`--json --profiles`** together.
- **`qcoder context`** — deterministic preflight context artifacts (**JSON + Markdown**), including optional `--guidance`, optional **`--profiles`**, 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 (optional extras)

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

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.

Optional **`--profiles`** adds deterministic **`feature_profiles`** derived from `feature_map` for compact structural taxonomy. This is an additive interpretation layer with its own schema version and does not modify canonical `features` (`schema_version`, `feature_names`, `features`).

`qcoder context` and `qcoder review` generate deterministic local artifacts (JSON + Markdown) intended for user-controlled 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 reference (other commands)

```bash
qcoder analyze path/to/circuit.qasm
qcoder analyze path/to/circuit.qasm --json
qcoder analyze path/to/circuit.qasm --json --guidance
qcoder analyze path/to/circuit.qasm --json --profiles
qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md preflight.context.md --guidance
qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md preflight.context.md --profiles
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`.
