qcoder 0.2.0a1__tar.gz → 0.4.0a1__tar.gz

qcoder-0.4.0a1/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on common practice for pre-1.0 semantic versioning: **`MAJOR.MINOR.PATCH`** with **`aN`** for alpha prereleases.
+
+## 0.4.0a1 (alpha)
+
+qCoder **0.4.0a1** adds opt-in derived **feature profiles**, mixed-width **review** checks, and a **5‑minute preflight→review** path.
+
+### Added
+
+- **`--profiles`** on **`qcoder analyze --json`** and **`qcoder context`** — deterministic derived **`feature_profiles`** from **`feature_map`**, emitted with **`feature_profiles_schema_version: "0.1"`** and **`basis: "deterministic_formula_from_feature_map"`**; **`not_guarantees: true`**.
+- **`bitstring_width_consistency`** check in **`qcoder review`** — warns when observed bitstring key lengths disagree; derived metrics still use observed counts (also covers **`qcoder`** and **`qiskit_counts`** normalization paths).
+
+### Improved
+
+- **README — First 5 minutes** — quick install → Bell QASM → **`qcoder context --guidance --profiles`** → **`qcoder review`** with sample counts.
+- **`examples/`** — Bell OpenQASM, illustrative counts fixture, copy-paste workflow docs, and optional **Qiskit / Cirq / PennyLane** export scripts (structure/export only).
+- **Profile label polish** — `connected_small_graph` for tiny circuits instead of misleading `connected_high_density`; **`statevector_scale`** tier key (replacing `circuit_width`); **`llm_summary_profile`** rendered as short sub-bullets in preflight Markdown.
+- **Execution review Markdown** — explicit that counts are user-provided and qCoder did not execute the circuit; **Assumptions and Limits** section when present.
+
+### Unchanged / scope
+
+- **Canonical feature schema** — same version, field order, and feature vector layout as **`0.3.0a1`** (`schema_v0`/compute path); profiles are additive only and do not alter canonical **`features`**.
+
+### Local-only boundaries
+
+- No LLM calls, telemetry, uploads, retrieval, or embeddings; no simulator or hardware execution, transpilation, or runtime execution in these CLI flows. Artifacts are local files under your control.
+
+## 0.3.0a1 (alpha)
+
+Optional Cirq and PennyLane intake alongside the existing Qiskit adapter. All adapters follow the same structural rules: framework object → OpenQASM 2 text → qCoder's shared parser pipeline.
+
+### Added
+
+- **`qcoder[cirq]`** — optional **Cirq** `Circuit` intake via OpenQASM 2 export (`cirq.qasm`) into the same canonical extractor used for `.qasm` files.
+- **`qcoder[pennylane]`** — optional **PennyLane** intake (`QNode`, and **`QuantumScript`** where the installed version exposes it) via OpenQASM 2 export into the same canonical extractor used for `.qasm` files.
+
+### Changed
+
+- **Adapter error handling** — Qiskit intake wraps **`qiskit.qasm2.dumps`** failures and QASM-parse failures at the adapter boundary in actionable **`RuntimeError`** messages aligned with Cirq and PennyLane adapters.
+
+### Unchanged / scope
+
+- **Canonical feature schema** — same version, field order, and feature vector layout as **`0.2.0a1`** (`schema_v0`/compute path).
+- **Intake semantics** — Qiskit, Cirq, and PennyLane adapters are **structure/export intake only**: no transpiler upload, execution, simulator/hardware runs, telemetry, LLM calls, retrieval, or embeddings inside qCoder for these flows.
+
+## 0.2.0a1 (alpha)
+
+Local-only deterministic CLI tooling for quantum circuit analysis and LLM-ready workflow artifacts.
+
+### Added
+
+- **CLI help fixes** — consistent subcommands and help text (`analyze`, `batch`, `context`, `review`).
+- **`feature_map`** — derived `name → value` view alongside canonical nested `features` in machine-readable analyze output for readability.
+- **`--guidance`** — optional heuristic resource guidance on `qcoder analyze` and `qcoder batch` for shot budgets and simulator / MPS starting points (deterministic from structure only; non-guaranteed).
+- **`qcoder context`** — preflight artifacts as **Markdown + JSON** (optional `--guidance`, optional **`--full-features`** glossary appendix).
+- **`qcoder review`** — post-execution artifacts as **Markdown + JSON** from user-supplied counts; optional linkage to preflight JSON.
+- **`qcoder.counts.v0`** counts schema and **`qiskit_counts`** normalization into the same deterministic review pipeline.
+- **Feature glossary** — short deterministic definitions aligned with schema v0 feature names; surfaced in context bundles and **`--full-features`** appendix.
+- **Conservative `shots_total` handling** — when declared `shots_total` disagrees with `sum(counts)`, review-derived probabilities use the observed sum, with explicit **`shots_total_match` check**, warning text, and `declared_shots_total` / `shots_total_basis` fields.
+
+### Behaviour
+
+- **Local-only** — no LLM calls, no telemetry, no network, no retrieval or embeddings, no simulator or hardware execution within these CLI flows. Artifacts are files for you to attach or paste into tools of your choice.
+
+### Unchanged
+
+- Canonical circuit feature schema (version, order, and vector layout in `features`) is unchanged for this release.

qcoder-0.4.0a1/PKG-INFO

@@ -0,0 +1,185 @@
+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`.

qcoder-0.4.0a1/README.md

@@ -0,0 +1,155 @@
+# 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`.

{qcoder-0.2.0a1 → qcoder-0.4.0a1}/docs/architecture.md

@@ -4,6 +4,8 @@
 
 - Primary path: **OpenQASM / QASM** text analyzed on the developer machine.
 - Optional path: **`qcoder[qiskit]`** can ingest **Qiskit `QuantumCircuit`** objects into the **same extractor** as OpenQASM.
+- Optional path: **`qcoder[cirq]`** can ingest **Cirq `Circuit`** objects into the **same extractor** as OpenQASM.
+- Optional path: **`qcoder[pennylane]`** can ingest **PennyLane circuits** into the **same extractor** as OpenQASM.
 
 The field glossary is defined in **`src/qcoder/engines/feature_extraction/features/schema_v0.py`** (`FEATURE_NAMES_V0`). The [qcoder.ai manual — Feature reference](https://qcoder.ai/manual/feature-reference/) summarizes each field name.
 
@@ -11,13 +13,18 @@ The supported product surface described in **`README.md`** (**Package layout**)
 
 - **`qcoder analyze`** and **`qcoder batch`** for deterministic structural extraction output.
 - Optional **`--guidance`** for deterministic heuristic starting points derived from `feature_map`.
+- Optional **`--profiles`** on `analyze` / `context` for deterministic derived structural taxonomy from `feature_map`.
 - **`qcoder context`** for deterministic preflight artifacts (**JSON + Markdown**), with optional `--full-features` glossary appendix.
 - **`qcoder review`** for deterministic post-run review artifacts (**JSON + Markdown**) from user-provided counts.
 - Counts normalization from **`qcoder.counts.v0`** and **`qiskit_counts`** into one deterministic review path.
-- Optional **`qcoder[qiskit]`** ingestion into the same extractor as OpenQASM.
+- Optional **`qcoder[qiskit]`**, **`qcoder[cirq]`**, and **`qcoder[pennylane]`** ingestion into the same extractor as OpenQASM.
 
 The canonical circuit feature schema remains the existing `features` payload (`schema_version`, `feature_names`, `features`) produced by extraction. Guidance/context/review outputs are additive artifact layers and do not change canonical feature schema/version/order.
 
 When requested via CLI flags, qCoder may emit an additional top-level `guidance` block built deterministically from `feature_map`. This guidance is outside the canonical feature schema (`features`) and is intended as transparent heuristic starting points rather than execution-validated recommendations.
 
+qCoder may also emit an optional top-level `feature_profiles` block derived deterministically from `feature_map`. `feature_profiles` is additive, separately versioned (`feature_profiles_schema_version`), and does not alter canonical `features` schema/version/order.
+
 The `context` and `review` commands generate deterministic local artifacts (Markdown/JSON) for user-controlled planning and post-run analysis workflows. "LLM-ready/RAG-ready" in this context means users can attach/paste artifacts manually; qCoder itself makes no LLM calls and performs no retrieval, embeddings, network calls, telemetry upload, or database writes. qCoder also does not execute simulators or hardware backends in these flows.
+
+Optional framework adapters perform conversion/intake only; they do not execute circuits, simulators, or hardware.

{qcoder-0.2.0a1 → qcoder-0.4.0a1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qcoder"
-version = "0.2.0a1"
+version = "0.4.0a1"
 description = "Quantum circuit analysis and structured feature extraction tools."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -28,6 +28,8 @@ dependencies = ["numpy"]
 
 [project.optional-dependencies]
 qiskit = ["qiskit>=1.0"]
+cirq = ["cirq-core>=1.4"]
+pennylane = ["pennylane>=0.44"]
 
 [project.urls]
 Homepage = "https://qcoder.ai"

{qcoder-0.2.0a1 → qcoder-0.4.0a1}/src/qcoder/__init__.py

@@ -1,3 +1,3 @@
 __all__ = []
-__version__ = "0.2.0a1"
+__version__ = "0.4.0a1"
 file = __file__

{qcoder-0.2.0a1 → qcoder-0.4.0a1}/src/qcoder/cli.py

@@ -30,10 +30,22 @@ def _cmd_analyze(argv: list[str]) -> int:
     p.add_argument("--threshold", type=float, default=None, help="Optional threshold/bond-dim conditioning value")
     p.add_argument("--mirror-artifacts-dir", default=None, metavar="DIR", help="If set, write mirror QASM to DIR and add adjoint_supported/adjoint_reason/mirror_qasm_ref to output")
     p.add_argument("--guidance", action="store_true", help="Include heuristic resource guidance (shots and simulator/MPS starting points)")
+    p.add_argument(
+        "--profiles",
+        action="store_true",
+        help="Include derived feature_profiles in JSON output (requires --json for analyze)",
+    )
 
     p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
     args = p.parse_args(argv)
 
+    if args.profiles and not args.json:
+        print(
+            "qcoder: --profiles is currently emitted only with --json for analyze; use --json --profiles.",
+            file=sys.stderr,
+        )
+        return 2
+
     report = analyze_qasm(
         args.qasm,
         circuit_id=args.circuit_id,
@@ -45,7 +57,13 @@ def _cmd_analyze(argv: list[str]) -> int:
     )
 
     if args.json:
-        print(json.dumps(report.to_json_dict(include_guidance=args.guidance), indent=2, sort_keys=True))
+        print(
+            json.dumps(
+                report.to_json_dict(include_guidance=args.guidance, include_profiles=args.profiles),
+                indent=2,
+                sort_keys=True,
+            )
+        )
         return 0
 
     ex = report.example
@@ -62,7 +80,7 @@ def _cmd_analyze(argv: list[str]) -> int:
     print(f"schema: {fv.schema_version}")
     print(f"n_features: {len(fv.features)}")
     if args.guidance:
-        out = report.to_json_dict(include_guidance=True)
+        out = report.to_json_dict(include_guidance=True, include_profiles=args.profiles)
         guidance = out.get("guidance", {})
         shot = guidance.get("shot_guidance", {})
         sim = guidance.get("simulation_guidance", {})
@@ -122,6 +140,11 @@ def _cmd_context(argv: list[str]) -> int:
     p.add_argument("--id", dest="circuit_id", default=None, help="Optional circuit id")
     p.add_argument("--name", dest="circuit_name", default=None, help="Optional circuit name")
     p.add_argument("--guidance", action="store_true", help="Include heuristic resource guidance in context artifacts")
+    p.add_argument(
+        "--profiles",
+        action="store_true",
+        help="Include deterministic derived feature profiles in context artifacts",
+    )
     p.add_argument(
         "--full-features",
         action="store_true",
@@ -134,6 +157,7 @@ def _cmd_context(argv: list[str]) -> int:
         out_json=args.out_json,
         out_md=args.out_md,
         include_guidance=args.guidance,
+        include_profiles=args.profiles,
         include_full_features=args.full_features,
         circuit_id=args.circuit_id,
         circuit_name=args.circuit_name,

{qcoder-0.2.0a1 → qcoder-0.4.0a1}/src/qcoder/engines/context/bundle.py

@@ -22,11 +22,26 @@ def qasm_sha256(path: str) -> str:
     return hashlib.sha256(data).hexdigest()
 
 
+def context_bundle_basis(analysis: dict[str, Any]) -> str:
+    """Human-readable bundle basis from which optional blocks are included."""
+    has_g = "guidance" in analysis
+    has_p = "feature_profiles" in analysis
+    if has_g and has_p:
+        return "deterministic_analysis_plus_guidance_and_profiles"
+    if has_g:
+        return "deterministic_analysis_plus_guidance"
+    if has_p:
+        return "deterministic_analysis_plus_profiles"
+    return "deterministic_analysis"
+
+
 def analysis_fingerprint(analysis: dict[str, Any]) -> str:
     canonical = {
         "features": analysis.get("features", {}),
         "feature_map": analysis.get("feature_map", {}),
     }
+    if "feature_profiles" in analysis:
+        canonical["feature_profiles"] = analysis.get("feature_profiles", {})
     raw = json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode("utf-8")
     return hashlib.sha256(raw).hexdigest()
 
@@ -58,11 +73,22 @@ def build_context_bundle(
     }
     if "guidance" in analysis:
         analysis_block["guidance"] = analysis["guidance"]
+    if "feature_profiles" in analysis:
+        analysis_block["feature_profiles"] = analysis["feature_profiles"]
+
+    llm_limits = [
+        "Do not interpret this artifact as simulator or hardware execution evidence.",
+        "Guidance is heuristic and non-guaranteed when present.",
+    ]
+    if "feature_profiles" in analysis:
+        llm_limits.append(
+            "Feature profiles are deterministic structural taxonomy, not execution evidence."
+        )
 
     return {
         "context_bundle_schema_version": "0.1",
         "artifact_type": "qcoder.preflight_context",
-        "basis": "deterministic_analysis_plus_optional_guidance",
+        "basis": context_bundle_basis(analysis),
         "generated_utc": generated_utc or utc_now_iso(),
         "qcoder_version": qcoder_version,
         "circuit": circuit,
@@ -77,10 +103,7 @@ def build_context_bundle(
         ],
         "llm_use": {
             "intended_use": "Attach or paste this artifact for AI-assisted circuit planning.",
-            "limits": [
-                "Do not interpret this artifact as simulator or hardware execution evidence.",
-                "Guidance is heuristic and non-guaranteed when present.",
-            ],
+            "limits": llm_limits,
         },
     }
 

{qcoder-0.2.0a1 → qcoder-0.4.0a1}/src/qcoder/engines/context/markdown.py

@@ -19,6 +19,7 @@ def render_context_markdown(bundle: dict[str, Any]) -> str:
     feature_names = list(features_obj.get("feature_names") or [])
     feature_values = list(features_obj.get("features") or [])
     guidance = analysis.get("guidance")
+    feature_profiles = analysis.get("feature_profiles")
     lines: list[str] = []
 
     lines.append("# qCoder Preflight Context")
@@ -52,6 +53,39 @@ def render_context_markdown(bundle: dict[str, Any]) -> str:
             else:
                 lines.append(f"- {key}: `{_fmt_num(feature_map.get(key))}`")
     lines.append("")
+    if feature_profiles is not None:
+        profiles = feature_profiles.get("profiles", {})
+        lines.append("## Derived feature profiles")
+        lines.append(
+            "- Deterministic structural taxonomy derived from `feature_map`; not execution evidence."
+        )
+        lines.append(
+            "- Additive interpretation layer only; canonical `features` remains the source-of-truth vector."
+        )
+        ordered = [
+            "size_profile",
+            "sampling_profile",
+            "entanglement_profile",
+            "topology_profile",
+            "locality_profile",
+            "simulation_pressure_profile",
+            "llm_summary_profile",
+        ]
+        for key in ordered:
+            prof = profiles.get(key, {})
+            if key == "llm_summary_profile":
+                summary_lines = prof.get("lines", [])
+                lines.append(f"- {key}:")
+                for summary_line in summary_lines:
+                    lines.append(f"  - {summary_line}")
+                continue
+            tiers = prof.get("tiers", {})
+            tier_keys = sorted(tiers.keys())
+            tier_str = ", ".join(f"{k}={tiers[k]}" for k in tier_keys)
+            labels = prof.get("labels", [])
+            labels_str = ", ".join(str(x) for x in labels)
+            lines.append(f"- {key}: tiers=`{tier_str}` labels=`{labels_str}`")
+        lines.append("")
     if guidance is not None:
         shot = guidance.get("shot_guidance", {})
         sim = guidance.get("simulation_guidance", {})