2026 – present
Homeschool Tools
A parent photographs a handwritten math problem, a vision model returns a validated template, and a preview-or-retake step feeds practice tests on the web and in the Maxon Practice iOS app.
Private repo, walkthrough on request
- Grade 2 spec
- 15 questions, 30 points
- Photo size cap
- 1600 px JPEG
AI details
What the system actually does
Models
- Vision model through an AI Gateway.
Techniques
- Downscale the photo to at most 1600 px JPEG before the vision call.
- Ask for a reusable JSON template, not a copy of the numbers in the photo.
- Validate the JSON on the server and in the iOS client before anything is saved.
- Show a preview with fresh sample numbers, then Save or Retake.
Data
- One handwritten first- or second-grade math question, or a worksheet of one problem type.
- Maxon Test A photos plus Practice Tests 1 to 6, used as the source for a written Grade 2 spec.
Evaluation
- A bad reply is rejected with an error a parent can read, and it isn't stored.
- Unit tests cover photo-import layouts and the boxed 3-digit add and subtract types.
- Playwright scripts check the web app, including production checks against the live site.
- Maxon Practice has had an iPad QA pass.
Challenges
- The template has to keep the same difficulty with new numbers, using placeholders and ranges.
- A failed or unconfirmed parse must never become a live question type.
- Vertical column work and written boxed 3-digit problems are different layouts.
- Maxon Practice is an iOS app.
Innovations
- The same photo-to-template flow runs on homeschooltools.co and in the Maxon Practice iOS app.
- A parent preview is the gate between the model and a saved question type.
- New Test regenerates all 15 spec questions with fresh numbers, and weak types can build a trouble-spots test.
Stack and tags
- Vercel
- AI Gateway
- JSON schema
- Playwright
- iOS
- vision
- human-in-the-loop
- education
- structured-output
Problem
When a parent has a math problem in front of them, they need more practice of that same kind, not a photocopy with the same numbers. Homeschool Tools is my web test generator (package name home-school-test-generator, page title "Home School Test Generator") on Vercel at homeschooltools.co. The Maxon Practice iOS app uses the same photo-to-template flow.
Why I built it
With it, a parent (or a demo) can photograph one handwritten first- or second-grade math question and get back a reusable question type. The same path turns photos of Maxon's example tests into a written Grade 2 spec and a set of practice tests.
How it works
The photo gets downscaled to at most 1600 px JPEG and sent to a vision model through an AI Gateway. The model is told to return a reusable JSON template: a type name, a layout, placeholders for the operands, an answer formula, and ranges that keep the difficulty the same. A worksheet of several problems of the same kind should come back as one template.
Supported layouts include a single answer box, two-part word problems, fill-in equations, multiple choice, vertical column addition or subtraction (ones, then tens, then hundreds), missing-digit column problems, and sentence frames. A bar-graph visual is allowed only when the photo has a graph the child has to read.
The web route POST /api/template and the iOS VisionClient both validate the JSON before anything is saved. A bad reply is rejected with an error a parent can read, and the parent can retake the photo. The preview shows sample questions with fresh numbers. Save stores the type, and Retake starts over. Nothing from a failed or unconfirmed parse is stored as a live question type.
Saved types then show up in generated practice tests on the website and in Maxon Practice. The iOS app can also share or save a PDF of a test.
Written boxed addition and subtraction are their own built-in types, Q22 and Q23. Each uses two 3-digit numbers from 100 to 999 (addition sums stay at 999 or less), a 4-column by 3-row written work grid, and an answer typed right-aligned on the bottom row. That layout is separate from the photo vertical column layout.
Maxon Practice Tests start from the Test A photos and the Practice Tests 1 to 6 generators. Those are the source for a Grade 2, Chapter 2 Addition and Subtraction Part 1 spec: 15 questions, 30 points, Section A multiple choice (questions 1 to 5), Section B written (questions 6 to 15), number rules, distractors, and bar and number-bond visuals. New Test regenerates all 15 with fresh numbers. Each question can be checked, and Print makes a PDF of the full test plus an optional answer key. The app tracks progress locally and can build a "practice my trouble spots" test from weak types. A person reviewed the printed PDFs and the spec before the generators and the app used them.
Outcome
The result is a reusable question type, or a full 15-question Maxon practice test, on the web and in the iOS app, with fresh numbers every time a test is generated.
Templates are schema-validated before they're saved. Unit tests cover the photo-import layouts (including vertical addition and subtraction, missing digits, and sentence layouts) plus the boxed 3-digit types. Playwright scripts cover the web app, including production checks and local previews of vertical and boxed problems. Maxon Practice has had an iPad QA pass.