Code Questions — AI Authoring Reference

Overview

A Code question gives the student a real code editor (CodeMirror 6) and runs their code right in the browser. Six languages are supported — javascript, python (via Pyodide/WebAssembly), p5js, html, htmlcss, and htmlcssjs. You can give the student starter code, run-on-demand test cases, static code checks, and progressive AI hints.

Everything about a Code question is configured in the Code Settings Helper — the panel that appears in the question editor when you set the question type to “Code.” The helper writes all the settings into the question’s Common Control code for you, so you never hand-write escaped JSON.

On top of the helper sits an Author-with-AI toolbar: a row of buttons that let you generate a whole question from a one-line idea, browse a gallery of ready-made templates, or round-trip your question through any AI chat (Claude, ChatGPT, Gemini) using a portable plain-text bundle. The rest of this page covers those tools.

Three ways to author

Pick whichever fits how you like to work — they all end up writing the same control-code settings:

1. Fill in the helper by hand. Choose a language, type starter code into the per-file editors, add test-case and code-check rows, and pick a score method. Your settings are saved automatically when you save the question. Best when you already know exactly what you want.
2. Draft with AI inside the editor. Click Draft / Adapt with AI, describe the question in a sentence, and the built-in assistant fills the whole helper in for you. Best for going from zero to a working draft fast.
3. Round-trip through your own AI chat. Click AI Instructions (and optionally Copy My Code) to copy a prompt into Claude/ChatGPT/Gemini, work on the question there, then paste the reply back with Paste AI Response. Best when you want a longer back-and-forth in a full chat with your own context.

You can mix all three freely — start from a template, refine with the chat round-trip, then tweak a test row by hand. The bundle format below is the common language that ties options 2 and 3 together.

The Author-with-AI toolbar

The toolbar appears at the top of the Code Settings Helper. Each button is described below.

Draft / Adapt with AI BETA

Opens a dialog where you type a plain-English description of the question you want. The built-in assistant (Google Gemini) returns a complete question — language, question text, starter code, tests, checks, score method, and hints — and applies it straight into the helper. If the helper already has content, the assistant adapts what’s there instead of starting over (e.g. “change this to Python” or “add two hidden edge-case tests”).

Draft mode

Triggered when the helper is empty. Example prompt: “A JavaScript function isPrime(n) that returns true for primes, with visible and hidden tests and two progressive hints.”

Adapt mode

Triggered when the helper already has content. Example prompt: “Convert this to Python and add a code check that forbids importing math.”

Browse Templates…

Opens a gallery of ready-made Code questions you can drop in and edit. There are 17 templates across five categories:

Pick a category on the left, click a card to preview its full bundle, then click Use this template. The template loads into the helper exactly as if you’d pasted it — so it’s fully editable afterward. Loading a template replaces the current helper contents, so do it before you start customizing.

AI Instructions · Copy My Code · Paste AI Response

These three buttons let you author with any AI chat in a separate browser tab:

AI Instructions

Copies a ready-to-paste system prompt to your clipboard. Paste it as the first message to Claude, ChatGPT, or Gemini — it teaches the AI the Code-question bundle format and the rules it must follow. Do this once at the start of a chat.

Copy My Code

Copies your current question as a bundle so the AI can see and modify what you already have. Use this when you want to revise an existing question rather than start fresh.

Paste AI Response

Opens a paste box. Drop the AI’s reply in and click Apply — the changed sections are parsed and written back into the helper fields. You can paste the whole chat message; the parser finds the bundle inside it.

What’s New

Shows recent changes to the Code authoring tools. A small badge appears on the button when there’s something you haven’t seen; opening the panel and marking it read clears the badge. This list is specific to Code questions and is separate from the Interactive2 “What’s New.”

The authoring bundle format

A bundle is a portable plain-text representation of a whole Code question. Templates are bundles, the AI exchanges bundles, and Copy My Code / Paste AI Response read and write bundles. It is plain text with no fancy escaping, so it survives copy/paste through any chat. You rarely write one by hand — but understanding it helps you read AI replies and fix them when something doesn’t apply.

Sections

A bundle is a series of ===== HEADER ===== sections. Only the sections that apply to the question’s language are emitted. The recognized headers:

Test-case lines

Under ===== TEST CASES =====, write one test per line in this friendly form:

functionCall(args) => expectedValue | hidden | wt 2

• Before => — the call to run, e.g. add(2, 3) or is_palindrome('racecar').
• After => — the expected return value, compared as a string. For Python, write True/False exactly.
• | hidden (optional) — the test runs but isn’t shown to the student.
• | wt N (optional) — the test’s weight when scoring (default 1).

Flags are read from the right, so an expected value may itself contain => characters. A raw JSON array is also accepted if you prefer.

Code-check lines

Under ===== CODE CHECKS =====, write one static check per line:

type: value | "label" | wt 0.5

• type — one of contains_function, contains_class, contains_call, contains_keyword, not_contains, regex, min_lines. (Full descriptions in Writing Questions › Code.)
• value — the function/class/keyword name, regex pattern, or line count.
• "label" (optional) — student-facing text. Quote it so a regex pattern containing | isn’t mistaken for a flag.
• | wt N (optional) — the check’s scoring weight (default 1).

Score method & AI hints

These two sections use @subkey: lines (which may also be written inline on the value line):

===== SCORE METHOD =====
auto
@includeTests: true
@includeChecks: true
@showChecks: true

===== AI HINTS =====
@enabled: true
@max: 3
@prompt: Nudge the student toward recursion. Do not reveal the base case
until the final hint.

• SCORE METHOD first token is the mode: manual, auto, or takeanything. @includeTests / @includeChecks turn each scoring source on; @showChecks shows the check-results panel to the student.
• AI HINTS — @enabled toggles the Hint button, @max caps hints per attempt (1–10), and @prompt is your teaching guidance (runs to the end of the section, so it can be multi-line).

A complete example

===== LANGUAGE =====
javascript

===== QUESTION TEXT =====
<p>Write a function <code>factorial(n)</code> that returns n!.</p>
<p>[AB]</p>

===== STARTER CODE =====
function factorial(n) {
  // your code here
}

===== TEST CASES =====
factorial(0) => 1
factorial(5) => 120
factorial(10) => 3628800 | hidden

===== CODE CHECKS =====
contains_function: factorial | "Defines a factorial function"
not_contains: Math. | "Implements it without the Math library" | wt 0.5

===== SCORE METHOD =====
auto @includeTests:true @includeChecks:true @showChecks:true

===== AI HINTS =====
@enabled: true
@max: 3
@prompt: Guide toward either recursion or a loop; never paste the full body.

===== SOLUTION =====
<p>function factorial(n) { return n <= 1 ? 1 : n * factorial(n - 1); }</p>

Paste that into Paste AI Response and the whole question fills in.

Scoring strategy

A quick recap of how grading works, with the practical implications for how you should design a question. The full variable reference is in Writing Questions › Code.

Score methods

manual

The default. Any non-blank submission is flagged for you to grade. Use for open-ended or creative work (most p5.js and HTML/CSS questions).

auto

Scores as a weighted ratio of passed code checks and/or test cases. Turn on @includeChecks and/or @includeTests. Best for function-writing questions with clear correct answers.

takeanything

Full credit for any non-blank submission that differs from the starter code.

Tests vs. checks — when to use which

The two auto-scoring sources behave very differently. Choosing correctly matters:

A common, robust pattern: use tests for fast student feedback (@includeTests off or on for low stakes), and a couple of contains_function / not_contains checks as the scored signal.

AI hints

With @enabled: true (or the AI Hints toggle in the helper) a Hint button appears in the student’s editor. Hints are progressive — vague at first, more specific later — and capped by @max (1–10, default 3). The assistant is instructed never to hand over a full solution and never to execute or trace the student’s code for them.

Shape the teaching with @prompt (the per-question prompt):

===== AI HINTS =====
@enabled: true
@max: 4
@prompt: Steer toward using a dictionary to count occurrences. Do not mention
the .get() default-value trick until the third hint.

Student images

Sometimes the skill being practiced is putting an image URL into markup (e.g. <img src="…">). Attach images to the question and the student gets an Images button in the editor toolbar that opens a panel listing each one — thumbnail, name, and a copy-able URL. The URLs are surfaced to the student on purpose; they are not inserted into the question source (that is the difference from how Interactive2 uses media).

Manage them in the Student Images panel of the Code Settings Helper:

• Upload image — uploads to your shared media library and attaches it to this question.
• Choose from library — opens the same media picker used by Interactive2, so images are reusable across questions and question types.

These settings persist in the $codeimages control variable (a JSON array of {url, name, media_id}); see Writing Questions › Code › Student Images for the variable reference.

Tips & gotchas

• Always include [AB] in the question text. It marks where the editor goes. If you forget it, the bundle parser adds it for you at the end — but place it yourself for control over layout.
• p5.js can’t load image files. The sandbox has no filesystem, so loadImage() and external assets won’t work. Use shape-drawing functions (rect, ellipse, triangle, arc…) instead.
• The first Python run is slow. Python loads Pyodide (WebAssembly) on first run — expect a few seconds. Subsequent runs are fast. Tell students this in the question text if it matters.
• Match expected test values exactly as strings. Python booleans are True/False; numbers that are floats print as 32.0, not 32. If a test fails unexpectedly, check the exact printed form first.
• Loading a template or pasting a bundle replaces the helper contents. Do it before customizing, not after.
• Preview as a student before saving. Run the tests, click the hints, and submit once to confirm the score lands where you expect — especially for auto questions.
• Don’t use the macro/randomization library help with Code questions. Code questions don’t run through the math-question interpreter, so the algorithm-library functions don’t apply here.

See also

• Writing Questions › Code — the full variable reference (languages, starter code, tests, checks, scoring flags, AI hints, accessibility) with per-language examples.
• Code Samples in Question Text — embedding runnable snippets inside any question’s text.
• Interactive2 Stdlib Reference — the sibling custom-widget question type, which shares the same execution sandbox.