Dead Reckoning
A way for our technicians to get answers out of thousands of equipment manuals — where every answer shows the page it came from, and the system says so when the manual doesn't cover it.
- My role
- Scoped it, built it, deployed it, keep it running
- Built with
- AI assistance (Claude, ChatGPT)
- Users
- Field and shop technicians
- Where it runs
- An internal Linux server
The problem
We sell and service crushing and screening equipment. Every machine comes with operations, parts and service manuals, and there are thousands of them sitting on a network drive as PDFs.
When a technician is standing in front of a broken machine, what they need is a torque spec, a hydraulic routing, or a parts diagram with the item numbers on it. Getting there means working out which manual covers that serial number, opening it, and scrolling. In practice most people just called one of the two guys who already knew — which works until those two are busy or on vacation.
The obvious idea is to let people ask an AI. The obvious problem is that a made-up torque spec on a rock crusher isn't a bad user experience, it's a safety issue. So the rule was set before anything got built: it can't tell you anything it can't point at, and it has to be willing to say the manual doesn't cover it.
How it works
When a manual gets added, the system saves a picture of every page along with the text on it. The pictures matter more than you'd expect — most of the diagrams in these manuals aren't really "text," so pulling the text out of a schematic page gets you a few stray labels and nothing useful. The picture is the only thing that captures what the drawing actually shows.
Then it looks at each of those page images and works out what it is — a hydraulic schematic, a wiring diagram, a parts diagram, a photo, a plain page of text. For anything that's a real diagram, it writes a short description of what's in it and lists the labelled parts, keeping the item numbers that make a parts diagram useful in the first place.
That description gets stored the same way the manual's text is stored. Which means when somebody searches for "hydraulic schematic for the conveyor lift," the diagrams are searchable right alongside the words — no separate system, no second place to look.
Keeping it honest
Three things stop it from making things up, and only one of them is an instruction.
The instruction is a set of rules it has to follow, including a list of words it isn't allowed to use — "typically," "usually," "generally," "it is likely." Those are the words that show up when something is guessing. If it doesn't have enough to go on, it has to say so and explain what's missing.
The other two are checks in the code, not requests. After an answer comes back, the system compares the pages it claims to be citing against the pages it actually pulled up, and throws away anything that doesn't match. And the details about which manual and machine you're looking at get attached by the system afterwards rather than being repeated back by the AI — one less thing that can be wrong.
The instructions are a request. The checks in the code are what actually guarantees it. That distinction is most of what I learned building this.
Three versions
The first version worked, on my machine, for me. It also had a shortcut in it I'm not proud of: every question got a handful of maintenance-related words tacked onto it before searching, because that fixed one query I was testing. It quietly skewed every other search toward maintenance content and I didn't catch it for months.
The second version didn't add any features. It was a rebuild to make the thing organised — proper structure, real logging instead of print statements, one place for settings that fails clearly when something's missing. It also started keeping a record of each manual added and automatically marking the older version of a manual as superseded.
The third version added the diagram reading, and went back to fix most of the shortcuts from the second. Adding a manual became a background job with a progress bar, because a 400-page manual was never going to finish while someone sat there waiting. Short pages stopped being skipped — the spec plates and warning pages are short, and they're exactly what people search for. And the keyword shortcut finally came out.
If there's one thing in this project I'd point at, it isn't the diagram feature. It's that the shortcut survived two versions before I noticed it and took it out.
Running it
It sits on an internal Linux server with a setup script that installs everything, and it restarts itself if it falls over. Versions of everything it depends on are pinned, so it doesn't change under me unexpectedly.
The notes I keep with it include what it costs to run — roughly a cent per page to read the diagrams — so reprocessing everything is a decision somebody makes deliberately rather than a button somebody clicks by accident.
What it still needs
There's no automated testing. For something whose whole value is that the citations are right, that's the first gap I'd close — a set of known questions with known correct pages, run every time something changes.
There's no login. Anyone on our network can reach it. That's a reasonable call for an internal tool on a private network and a bad one anywhere else, and it's worth being clear about which assumption it's built on.
I also don't have real numbers on how good the search is. I know it works because people use it and don't complain, which isn't the same as measuring it.