Odyssey Rag Patterns

Proven Patterns

Pattern 1: Nullable Filter SQL

When adding optional filters to SQL queries, use the CAST/IS NULL pattern:

AND (CAST(:param AS TEXT) IS NULL OR d.column = CAST(:param AS TEXT))

Pass None for unset filters. The clause evaluates to TRUE and is skipped. Used in: vector_search.py, bm25_search.py

Pattern 2: Pre-computed tsvector for BM25

PostgreSQL maintains tsvector_content via DB trigger with weighted sections:

• Section title → weight A
• Subsection → weight B
• Content → weight C Always use c.tsvector_content with the GIN index idx_chunk_tsvector. Anti-pattern: to_tsvector('english', c.content) bypasses the index entirely.

Pattern 3: Async Executor for ML Inference

loop = asyncio.get_running_loop()
scores = await loop.run_in_executor(None, self._model.predict, pairs)

When changing sync → async:

1. Update the method signature
2. Grep ALL callers (add await)
3. Check interface siblings (e.g., PassthroughReranker)

Pattern 4: Source Type Detection Chain

SOURCE_TYPE_RULES is an ordered list of (regex, type) tuples. First match wins.

• Specific patterns (e.g., IPS_Annex_B) come first
• General patterns (e.g., \.md$) come last
• When adding multi-brand detection, handle variant spellings: payss?ett? for "Payset/Paysett/Paysset"

Pattern 5: Integration Filter Passthrough

When adding a new filter parameter, wire it through the full stack:

MCP tool (@mcp.tool) → handler (tools/search.py) → engine (tool_context) → 
  all_filters dict → vector_search() AND bm25_search()

Both search paths MUST receive the filter. Missing one creates silent inconsistency.

Pattern 6: Health Endpoint Before Auth

For HTTP services with auth middleware, insert health routes BEFORE the middleware:

routes = [Route("/health", health_handler)] + existing_routes

Docker healthcheck pattern: httpx.get("http://localhost:PORT/health")

Pattern 7: Document Versioning (Supersede)

• New version: supersede(source_path) marks old is_current=False, then inserts new doc
• Change detection: SHA-256 file hash comparison
• Caution: Different filenames = treated as separate documents (duplicate risk)
• Old chunks/embeddings are NOT deleted — requires garbage collection (S1)

Tool Strategy Pattern

Tool-specific retrieval behavior is defined in tool_strategies.py:

@dataclass
class ToolStrategy:
    metadata_filters: dict[str, str]
    source_type_boosts: dict[str, float]
    require_source_types: list[str]
    focus_filters: dict[str, dict[str, str]]
    bm25_boost_terms: list[str]

Strategies are data-driven, not if/else chains. Add new strategies as dataclass instances.

Database Schema Quick Reference

Testing Patterns

• Tests: PYTHONPATH=src .venv/bin/python -m pytest tests/unit/ -x
• Lint: .venv/bin/ruff check src/ tests/
• Docker: docker compose build && docker compose up -d
• All external I/O must be mocked in unit tests
• Current baseline: 204+ unit tests passing

Common Pitfalls

1. Forgetting both search paths: When adding a filter, add to BOTH vector_search.py AND bm25_search.py
2. Regex spelling variants: Use payss?ett? not paysett? for brands with spelling variants
3. Sync ML in async context: Always check if ML libraries return synchronous results
4. Dead fields: If adding a DB column, ensure it's used in at least one query path
5. Scribe tool limit: Scribe agent spawns may fail if too many tools (>128). Use gpt-5-mini or gpt-4.1 for Scribe.

Architecture Overview

User/AI → MCP Server (stdio/HTTP) → RetrievalEngine
                                        ├→ QueryProcessor
                                        ├→ Vector Search (pgvector HNSW)
                                        ├→ BM25 Search (PostgreSQL tsvector GIN)
                                        ├→ RRF Fusion (k=60)
                                        ├→ Tool Strategy (boosts/filters)
                                        ├→ Cross-Encoder Reranker
                                        └→ ResponseBuilder → {evidence, gaps, followups}

Admin → FastAPI API → Ingestion Pipeline → DB

Created: 2026-04-17 | Last updated: 2026-04-17