AI Sherlock (Root Cause Analysis)

AI Sherlock is an Enterprise capability that turns the noisy history of an asset or work order into a ranked list of plausible root causes plus concrete next actions. It runs a reasoning model over a structured case file (history, downtime, meters, peer assets) and — when documents are uploaded — over the relevant chapters of your own manuals and SOPs.

How to run an analysis

Open any asset or work order detail page and click 'Analyze with AI Sherlock'. Optionally add a one-line symptom hint to focus the analysis (e.g. 'unusual noise on startup'). The model returns a summary, 2–5 ranked hypotheses with evidence, 2–5 recommended actions, and citations to the documents it drew from. Past analyses are listed at /ai-sherlock for re-review and audit.

How the RAG layer works

When you upload a PDF or DOCX in the Documents module, Sherlock extracts the text, splits it into ~1200-character chunks with overlap, embeds them via the same provider used by the chatbot cache, and stores them per-tenant. At analyze time it pulls the top-4 most semantically relevant chunks and injects them into the prompt. Ingestion is best-effort and fire-and-forget: uploading is never blocked, and RAG silently degrades to structured-context-only if extraction or embedding fails.

Strict tenant scoping

Every context query is filtered by companyId. Subjects from another tenant return 404 (never 403, to avoid leaking existence). RAG retrieval is also company-scoped at the SQL level. Audit logs of every analysis are persisted as SherlockAnalysis rows (model, tokens, cost, latency) and surface in /admin/ai-usage for super-admins.

Permissions and tier gating

• Feature: AI_SHERLOCK — Enterprise tier only. Lower tiers see an upgrade badge.
• Permission: ai:sherlock — seeded for ADMIN by default. Grant via /people/roles for any other custom role.
• Analysis results never override your data — they're advisory; verify against your maintenance procedures before acting.

Cost and configuration

Sherlock calls the model declared in the 'sherlock_primary' slot (fallback 'sherlock_fallback') under /admin/ai-usage. Defaults are conservative reasoning models on OpenRouter. Per analysis: typically <$0.01 for the LLM call + a few cents per ~50 chunks of document ingest (one-off per upload). All AI calls are logged in AiUsageLog for tenant cost transparency.