Skip to content
TangxuZouPublic
forked from Imaad08/equalize

About

Prompt-a-thon Project

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Equalize

See your lesson through every student's eyes — then fix it for each of them.

Equalize is a tool for teachers. Upload a lesson (paste text, or drop in a worksheet PDF or photo), experience it the way your students with disabilities do, get an AI audit of every barrier, and receive a rebuilt version personalized to each student's accommodation plan.

Built for the hackathon prompt: "How can AI be used to help students with disabilities inside the classroom?"

The problem

A teacher with 30 students may have five or more accommodation plans (IEPs / 504 plans) to follow. Each plan is a list of requirements — large print, chunked directions, transcripts, no colour-only meaning — and every worksheet, slide, and quiz is supposed to meet all of them.

In practice that almost never happens, for two reasons:

  1. Teachers can't see the barrier. A worksheet that looks fine to the person who wrote it can be unreadable to a student with low vision, or unanswerable for a student who can't hear the audio clip.
  2. Adapting materials by hand takes hours. Rewriting one lesson five different ways, for every lesson, is not realistic.

How it works

One page, five steps:

Step What happens
1. Upload Paste a lesson, upload a worksheet PDF or image, or load the sample (an 8th-grade photosynthesis worksheet with deliberate accessibility problems). Five sample accommodation plans are shown, one per disability profile.
2. Experience it The original lesson is shown through each student's eyes, and the teacher tries to answer a question from their own material while the simulation runs.
3. Audit AI checks the lesson against every line of every plan. It returns an accessibility score out of 100 and a card for each barrier: the quoted part of the lesson, the student affected, the line of their plan it conflicts with, severity, and a one-line fix. Filterable by student.
4. Fix and personalize AI rebuilds the lesson once per student, then re-audits each rebuilt version against that student's plan. Each version is rendered with its formatting actually applied, lists every change with a reason, shows how many plan lines are now met, and confirms it still tests the same learning objective.
5. Before and after Original vs. rebuilt, side by side, with the score jump and a "Download all versions" button (a single print-ready HTML file).

The five profiles

Profile Simulation in step 2 Rebuilt version in step 4
Low vision Blur, reduced contrast, a narrow field of view that follows the pointer 24pt bold, white on black, written image descriptions
ADHD Pop-up distractions, movement at the edges, a countdown timer One step in focus at a time with checkboxes, extended time
Dyslexia Letters swap and jitter, crowded spacing Short sentences, Lexend font, wide spacing, read-aloud button
Deaf / hard of hearing The audio clip plays muffled; captions show the words that get through, with blanks for the rest Full transcript, visual cues instead of sound
Red-green colour blindness A deuteranopia colour filter — the red "required" words and green "bonus" words become identical Text labels and symbols, solid vs. dashed arrows, no red/green pair

These simulations are approximations meant to build empathy. They do not reproduce any individual's experience. The audit and the fixes are based on each student's written plan, not on the simulation. The profiles are fictional sample plans, identified by need rather than by name.

How AI is used

AI does the two jobs that are too slow for a teacher to do by hand:

  • POST /api/audit — turns every line of every accommodation plan into a checklist and asks the model for an explicit verdict on each one: violated or not, the passage of the lesson that shows the problem, a severity, and a concrete fix. Going line by line means no student and no plan line gets skipped.
  • POST /api/rebuild — makes one call per student, in parallel. Each call receives the lesson, that student's plan, the barriers found for them, and a description of how the app will format their version, and returns the rebuilt lesson as typed content blocks (heading, steps, image description, transcript, key, paragraph, question), the list of changes with reasons, and a note confirming the learning objective is unchanged. One further call then puts all the rebuilt versions through the same checklist audit, each against its own student's plan.

Guardrails on the AI's output. The model is told never to invent content it was not given. A transcript is also checked in code: if most of it cannot be found in the original lesson, it is thrown away and replaced with a clearly marked "Teacher: add this before handing out" note, so a made-up transcript can never reach a student. Every rebuilt version is labelled as an AI-generated draft for the teacher to review.

How the score works. The score is computed, not guessed by the model: it starts at 100 and each barrier subtracts 5.5 (high), 4 (medium) or 2 (low). The "before" score comes from the audit of the original; the "after" score comes from the re-audit of the rebuilt versions, using the same formula. 100 means every line of every plan is met — it is a measure of plan compliance, not a claim that the lesson is perfect.

Details:

  • Calls go through server-side route handlers using the OpenAI Chat Completions API with strict JSON-schema structured output. Responses are validated again with Zod before they reach the browser.
  • The API key is read from OPENAI_API_KEY on the server and never sent to the client. The model is read from OPENAI_MODEL (default: gpt-4.1-mini).
  • A full run is 7 requests: 1 audit, 1 rebuild per student, 1 re-audit (plus 1 to read an upload). OpenAI counts rate limits per model, so if the main model is rate limited the call is retried on the models in OPENAI_FALLBACK_MODELS (default: gpt-4o-mini,gpt-4.1-nano). In npm run dev the terminal prints how many requests each model has left.
  • Fallback: if the key is missing, or a call fails, times out, or returns invalid data, the routes return realistic pre-written results for the sample lesson so the demo never breaks. A small "Demo data" badge appears in the header when this happens; hovering it shows the reason (no key, no credits, rate limit, timeout).

The simulations in step 2 run entirely in the browser (CSS filters, an SVG colour matrix, Web Audio) and do not use AI.

Uploading a PDF or image

Real worksheets are not plain text, so Equalize reads the page itself:

  1. The PDF (up to 3 pages) or image is rendered to page images in the browser with pdf.js. Nothing is stored on a server.
  2. Two facts are measured from the file, not estimated by AI: the font size (read from the PDF's text) and the text contrast (computed from the rendered pixels).
  3. POST /api/extract sends the page images to a vision model, which transcribes the worksheet and adds bracketed notes for what plain text would lose: formatting, a description of every image and chart, and where colour carries meaning (for example "numerator (red text)"). The measured facts are prepended in code.
  4. The teacher can correct that text before continuing. From there the audit and rebuild work exactly as for pasted text.

The uploaded pages are what you see in steps 2 and 5, so the simulations run on the real worksheet: the colour-blindness filter on its actual chart, the low-vision blur on its actual print. Each rebuilt version carries the original page image with it; for the colour-blindness version it is recoloured (red becomes blue) so a red/green pair can be told apart.

For the dyslexia simulation the app uses the PDF's own text positions: each line on the page is covered and redrawn in the same place, size and colour with its letters scrambled, so the worksheet keeps its real layout and images. A photo or scan has no text positions, so its print is distorted with a wobble instead.

Limits: uploads need live AI (there is no demo fallback for a file the app has never seen), and images are described and recoloured but not redrawn.

Run it locally

Requires Node.js 20 or newer.

npm install
cp .env.example .env.local   # then add your OpenAI key to .env.local
npm run dev

Open http://localhost:3000.

The app works without a key — it uses the built-in demo data for the sample lesson. To analyse your own lessons with live AI, set OPENAI_API_KEY in .env.local and restart npm run dev.

npm run build   # production build
npm start       # serve the production build

.env.local is git-ignored. Do not commit it. To deploy on Vercel, import the repo and add OPENAI_API_KEY (and optionally OPENAI_MODEL) as environment variables — no code changes needed.

30-second demo path

  1. Click Use sample lesson, then Experience it.
  2. Click Color blindness (or Low vision) and ask someone to answer the question on the right.
  3. Click Find every barrier → Audit this lesson. With live AI the score lands around 30–40 with 12–14 barriers (exactly 38 and 13 on demo data). Takes about 10 seconds live.
  4. Click Fix it for every student → Rebuild for every student. Flip through the five tabs.
  5. Click See before and after. The score jumps to whatever the re-audit measured — typically 96–100 live, 100 on demo data.

Accessibility of the app itself

  • Semantic landmarks, headings, lists, and a skip link; real <button>, <label>, and form controls throughout.
  • Fully keyboard operable, with visible focus rings; focus moves to the new heading on each step change; student tabs support arrow keys.
  • Body text is set in Atkinson Hyperlegible (designed by the Braille Institute for low-vision readers) at high contrast.
  • Severity, scores, and status are never conveyed by colour alone — each has an icon and a text label.
  • prefers-reduced-motion is respected: transitions, the 3D scene, and the moving parts of the simulations are stilled.
  • Decorative graphics (the 3D equalizer, simulation overlays) are hidden from assistive technology; scrambled text keeps a readable copy for screen readers.

Tech

Next.js (App Router) · TypeScript · Tailwind CSS · Framer Motion · Three.js via React Three Fiber · pdf.js · Zod · OpenAI API

src/
  app/
    page.tsx              entry
    api/extract/route.ts  AI vision: reads an uploaded PDF or image into lesson text
    api/audit/route.ts    AI audit, with fallback
    api/rebuild/route.ts  AI rebuild (one call per student), with fallback
  components/
    EqualizeApp.tsx       state, stepper, step transitions
    Steps.tsx             the five steps
    Lesson.tsx            original worksheet + all five simulations
    VersionView.tsx       renders a rebuilt version in each student's format
    EqualizerScene.tsx    3D equalizer bars
    ui.tsx                score ring, avatars, badge
  lib/
    data.ts               students, sample lesson, pre-written fallback results
    ai.ts                 OpenAI call, JSON schemas, Zod validation
    upload.ts             renders PDF/image pages, measures font size and contrast
    download.ts           print-ready export

What we'd build next

  • Redraw images, not just describe and recolour them (for example a chart re-rendered with patterns and labels), and handle slide decks and longer documents.
  • Import real IEP / 504 documents and turn them into structured rules.
  • Automatic transcription of audio and video in a lesson.
  • A human-in-the-loop review step: the teacher approves or edits each change before a version goes to a student.
  • Track accommodation coverage across a whole term, per student.

About

Prompt-a-thon Project

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages