Reviewing drafts¶
/tools — the workbench. A document goes in, a model proposes questions, you
read them, and the ones worth keeping move into the bank. A spreadsheet or a
QTI file arrives in the same place.
Nothing is in the bank until you put it there. Moderator-only, throughout.
The whole path, in order¶
- Upload a PDF (
/upload) — or import a spreadsheet or QTI file from the workbench itself. See Importing a document. - Open the document and define a section: a name and a page range.
- Choose an extraction mode and a model, and run it.
- Watch the job. When it finishes you are taken straight to
/tools?batch={id}with the batch open. - File the batch into a topic.
- Read the drafts, fix what needs fixing, and move the good ones across.
Defining a section¶
POST /documents/{id}/sections. Name, start page, end page.
- The document must be
ready— a PDF still being read has no page text yet. - Page numbers start at 1, and the end page cannot be past the document's length.
- The range is inclusive, and a one-page section is allowed: start and end the same reads exactly that page.
A section can be deleted; questions already extracted from it stay in the bank. So can the whole document — same rule, and the dialog says so.
Running the extraction¶
The only two choices that belong to extraction are how to read the pages and which model reads them. There is no title, no mode and no time limit, because extraction does not make a quiz any more — it makes a batch of drafts.
The progress panel streams the worker's steps. Closing it does not stop the job: the drafts land in the workbench either way. If the job finishes without recording a batch, the panel says so and points at Jobs and logs.
The batch¶
Everything that came out of one run, kept as a record of what was decided rather than a list that empties as you work through it.
File it first¶
A batch has one Files into topic, chosen once, and nothing can cross over until it is set. Every question accepted from the batch is filed there.
The reason is blunt: a question with no category reaches nothing — no discipline, no organ system, no relevance, and no row on any tab of the analysis. It would sit in the bank invisible to every page that counts it.
A draft may carry its own category, which wins over the batch's.
What "not ready" means¶
Each pending draft is checked before it is offered, and the reason is printed on the row rather than waiting for a failed attempt:
| Said | When |
|---|---|
| no question text | The stem is empty |
| fewer than two options | An MCQ with one option or none |
| no correct answer marked | An MCQ with options but no key |
| the correct answer is not one of the options | Exactly that |
| no correct answer | A non-MCQ with nothing in the answer field |
A draft is allowed to be incomplete — that is what a draft is for — so these are checked at acceptance, not at extraction. The checkbox on an unready row is disabled; fix it in place and it becomes selectable.
Fixing one in place¶
Edit opens the stem, the options (one a line), the correct answer and the
explanation. PATCH /drafts/{id}. An already-accepted draft cannot be edited —
it is a question now, and the question editor is where it is changed.
The four decisions¶
| Action | Endpoint | Does |
|---|---|---|
| Move into the bank | POST /drafts/accept |
Copies the draft into a new Question. |
| Drop | POST /drafts/reject |
Marks it rejected. It stays on the list. |
| Restore | POST /drafts/{id}/reopen |
A dropped draft becomes pending again. |
| Delete | DELETE /drafts/{id} |
Removes a rejected draft for good. Refused on anything else. |
Accepting is all or nothing. Everything selected is checked before anything
is created — a batch half-accepted because the twentieth draft was missing an
answer is worse than a refusal naming it. A draft already in the bank comes
back as 409 ("already in the bank"), which is a different answer from "not
ready".
Acceptance is the only moment a question id is taken
Ids come from a sequence and are never reissued. If a machine's first attempt took one the moment it was produced, every rejected draft would burn an id and every draft being fixed would be sitting in the bank while it was being fixed. So a draft has no question id until this step, and an accepted draft records what it became — "Now question #1423".
A batch closes itself¶
When no pending drafts are left, the batch's status becomes closed and it
drops out of the default list. Show finished brings the closed ones back.
The banner at the top of the workbench counts every pending draft across every batch and opens the first one waiting.
Lab values are here too¶
The same page carries the Lab reference values table, for educators. It is here rather than inside a session for a reason — see Lab reference values.