Add multi-course support and Python notebook courses to QDK Learning by minestarks · Pull Request #3394 · microsoft/qdk

minestarks · 2026-06-26T17:43:45Z

This change generalizes the QDK Learning feature to support multiple courses of different kinds, including author-provided Python Jupyter notebook courses, while keeping the Quantum Katas as the default.

amcasey · 2026-06-30T02:08:31Z

+        "The function just needs to return a value equal to the integer 42.",
+        "The simplest answer is to return the literal `42` itself."
+      ],
+      "solution": "@exercise\ndef forty_two():\n    return qsharp.eval(\"40 + 2\")",


In the katas, we sometimes found that we wanted to provide multiple solutions. If this is a generalization, we might want that here?

amcasey · 2026-06-30T02:11:22Z

+    "from qdk.widgets import Circuit\n",
+    "\n",
+    "# Define a few operations we'll use throughout this unit.\n",
+    "OPERATIONS = \"\"\"\n",


I'm not familiar enough with python to suggest an alternative, but this seems like a painful level of escaping.

I guess I don't actually know how this got here. Maybe you never actually touch this file and the escaping is done for you when it's persisted?

amcasey · 2026-06-30T02:16:56Z

+  "id": "circuit-diagrams",
+  "title": "Generating Circuit Diagrams",
+  "shortDescription": "Build and visualize quantum circuits with the QDK in Python notebooks.",
+  "readme": "README.md",


Why reference the readme but not the project? They seem similar to me, but I may be missing something.

We probably don't need to reference either - they have well-known names.

amcasey · 2026-06-30T02:20:04Z

 > Quantum Katas (_kaˑta_ | kah-tuh — Japanese for "form", a pattern of learning and practicing new skills) are self-paced, AI-assisted tutorials for quantum computing and Q# programming. Each tutorial includes relevant theory and interactive hands-on exercises designed to test knowledge.

-The tools refer to each kata as a "unit." Each unit contains ordered activities (lessons, examples, exercises).
+The tools refer to each unit of a course as a "unit." Each unit contains ordered activities (lessons, examples, exercises).


This change makes it a little tautological.

amcasey · 2026-06-30T02:22:58Z

+**Handling guidance:**
+
+- When the user asks to change courses, call `list-courses` first if you're unsure of the exact `courseId`, match the user's request to a course, then call `switch-course`. After switching, call `show` to surface the new course's current activity and briefly tell the user where they landed.
+- Drop-in courses run author-provided code and only load in a **trusted** workspace. If a drop-in course doesn't appear or won't run, the workspace may be in Restricted Mode — suggest trusting the workspace.


I'm a little nervous about "suggest trusting the workspace". Maybe "explain that the user will need to trust the workspace to continue and should only do so if they trust the course material provider"?

This is moot - our extension is entirely disabled in untrusted workspaces

amcasey · 2026-06-30T02:29:52Z

+
+    // Prefer `uv` when it's available — it's faster and is the modern
+    // default tooling. Fall back to the standard library `venv` module.
+    if (await this.uvAvailable()) {


This may be covered below, but I'm wondering if we want a way for users to force venv, rather than uv, even if the latter is available.

amcasey · 2026-06-30T02:30:54Z

+        "This Python installation can't create virtual environments " +
+          "(the `venv`/`ensurepip` modules are missing). On Debian/Ubuntu " +
+          "install them with `sudo apt install python3-venv` (matching your " +
+          "Python version, e.g. `python3.12-venv`), then try again.",


Don't we know their python version?

amcasey · 2026-06-30T02:34:09Z

+   * are typed here.
+   */
+  private async pythonEnvironmentsApi(): Promise<
+    | {


Nit: why not name this type?

amcasey · 2026-06-30T02:37:52Z

 export const KATAS_COURSE_ID = "katas";

+/** Per-course virtual environment folder (under the course working copy). */
+export const LEARNING_VENV_DIR = ".venv";


Would there be any value in making this name more unique?

Seems like it's in a folder people won't be editing and it might break notebook discovery, so probably not?

Aside: the default discovery system only looks in the root and one level down - it doesn't recursively search for .venv. There may be a workspace setting to override it

amcasey · 2026-06-30T02:42:59Z

+  }
+
+  /** Read and JSON-parse a course manifest, or `undefined` if absent/invalid. */
+  private async readManifest(


Remind me what guardrails we need when reading untrusted (?) files from disk. Or maybe this only works if they're in a trusted folder?

minestarks · 2026-06-30T18:31:21Z

+import * as vscode from "vscode";
+import type { LearningService } from "./service.js";
+
+/**


The way to check whether a cell is an exercise is to refer to the exercies.json metadata

amcasey

The old kata notebooks at github.com/microsoft/quantumkatas may be useful references

amcasey · 2026-06-30T17:43:40Z

+    }
+  ],
+  "environment": {
+    "importChecks": ["qdk", "qdk.widgets"]


Could we discover these from the cells?

Per our offline discussion, that's probably overkill

amcasey · 2026-06-30T17:44:08Z

+  "id": "circuit-diagrams",
+  "title": "Generating Circuit Diagrams",
+  "shortDescription": "Build and visualize quantum circuits with the QDK in Python notebooks.",
+  "readme": "README.md",


We probably don't need to reference either - they have well-known names.

amcasey · 2026-06-30T17:45:02Z

@@ -0,0 +1,10 @@
+[project]


This (using a standard python project format) is part of achieving our goal that you could get the basic course experience in any jupyter environment.

amcasey · 2026-06-30T17:58:24Z

+  "exercises": [
+    {
+      "id": "forty_two",
+      "cellIndex": 7,


This seems brittle. Is the cell ID more stable?

amcasey · 2026-06-30T18:04:10Z

+won't start, or the first cell reports a problem, set up and check your
+environment here first:
+
+👉 [Check my environment](command:qsharp-vscode.learningDoctor)


This needs to be on screen somewhere, in case the notebook doesn't work. This file is basically an excuse to do that - we could find a different place for it.

amcasey · 2026-06-30T18:07:45Z

+**Handling guidance:**
+
+- When the user asks to change courses, call `list-courses` first if you're unsure of the exact `courseId`, match the user's request to a course, then call `switch-course`. After switching, call `show` to surface the new course's current activity and briefly tell the user where they landed.
+- Drop-in courses run author-provided code and only load in a **trusted** workspace. If a drop-in course doesn't appear or won't run, the workspace may be in Restricted Mode — suggest trusting the workspace.


This is moot - our extension is entirely disabled in untrusted workspaces

amcasey · 2026-06-30T18:12:17Z

        }
      ],
      "view/item/context": [
+        {


This hasn't been reviewed by humans.

amcasey · 2026-06-30T18:23:12Z

 export const KATAS_COURSE_ID = "katas";

+/** Per-course virtual environment folder (under the course working copy). */
+export const LEARNING_VENV_DIR = ".venv";


Aside: the default discovery system only looks in the root and one level down - it doesn't recursively search for .venv. There may be a workspace setting to override it

amcasey · 2026-06-30T18:26:27Z

@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft Corporation.


Might be mergeable with catalog.ts

python notebooks in QDK Learning

6c2eda4

amcasey reviewed Jun 30, 2026

View reviewed changes

minestarks commented Jun 30, 2026

View reviewed changes

amcasey reviewed Jun 30, 2026

View reviewed changes

Uh oh!

Conversation

minestarks commented Jun 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amcasey left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants