luxinyue0910/speclens

How luxinyue0910/speclens works

SpecLens is a local-first, evaluation-driven RAG service. Its main workflow ingests engineering documents and linked images into searchable chunks, routes questions to keyword, vector, or hybrid retrieval, then produces evidence-grounded answers and citations. Evaluation compares route accuracy, retrieval quality, latency, and cost. The README documents ingestion and evaluation capabilities beyond the sampled source; those branches are shown at their documented subsystem paths, with uncertain internal wiring omitted.

Main entry points: pipeline.py RAG pipeline · build_indexes.py Index builder · run_experiment.py Experiment runner · main.py FastAPI app

Components 30

API service

FastAPI app apps/api/main.py
Ask endpoint apps/api/routes/ask.py
Ingest endpoint apps/api/routes/ingest.py
Eval endpoint apps/api/routes/eval.py

Evidence ingestion

Document loader rag/ingestion/loader.py
Text chunking rag/ingestion/chunker.py
Image evidence rag/ingestion/image_assets.py
OCR extraction rag/ingestion/ocr.py
Image summaries rag/ingestion/vision_summary.py
Index builder rag/ingestion/build_indexes.py
Chunk data data/indexes

Retrieval and answers

RAG pipeline rag/pipeline.py
Keyword retrieval rag/retrieval/keyword_retriever.py
Query routing rag/routing/query_router.py
Vector retrieval rag/retrieval/vector_retriever.py
Hybrid fusion rag/retrieval/hybrid_retriever.py
Optional reranking rag/retrieval/reranker.py
Answer generation rag/generation/answer_generator.py
Grounded citations rag/generation/citation_builder.py

Evaluation

Experiment runner rag/evaluation/run_experiment.py
Evaluation metrics rag/evaluation/metrics.py
LLM judge rag/evaluation/llm_judge.py
Report generation rag/evaluation/report_generator.py
Labeled questions data/eval/questions.jsonl
Experiment reports reports/experiments

Other components

Questioner
Engineering corpus data/docs
Linked image assets data/assets
Vector index
Ollama model

Connections 35

Questioner → FastAPI app: asks
FastAPI app → Ask endpoint: dispatches
FastAPI app → Ingest endpoint: dispatches
FastAPI app → Eval endpoint: dispatches
Ask endpoint → RAG pipeline: calls
Ingest endpoint → RAG pipeline: calls
Eval endpoint → Experiment runner: runs
RAG pipeline → Query routing: routes
RAG pipeline → Keyword retrieval: selects
RAG pipeline → Vector retrieval: selects
RAG pipeline → Hybrid fusion: selects
RAG pipeline → Optional reranking: reranks
RAG pipeline → Answer generation: generates
Answer generation → Ollama model: requests
Answer generation → Grounded citations: builds citations
Hybrid fusion → Keyword retrieval: retrieves
Hybrid fusion → Vector retrieval: retrieves
Vector retrieval → Vector index: queries
Keyword retrieval → Chunk data: loads chunks
RAG pipeline → Index builder: builds indexes
Index builder → Document loader: loads
Document loader → Engineering corpus: reads
Index builder → Text chunking: chunks text
Index builder → Image evidence: extracts image evidence
Image evidence → Linked image assets: resolves assets
Image evidence → OCR extraction: extracts text
Image evidence → Image summaries: summarizes
Index builder → Chunk data: writes chunks
Index builder → Vector index: writes vectors
Experiment runner → Labeled questions: loads questions
Experiment runner → RAG pipeline: benchmarks
Experiment runner → Evaluation metrics: measures
Experiment runner → LLM judge: judges
Experiment runner → Report generation: generates
Report generation → Experiment reports: writes

More Python diagrams: langchain-ai/langgraph-swarm-py · p1sec/qcsuper · vinhhien112/img2obj · d-star-ai/dsrag · zimengxiong/tinytouch

Drawn by GitDiagram on September 28, 2026 from the repository's file tree, README and source files. Read as Markdown ·