qcoder 0.3.0a1

Quantum circuit analysis and structured feature extraction tools.

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 · manual. Source: github.com/QuantumReadySolutions/qCoder. Support: [e-mail].

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

pip install qcoder

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

Optional Qiskit adapter:

pip install "qcoder[qiskit]"

Optional Cirq adapter:

pip install "qcoder[cirq]"

Optional PennyLane adapter:

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

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.

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.