Way In

Picks the class novel from an approved list using Qloo rankings for each student, finds a film to bridge the book for the rest, and tracks who gets left out all term.

Comment

Inspiration

In 2023, 14% of US 13-year-olds said they read for fun almost every day. In 2012 it was 27% (NAEP Long-Term Trend, NCES). Many middle school English classes still read whole-class novels picked from a department-approved list, and many teachers hand out an interest survey in the first weeks. In the demo class, Sofia writes Stranger Things and Olivia Rodrigo, Lucas writes One Piece and Hollow Knight. Often the class then reads the book that worked last year. Way In keeps a record of which students each pick leaves out.

I wanted the survey to help decide which book from the approved list gives the most students a way in, and to show the teacher who is still left out after that.

What it does

Way In is a planning tool for one teacher and one class. It does three things a reading list does not:

  • One ranking per student. Qloo scores every unread approved book against each student's favorites, and Way In compares each score with how the book scores for the rest of the class. A book that fits a student better than it fits the class, and is among their top 3 such books, is their way in.
  • Bridge clips. For students the book misses, Way In takes the films Qloo says the book's readers also like, scores them against that student's favorites, and keeps the films with the best combined place on both lists: at most three films for the class, within its allowed ratings (G and PG by default, plus TV-Y7 to TV-PG for TV films), checked for a 13-year-old audience.
  • A term record. For each unit, every student had a way in, a bridge clip, or nothing. Students who had nothing, or didn't connect with what they got, count extra in the next pick (in the shortlist ranking, a way in counts 1 plus 0.5 for each earlier unit that student missed).

The demo has a fictional 8th grade class of 18 students, a 12-book approved list, and two earlier units (Hatchet and The Giver) that were picked before Way In.

  1. Read a survey. Diego transferred in this week. The agent reads his few lines, finds Olivia Rodrigo, The Wild Robot and EA Sports FC 24 in Qloo, asks the teacher which Spider-Verse film Diego meant, and turns "not into scary movies" into Qloo's horror tag, which is kept out of the clips suggested to Diego.
  2. Pick the next class read. The agent ranks the ten unread books for every student, compares the strongest books, searches bridge clips for the students each one leaves out, reads the teacher's note, and picks the book that leaves the fewest students with nothing. It states the numbers it compared. The plan opens with what to prepare: clips to queue and for whom, one-to-one check-ins (with Qloo's best book for that student outside the list as an independent-reading idea), and what to keep away from. In the live run, with the note "We just read two serious books in a row. Something with more humor or adventure would be good.", the agent compared New Kid, A Wrinkle in Time and Holes and picked A Wrinkle in Time: 6 students have a way in, 10 get one of three clip films (Bridge to Terabithia, Sabrina the Teenage Witch, Ballet Shoes), and 2 get a one-to-one check-in with an independent-reading idea.
  3. Close the unit. The teacher taps how each student took the book. A book someone was hooked by becomes one of their favorites. The agent reads the teacher's note ("Lucas would rather read something like Ghost by Jason Reynolds"), finds Ghost in Qloo and adds it to Lucas's profile, and writes a one-line note per student.

How Qloo is used

All Qloo calls run on the server against the hackathon API.

  • /search turns survey answers into entities across tv_show, movie, artist, videogame, book and person.
  • /v2/tags turns dislikes into tags (filter.parents.types = movie and TV).
  • /v2/insights per student with filter.type=urn:entity:book, the student's favorites as signal.interests.entities, and the approved books as filter.results.entities. That parameter limits scoring to books the teacher can actually choose. Way In turns each score into a z-score within its book across the class. feature.explainability=true tells which favorite pulled each book up, so the plan can say "Ghost leads into Long Way Down."
  • /v2/insights for bridge clips in two steps: films with the book as the only signal and filter.content_rating for the class's ratings, then those films (filter.results.entities) scored against each student's favorites, with filter.exclude.tags for the student's dislikes. The book's audience includes adults: the New Kid list was led by a PG papal thriller. So a clip also needs a youth genre (family, animation, adventure, fantasy, sci-fi, musical or sport) or a teen or family tag, counted by whole tag name. Thriller, crime, horror, war and documentary are out, a romance needs a family genre or a teen tag, and a PG from before 1985 must be a family film. A greedy cover keeps three films for the class.
  • One request in full: Nia's four favorites (Pokemon Scarlet, Roblox, Ghost, Jason Reynolds) go to /v2/insights?filter.type=urn:entity:book&signal.interests.entities=<Nia's four>&filter.results.entities=<the 12 approved books>&signal.demographics.age=24_and_younger&feature.explainability=true. Long Way Down comes out on top for Nia against the class average (z 2.3), and explainability names Ghost, by the same author, as the favorite behind it.
  • /v2/insights without the list filter gives each student's strongest books outside the list, kept to books Qloo tags Middle Grade, Young Adult or 13-17 and without the student's dislikes, as independent-reading ideas.
  • The chosen book's Qloo tags and the favorites that lead into it give the opening activity.

A language model will rank the list too. On five demo students, GPT-6.1 alone and Way In shared 6 or 7 of 15 top-3 places over three runs (table and script in the README). The overlap shows the two rankings differ, not which one suits a student better; neither has been tested with real students. What Qloo adds is a trace: each Way In pick names the favorite that Qloo says carries the score, measured against the rest of the class.

How I built it

  • Node.js server with no npm dependencies, plain HTML, CSS and JavaScript front end.
  • The agent runs on Azure OpenAI (GPT-6.1) through the Responses API with function tools: survey reading, picking (get_class, rank_texts, find_bridges, look_at_book, choose_text, submit_unit_plan) and closing a unit. Every step and every Qloo request streams to the page.
  • The server checks the model's output: IDs must come from Qloo responses in the same run, a book can only be chosen after its bridge clips were checked, way-in notes only go to students who have a way in, bridge notes must use the clip Qloo returned, and a favorite added from a teacher note must quote the note.
  • Searches that contain a classmate's first name or a word like Mr. or Ms. are refused before they reach Qloo.
  • If the model is unavailable, the same Qloo pipeline runs with fixed rules and templates, and the page says "Picked with fixed rules".
  • Qloo responses are cached on the server, requests are queued under 5 per second, and the public demo has daily and per-address limits.
  • Each visitor gets a private copy of the demo class.
  • 23 automated tests run against a mock of the Qloo API with the same response shapes; the demo runs on the live hackathon API.

Challenges

  • Ranked by raw Qloo affinity, The Giver was in the top 3 for 15 of 17 students, Holes for 14 and The Crossover for 13. Popular books win everyone's list. Scoring each book against the class average spread the top-3 places: each of the ten unread books is now in the top 3 of 3 to 8 students.
  • The same thing happened to bridge clips: the two Spider-Verse films were the clip for 10 of 12 students. Ordering each student's films by fit over the other students spread them out, and capping the class at three films keeps the teacher's prep to three films.
  • A first version picked clips by explainability share. With the book and one favorite as inputs, most shares came back between 50/50 and 60/40 and 97% passed a 20% test, so it let weak picks through. The two-list method replaced it.
  • Showing "87%" next to a 13-year-old's name would read as a prediction about them, so the app shows ranks ("#2 of 10").
  • Students write "Spider-Verse" and "FC 24". Book titles in Qloo carry series notes ("Holes (Holes, #1)"). The agent searches the likely type, matching ignores the series note, and the teacher is asked when two titles could both be meant.

Accomplishments

  • In the live run the agent compared three books (ways in / bridge clips / nothing, with three clip films per book: New Kid 6/9/3, A Wrinkle in Time 6/10/2, Holes 6/8/4) and picked the one that leaves the fewest students with nothing, saying the note's request for adventure fits it too.
  • What happens in class goes back into Qloo signals. A book a student was hooked by becomes a signal for that student's next ranking, and a student who didn't connect counts extra next time.

What I learned

A Qloo score on its own said little about a student until it was compared with the same book's score for the classmates. And a ranked list is only half a plan: with one book per unit, most students won't have it in their top 3, so the tool has to say what to do for the rest.

What's next

  • Import surveys from Google Forms.
  • Let a department see across classes which approved books leave the most students out.
  • Add reading level and content notes from the school's own catalog next to each book.

Known limitations

  • A way in is a rank within the approved list, not a prediction. With one book per unit, most students won't have it in their top 3; the clips and the term record are there for that.
  • Way In does not check reading level, standards or content warnings; the approved list and the teacher cover those.
  • Some favorites are not in Qloo, and search can return near matches; the teacher confirms ambiguous titles.
  • Bridge clips are suggestions for the teacher to preview; the rating and genre checks are a floor, not a review. The teacher can reject a clip and the student gets their next option; the class still keeps at most three films.

Built With

Share this project:

Updates

Submission history