Field Service Repair Assistant

A mobile-first PWA that turns equipment service-manual PDFs into an interactive, AI-assisted diagnostic tool with strict anti-hallucination safeguards. Designed for field service engineers working on medical, industrial, or technical equipment.

Status: working personal project. Not actively supported. Feedback and PRs welcome but response time may be slow.

What it does

• Import a PDF service manual → AI extracts alarms, parts, serial-number ranges, figure callouts
• Diagnose by typing a symptom or alarm code → AI matches against imported manual and your case history
• Ask any question against the manual full text (RAG)
• Parts lookup by code, description, or alarm
• Cases — your repair history becomes searchable diagnostic context
• Offline — all imported data lives in IndexedDB; AI calls degrade gracefully without network

Anti-hallucination design

Field service is a domain where wrong information is dangerous. The system:

• Tags every AI output as manual:page\_N, case:YYYY-MM-DD, inference, or insufficient\_data
• Whitelists part numbers — AI cannot invent them, only select from extracted manual data
• Validates page references against actual manual length
• Records every "dropped" hallucination so the UI can show "AI tried to invent X, suppressed"

See src/ai/validators.js.

Tech stack

• React + Tailwind (CDN) — single self-contained HTML output
• PDF.js — local PDF parsing + page rendering
• IndexedDB — manual storage, embeddings, cases, figures
• Anthropic Claude API — structuring + diagnosis (or DeepSeek for cheaper alternative)
• OpenAI embeddings — semantic search via int8-quantized vectors
• esbuild — bundles src/ → single dist/repair-assist.html

Quick start

npm install
npm run build           # produces dist/repair-assist.html
npm run serve           # http://localhost:8080

For AI features, get an API key from one of:

• https://console.anthropic.com (recommended)
• https://platform.deepseek.com (cheaper)

Plus optionally https://platform.openai.com for embeddings (enables semantic search).

Set keys inside the app: Manuals tab → API key fields. Keys stored in browser localStorage, never sent anywhere except the respective AI provider.

Cost expectations

For a typical 300-page service manual:

• PDF.js text extraction (free, local)
• AI structuring (Phase A-E): ~$0.50-2 with Anthropic, ~$0.05-0.20 with DeepSeek
• Vision OCR (optional, for manuals with complex tables): ~$3-11 per manual
• Embeddings (optional, for semantic Ask): ~$0.01 per manual
• Figure callouts (optional): ~$1 per 200 figures with Haiku

Daily/per-import spend caps are configurable.

Single-user data model

This is designed for one engineer on one device. There's no backend, no cloud sync, no account.

Multi-device sync is via JSON export/import (Manuals tab → BACKUP/RESTORE). Backups can be tiered:

• Core only — ~250 KB/manual (structured data, no embeddings or figures)

• Embeddings (int8) — ~1.5 MB/manual (Ask semantic search works)

• Embeddings (float32) — ~6 MB/manual (zero recall loss)

• Full — ~16.5 MB/manual (with figure JPEGs, complete offline)

Known limitations

• iOS not supported — IndexedDB quotas and Safari quirks make it unreliable. Use Android Chrome.
• PDF tables — vision OCR helps but complex multi-page tables still come out as text. Best results on manuals with clear single-column layouts.
• Service Worker doesn't pre-cache CDN dependencies (Tailwind, Fonts, PDF.js worker). First load needs network even after install.
• No cross-manual reasoning by default — manuals are scoped to their model. Toggle "Search all" for cross-machine lookups (use with care: different machines may share alarm names but not mechanics).
• Cost tracker is best-effort — not transactional. Crashes mid-call may miss recording spend.

Architecture

src/
  db/        IndexedDB wrapper + schema (manuals, chunks, figures, cases, history)
  pdf/       PDF.js parsing, chunking, figure-page detection
  ai/        API clients, prompt templates, anti-hallucination validators, 4-phase structurer
  search/    Tokenizer, stemming, hybrid retrieval, case similarity
  ui/        App, components, 5 tabs (Diagnose / Search / Cases / Parts / Manuals)
build.js     esbuild bundle → single dist/repair-assist.html

Contributing

If you find this useful for your own work, please open an issue describing your equipment domain — adapting the prompts for non-medical-sterilizer manuals will likely need iteration.

Pull requests welcome especially for:

• Manufacturer-specific prompt tuning (Belimed, Getinge, Steelco, washer-disinfector lines)
• Better PDF table extraction
• Bug fixes

Please open an issue before starting large changes so we can discuss the design.

License

MIT — see LICENSE.

This project uses third-party libraries under their own licenses (React, PDF.js, etc — see package.json).

Contact： bahu69@hotmail.com