qcoder 0.3.0a1__tar.gz → 0.4.0a2__tar.gz

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

@@ -4,6 +4,41 @@ 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.0a2 (alpha)
+
+### Added
+
+- **Local Guidance Pack shadow metadata** — optional **`guidance_metadata`** records the bundled local resource-guidance candidate pack, including pack identity, version/hash metadata, caveats, and **`shadow_guidance`** with **`applied: false`**; deterministic guidance remains authoritative.
+
+### Improved
+
+- **Free Single-Run Intelligence** and **BYO LLM** artifact examples clarify that shadow guidance is metadata only.
+- **Release notes** — this alpha has no hosted qCoder compute, no telemetry upload, no qCoder-hosted LLM, no runtime ML dependency, and no optimality, fidelity, runtime, hardware, backend-ranking, or causal-savings claims.
+
+## 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.4.0a2/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: qcoder
+Version: 0.4.0a2
+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.0a2`**.
+
+**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).
+
+- **Free single-run intelligence** and **BYO LLM artifact workflow:** [`examples/06_single_run_intelligence.md`](examples/06_single_run_intelligence.md), [`examples/07_byo_llm_artifact_pack.md`](examples/07_byo_llm_artifact_pack.md), copy-paste prompt [`examples/prompts/single_run_artifact_to_action.md`](examples/prompts/single_run_artifact_to_action.md).
+- Full walkthrough on the site: [Single-run intelligence with qCoder](https://qcoder.ai/manual/workflows/single-run-intelligence/).
+
+---
+
+## 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)
+
+**Current supported public surface:**
+
+- **`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.
+
+The public package contains the documented deterministic free-product surface 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. When a bundled local guidance pack is present, the guidance JSON may also include **`guidance_metadata`** (pack id/version/hash, shadow suggestions, explicit `fallback_used`) for BYO-LLM workflows; **deterministic** `pressure` / `starting_points` remain the user-visible values until a future release explicitly applies pack output.
+
+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.0a2/README.md

@@ -0,0 +1,158 @@
+# 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.0a2`**.
+
+**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).
+
+- **Free single-run intelligence** and **BYO LLM artifact workflow:** [`examples/06_single_run_intelligence.md`](examples/06_single_run_intelligence.md), [`examples/07_byo_llm_artifact_pack.md`](examples/07_byo_llm_artifact_pack.md), copy-paste prompt [`examples/prompts/single_run_artifact_to_action.md`](examples/prompts/single_run_artifact_to_action.md).
+- Full walkthrough on the site: [Single-run intelligence with qCoder](https://qcoder.ai/manual/workflows/single-run-intelligence/).
+
+---
+
+## 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)
+
+**Current supported public surface:**
+
+- **`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.
+
+The public package contains the documented deterministic free-product surface 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. When a bundled local guidance pack is present, the guidance JSON may also include **`guidance_metadata`** (pack id/version/hash, shadow suggestions, explicit `fallback_used`) for BYO-LLM workflows; **deterministic** `pressure` / `starting_points` remain the user-visible values until a future release explicitly applies pack output.
+
+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.3.0a1 → qcoder-0.4.0a2}/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.
@@ -20,8 +21,12 @@ The supported product surface described in **`README.md`** (**Package layout**)
 
 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.
+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. The same block may include **`guidance_metadata`** describing a packaged **shadow-mode** local guidance JSON candidate (read from disk via `importlib.resources`; no network): pack id/version/content hash, optional shadow suggestions, and explicit fallback flags. **Deterministic** MPS `pressure` and `starting_points` stay authoritative in this slice; the pack does not override them yet.
+
+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.
+
+The public package contains the documented deterministic free-product surface. Backend-specific runners, learned-prediction experiments, and private analysis prototypes are not part of the public package.

qcoder-0.4.0a2/docs/model-cards/resource-guidance-local-v0.md

@@ -0,0 +1,33 @@
+# Model card — `resource_guidance_local_v0` (shadow / metadata only)
+
+**Status:** Packaged as **candidate** JSON (`0.1.0-candidate`) in the public `qcoder` wheel under `qcoder.model_packs`. **Shadow mode only:** qCoder **does not** apply pack suggestions to `simulation_guidance.mps_bond_dimension.pressure` or `starting_points` in this release slice. Deterministic structural heuristics remain the user-visible source of truth.
+
+## Data scope
+
+- **Synthetic / public / qCoder-owned generated variants** only (as declared in the pack `training_data` block).
+- **No** real user telemetry, **no** Pro/private workflow exports, **no** unaudited archive dumps.
+
+## Runtime posture
+
+- **Local** package data only (`importlib.resources`); **no** network calls, **no** hosted inference, **no** telemetry upload from this path.
+- **No** runtime ML dependency (plain JSON; stdlib load and validate).
+
+## Non-claims (machine-readable keys also appear in the pack JSON)
+
+This pack and any shadow suggestions are **not**:
+
+- an optimality proof (`not_optimality_proof`);
+- a fidelity proof (`not_fidelity_proof`);
+- hardware correctness proof (`not_hardware_correctness_proof`);
+- a runtime guarantee (`not_runtime_guarantee`);
+- backend ranking or universal QPU quality scoring (`not_backend_ranking`);
+- causal savings or cost optimality (`not_causal_savings`).
+
+## Behavior in qCoder today
+
+- **Deterministic fallback preserved:** `build_resource_guidance` continues to set `pressure` and `starting_points` from structural scores only.
+- **`guidance_metadata`:** additive block on the guidance dict documenting pack id/version/hash, `fallback_used`, and `shadow_guidance` with `applied: false` until a future evaluated release explicitly enables application.
+
+## Promotion (future)
+
+Public promotion requires evaluation gates, reproducible labels, and explicit product/API review before any **non-shadow** application of pack outputs.

{qcoder-0.3.0a1 → qcoder-0.4.0a2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qcoder"
-version = "0.3.0a1"
+version = "0.4.0a2"
 description = "Quantum circuit analysis and structured feature extraction tools."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -46,6 +46,9 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+qcoder = ["model_packs/*.json"]
+
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 

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

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

{qcoder-0.3.0a1 → qcoder-0.4.0a2}/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.0a2}/src/qcoder/core/run_config.py

@@ -30,7 +30,7 @@ def normalize_precision(x: str | None) -> str:
 @dataclass(frozen=True)
 class RunConfig:
     """
-    Conditioning variables for runtime/fidelity predictors.
+    User-supplied run context for analyze reports.
 
     These are NOT circuit-derived features.
     """
@@ -38,10 +38,6 @@ class RunConfig:
     backend: str                    # normalized: "CPU" | "GPU"
     precision: str                  # normalized: "single" | "double"
     threshold: float | None = None  # e.g. bond-dimension/threshold conditioning
-    prediction_artifact_path: str | None = None
-    prediction_allow_schema_mismatch: bool = False
-    prediction_fidelity_target: float | None = None
-    prediction_fidelity_metric: str | None = None
 
     @staticmethod
     def from_raw(
@@ -50,10 +46,6 @@ class RunConfig:
         backend: str | None = None,
         precision: str | None = None,
         threshold: float | None = None,
-        prediction_artifact_path: str | None = None,
-        prediction_allow_schema_mismatch: bool | None = None,
-        prediction_fidelity_target: float | None = None,
-        prediction_fidelity_metric: str | None = None,
     ) -> "RunConfig":
         # accept processor OR backend as the same input channel
         raw = processor if processor is not None else backend
@@ -65,10 +57,6 @@ class RunConfig:
             backend=normalize_backend(raw or backend),
             precision=normalize_precision(precision),
             threshold=float(threshold) if threshold is not None else None,
-            prediction_artifact_path=prediction_artifact_path,
-            prediction_allow_schema_mismatch=prediction_allow_schema_mismatch or False,
-            prediction_fidelity_target=prediction_fidelity_target,
-            prediction_fidelity_metric=prediction_fidelity_metric,
         )
 
     def to_dict(self) -> dict:
@@ -77,8 +65,4 @@ class RunConfig:
             "backend": self.backend,
             "precision": self.precision,
             "threshold": self.threshold,
-            "prediction_artifact_path": self.prediction_artifact_path,
-            "prediction_allow_schema_mismatch": self.prediction_allow_schema_mismatch,
-            "prediction_fidelity_target": self.prediction_fidelity_target,
-            "prediction_fidelity_metric": self.prediction_fidelity_metric,
         }

{qcoder-0.3.0a1 → qcoder-0.4.0a2}/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,
         },
     }