qcoder 0.3.0a1__tar.gz → 0.4.0a1__tar.gz

{qcoder-0.3.0a1 → qcoder-0.4.0a1}/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.

{qcoder-0.3.0a1 → qcoder-0.4.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.3.0a1
+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>
@@ -30,15 +30,89 @@ 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.
+**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.
 
-**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]"`**.
+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 declarations in your source files. Pair its JSON output with simulator or hardware run data whenever you need **execution evidence**.
+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)
 
@@ -47,7 +121,8 @@ 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.
+- **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.
@@ -59,49 +134,33 @@ Other modules under **`src/qcoder`** may exist for prototyping (extra tooling or
 
 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:
+## Install (optional extras)
 
 ```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.
+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 quickstart
+## 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

{qcoder-0.3.0a1 → qcoder-0.4.0a1}/README.md

@@ -1,14 +1,88 @@
 # 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.
+**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.
 
-**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]"`**.
+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 declarations in your source files. Pair its JSON output with simulator or hardware run data whenever you need **execution evidence**.
+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)
 
@@ -17,7 +91,8 @@ 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.
+- **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.
@@ -29,49 +104,33 @@ Other modules under **`src/qcoder`** may exist for prototyping (extra tooling or
 
 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:
+## Install (optional extras)
 
 ```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.
+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 quickstart
+## 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

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

@@ -13,6 +13,7 @@ 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.
@@ -22,6 +23,8 @@ The canonical circuit feature schema remains the existing `features` payload (`s
 
 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.3.0a1 → qcoder-0.4.0a1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qcoder"
-version = "0.3.0a1"
+version = "0.4.0a1"
 description = "Quantum circuit analysis and structured feature extraction tools."
 readme = "README.md"
 requires-python = ">=3.11"

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

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

{qcoder-0.3.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.3.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.3.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", {})