Cognitive Cache

Privacy-first, AI-powered context prediction platform. Captures developer context signals and predicts next-needed documents using a hybrid ML pipeline with continuous feedback.

Overview

Captures developer context events (active file, language, application) via REST and WebSocket. Predicts documents the developer will need next using a hybrid search pipeline combining semantic vector search (Qdrant + sentence-transformers) with BM25 keyword ranking, boosted by LightGBM and a continuous feedback loop. Runs entirely locally — no data leaves infrastructure.

Core Architecture

flowchart LR
    Dashboard["Next.js Dashboard"] -->|WebSocket| WS["/ws/predictions"]
    Dashboard -->|REST API| Backend["FastAPI Backend"]
    Backend -->|auth| JWT["JWT + Argon2"]
    Backend -->|queries| DB[(Postgres 16)]
    Backend -->|vector search| Qdrant["Qdrant Vector DB"]
    Backend -->|embeddings| ST["sentence-transformers"]
    Backend -->|hybrid rank| BM25["BM25 + LightGBM"]
    Backend -->|documents| DocSvc["Document Intelligence"]
    DocSvc -->|indexes| Qdrant
    User -->|feedback| Backend
    Backend -->|feedback boost| Qdrant

Loading

System Components

Component	Responsibility
frontend/	Next.js + Tailwind dashboard — predictions panel, context banner, activity feed
backend/app/	FastAPI REST API, WebSocket, authentication, document management
backend/services/	Embedding, BM25 ranking, LightGBM prediction, document chunking
data/sample_docs/	Sample documents for quick-start seeding
docker-compose.yml	Postgres, Qdrant, backend, frontend orchestration

Repository Layout

Directory	Purpose
frontend/	Next.js web dashboard
backend/	FastAPI REST API and ML engine
data/	Sample documents
docker-compose.yml	Container orchestration

Technology Stack

Layer	Technology	Purpose
Frontend	Next.js + Tailwind CSS	Web dashboard
Backend	FastAPI + Python	REST API and WebSocket
Vector DB	Qdrant	Semantic search embeddings
Database	Postgres 16	Metadata and prediction records
Embeddings	sentence-transformers (BAAI/bge-small-en-v1.5)	Document and context embeddings
Ranking	BM25 + LightGBM	Hybrid ranking and prediction
Auth	JWT + Argon2	Secure API access
Container	Docker Compose	Local deployment

Requirements

• Docker and Docker Compose (recommended)
• Python 3.13 (for local backend development)
• Node.js 18+ (for local frontend development)

Configuration

File	Purpose
docker-compose.yml	Service orchestration
.env.example	Environment variable template
backend/.env	Backend config: DATABASE_URL, QDRANT_URL, JWT_SECRET, DEFAULT_EMBEDDING_MODEL

Key variables: DATABASE_URL, QDRANT_URL, DEFAULT_EMBEDDING_MODEL, JWT_SECRET, JWT_ALGORITHM, JWT_EXPIRE_MINUTES, BM25_TOP_K, VECTOR_TOP_K, FEEDBACK_BOOST_FACTOR.

Getting Started

docker compose up --build

Open http://localhost:3000 (dashboard) and http://localhost:8000/docs (API docs).

Development

# Backend
cd backend
pip install -e ".[dev]"
uvicorn app.main:app --reload

# Frontend
cd frontend
npm install
npm run dev

# Tests
cd backend && pytest

Request / Data Flow

sequenceDiagram
    participant Dev
    participant Dashboard
    participant Backend
    participant Qdrant
    participant Postgres

    Dev->>Backend: Context event (app, file, language)
    Backend->>Postgres: Store event
    Backend->>Qdrant: Embed + index context
    Backend->>BM25: Rank documents by keyword match
    Backend->>LightGBM: Predict next-needed docs
    Backend-->>Dashboard: Prediction rankings via WebSocket

    Dev->>Backend: Submit feedback on prediction
    Backend->>Qdrant: Apply per-document feedback boost
    Qdrant-->>Backend: Updated rankings

Loading