qcoder 0.1.0a1__tar.gz → 0.2.0a1__tar.gz

qcoder-0.2.0a1/CHANGELOG.md

@@ -0,0 +1,28 @@
+# 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.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.1.0a1 → qcoder-0.2.0a1}/MANIFEST.in

@@ -1,6 +1,7 @@
 include LICENSE
 include NOTICE
 include README.md
+include CHANGELOG.md
 include pyproject.toml
 graft src
 graft tests

{qcoder-0.1.0a1/src/qcoder.egg-info → qcoder-0.2.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.1.0a1
+Version: 0.2.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>
@@ -28,7 +28,7 @@ Dynamic: license-file
 
 **qCoder** helps developers **inspect quantum circuits before they run them.** It reads **OpenQASM** circuits, extracts **repeatable structural features**, and emits **structured JSON** (single file) or **JSONL** (batches)—useful for **notebooks**, **CI**, **pull-request review**, and **AI coding assistants** when you attach or paste deterministic context next to circuit text.
 
-**CLI:** **`qcoder analyze`** and **`qcoder batch`**. Optional **Qiskit** intake: **`pip install "qcoder[qiskit]"`**.
+**CLI:** **`qcoder analyze`**, **`qcoder batch`**, **`qcoder context`**, and **`qcoder review`**. Optional **Qiskit** intake: **`pip install "qcoder[qiskit]"`**.
 
 **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).
 
@@ -42,10 +42,14 @@ For **this release**, treat the **supported surface** as:
 
 - **`qcoder analyze`** — single-circuit extraction (human or `--json`).
 - **`qcoder batch`** — directory batch to **JSONL**.
+- **Optional `--guidance`** on `analyze` / `batch` — deterministic heuristic starting points (shots and simulator/MPS settings) derived from circuit structure.
+- **`qcoder context`** — deterministic preflight context artifacts (**JSON + Markdown**), including optional `--guidance` and optional `--full-features` glossary appendix.
+- **`qcoder review`** — deterministic post-run review artifacts (**JSON + Markdown**) from user-provided counts.
+- **Counts intake normalization** — `qcoder.counts.v0` and `qiskit_counts` normalization into the same deterministic review path.
 - **`qcoder[qiskit]`** — optional `QuantumCircuit` intake into the **same extractor** as OpenQASM.
 - **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 **`analyze`** / **`batch`** and documented output.
+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`**.
 
@@ -55,7 +59,7 @@ Brief notes live in **`docs/architecture.md`**.
 pip install qcoder
 ```
 
-Pre-release lines on PyPI use segments such as **`0.1.0a1`**.
+Pre-release lines on PyPI use segments such as **`0.2.0a1`**.
 
 Optional Qiskit adapter:
 
@@ -65,16 +69,30 @@ pip install "qcoder[qiskit]"
 
 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.
+
 ## CLI quickstart
 
 ```bash
 qcoder analyze path/to/circuit.qasm
 qcoder analyze path/to/circuit.qasm --json
-qcoder batch path/to/qasm_dir/ --out features.jsonl
+qcoder analyze path/to/circuit.qasm --json --guidance
+qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md preflight.context.md --guidance
+qcoder batch circuits --out batch.features.jsonl --pattern "*.qasm"
+qcoder batch circuits --out batch.features.jsonl --pattern "*.qasm" --guidance
+qcoder review --counts-json counts.json --format qiskit_counts --preflight-json preflight.context.json --out-json execution.review.json --out-md execution.review.md
 ```
 
+**Batch:** JSONL records are written to **`--out`**. Status lines (for example record counts) may go to **stderr**, so prefer **`--out`** over shell stdout redirection for the JSONL stream.
+
 ## Develop / test (from a clone)
 
+If you use **pyenv**, select the intended Python before creating the venv (for example `pyenv local 3.11.x` or `pyenv shell 3.11.x`) so `python -m venv` uses that interpreter.
+
 ```bash
 python -m venv .venv
 source .venv/bin/activate

qcoder-0.2.0a1/README.md

@@ -0,0 +1,80 @@
+# qCoder
+
+**qCoder** helps developers **inspect quantum circuits before they run them.** It reads **OpenQASM** circuits, extracts **repeatable structural features**, and emits **structured JSON** (single file) or **JSONL** (batches)—useful for **notebooks**, **CI**, **pull-request review**, and **AI coding assistants** when you attach or paste deterministic context next to circuit text.
+
+**CLI:** **`qcoder analyze`**, **`qcoder batch`**, **`qcoder context`**, and **`qcoder review`**. Optional **Qiskit** intake: **`pip install "qcoder[qiskit]"`**.
+
+**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).
+
+## What qCoder analyzes
+
+qCoder summarizes **circuit structure** from declarations in your source files. Pair its JSON output with simulator or hardware run data whenever you need **execution evidence**.
+
+## Package layout (supported public surface)
+
+For **this release**, treat the **supported surface** as:
+
+- **`qcoder analyze`** — single-circuit extraction (human or `--json`).
+- **`qcoder batch`** — directory batch to **JSONL**.
+- **Optional `--guidance`** on `analyze` / `batch` — deterministic heuristic starting points (shots and simulator/MPS settings) derived from circuit structure.
+- **`qcoder context`** — deterministic preflight context artifacts (**JSON + Markdown**), including optional `--guidance` and optional `--full-features` glossary appendix.
+- **`qcoder review`** — deterministic post-run review artifacts (**JSON + Markdown**) from user-provided counts.
+- **Counts intake normalization** — `qcoder.counts.v0` and `qiskit_counts` normalization into the same deterministic review path.
+- **`qcoder[qiskit]`** — optional `QuantumCircuit` intake into the **same extractor** as OpenQASM.
+- **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
+
+```bash
+pip install qcoder
+```
+
+Pre-release lines on PyPI use segments such as **`0.2.0a1`**.
+
+Optional Qiskit adapter:
+
+```bash
+pip install "qcoder[qiskit]"
+```
+
+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.
+
+## CLI quickstart
+
+```bash
+qcoder analyze path/to/circuit.qasm
+qcoder analyze path/to/circuit.qasm --json
+qcoder analyze path/to/circuit.qasm --json --guidance
+qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md preflight.context.md --guidance
+qcoder batch circuits --out batch.features.jsonl --pattern "*.qasm"
+qcoder batch circuits --out batch.features.jsonl --pattern "*.qasm" --guidance
+qcoder review --counts-json counts.json --format qiskit_counts --preflight-json preflight.context.json --out-json execution.review.json --out-md execution.review.md
+```
+
+**Batch:** JSONL records are written to **`--out`**. Status lines (for example record counts) may go to **stderr**, so prefer **`--out`** over shell stdout redirection for the JSONL stream.
+
+## Develop / test (from a clone)
+
+If you use **pyenv**, select the intended Python before creating the venv (for example `pyenv local 3.11.x` or `pyenv shell 3.11.x`) so `python -m venv` uses that interpreter.
+
+```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/docs/architecture.md

@@ -0,0 +1,23 @@
+# qCoder architecture notes (public)
+
+**qCoder** maps circuit sources onto **repeatable structured output**: a **`schema_version`**, **`feature_names`**, and paired numeric **`features`** consumed from the extractor.
+
+- 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.
+
+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.
+
+The supported product surface described in **`README.md`** (**Package layout**) is:
+
+- **`qcoder analyze`** and **`qcoder batch`** for deterministic structural extraction output.
+- Optional **`--guidance`** for deterministic heuristic starting points derived 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.
+
+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.
+
+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.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qcoder"
-version = "0.1.0a1"
+version = "0.2.0a1"
 description = "Quantum circuit analysis and structured feature extraction tools."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -44,5 +44,8 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
 [tool.ruff]
 line-length = 100

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

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

qcoder-0.2.0a1/src/qcoder/cli.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from qcoder.pipelines.analyze import analyze_qasm
+from qcoder.tools.batch import analyze_qasm_dir_to_jsonl
+from qcoder.pipelines.context import write_preflight_context
+from qcoder.pipelines.review import write_execution_review
+
+
+def _cmd_analyze(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="qcoder analyze", add_help=True)
+    p.add_argument("qasm", help="Path to a .qasm file")
+
+    # Circuit identity / metadata
+    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")
+
+    # Run config (conditioning vars for predictors; not used by feature extraction)
+    p.add_argument(
+        "--processor",
+        "--backend",
+        dest="processor",
+        default="CPU",
+        help='Processor/backend label (aliases: Scarlet/Amber, CPU/GPU)',
+    )
+    p.add_argument("--precision", default="single", help="Precision: single|double (aliases: fp32/fp64)")
+    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("--json", action="store_true", help="Emit machine-readable JSON")
+    args = p.parse_args(argv)
+
+    report = analyze_qasm(
+        args.qasm,
+        circuit_id=args.circuit_id,
+        circuit_name=args.circuit_name,
+        processor=args.processor,
+        precision=args.precision,
+        threshold=args.threshold,
+        mirror_artifacts_dir=args.mirror_artifacts_dir or None,
+    )
+
+    if args.json:
+        print(json.dumps(report.to_json_dict(include_guidance=args.guidance), indent=2, sort_keys=True))
+        return 0
+
+    ex = report.example
+    rc = report.run_config
+    print(f"file: {ex.qasm_path}")
+    print(f"format: {ex.ir.source_format}")
+    if ex.name:
+        print(f"name: {ex.name}")
+    print(f"function_hint: {ex.function_hint} ({ex.function_source})")
+    print(f"processor: {rc.processor}  backend: {rc.backend}  precision: {rc.precision}  threshold: {rc.threshold}")
+    print(f"n_qubits: {ex.ir.n_qubits}")
+    print(f"n_ops: {ex.ir.n_ops}")
+    fv = ex.global_features
+    print(f"schema: {fv.schema_version}")
+    print(f"n_features: {len(fv.features)}")
+    if args.guidance:
+        out = report.to_json_dict(include_guidance=True)
+        guidance = out.get("guidance", {})
+        shot = guidance.get("shot_guidance", {})
+        sim = guidance.get("simulation_guidance", {})
+        mps = sim.get("mps_bond_dimension", {})
+        print("guidance: non-guaranteed heuristic starting points only; no backend execution")
+        print(
+            f"shots: applicability={shot.get('applicability')} "
+            f"starting={shot.get('starting_shots', [])}"
+        )
+        print(
+            f"simulator starting points: statevector_scale={sim.get('statevector', {}).get('scale')} "
+            f"mps_pressure={mps.get('pressure')} "
+            f"mps_starting_points={mps.get('starting_points', [])}"
+        )
+    return 0
+
+
+def _cmd_batch(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="qcoder batch", add_help=True)
+    p.add_argument("circuits_dir", help="Directory containing QASM files")
+    p.add_argument("--out", required=True, help="Output JSONL path")
+    p.set_defaults(recursive=True)
+    p.add_argument("--recursive", dest="recursive", action="store_true", help="Discover files recursively (default)")
+    p.add_argument("--non-recursive", dest="recursive", action="store_false", help="Only discover top-level files")
+    p.add_argument("--pattern", default="*.qasm", help="Glob pattern for files (default: *.qasm)")
+    p.add_argument("--skip-errors", action="store_true", help="Continue on error, emit error records (default: fail-fast)")
+    p.add_argument("--processor", default=None, help="Processor/backend label for run_config")
+    p.add_argument("--backend", default=None, help="Backend label (CPU/GPU, etc.)")
+    p.add_argument("--precision", default=None, help="Precision: single|double|fp32|fp64")
+    p.add_argument("--threshold", type=float, default=None, help="Optional threshold for run_config")
+    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 each record")
+    p.add_argument("--guidance", action="store_true", help="Include heuristic resource guidance block in each successful JSONL record")
+    args = p.parse_args(argv)
+
+    n = analyze_qasm_dir_to_jsonl(
+        args.circuits_dir,
+        args.out,
+        processor=args.processor,
+        backend=args.backend,
+        precision=args.precision,
+        threshold=args.threshold,
+        recursive=args.recursive,
+        pattern=args.pattern,
+        fail_fast=not args.skip_errors,
+        mirror_artifacts_dir=args.mirror_artifacts_dir or None,
+        include_guidance=args.guidance,
+    )
+    print(f"Wrote {n} records to {args.out}", file=sys.stderr)
+    return 0
+
+
+def _cmd_context(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="qcoder context", add_help=True)
+    p.add_argument("qasm", help="Path to a .qasm file")
+    p.add_argument("--out-json", required=True, help="Output preflight JSON context path")
+    p.add_argument("--out-md", required=True, help="Output preflight Markdown context path")
+    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(
+        "--full-features",
+        action="store_true",
+        help="Include full feature glossary/appendix in context artifacts (default: selected structural features only)",
+    )
+    args = p.parse_args(argv)
+
+    write_preflight_context(
+        args.qasm,
+        out_json=args.out_json,
+        out_md=args.out_md,
+        include_guidance=args.guidance,
+        include_full_features=args.full_features,
+        circuit_id=args.circuit_id,
+        circuit_name=args.circuit_name,
+    )
+    print(f"Wrote preflight context JSON to {args.out_json}", file=sys.stderr)
+    print(f"Wrote preflight context Markdown to {args.out_md}", file=sys.stderr)
+    return 0
+
+
+def _cmd_review(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="qcoder review", add_help=True)
+    p.add_argument("--counts-json", required=True, help="Input counts JSON path")
+    p.add_argument(
+        "--format",
+        dest="counts_format",
+        choices=["qcoder", "qiskit_counts"],
+        default="qcoder",
+        help="Input counts format (default: qcoder)",
+    )
+    p.add_argument("--preflight-json", default=None, help="Optional preflight context JSON path for linkage/checks")
+    p.add_argument("--out-json", required=True, help="Output execution review JSON path")
+    p.add_argument("--out-md", required=True, help="Output execution review Markdown path")
+    args = p.parse_args(argv)
+
+    write_execution_review(
+        counts_json=args.counts_json,
+        counts_format=args.counts_format,
+        preflight_json=args.preflight_json,
+        out_json=args.out_json,
+        out_md=args.out_md,
+    )
+    print(f"Wrote execution review JSON to {args.out_json}", file=sys.stderr)
+    print(f"Wrote execution review Markdown to {args.out_md}", file=sys.stderr)
+    return 0
+
+
+def _print_root_help() -> None:
+    """Top-level help (subcommand parsers own analyze/batch --help)."""
+    print(
+        "usage: qcoder [--version | -V] [-h] {analyze,batch,context,review} ...\n\n"
+        "Quantum circuit analysis CLI.\n\n"
+        "positional arguments:\n"
+        "  {analyze,batch,context,review}  subcommand\n\n"
+        "  analyze          Analyze a QASM file (feature extraction + metadata + run config).\n"
+        "  batch            Batch extract a directory to JSONL (requires --out).\n\n"
+        "  context          Build deterministic preflight context artifacts.\n"
+        "  review           Build deterministic execution review artifacts from counts.\n\n"
+        "Run `qcoder <subcommand> --help` for subcommand options.",
+        end="",
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if argv in (["--version"], ["-V"]):
+        from qcoder import __version__
+
+        print(__version__)
+        return 0
+
+    if not argv or argv in (["-h"], ["--help"]):
+        _print_root_help()
+        return 0
+
+    cmd, *rest = argv
+    if cmd == "analyze":
+        return _cmd_analyze(rest)
+    if cmd == "batch":
+        return _cmd_batch(rest)
+    if cmd == "context":
+        return _cmd_context(rest)
+    if cmd == "review":
+        return _cmd_review(rest)
+
+    print(
+        f"qcoder: unknown subcommand {cmd!r} (expected analyze, batch, context, or review)",
+        file=sys.stderr,
+    )
+    print("Run `qcoder --help` for usage.", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qcoder-0.2.0a1/src/qcoder/engines/context/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .bundle import build_context_bundle
+from .markdown import render_context_markdown
+
+__all__ = ["build_context_bundle", "render_context_markdown"]
+

qcoder-0.2.0a1/src/qcoder/engines/context/bundle.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from qcoder.engines.feature_extraction.features.glossary_v0 import (
+    STRUCTURAL_SUMMARY_FEATURES,
+    full_feature_definitions,
+    selected_feature_definitions,
+)
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def qasm_sha256(path: str) -> str:
+    data = Path(path).read_bytes()
+    return hashlib.sha256(data).hexdigest()
+
+
+def analysis_fingerprint(analysis: dict[str, Any]) -> str:
+    canonical = {
+        "features": analysis.get("features", {}),
+        "feature_map": analysis.get("feature_map", {}),
+    }
+    raw = json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()
+
+
+def build_context_bundle(
+    *,
+    qasm_path: str,
+    analysis: dict[str, Any],
+    qcoder_version: str,
+    generated_utc: str | None = None,
+    include_full_features: bool = False,
+) -> dict[str, Any]:
+    circuit = {
+        "qasm_path": analysis.get("qasm_path", qasm_path),
+        "circuit_id": analysis.get("circuit_id"),
+        "circuit_name": analysis.get("circuit_name"),
+        "source_format": analysis.get("source_format"),
+        "n_qubits": analysis.get("n_qubits"),
+        "n_cbits": analysis.get("n_cbits"),
+        "n_ops": analysis.get("n_ops"),
+    }
+    defs = full_feature_definitions() if include_full_features else selected_feature_definitions(STRUCTURAL_SUMMARY_FEATURES)
+    defs_scope = "full" if include_full_features else "selected"
+    analysis_block: dict[str, Any] = {
+        "features": analysis.get("features", {}),
+        "feature_map": analysis.get("feature_map", {}),
+        "feature_definitions": defs,
+        "feature_definitions_scope": defs_scope,
+    }
+    if "guidance" in analysis:
+        analysis_block["guidance"] = analysis["guidance"]
+
+    return {
+        "context_bundle_schema_version": "0.1",
+        "artifact_type": "qcoder.preflight_context",
+        "basis": "deterministic_analysis_plus_optional_guidance",
+        "generated_utc": generated_utc or utc_now_iso(),
+        "qcoder_version": qcoder_version,
+        "circuit": circuit,
+        "hashes": {
+            "qasm_sha256": qasm_sha256(qasm_path),
+            "analysis_fingerprint": analysis_fingerprint(analysis),
+        },
+        "analysis": analysis_block,
+        "assumptions": [
+            "No backend execution was performed.",
+            "This artifact is deterministic context, not execution results.",
+        ],
+        "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.",
+            ],
+        },
+    }
+

qcoder-0.2.0a1/src/qcoder/engines/context/markdown.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def _fmt_num(value: Any) -> str:
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value)
+
+
+def render_context_markdown(bundle: dict[str, Any]) -> str:
+    circuit = bundle.get("circuit", {})
+    analysis = bundle.get("analysis", {})
+    feature_map = analysis.get("feature_map", {})
+    feature_defs = analysis.get("feature_definitions", {})
+    defs_scope = analysis.get("feature_definitions_scope", "selected")
+    features_obj = analysis.get("features", {})
+    feature_names = list(features_obj.get("feature_names") or [])
+    feature_values = list(features_obj.get("features") or [])
+    guidance = analysis.get("guidance")
+    lines: list[str] = []
+
+    lines.append("# qCoder Preflight Context")
+    lines.append("")
+    lines.append("## Purpose")
+    lines.append("Deterministic pre-execution context artifact for planning and review.")
+    lines.append("")
+    lines.append("## Circuit")
+    lines.append(f"- Path: `{circuit.get('qasm_path')}`")
+    lines.append(f"- Source format: `{circuit.get('source_format')}`")
+    lines.append(f"- Circuit id: `{circuit.get('circuit_id')}`")
+    lines.append(f"- Circuit name: `{circuit.get('circuit_name')}`")
+    lines.append(f"- n_qubits: `{_fmt_num(circuit.get('n_qubits'))}`")
+    lines.append(f"- n_cbits: `{_fmt_num(circuit.get('n_cbits'))}`")
+    lines.append(f"- n_ops: `{_fmt_num(circuit.get('n_ops'))}`")
+    lines.append("")
+    lines.append("## Structural Summary")
+    summary_keys = [
+        "real_depth",
+        "entangling_depth",
+        "n_2q_gate_ops",
+        "span_max",
+        "cut_max",
+        "ig_edge_density",
+    ]
+    for key in summary_keys:
+        if key in feature_map:
+            meaning = feature_defs.get(key, "")
+            if meaning:
+                lines.append(f"- {key}: `{_fmt_num(feature_map.get(key))}` — {meaning}")
+            else:
+                lines.append(f"- {key}: `{_fmt_num(feature_map.get(key))}`")
+    lines.append("")
+    if guidance is not None:
+        shot = guidance.get("shot_guidance", {})
+        sim = guidance.get("simulation_guidance", {})
+        mps = sim.get("mps_bond_dimension", {})
+        lines.append("## Resource Guidance")
+        lines.append("- Non-guaranteed heuristic starting points; no backend execution performed.")
+        lines.append(
+            f"- Shots: applicability=`{shot.get('applicability')}` starting=`{shot.get('starting_shots', [])}`"
+        )
+        lines.append(
+            f"- Simulation: statevector_scale=`{sim.get('statevector', {}).get('scale')}` "
+            f"mps_pressure=`{mps.get('pressure')}` mps_starting_points=`{mps.get('starting_points', [])}`"
+        )
+        lines.append("")
+    if defs_scope == "full" and feature_names and feature_values:
+        value_map = dict(zip(feature_names, feature_values))
+        lines.append("## Full Feature Reference")
+        for name in feature_names:
+            value = value_map.get(name)
+            meaning = feature_defs.get(name, "")
+            if meaning:
+                lines.append(f"- {name}: `{_fmt_num(value)}` — {meaning}")
+            else:
+                lines.append(f"- {name}: `{_fmt_num(value)}`")
+        lines.append("")
+    lines.append("## Assumptions and Limits")
+    for item in bundle.get("assumptions", []):
+        lines.append(f"- {item}")
+    for item in bundle.get("llm_use", {}).get("limits", []):
+        lines.append(f"- {item}")
+    lines.append("")
+    lines.append("## Suggested Use With an LLM")
+    lines.append(bundle.get("llm_use", {}).get("intended_use", ""))
+    lines.append("")
+    return "\n".join(lines)
+