Tutor: turn one chapter into a study session you can verify

What the documentation establishes

Tutor turns supplied books into a concept-based course. Its model writes lessons and grades answers. Source ↗

Chapter previews write review files without changing the database; they still make billable model requests. Source ↗

The walkthrough below is an original worked exercise. We have not independently tested this product’s performance.

1. Choose one thing you want to do without help

For the first session, choose a short chapter about SQL grouping. Write this objective before opening a lesson: given a small table, I can explain how filtering rows before aggregation differs from filtering grouped results. If your chapter covers another subject, keep the structure of the exercise and replace the example.

Limit the session to three concepts: row filtering, grouping, and aggregate filtering. Exclude joins, window functions, indexing, and performance tuning for now. Those topics are valuable, but they make it difficult to tell which misconception caused a wrong answer. Keep a page or section reference next to each concept in your own notes.

Topic: row filters versus group filters
Time box: 30 minutes, plus a five-minute check tomorrow
Starting evidence: one prediction written before any hints
Source boundary: one chapter; write the edition and section references
Success: explain the intermediate rows and solve a changed example
Stop: source text is missing, costs exceed my limit, or feedback contradicts the chapter
Record: my answer, the feedback, the source, and the correction

2. Prepare the project and inspect one chapter

Clone the linked Tutor repository, enter its folder, and run npm install. Copy .env.example to .env and choose a provider, model, and matching key there. No model is selected for you. API requests are billed by the provider, and book text leaves your computer for that service.

In the commands below, replace the book path. Run parse first; then replace 2 with the chapter index from its report, which may differ from the printed chapter number. Inspect the extracted text before accepting model requests.

npm run parse -- /path/to/book.epub
npm run ingest -- SQL /path/to/book.epub --chapters 2 --preview

Preview uses the model but does not update the database. Inspect concept-map.preview.md in the reported book folder. If it matches your chapter, repeat the ingest command without --preview, then run npm start and open localhost:3000.

For this exercise, compare one definition, one code sample, and one table with the original book. If an operator or column disappears during extraction, stop here. A fluent lesson built on a broken source is hard to diagnose later. Make your first run small enough that you can inspect every concept it proposes.

3. Write an answer before accepting a hint

Use the following invented data as a paper exercise. It is deliberately small enough to calculate by hand. Predict which regions appear in each query and their totals. Write your reasoning before reading the answer below; recognizing an answer after seeing it is a weaker check than producing it yourself.

-- Fictional sales: region, amount
-- North, 40
-- North, 70
-- South, 120
-- South, 10

-- A: filter rows, then group
SELECT region, SUM(amount) AS total
FROM sales
WHERE amount >= 50
GROUP BY region;

-- B: group all rows, then filter groups
SELECT region, SUM(amount) AS total
FROM sales
GROUP BY region
HAVING SUM(amount) >= 100;

Answer A contains North = 70 and South = 120. The 40 and 10 rows were removed first. Answer B contains North = 110 and South = 130 because all rows contributed before the group totals were compared with 100. If your answer differs, name the stage where your mental calculation changed. Do not settle for saying that WHERE and HAVING are different.

4. Use the lesson to repair a specific mistake

In Tutor, choose concepts to test or learn and arrange the study queue. Lessons include book references; answers are model-graded. Its grade-dispute action counts an answer as correct, so keep your own evidence of understanding.

Before studying, write one precise uncertainty, such as “I thought every South row was removed because one value was below 50.” During review, locate the relevant passage in the chapter. Restate it in your own words, then explain how it applies to one specific row. This prevents a correct general definition from hiding an incorrect application.

If feedback seems wrong, preserve your original answer rather than silently replacing it. Compare the disputed claim with the chapter and the hand calculation. Mark it unresolved if neither settles it. For a real course, bring that short record to a teacher or a knowledgeable colleague; a green progress indicator is not a substitute for resolving the disagreement.

5. Change the problem and check again tomorrow

Add East = 60 and East = 60. Change query A to WHERE amount >= 100 and query B to HAVING SUM(amount) >= 120. Predict the results on paper without the lesson. A now returns only South = 120. B returns South = 130 and East = 120. North no longer passes B because its group total is 110.

The new East group makes the distinction visible: neither individual row passes the first filter, while their combined value passes the second. Explain that sentence to somebody who has not read the chapter. If you need to look up the answer, return to the relevant concept and try another pair of values.

Tomorrow, invent a fourth region whose sum passes the group threshold although every row fails the row threshold. Save your example and answer. Add another chapter only when you can explain this case, rather than treating ingestion of more material as progress.

6. Diagnose the first failure before adding complexity

A useful session ends with a small artifact: your initial prediction, the correction, and a successful transfer problem. Keep those three items together. They tell you what changed in your understanding and give the next study session a concrete starting point.

Guide history

Revisions preserve the original instructions. A source recheck alone does not create a new revision.

Revision 2 · Explicit provider configuration/check, documented chapter preview flow, complete SQL fixture and independently executed four-case answer checker.

Revision 1 · First guide: chapter preview, original SQL task, independent answer key, retention check and troubleshooting.