Hermes Wiki
Projects/TraceLens

TraceLens — Investigative RAG Platform

Turns raw incident data — logs, traces, deploy records, metrics — into evidence-cited, hypothesis-backed root-cause reports, not just retrieved chunks. Full-stack RAG system built around an 8-node investigation graph.

Designed and built end-to-end: retrieval, investigation graph, and frontend.

Repo: fullstackfusions/rag_project

The Investigation Graph

8 sequential LangGraph nodes, every question → answer:

  1. extract_entities — services, envs, error tokens
  2. set_time_window — expand or narrow the window
  3. retrieve_hybrid — Qdrant + Postgres FTS, RRF-merged
  4. rerank — Cohere + incident-aware scoring
  5. build_timeline — chronological ordering
  6. hypothesis_generator — confidence + cited evidence
  7. next_best_question — 2–4 follow-ups
  8. compose_evidence_pack — cited narrative answer

What It Does

  • Hybrid Search & Reranking — Qdrant vector search and Postgres full-text run in parallel, top 40 each, merged with Reciprocal Rank Fusion, then reranked by Cohere v3.5 blended 60/40 with incident-aware signals: recency, service match, source type, pin state.
  • Evidence-Cited Answers — every hypothesis must reference specific evidence IDs; a post-processing pass validates each citation actually exists in the retrieved set before the answer ships — no unsupported claims.
  • Timeline Strip — evidence rendered as a chronological, clickable strip above the chat — deploy records, metrics, and logs clustered by timestamp, one click from full detail.
  • Quick Refine Chips — up to 8 one-click follow-ups per turn — 4 LLM-generated from the live investigation, 4 deterministic (expand window, filter to service, pre/post-deploy).
  • Incident Sessions — scoped investigation contexts that persist pinned and rejected evidence, service filters, and time windows across every follow-up in the thread.
  • Zero-Dependency Fallbacks — every LLM-backed node has a deterministic fallback path; pull the API key and the full 8-stage pipeline still runs end to end.

Engineering Notes

  • Design — the graph is intentionally linear, not looped, for predictability and traceability in v2. Loop-back re-retrieval (retry if evidence is thin) is scoped for v3.
  • Validate — hypothesis generation is constrained to emit supporting_evidence_ids; anything referencing an ID outside the retrieved set is discarded before it reaches the response.
  • Rerank fallback — skips Cohere entirely: a 5-signal weighted score (FTS rank, recency, service match, source type, pin boost) keeps ranking coherent offline.
  • State — every refine click triggers a full re-investigation (fresh retrieval, rerank, timeline, hypotheses) while session state (pins, rejects, windows) carries forward turn to turn.

Stack

Component Role
FastAPI backend
React 19 frontend
PostgreSQL 16 records + full-text search
Qdrant vector store
LangGraph investigation graph orchestration
OpenAI generation
Cohere reranking
Hermes Wiki