qc-grader 2026.6.18__tar.gz

qc_grader-2026.6.18/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.10"
+      - uses: extractions/setup-just@v3
+      - name: install
+        run: uv sync
+      - run: just lint
+      - run: just test

qc_grader-2026.6.18/.github/workflows/release.yml

@@ -0,0 +1,147 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'qc_grader/__init__.py'
+  workflow_dispatch:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.get-version.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get version from qc_grader/__init__.py
+        id: get-version
+        run: |
+          VERSION=$(python -c "import re; print(re.search(r'__version__\s*=\s*\"([^\"]+)\"', open('qc_grader/__init__.py').read()).group(1))")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Version to release: $VERSION"
+
+      - name: Validate version format (YEAR.MONTH.DAY, no leading zeros)
+        run: |
+          VERSION="${{ steps.get-version.outputs.version }}"
+          if ! [[ "$VERSION" =~ ^[0-9]{4}\.(1[0-2]|[1-9])\.(3[01]|[12][0-9]|[1-9])(\.[0-9]+)?$ ]]; then
+            echo "Error: Invalid version format: $VERSION"
+            echo "Expected a date-based version YEAR.MONTH.DAY with no leading zeros, e.g. 2026.6.18"
+            exit 1
+          fi
+
+      - name: Check if tag exists
+        run: |
+          VERSION="${{ steps.get-version.outputs.version }}"
+          if git ls-remote --tags origin "v$VERSION" | grep -q .; then
+            echo "Error: Tag v$VERSION already exists"
+            exit 1
+          fi
+
+  test:
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.10"
+      - uses: extractions/setup-just@v3
+      - name: install
+        run: uv sync
+      - run: just lint
+      - run: just test
+
+  build:
+    needs: [validate, test]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/qc_grader/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-release:
+    needs: [validate, publish-to-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create and push tag
+        run: |
+          VERSION="${{ needs.validate.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "v$VERSION" -m "Release version $VERSION"
+          git push origin "v$VERSION"
+
+      - name: Write release notes
+        env:
+          VERSION: ${{ needs.validate.outputs.version }}
+          REPO: ${{ github.repository }}
+        run: |
+          # The previous release tag, if any. HEAD is already tagged v$VERSION,
+          # so look at HEAD^ to find the prior release.
+          PREV=$(git describe --tags --abbrev=0 --match 'v*' "v$VERSION^" 2>/dev/null || true)
+          if [ -n "$PREV" ]; then
+            URL="https://github.com/$REPO/compare/$PREV...v$VERSION"
+          else
+            URL="https://github.com/$REPO/commits/v$VERSION"
+          fi
+          {
+            echo "**What changed:** see the commits included in this release:"
+            echo ""
+            echo "$URL"
+          } > release-notes.md
+          cat release-notes.md
+
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.validate.outputs.version }}
+        run: |
+          gh release create "v$VERSION" \
+            --title "v$VERSION" \
+            --notes-file release-notes.md \
+            dist/*

qc_grader-2026.6.18/.gitignore

@@ -0,0 +1,74 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+*.manifest
+*.spec
+
+pip-log.txt
+pip-delete-this-directory.txt
+
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+.ipynb_checkpoints
+profile_default/
+ipython_config.py
+
+.python-version
+
+__pypackages__/
+
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+.pyre/
+
+.DS_Store
+
+.vscode
+.idea/
+
+setup.cfg
+qc_archives/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.claude/

qc_grader-2026.6.18/AGENTS.md

@@ -0,0 +1,17 @@
+# Agents.md
+
+## About the project
+
+This project is a Python library for students to submit their answers to quantum computing challenges to a grader server. The server will return back whether the answer was correct or not.
+
+Users use this Python library through a REPL or Jupyter notebook, rather than a traditional Python program.
+
+Users are primarily students and are sometimes beginners to either programming or quantum computing. So, where reasonable, we try to make the program user-friendly, such as useful error messages.
+
+## Workflows
+
+* Format: `just fmt`
+* Linter and type checker: `just lint`
+* Test: `just test`
+* Add new labs and exercises: refer to `CONTRIBUTING.md`
+* Releases: refer to `CONTRIBUTING.md`. All user-facing changes should have a new release.

qc_grader-2026.6.18/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

qc_grader-2026.6.18/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+<!-- Copyright Contributors to the Qiskit project. -->
+
+# Code of Conduct
+All members of this project agree to adhere to the Qiskit Code of Conduct listed at [https://github.com/Qiskit/qiskit/blob/master/CODE_OF_CONDUCT.md](https://github.com/Qiskit/qiskit/blob/master/CODE_OF_CONDUCT.md)
+
+----
+
+License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/),
+Copyright Contributors to Qiskit.

qc_grader-2026.6.18/CONTRIBUTING.md

@@ -0,0 +1,279 @@
+# Contributing
+
+## Prerequisites
+
+* [uv](https://docs.astral.sh/uv/getting-started/installation/)
+* [Just](https://just.systems/man/en/)
+
+## Installation
+
+```sh
+uv sync
+```
+
+(uv automatically creates and manages a virtual environment.)
+
+## Format code
+
+```
+just fmt
+```
+
+## Lint
+
+```
+just lint
+```
+
+To run the individual linters:
+
+* Ruff: `uv run ruff check`
+* Ty (type check): `uv run ty check`
+
+## Tests
+
+```
+just test
+```
+
+## Update dependencies
+
+([Original documentation](https://docs.astral.sh/uv/concepts/projects/dependencies/))
+
+Add a dependency:
+
+```
+uv add <dependency>
+```
+
+Add a dev dependency:
+
+```
+uv add <dependency> --dev
+```
+
+## Release a new version
+
+You should release a new version any time you make user-facing changes.
+
+Releasing is automated. To cut a release, update `__version__` in
+[`qc_grader/__init__.py`](qc_grader/__init__.py) to **today's date** and merge to `main`.
+A GitHub Actions workflow then builds the package, publishes it to PyPI, and creates a
+GitHub Release whose notes link to the commits included in that release.
+
+### Version format
+
+Versions are date-based, written as **`YEAR.MONTH.DAY`** with **no leading zeros**:
+
+* The year comes first, then the month, then the day (`YEAR.MONTH.DAY`).
+* Do not pad with zeros: use `6`, not `06`.
+
+For example, a release made on **18 June 2026** is version `2026.6.18`.
+
+| Date           | Version     |
+| -------------- | ----------- |
+| 18 June 2026   | `2026.6.18` |
+| 1 December 2026 | `2026.12.1` |
+| 5 January 2027 | `2027.1.5`  |
+
+If you need to release more than once on the same day, add a counter at the end, starting
+at `.1`: the second release on 18 June 2026 is `2026.6.18.1`, the third is `2026.6.18.2`,
+and so on.
+
+Versions only ever move forward — we always release from the latest `main` and never
+maintain older versions in parallel.
+
+## Run the client
+
+Use this workflow to test the Python client against the Grader server.
+
+### Initial setup
+
+You must create a Quantum API token for an account with at least one instance.
+
+Prod server:
+
+1. Use https://quantum.cloud.ibm.com to create the API key
+2. Save the key by running `uv run python`, then this code:
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService
+
+QiskitRuntimeService.save_account(
+    token="<your-api-key>",
+    instance="<CRN>",
+)
+```
+3. Close the REPL.
+
+Staging or local development server:
+
+1. Use https://quantum.test.cloud.ibm.com to create the API key.
+2. Save the key by running `uv run python`, then this code:
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService
+
+QiskitRuntimeService.save_account(
+    token="<your-api-key>",
+    instance="<CRN>",
+    name="grader-staging",
+)
+```
+3. Close the REPL.
+
+### How to run
+
+1. Launch a Python REPL:
+  - Prod server: `uv run python`
+  - Staging server: `STAGING=1 uv run python`
+  - Local development server: `DEV=1 uv run python`
+2. In the REPL, import and run your exercises. For example:
+
+```python
+>>> from qc_grader.challenges.qgss_2026 import grade_lab0_ex1
+>>> grade_lab0_ex1()
+```
+
+For developers testing how the server behaves, you can use the files from `qc_grader.challenges.test_challenges`, such as `grade_success` from `qc_grader.challenges.test_challenges.individual`.
+
+## Adding a new challenge
+
+Create a new folder under `qc_grader/challenges` with the name of the challenge. This folder should contain:
+
+* A file for each lab (such as `lab0.py`, `lab2.py`)
+* An `__init__.py`, which imports and re-exports the grading functions from your labs.
+
+  Every challenge must also export a `check_progress` function so users can see how far they've gotten:
+
+  ```python
+  from qc_grader.grader.grade import create_check_progress_function
+
+  # Replace the string with the name of your challenge
+  check_progress = create_check_progress_function("...")
+  ```
+
+  Users call `check_progress()` (no arguments) to print a per-lab and per-exercise breakdown of their submissions plus a challenge-wide aggregate.
+
+  If your challenge is a team challenge, you should also export a `join_team` function so users can register with a team when they start.
+
+  ```python
+  from qc_grader.grader.grade import create_join_team_function
+
+  # Replace the string with the name of your challenge
+  join_team = create_join_team_function("...")
+  ```
+
+  Users must call `join_team()` with their team name to participate in a team challenge. They can switch teams any time.
+
+You may find it easier to copy an existing challenge and modify it.
+
+## Adding new labs
+
+A *lab* is a single Python file corresponding to a Jupyter notebook that users receive. Each *challenge* has one or more labs. When you add new exercises to the server, add a matching Python file here so that users can call grading functions from their Jupyter notebooks.
+
+Create `qc_grader/challenges/{challenge}/{lab}.py`, e.g. `qc_grader/challenges/qgss_2027/lab1.py`.
+
+The `_CHALLENGE` and `_LAB` constants, and each exercise string (e.g., `"ex1"`), must exactly match the identifiers configured on the server. These are permanent: once a challenge is live, changing them breaks existing notebook submissions.
+
+A minimal lab file:
+
+```python
+# qc_grader/challenges/qgss_2027/lab1.py
+from typing import Any
+
+from typeguard import typechecked
+
+from qc_grader.grader.grade import grade_answer
+
+_CHALLENGE = "qgss_2027"
+_LAB = "lab1"
+
+
+def _grade(answer: Any, exercise: str) -> None:
+    grade_answer(answer, lab=_LAB, exercise=exercise, challenge=_CHALLENGE)
+
+
+@typechecked
+def grade_lab1_ex1(answer: str) -> None:
+    _grade(answer, "ex1")
+
+
+@typechecked
+def grade_lab1_ex2(answer: int) -> None:
+    _grade(answer, "ex2")
+```
+
+Then, export every grading function from the challenge package's `__init__.py`:
+
+```python
+# qc_grader/challenges/qgss_2027/__init__.py
+from .lab1 import grade_lab1_ex1, grade_lab1_ex2
+
+__all__ = ["grade_lab1_ex1", "grade_lab1_ex2"]
+```
+
+Users can then import your functions like this:
+
+```python
+from qc_grader.challenges.qgss_2027 import grade_lab1_ex1
+```
+
+### Type validation
+
+All grading functions must use the `@typechecked` decorator from `typeguard` and precise type hints on the answer parameter. This lets the client reject submissions with the wrong data type before they reach the server.
+
+Use the most specific type that describes what the user should submit — `QuantumCircuit`, `Statevector`, `int`, `float`, etc. Avoid `Any` or bare `dict` and bare `list`.
+
+```python
+from typeguard import typechecked
+
+@typechecked
+def grade_lab1_ex1(arg1: str, arg2: list[int], arg3: QuantumCircuit) -> None:
+    ...
+```
+
+#### Dictionaries with required keys
+
+If the user submits a dictionary with specific keys, use `typing.TypedDict` rather than a generic `dict`. `TypedDict` allows `typechecked` to validate each key's name and type:
+
+```python
+from typing import TypedDict
+
+from typeguard import typechecked
+
+Ex1Input = TypedDict("Ex1Input", {"0": int, "1": int})
+
+@typechecked
+def grade_lab0_ex1(counts: Ex1Input) -> None:
+    ...
+```
+
+#### Multiple accepted types
+
+Use a union (`|`) to accept more than one type:
+
+```python
+@typechecked
+def grade_lab0_ex1(answer: int | float) -> None:
+    ...
+```
+
+#### Flexible types with transformation
+
+It is often helpful to accept a more flexible data type and transform it before sending to the server. When doing so, anticipate likely user mistakes and raise a `ValueError` if they violate your assumptions. For example, this accepts either a `float` or an `ndarray` (useful when users are working with NumPy) and validates that the array is a scalar:
+
+```python
+from typeguard import typechecked
+
+@typechecked
+def grade_lab0_ex1(exp_val: np.ndarray | float) -> None:
+    arr = np.asarray(exp_val)
+    if arr.ndim != 0 and arr.size != 1:
+        raise ValueError(
+            f"exp_val must be a scalar, got shape {arr.shape}. "
+            f"Use result[0].data.evs (not result.data.evs) for a single expectation value."
+        )
+    exp_val = float(arr.flat[0])
+    _grade(exp_val, "ex1")
+```

qc_grader-2026.6.18/Justfile

@@ -0,0 +1,10 @@
+fmt:
+    uv run ruff format
+
+lint:
+    uv run ruff format --check
+    uv run ruff check
+    uv run ty check --error-on-warning
+
+test:
+    uv run pytest