V1: RAG pipeline with hybrid search, reranker and Telegram bot

[johnma96]

Scope

Closes V1 of the ResearchOS roadmap: a complete RAG pipeline over open-access
papers, exposed through a Telegram bot, built on Clean Architecture with
Protocol-based abstractions.

What was built

Domain layer

• Pydantic v2 models: Document, Chunk, Message, Paper
• Protocols in domain/interfaces.py: LLMProvider, VectorStore,
  Retriever, MemoryStore
• Prompt templates as .txt files with str.format(), loaded via
  PromptTemplate

Ingestion pipeline (offline)

• arXiv API client with XML parsing and metadata extraction
• PDF text extraction with PyMuPDF
• Fixed-size chunking with overlap in chunking_service.py
• Orchestrated by ingestion_service.py, run via scripts/ingest_documents.py

Retrieval

• ChromaVectorStore with local embeddings (sentence-transformers,
  all-MiniLM-L6-v2)
• BM25Retriever using rank_bm25
• hybrid_search: Reciprocal Rank Fusion over an arbitrary list of
  Retriever implementations
• hybrid_rerank_search: Claude as a relevance reranker over hybrid candidates
• scripts/eval_retrieval.py compares four strategies (vector, BM25, hybrid,
  hybrid+rerank) with P@k and MRR

Delivery channel

• TelegramBot adapter in infrastructure/bot/telegram_bot.py
• Wiring in scripts/run_telegram_bot.py, injecting an
  AnswerFn = Callable[[str], Awaitable[str]]

Tests

• 25 unit tests with @pytest.mark.unit / @pytest.mark.integration
  separation, mocking Protocols rather than concrete implementations

Key architectural decisions

• Protocols over ABCs. Structural subtyping keeps application/ decoupled
  from inheritance hierarchies and lets test mocks satisfy contracts without
  importing infrastructure.
• hybrid_search accepts list[Retriever], not concrete classes. Adding a
  third retriever requires no signature change and no edits to
  application/.
• Engine/channel separation. The Telegram bot receives an injected
  AnswerFn and never instantiates AnthropicLLM or ChromaVectorStore.
  Dependency wiring lives in the composition root (scripts/). The same
  contract will serve Slack, FastAPI or a CLI.
• Composition over inheritance for agents. Shared behaviour lives in
  agent_utils.py; agents import what they need instead of inheriting from a
  base class.
• BM25 exposes an async search despite being in-memory, for uniformity
  with ChromaVectorStore under asyncio.gather in hybrid_search. Documented
  as a conscious trade-off; revisit if corpus size makes the blocking cost
  material.

Known debt

• test_extract_text_pdf depends on a sample PDF that is not versioned, so it
  fails on a clean clone. Should be mocked (V3).
• The 20-question eval dataset was written with knowledge of the indexed
  corpus (data leakage), so all four strategies score near 1.000 and the
  comparison is non-discriminative. Rebuilt in V3 with real bot queries.
• No conversational memory: answer_query takes no history, so follow-up
  questions lose their referent (V2).
• No query rewriting, so anaphoric queries ("what is the mechanism?") retrieve
  poorly even with memory (V2).
• The bot is wired to vector-only retrieval, not hybrid_rerank_search.
• Telegram truncates messages above 4096 characters; not handled.

Out of scope for V1

LangGraph orchestration, agent tools, morning briefing, observability,
guardrails, deployment. All planned in V2–V4.