Shelfwise

Inspiration

A patron says "I just binged Reservation Dogs, what should I read next?" The person at the library desk has seconds to answer, a small budget, and a shelf that took years to build. A buyer at an indie bookshop has the same problem in reverse: a few hundred dollars and a front table to fill.

Catalogue tools answer inside the book world: same author, same subject, same series. But people don't move between books that way. They move from a TV show to a game to a podcast to a novel. That cross-domain taste signal is exactly what Qloo models, and it is missing from the tools library staff actually use.

What it does

You give Shelfwise a place, an optional audience and a few things patrons are into right now (shows, films, games, podcasts, music, books). An agent plans and runs a visible chain of Qloo calls and hands back three things staff can use the same day:

1. A bridge shelf: printable "Loved X? Try Y" shelf-talker cards, one for every recommended book, six to a page with cut guides.
2. A buy / feature list: titles in rank order for that audience, each with its evidence: which signals returned it, where it ranked, its local fit near the library, and, when the agent checked trends, whether interest in the show or artist behind it is rising.
3. Three programme ideas: a film night, a themed display and a book club built on the same signals and books.

Every title, rank, affinity, local-fit value and trend on screen comes from a Qloo result, and every card has a Cite link that opens the exact call it came from, with its inputs and raw result. An evidence trail fills in call by call while the agent works. Follow-up chat ("make it for teens", "more translated fiction") re-runs only the Qloo calls that change. Recent runs keeps finished shelves in the browser, and the Print desk prints the cards and lists black on white.

Try it: open https://shelfwise.gotclass.xyz, click one of the four examples (for instance Tulsa, OK: Reservation Dogs, Brooklyn Nine-Nine, Baldur's Gate 3) and press Build my shelf. A run usually takes under half a minute. No login. The public demo is rate-limited per visitor to protect the shared API quota.

How we built it

• Agent: NVIDIA Nemotron 3 Super on Nebius Token Factory. nvidia/nemotron-3-super-120b-a12b is the planner, reached through Token Factory's OpenAI-compatible endpoint with native tool calling. Each run is a bounded loop of Nemotron turns: it writes the plan shown to the user, chooses Qloo tools and arguments (often several in parallel), reads the results, handles ambiguous names, empty results and errors, and finally calls submit_report.
• Qloo through the official harness. The server runs Qloo's own qloo mcp harness as one long-lived child process and talks to it with the MCP SDK. A typical run uses recommend (one call per signal, so "Loved X? Try Y" is true by construction), rank for the chosen audience and place, and where_popular for local fit. Also available to the agent: trends on the loved shows and artists (Qloo has no trend data for books, so Shelfwise reports the trend of the signal behind each book), compare_audiences to look for a bridging title, and tag and demographic lookups.
• A no-invention guard. The model never types a title or a number that reaches the user. It picks entities by reference (e12) to results it has seen, and its prose may name works only through {e12} placeholders. The server joins in titles, ranks, affinities, local fit and trends from the Qloo results it holds, rejects any pairing that no Qloo call supports, and sends the model back for a bounded repair with specific reasons. If the model leaves a buy-list book without a shelf-talker, the server writes one from the calls that returned it, with citations.
• Streaming UI. A Node 22 server streams the run to a React + Vite frontend as Server-Sent Events: plan, each tool call and result, questions back to the user, and the report.
• Built to be shared. Per-visitor limits, a run queue, a response cache and a daily call budget protect the API quota. It runs in Docker on a small Linux server behind a Cloudflare tunnel. 372 automated tests cover the agent loop (every Qloo status, pause and resume, retries, step limits), the guard and the server.

Challenges we ran into

• Making every claim traceable. A plausible-sounding shelf-talker the model made up is worse than none. The guard and the reference-only design took most of the engineering, and they are why a librarian can click Cite and see the evidence.
• Live data is not sample data. On the first day with the live key we found real response shapes that differed from the docs and our fixtures: trends requests for books return 400, entity types arrive as urn:entity, and where_popular can come back empty. Each became a fix plus a test.
• The model doing less than asked. Nemotron sometimes wrote two shelf-talkers for six books, or typed a title next to its placeholder. Instead of more prompt pleading, the server now enforces the shape: every buy-list book gets a cited card, a report with fewer than three programme ideas goes back for repair, and duplicated titles are collapsed.
• Rate limits. The Qloo endpoint sometimes answers 429; the agent retries only errors marked retryable, with backoff, and the evidence trail shows each retry.

Accomplishments that we're proud of

• Every visible fact links back to the Qloo call it came from.
• The output is something staff can print and put on a shelf the same afternoon, not a chat transcript.
• The agent's work is visible: the plan, each call and each result appear as they happen.

What we learned

• Cross-domain taste is the product. Without Qloo, Shelfwise shows nothing: there is no catalogue or model-memory fallback.
• A language model is a strong planner and writer when it works with references, and a weak source of facts. Separating the two made the output trustworthy.

What's next

• Check recommendations against a library's own catalogue (ILS / OPAC) so the shelf only shows books the branch owns or can order.
• Multi-branch view for library systems, and saved shelves shared across a team.
• Pilot with a public-library branch and measure circulation of featured titles.

Built with AI assistance

Shelfwise was written with Claude Code (Anthropic's AI coding assistant), directed and reviewed by a human. The code, tests and docs are open source under the MIT license.

Built With

• cloudflare
• docker
• model-context-protocol
• nebius-token-factory
• node.js
• nvidia-nemotron
• qloo
• react
• typescript
• vite