Animatores Romani, the FTC team I am part of, commits to reading the full FTC manual every year we participate. However, we often forget specific rules or details when we need them the most—a problem I knew isn't unique to us from talking to others at events. I wanted to create a tool that enabled more efficient searching and synthesis of the manual using AI.
Features
-
View the full manual PDF, annotable with embedded Adobe Acrobat
-
In a sidebar, ask questions about the manual to an AI chatbot powered by leading models that is fully informed on the manual's latest nuances and content
-
Click on page numbers cited by the model to navigate to that exact document page
Engineering
I built the site in Next.js, which in retrospect, was quite overkill because this is a simple one-page application. However, that doesn't mean it was bad; it did make for very easy deployment and scaling on Vercel. In the future, I might use Vite with React alone.
I used the OpenAI Assistants API because of how natively it supported RAG. However, I noticed that results increased significantly when uploading text files rather than PDFs, even though both are supported. So, I developed a script to transcribe each .pdf in a directory to the .txt file with the corresponding name, which I then uploaded to the Assistants dashboard. Then, the model can automatically use an OpenAI-hosted file search tool with just a toggle in the chat_completions.create call.
To prevent hallucinations and also begin to suggest a helpful tone and output style, I developed this system prompt:
You are a helpful AI assistant that helps find and provide answers to questions from the 2024-2025 FIRST Robotics FTC game manual. Do not use any prior knowledge; you have everything you need to answer game manual questions in the one PDF provided. Use markdown, especially lists and headings, to make responses more readable. Cite all files used. Answer like a mentor would.
Once a response is streamed in from the model, which happens in a Next.js API route, I render Markdown using react-markdown and specify a unique kind of mark: the OpenAI page citation structure, which should be converted to a bolded link to an exact page on the manual. Once you click one of these links, I use an effect to scroll to that exact page in the PDF viewer.
The PDF is rendered using the Adobe Acrobat PDF Embed API, which doesn't have great React, TypeScript, or NPM support, but does provide a great user experience with the ability to annotate and download their own copies of game manuals.
Reflection
I published the tool on my own domain at ftc-game-manual.tml.sh and posted about it on r/FTC and the FTC Discord. The posts got moderate engagement, but several FTC coaches and team members from around the country reached out to me sharing how much they appreciated the tool and how much it helped their entire teams. I found this super rewarding, especially when rookie teams said it made the competition more accessible.
So I'm proud of how this project turned out, and I also am proud of thinking for this idea and acting on it so early, since FTC even released their own exact version of this product a year later!
Additionally, to inspire an audience of passionate engineers and coders, I open-sourced the project on GitHub so anyone can self-host or expand it if they wish!
Screenshots
