📄 README.md 2,735 bytes Apr 30, 2026 📋 Raw

Brain Query Interface — Phase 6.3 Complete

Summary

Built the Brain Query Interface for natural language search across family documents with temporal weighting.

Files Created

Core Module (brain/)

brain/
├── __init__.py          # Module exports
├── embeddings.py        # Document chunking and Ollama embeddings
├── query.py             # Pattern detection and temporal scoring
├── store.py             # ChromaDB integration
├── router.py            # FastAPI endpoints
├── seed.py              # Test data seeding for Miller family
└── test_brain.py        # Unit tests

Architecture

User query → Pattern detection → Embedding → ChromaDB search → Temporal re-rank → Synthesize answer

Components

  1. Pattern Detection (query.py)
    - LOGISTICAL: Time-sensitive (schedules, current events)
    - ENTITY: Fact lookup (sizes, dates, values)
    - HISTORICAL: Past events (roofer names, old invoices)

  2. Temporal Weighting (query.py)
    - Logistical: Exponential decay (7-day half-life)
    - Entity: Linear decay (90-day half-life)
    - Historical: No decay

  3. Vector Search (store.py)
    - ChromaDB with nomic-embed-text embeddings via Ollama
    - Combined scoring: 70% semantic + 30% temporal

  4. API (router.py)
    - POST /api/brain/query — Natural language query
    - GET /api/brain/stats — Collection statistics
    - GET /api/brain/health — Health check
    - GET /api/brain/patterns — Available patterns
    - POST /api/brain/admin/documents — Add documents

Test Data

Seeded with 7 Miller family documents:
- newsletter_march_2026 — School newsletter
- email_principal_march_2026 — Schedule update email
- invoice_hvac_2026 — HVAC service
- invoice_dance_2026 — Dance academy
- receipt_vet_2026 — Vet visit receipt
- roofer_invoice_2024 — Historical roofing
- calendar_2025_2026 — School calendar

Integration

Updated main_v2.py:

from brain import brain_router as brain_query_router
family_app.include_router(brain_query_router, tags=["brain-query"])

Verification

All tests pass:

pytest brain/test_brain.py -v
# 16 passed, 1 deselected

Example queries work:
- "Is Friday a half-day?" → Returns March email (logistical pattern)
- "What size is our HVAC filter?" → Returns 16x25x4 (entity pattern)
- "What was the roofer's name?" → Returns Madison Roofing Co. (historical pattern)

Dependencies

Added to requirements.txt:
- chromadb>=1.5.0

Next Steps (Phase 7)

  • LLM answer synthesis (instead of simple text extraction)
  • Telegram bot integration
  • Document ingestion pipeline
  • Optimize chunking
← Back