qcoder 0.4.0a1

Quantum circuit analysis and structured feature extraction tools.

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

---

First 5 minutes: preflight → review

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

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 from a clone:

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

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

From the repo root you can instead run:

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:

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:

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

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)

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.

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.