qcoder 0.5.0a3__tar.gz → 0.5.0a4__tar.gz

{qcoder-0.5.0a3 → qcoder-0.5.0a4}/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
 
+## 0.5.0a4
+
+- Add public Student aliases: `qcoder student status` and `qcoder student demo`.
+- Add `qcoder student evidence` for the existing deterministic hosted guided-evidence endpoint.
+- Polish Student CLI output so `status` is access-framed, `demo` is the built-in teaching demo, and `evidence` renders learner-friendly summaries by default.
+- Hide hosted meta fields in default Student output; add `--json` on Student subcommands for intentional raw payload output.
+- Add `QCODER_STUDENT_BASE_URL` / `QCODER_STUDENT_TOKEN` aliases while preserving Preview/Pro env compatibility.
+- Student aliases reuse the hosted Preview client configuration: `QCODER_PREVIEW_BASE_URL` / `QCODER_PREVIEW_TOKEN`, with `QCODER_PRO_API_URL` / `QCODER_PRO_TOKEN` compatibility fallbacks.
+- No service deployment change is included in this public package slice.
+- Existing `qcoder pro preview status` and `qcoder pro preview demo` commands remain compatible.
+
 ## 0.5.0a3
 
 - Add public hosted Preview client commands: `qcoder pro preview status` and `qcoder pro preview demo`.

{qcoder-0.5.0a3 → qcoder-0.5.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.5.0a3
+Version: 0.5.0a4
 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>
@@ -41,12 +41,13 @@ Free `qcoder` commands run offline and do not call hosted services, upload telem
 - `qcoder context`
 - `qcoder review`
 - `qcoder pro` (Pro bootstrap and client contract; non-confidential local plumbing only)
+- `qcoder student` (Student status/demo/evidence aliases for hosted Preview connectivity checks)
 
 ## Pro Preview boundaries
 
 Public `qcoder` ships **Free local commands** plus a **Pro bootstrap/client contract**. It is **not** the sellable hosted Pro product.
 
-For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a2`**. It is not Pro V0.0 and not a sellable launched Pro product.
+For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a4`**. It is not Pro V0.0 and not a sellable launched Pro product.
 
 - **Free commands** (`analyze`, `batch`, `context`, `review`) are Apache-2.0, local-first/offline, and useful without Pro. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
 - **`qcoder pro` bootstrap** (`signup`, `login`, `install`, `status`, `validate`) stores local token/config only. It does not upload circuits, run confidential analysis, or generate Pro cards locally.
@@ -85,6 +86,9 @@ qcoder pro install --token <token-if-provided>
 qcoder pro status
 qcoder pro validate
 qcoder pro workflow --qasm path/to/circuit.qasm --dry-run-manifest pro.workflow.manifest.json
+qcoder student status
+qcoder student demo
+qcoder student evidence
 ```
 
 Use **`--dry-run-manifest`** unless QRS has given you a non-default service URL and token for contract rehearsal. Manifest-only submit (no artifact upload) is opt-in:

{qcoder-0.5.0a3 → qcoder-0.5.0a4}/README.md

@@ -11,12 +11,13 @@ Free `qcoder` commands run offline and do not call hosted services, upload telem
 - `qcoder context`
 - `qcoder review`
 - `qcoder pro` (Pro bootstrap and client contract; non-confidential local plumbing only)
+- `qcoder student` (Student status/demo/evidence aliases for hosted Preview connectivity checks)
 
 ## Pro Preview boundaries
 
 Public `qcoder` ships **Free local commands** plus a **Pro bootstrap/client contract**. It is **not** the sellable hosted Pro product.
 
-For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a2`**. It is not Pro V0.0 and not a sellable launched Pro product.
+For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a4`**. It is not Pro V0.0 and not a sellable launched Pro product.
 
 - **Free commands** (`analyze`, `batch`, `context`, `review`) are Apache-2.0, local-first/offline, and useful without Pro. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
 - **`qcoder pro` bootstrap** (`signup`, `login`, `install`, `status`, `validate`) stores local token/config only. It does not upload circuits, run confidential analysis, or generate Pro cards locally.
@@ -55,6 +56,9 @@ qcoder pro install --token <token-if-provided>
 qcoder pro status
 qcoder pro validate
 qcoder pro workflow --qasm path/to/circuit.qasm --dry-run-manifest pro.workflow.manifest.json
+qcoder student status
+qcoder student demo
+qcoder student evidence
 ```
 
 Use **`--dry-run-manifest`** unless QRS has given you a non-default service URL and token for contract rehearsal. Manifest-only submit (no artifact upload) is opt-in:

{qcoder-0.5.0a3 → qcoder-0.5.0a4}/pyproject.toml

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

{qcoder-0.5.0a3 → qcoder-0.5.0a4}/src/qcoder/__init__.py

@@ -1,3 +1,3 @@
 __all__ = []
-__version__ = "0.5.0a3"
+__version__ = "0.5.0a4"
 file = __file__

{qcoder-0.5.0a3 → qcoder-0.5.0a4}/src/qcoder/cli.py

@@ -20,6 +20,7 @@ from qcoder.pro_preview.client import ProServiceClient, ProServiceClientError
 from qcoder.pro_preview.client import (
     PreviewClientNetworkError,
     call_builtin_review_demo,
+    call_student_guided_evidence,
     resolve_preview_client_config,
     summarize_demo_payload,
 )
@@ -254,48 +255,359 @@ def _cmd_review(argv: list[str]) -> int:
     return 0
 
 
-def _run_pro_preview_demo_check(*, base_url_override: str | None) -> int:
+def _run_pro_preview_demo_check(
+    *,
+    base_url_override: str | None,
+    label: str = "qCoder Pro Preview demo",
+    error_prefix: str = "qcoder pro preview",
+) -> int:
     try:
-        config = resolve_preview_client_config(base_url_override=base_url_override)
+        config = resolve_preview_client_config(
+            base_url_override=base_url_override,
+            include_student_aliases=True,
+        )
     except ValueError as exc:
-        print(f"qcoder pro preview: {exc}", file=sys.stderr)
+        print(f"{error_prefix}: {exc}", file=sys.stderr)
         return 2
 
     try:
         response = call_builtin_review_demo(config)
     except PreviewClientNetworkError:
         print(
-            "qCoder Pro Preview demo: FAIL (network). Base URL may be unreachable.",
+            f"{label}: FAIL (network). Base URL may be unreachable.",
             file=sys.stderr,
         )
         print(f"  base_url: {config.base_url}", file=sys.stderr)
         return 2
 
     if response.status_code == 200:
-        print("qCoder Pro Preview demo: PASS (HTTP 200).")
+        print(f"{label}: PASS (HTTP 200).")
         print(f"  base_url: {config.base_url}")
         for line in summarize_demo_payload(response.payload):
             print(f"  {line}")
         return 0
     if response.status_code == 401:
         print(
-            "qCoder Pro Preview demo: FAIL (HTTP 401). Token is missing, invalid, or revoked.",
+            f"{label}: FAIL (HTTP 401). Token is missing, invalid, or revoked.",
             file=sys.stderr,
         )
         return 1
     if response.status_code == 403:
         print(
-            "qCoder Pro Preview demo: FAIL (HTTP 403). Private/outer service access may be blocking access.",
+            f"{label}: FAIL (HTTP 403). Private/outer service access may be blocking access.",
             file=sys.stderr,
         )
         return 1
 
-    print(f"qCoder Pro Preview demo: FAIL (HTTP {response.status_code}).", file=sys.stderr)
+    print(f"{label}: FAIL (HTTP {response.status_code}).", file=sys.stderr)
     for line in summarize_demo_payload(response.payload):
         print(f"  {line}", file=sys.stderr)
     return 2
 
 
+def _format_summary_value(value: str | int | float | bool) -> str:
+    if isinstance(value, bool):
+        return str(value).lower()
+    return str(value)
+
+
+def _print_raw_payload_json(payload: dict[str, object] | None) -> None:
+    print(json.dumps(payload or {}, indent=2, sort_keys=True))
+
+
+def _is_scalar(value: object) -> bool:
+    return isinstance(value, (str, int, float, bool))
+
+
+def _sample_count(payload: dict[str, object] | None) -> int | None:
+    if not payload:
+        return None
+    samples = payload.get("samples")
+    if isinstance(samples, list):
+        return len(samples)
+    sample_count = payload.get("sample_count")
+    if isinstance(sample_count, int):
+        return sample_count
+    return None
+
+
+def _format_beginner_metrics(value: object) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    parts: list[str] = []
+    for key in sorted(value):
+        metric = value[key]
+        if _is_scalar(metric):
+            parts.append(f"{key}={_format_summary_value(metric)}")
+    return ", ".join(parts) if parts else None
+
+
+def _summarize_student_glossary(value: object) -> list[str]:
+    lines: list[str] = []
+    if isinstance(value, dict):
+        for term in sorted(value)[:4]:
+            definition = value[term]
+            if isinstance(definition, str):
+                lines.append(f"  {term}: {definition}")
+            elif isinstance(definition, dict):
+                text = definition.get("definition") or definition.get("summary")
+                if isinstance(text, str):
+                    lines.append(f"  {term}: {text}")
+    elif isinstance(value, list):
+        for item in value[:4]:
+            if isinstance(item, dict):
+                term = item.get("term") or item.get("name")
+                definition = item.get("definition") or item.get("summary")
+                if isinstance(term, str) and isinstance(definition, str):
+                    lines.append(f"  {term}: {definition}")
+            elif isinstance(item, str):
+                lines.append(f"  {item}")
+    return lines
+
+
+def _summarize_student_demo_payload(payload: dict[str, object] | None) -> list[str]:
+    if not payload:
+        return ["summary: built-in teaching demo reached; no summary payload returned"]
+    lines: list[str] = []
+    summary = payload.get("student_summary")
+    if isinstance(summary, str):
+        lines.append(f"summary: {summary}")
+    elif isinstance(summary, dict):
+        for key in ("title", "summary", "next_step"):
+            value = summary.get(key)
+            if _is_scalar(value):
+                lines.append(f"{key}: {_format_summary_value(value)}")
+    mode = payload.get("mode")
+    if _is_scalar(mode):
+        lines.append(f"mode: {_format_summary_value(mode)}")
+    count = _sample_count(payload)
+    if count is not None:
+        lines.append(f"samples: {count}")
+    samples = payload.get("samples")
+    if isinstance(samples, list):
+        for index, sample in enumerate(samples[:2], start=1):
+            if isinstance(sample, dict):
+                plain_summary = sample.get("plain_summary")
+                if isinstance(plain_summary, str):
+                    lines.append(f"sample {index}: {plain_summary}")
+    return lines
+
+
+def _summarize_student_evidence_payload(payload: dict[str, object] | None) -> list[str]:
+    if not payload:
+        return ["summary: Student evidence endpoint reached; no summary payload returned"]
+    lines: list[str] = []
+    summary = payload.get("student_summary")
+    if isinstance(summary, str):
+        lines.append(f"summary: {summary}")
+    elif isinstance(summary, dict):
+        for key in ("title", "summary", "what_this_means", "next_step"):
+            value = summary.get(key)
+            if _is_scalar(value):
+                lines.append(f"{key}: {_format_summary_value(value)}")
+    anatomy_label = payload.get("anatomy_label")
+    if _is_scalar(anatomy_label):
+        lines.append(f"anatomy_label: {_format_summary_value(anatomy_label)}")
+    count = _sample_count(payload)
+    if count is not None:
+        lines.append(f"samples: {count}")
+    samples = payload.get("samples")
+    if isinstance(samples, list):
+        for index, sample in enumerate(samples[:3], start=1):
+            if not isinstance(sample, dict):
+                continue
+            plain_summary = sample.get("plain_summary")
+            if isinstance(plain_summary, str):
+                lines.append(f"sample {index}: {plain_summary}")
+            sample_anatomy = sample.get("anatomy_label")
+            if _is_scalar(sample_anatomy):
+                lines.append(f"sample {index} anatomy: {_format_summary_value(sample_anatomy)}")
+            metrics = _format_beginner_metrics(sample.get("beginner_metrics"))
+            if metrics:
+                lines.append(f"sample {index} beginner_metrics: {metrics}")
+    metrics = _format_beginner_metrics(payload.get("beginner_metrics"))
+    if metrics:
+        lines.append(f"beginner_metrics: {metrics}")
+    glossary = _summarize_student_glossary(payload.get("glossary"))
+    if glossary:
+        lines.append("glossary:")
+        lines.extend(glossary)
+    return lines
+
+
+def _run_student_builtin_review_check(
+    *,
+    base_url_override: str | None,
+    mode: str,
+    json_output: bool,
+) -> int:
+    try:
+        config = resolve_preview_client_config(
+            base_url_override=base_url_override,
+            include_student_aliases=True,
+        )
+    except ValueError as exc:
+        print(f"qcoder student: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        response = call_builtin_review_demo(config)
+    except PreviewClientNetworkError:
+        print(
+            "qCoder Student: FAIL (network). The service may be unreachable; check your base URL.",
+            file=sys.stderr,
+        )
+        print(f"  base_url: {config.base_url}", file=sys.stderr)
+        return 2
+
+    if json_output:
+        _print_raw_payload_json(response.payload)
+        return 0 if response.status_code == 200 else 1 if response.status_code in {401, 403} else 2
+
+    if response.status_code == 200:
+        if mode == "status":
+            print("qCoder Student access: OK")
+            print(f"  http_status: {response.status_code}")
+            print("  service: available")
+            count = _sample_count(response.payload)
+            if count is not None:
+                print(f"  teaching_demo_samples: {count}")
+            print("Next: try qcoder student demo, then qcoder student evidence.")
+        else:
+            print("qCoder Student built-in teaching demo: PASS (HTTP 200).")
+            for line in _summarize_student_demo_payload(response.payload):
+                print(f"  {line}")
+        return 0
+    if response.status_code == 401:
+        print(
+            "qCoder Student: FAIL (HTTP 401). Your token is missing, invalid, revoked, or lacks Student access.",
+            file=sys.stderr,
+        )
+        return 1
+    if response.status_code == 403:
+        print(
+            "qCoder Student: FAIL (HTTP 403). Your token does not have access to this Student command.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"qCoder Student: FAIL (HTTP {response.status_code}).", file=sys.stderr)
+    if mode == "demo":
+        for line in _summarize_student_demo_payload(response.payload):
+            print(f"  {line}", file=sys.stderr)
+    return 2
+
+
+def _run_student_evidence_check(*, base_url_override: str | None, json_output: bool) -> int:
+    try:
+        config = resolve_preview_client_config(
+            base_url_override=base_url_override,
+            include_student_aliases=True,
+        )
+    except ValueError as exc:
+        print(f"qcoder student: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        response = call_student_guided_evidence(config)
+    except PreviewClientNetworkError:
+        print(
+            "qCoder Student evidence: FAIL (network). The service may be unreachable; check your base URL.",
+            file=sys.stderr,
+        )
+        print(f"  base_url: {config.base_url}", file=sys.stderr)
+        return 2
+
+    if json_output:
+        _print_raw_payload_json(response.payload)
+        return 0 if response.status_code == 200 else 1 if response.status_code in {401, 403} else 2
+
+    if response.status_code == 200:
+        print("qCoder Student evidence: PASS (HTTP 200).")
+        for line in _summarize_student_evidence_payload(response.payload):
+            print(f"  {line}")
+        return 0
+    if response.status_code == 401:
+        print(
+            "qCoder Student evidence: FAIL (HTTP 401). Your token is missing, invalid, revoked, or lacks Student evidence access.",
+            file=sys.stderr,
+        )
+        return 1
+    if response.status_code == 403:
+        print(
+            "qCoder Student evidence: FAIL (HTTP 403). Your token does not have access to Student evidence.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"qCoder Student evidence: FAIL (HTTP {response.status_code}).", file=sys.stderr)
+    for line in _summarize_student_evidence_payload(response.payload):
+        print(f"  {line}", file=sys.stderr)
+    return 2
+
+
+def _cmd_student(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(
+        prog="qcoder student",
+        add_help=True,
+        description="Hosted Student status/demo/evidence connectivity checks.",
+    )
+    sub = p.add_subparsers(dest="student_command")
+
+    p_status = sub.add_parser(
+        "status",
+        help="Check qCoder Student access and print the next step.",
+    )
+    p_status.add_argument(
+        "--base-url",
+        default=None,
+        help="Override qCoder Student base URL (default env: QCODER_STUDENT_BASE_URL, QCODER_PREVIEW_BASE_URL, or QCODER_PRO_API_URL).",
+    )
+    p_status.add_argument("--json", action="store_true", help="Emit raw service payload as JSON.")
+    p_status.set_defaults(student_command="status")
+
+    p_demo = sub.add_parser(
+        "demo",
+        help="Run the built-in qCoder Student teaching demo.",
+    )
+    p_demo.add_argument(
+        "--base-url",
+        default=None,
+        help="Override qCoder Student base URL (default env: QCODER_STUDENT_BASE_URL, QCODER_PREVIEW_BASE_URL, or QCODER_PRO_API_URL).",
+    )
+    p_demo.add_argument("--json", action="store_true", help="Emit raw service payload as JSON.")
+    p_demo.set_defaults(student_command="demo")
+
+    p_evidence = sub.add_parser(
+        "evidence",
+        help="Call hosted Student guided-evidence endpoint and print safe summary.",
+    )
+    p_evidence.add_argument(
+        "--base-url",
+        default=None,
+        help="Override qCoder Student base URL (default env: QCODER_STUDENT_BASE_URL, QCODER_PREVIEW_BASE_URL, or QCODER_PRO_API_URL).",
+    )
+    p_evidence.add_argument("--json", action="store_true", help="Emit raw service payload as JSON.")
+    p_evidence.set_defaults(student_command="evidence")
+
+    args = p.parse_args(argv)
+    if args.student_command is None:
+        p.print_help()
+        return 0
+
+    if args.student_command in {"status", "demo"}:
+        return _run_student_builtin_review_check(
+            base_url_override=args.base_url,
+            mode=args.student_command,
+            json_output=args.json,
+        )
+    if args.student_command == "evidence":
+        return _run_student_evidence_check(base_url_override=args.base_url, json_output=args.json)
+
+    p.print_help()
+    return 0
+
+
 def _cmd_pro(argv: list[str]) -> int:
     p = argparse.ArgumentParser(
         prog="qcoder pro",
@@ -674,15 +986,16 @@ def _cmd_pro(argv: list[str]) -> int:
 
 def _print_root_help() -> None:
     print(
-        "usage: qcoder [--version | -V] [-h] {analyze,batch,context,review,pro} ...\n\n"
+        "usage: qcoder [--version | -V] [-h] {analyze,batch,context,review,pro,student} ...\n\n"
         "Quantum circuit analysis CLI.\n\n"
         "positional arguments:\n"
-        "  {analyze,batch,context,review,pro}  subcommand\n\n"
+        "  {analyze,batch,context,review,pro,student}  subcommand\n\n"
         "  analyze          Analyze a QASM file (feature extraction + metadata + run config).\n"
         "  batch            Batch extract a directory to JSONL (requires --out).\n"
         "  context          Build deterministic preflight context artifacts.\n"
         "  review           Build deterministic execution review artifacts from counts.\n"
-        "  pro              Service-backed Pro shell (signup/install/status/validate/workflow).\n\n"
+        "  pro              Service-backed Pro shell (signup/install/status/validate/workflow).\n"
+        "  student          Hosted Student status/demo/evidence connectivity checks.\n\n"
         "Run `qcoder <subcommand> --help` for subcommand options.",
         end="",
     )
@@ -713,9 +1026,11 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_review(rest)
     if cmd == "pro":
         return _cmd_pro(rest)
+    if cmd == "student":
+        return _cmd_student(rest)
 
     print(
-        f"qcoder: unknown subcommand {cmd!r} (expected analyze, batch, context, review, or pro)",
+        f"qcoder: unknown subcommand {cmd!r} (expected analyze, batch, context, review, pro, or student)",
         file=sys.stderr,
     )
     print("Run `qcoder --help` for usage.", file=sys.stderr)

{qcoder-0.5.0a3 → qcoder-0.5.0a4}/src/qcoder/pro_preview/client.py

@@ -124,9 +124,12 @@ def _parse_http_error(exc: HTTPError) -> ServiceErrorDetail:
 
 PREVIEW_BASE_URL_ENV = "QCODER_PREVIEW_BASE_URL"
 PREVIEW_TOKEN_ENV = "QCODER_PREVIEW_TOKEN"
+STUDENT_BASE_URL_ENV = "QCODER_STUDENT_BASE_URL"
+STUDENT_TOKEN_ENV = "QCODER_STUDENT_TOKEN"
 PRO_API_URL_ENV = "QCODER_PRO_API_URL"
 PRO_TOKEN_ENV = "QCODER_PRO_TOKEN"
 BUILTIN_REVIEW_PATH = "/v0/demo/builtin-review"
+STUDENT_GUIDED_EVIDENCE_PATH = "/v0/student/guided-evidence"
 
 
 @dataclass(frozen=True)
@@ -146,17 +149,38 @@ class PreviewClientNetworkError(RuntimeError):
 
 
 def resolve_preview_client_config(
-    *, base_url_override: str | None = None, env_map: Mapping[str, str] | None = None
+    *,
+    base_url_override: str | None = None,
+    env_map: Mapping[str, str] | None = None,
+    include_student_aliases: bool = False,
 ) -> PreviewClientConfig:
     env = os.environ if env_map is None else env_map
+    if include_student_aliases:
+        env_base_url = str(
+            env.get(STUDENT_BASE_URL_ENV)
+            or env.get(PREVIEW_BASE_URL_ENV)
+            or env.get(PRO_API_URL_ENV)
+            or ""
+        )
+        token = str(env.get(STUDENT_TOKEN_ENV) or env.get(PREVIEW_TOKEN_ENV) or env.get(PRO_TOKEN_ENV) or "").strip()
+    else:
+        env_base_url = str(env.get(PREVIEW_BASE_URL_ENV) or env.get(PRO_API_URL_ENV) or "")
+        token = str(env.get(PREVIEW_TOKEN_ENV) or env.get(PRO_TOKEN_ENV) or "").strip()
     base_url = _normalize_base_url(
         base_url_override
         if base_url_override is not None
-        else str(env.get(PREVIEW_BASE_URL_ENV) or env.get(PRO_API_URL_ENV) or "")
+        else env_base_url,
+        include_student_aliases=include_student_aliases,
     )
-    token = str(env.get(PREVIEW_TOKEN_ENV) or env.get(PRO_TOKEN_ENV) or "").strip()
     if not token:
-        raise ValueError("missing hosted Preview token; set QCODER_PREVIEW_TOKEN or QCODER_PRO_TOKEN")
+        if include_student_aliases:
+            raise ValueError(
+                "missing qCoder Student token; set QCODER_STUDENT_TOKEN, "
+                "QCODER_PREVIEW_TOKEN, or QCODER_PRO_TOKEN"
+            )
+        raise ValueError(
+            "missing hosted Preview token; set QCODER_PREVIEW_TOKEN or QCODER_PRO_TOKEN"
+        )
     return PreviewClientConfig(base_url=base_url, token=token)
 
 
@@ -185,6 +209,28 @@ def call_builtin_review_demo(
     except URLError as exc:
         raise PreviewClientNetworkError(str(exc)) from exc
 
+
+def call_student_guided_evidence(
+    config: PreviewClientConfig, *, timeout_s: float = 10.0
+) -> PreviewClientResponse:
+    """Call the hosted Student guided-evidence endpoint."""
+    request = Request(
+        _join_service_url(config.base_url, STUDENT_GUIDED_EVIDENCE_PATH),
+        headers={"Authorization": f"Bearer {config.token}"},
+        method="GET",
+    )
+    try:
+        with urlopen(request, timeout=timeout_s) as response:
+            body = response.read().decode("utf-8", errors="replace")
+            status_code = int(getattr(response, "status", 200))
+            return PreviewClientResponse(status_code=status_code, payload=_safe_json_decode(body))
+    except HTTPError as err:
+        body = err.read().decode("utf-8", errors="replace")
+        return PreviewClientResponse(status_code=int(err.code), payload=_safe_json_decode(body))
+    except URLError as exc:
+        raise PreviewClientNetworkError(str(exc)) from exc
+
+
 def summarize_demo_payload(payload: dict[str, Any] | None) -> list[str]:
     if not payload:
         return []
@@ -199,9 +245,14 @@ def summarize_demo_payload(payload: dict[str, Any] | None) -> list[str]:
     return lines
 
 
-def _normalize_base_url(raw_base_url: str) -> str:
+def _normalize_base_url(raw_base_url: str, *, include_student_aliases: bool = False) -> str:
     base_url = raw_base_url.strip().rstrip("/")
     if not base_url:
+        if include_student_aliases:
+            raise ValueError(
+                "missing qCoder Student base URL; set QCODER_STUDENT_BASE_URL, "
+                "QCODER_PREVIEW_BASE_URL, or QCODER_PRO_API_URL, or pass --base-url"
+            )
         raise ValueError(
             "missing hosted Preview base URL; set QCODER_PREVIEW_BASE_URL or "
             "QCODER_PRO_API_URL, or pass --base-url"

{qcoder-0.5.0a3 → qcoder-0.5.0a4}/src/qcoder.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.5.0a3
+Version: 0.5.0a4
 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>
@@ -41,12 +41,13 @@ Free `qcoder` commands run offline and do not call hosted services, upload telem
 - `qcoder context`
 - `qcoder review`
 - `qcoder pro` (Pro bootstrap and client contract; non-confidential local plumbing only)
+- `qcoder student` (Student status/demo/evidence aliases for hosted Preview connectivity checks)
 
 ## Pro Preview boundaries
 
 Public `qcoder` ships **Free local commands** plus a **Pro bootstrap/client contract**. It is **not** the sellable hosted Pro product.
 
-For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a2`**. It is not Pro V0.0 and not a sellable launched Pro product.
+For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a4`**. It is not Pro V0.0 and not a sellable launched Pro product.
 
 - **Free commands** (`analyze`, `batch`, `context`, `review`) are Apache-2.0, local-first/offline, and useful without Pro. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
 - **`qcoder pro` bootstrap** (`signup`, `login`, `install`, `status`, `validate`) stores local token/config only. It does not upload circuits, run confidential analysis, or generate Pro cards locally.
@@ -85,6 +86,9 @@ qcoder pro install --token <token-if-provided>
 qcoder pro status
 qcoder pro validate
 qcoder pro workflow --qasm path/to/circuit.qasm --dry-run-manifest pro.workflow.manifest.json
+qcoder student status
+qcoder student demo
+qcoder student evidence
 ```
 
 Use **`--dry-run-manifest`** unless QRS has given you a non-default service URL and token for contract rehearsal. Manifest-only submit (no artifact upload) is opt-in: