Why:
- d5ccec2 locked ±3 in code; env template and domain glossary were still at 0/0.
Changes:
- NEIGHBOR_PREV/NEXT=3 in .env.example
- CONTEXT.md Neighbor Expansion defaults updated to 3/3
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Close the open ±N follow-up from the strategy finalization memo.
Changes:
- Add addendum with ±0…±3 evidence and binding ±3/3 default.
- Sync LLD config table with new neighbor expansion defaults.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Final benchmark selected fixed_size with neighbor expansion ±3 as the winning Candidate.
Changes:
- Set neighbor_prev/neighbor_next defaults to 3 in Settings.
- Default Query tab to fixed_size ±3/3 and Benchmarks to single-strategy fixed_size.
Impact:
- API and Dashboard runs use ±3 unless explicitly overridden.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Close the benchmark with a written family decision backed by Experiment composites.
Changes:
- Add the decision memo and SVG charts generated from SQLite.
Impact:
- Documents fixed_size over semantic under text-embedding-3-large; ±N remains follow-up.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Compare is the wrong surface for two-stage family selection over the 10-doc set.
Changes:
- Add the Decision Tab; raise GET /experiments default/max so the board can load the grid client-side.
Impact:
- Operators pick fixed_size ±N vs semantic@Boundary from existing Experiments.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Queries and Experiments must hit the Corpus Embedding Model's collections and optionally widen fixed_size context.
Changes:
- Resolve corpus model per request; apply Neighbor Expansion with Expansion Tree; persist and report expansion provenance.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Semantic strategies were silently falling back to fixed-count grouping when boundary embeds were missing.
Changes:
- Fail hard without aligned unit embeddings; orchestrator supplies Boundary embeds; Farsi-aware sentence split with line/paragraph fallback.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Different Embedding Models must not share Qdrant collections; Admin needs persisted role defaults and Experiment provenance.
Changes:
- Scope collection names by model id; add app_settings, embedding provenance columns, and queries.expansion_tree.
Impact:
- Process/query write only Model Corpus collections; legacy unscoped names are read-only for Admin labeling.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Operators need Cloud and Local Embedding Models with stable ids, dimensions, and defaults.
Changes:
- Add Embedding Model Registry; Ollama client; env defaults for model, Ollama host, and Neighbor Expansion knobs.
Impact:
- New installs default to text-embedding-3-large; OLLAMA_BASE_URL required for Local provider.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Make per-question strategy answers inspectable and show DOCX vs Text PDF source.
Changes:
- Side-by-side compare modal with HTML escaping; header source badge from filename.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Avoid a forked PDF UI while scoping Word vs PDF workflows.
Changes:
- formatFilter on shared tabs, PDF Workspace accordion tab, word-only defaults elsewhere.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Support Text PDFs in the same DocumentTree/markdown contract as DOCX.
Changes:
- PyMuPDF parser, text-layer gate, shared heading heuristics, upload dispatch for .pdf.
Impact:
- Scanned/image PDFs are rejected at upload; requires pymupdf installed.
Co-authored-by: Cursor <cursoragent@cursor.com>
Why:
- Need to track domain model, ADRs, task progress, and feature planning
Changes:
- CONTEXT.md: domain model with ADRs 0001-0014
- docs/tasks.md: updated task list with Phase 6 (Dashboard)
- docs/cant-do-yet.md: backend-ready but no UI features
- docs/out-of-scope-v1.md: intentionally excluded features
Impact:
- Project documentation centralized for reference
Why:
- Swagger UI is not user-friendly for non-technical users
- Need a proper web app for document management, querying, benchmarking, and administration
Changes:
- Babel-in-browser React dashboard with 5 tabs (Home, Documents, Query, Benchmarks, Admin)
- Dark blue theme matching benchmark report pages (#0F1419, #1A2332, #F59E0B)
- Comparison view for strategy analysis across documents
- Expandable experiment details with delete
- Admin panel with collapsible sections (Health, Qdrant, Chunk Preview, Questions, Cost Estimator)
- Document upload, processing, and strategy selection
- Query interface with chunk inspection
Impact:
- Dashboard served at /app/ via FastAPI StaticFiles
- All Swagger functionality available through web UI
Why:
- Users need to see each strategy's overall score at a glance in the report
- Technical report should show average metrics across all strategies
Changes:
- Each strategy card now shows its overall score below the metric bars
- Technical report aggregate table includes an AVERAGE row across all strategies
Impact:
- Managerial report: strategy cards now show overall score
- Technical report: aggregate table has a new AVERAGE row at the bottom
Why:
- Experiment list and detail responses showed raw IDs instead of filenames
- No way to delete experiments from the UI
Changes:
- Add document_filename field to ExperimentDetailResponse
- Enrich list endpoint with filenames and calculated best_strategy from aggregate_metrics
- Add DELETE /experiments/{id} endpoint
Impact:
- API responses now include document_filename for all experiment endpoints
- Frontend can display filenames instead of IDs
Why:
- Dashboard needs system health, Qdrant management, chunk preview, questions, and cost estimation endpoints
Changes:
- Add admin router with 11 endpoints (health, Qdrant CRUD, chunk preview, questions management, cost estimation)
- Add delete_experiment to SQLite storage
- Mount admin router and dashboard static files at /app
Impact:
- New /admin/* API routes available
- Dashboard served at /app/ via StaticFiles
Why:
- Need documentation for team onboarding and reference
- Need technical details for strategy implementations
- Need API reference for developers
Changes:
- README.md: Documentation index and quick start guide
- api-reference.md: All 10 endpoints with examples
- architecture.md: System structure and design decisions
- configuration.md: All environment variables and parameters
- data-flow.md: How data moves through the system
- evaluation-metrics.md: How scoring works with weights
- strategy-technical-details.md: Deep dive into each strategy's implementation
Why:
- Need visibility into API usage and performance
- Need to track request method, path, status, and duration
- Helps debugging production issues
Changes:
- Added RequestLoggingMiddleware class
- Logs at appropriate level (INFO/WARNING/ERROR)
- Non-invasive, no logic changes
Why:
- Need request/response models for benchmark endpoints
- Need routes for creating and retrieving benchmarks
- Need view parameter for managerial vs technical report views
Changes:
- models.py: Added BenchmarkRequest, BenchmarkResponse, StrategyMetrics, ExperimentDetailResponse
- routes.py: Added POST /benchmarks, GET /benchmarks/{id}, GET /experiments, view parameter for reports
Why:
- Need LLM-as-Judge evaluation for automated scoring
- Need benchmark orchestration to run questions × strategies
- Need HTML report generation with two views (managerial/technical)
Changes:
- evaluation.py: LLM-as-Judge scoring on 4 metrics (context, similarity, faithfulness, hallucination)
- benchmark_service.py: Orchestration with per-strategy failure isolation
- report.py: Dual-view HTML reports with dark mode, charts, and strategy cards
Why:
- Need structured logging for debugging query pipeline
- Need to mount benchmarking router
Changes:
- Added logging.basicConfig() with INFO level
- Mounted benchmarking router
- Registered QueryError exception handler
Why:
- Need to list documents to get document IDs for queries
- ProcessRequest should default to all 5 strategies
- paragraph_count should be optional (not always stored)
Changes:
- Added GET /documents endpoint with pagination
- Added DocumentListResponse model
- ProcessRequest now defaults to all 5 strategies
- DocumentResponse.paragraph_count now defaults to 0
Why:
- Qdrant was storing only metadata, not chunk text
- Queries returned empty text in retrieved chunks
- Scores were low (~0.25) because embeddings were on empty strings
Changes:
- Added 'text' field to ChunkMetadata model
- Updated chunk_to_metadata() to copy text
Why:
- Need implementation plan and task tracking documentation
- Need strategy explanations for reference
Changes:
- phases.md: 5-phase implementation plan with status tracking
- tasks.md: 25 tasks mapped to phases and steps
- chunking_strategies.md: detailed explanations of all 5 strategies
Why:
- App factory needs to mount document routes and initialize SQLite at startup
Changes:
- Import and mount documents_router
- Call init_db() on app creation
Why:
- Need abstract base class for all chunking strategies
- Need OpenAI embedding service (text-embedding-3-small)
- Need orchestration to run chunk → embed → store pipeline
Changes:
- Base: ChunkingStrategy ABC, token counting, chunk ID generation, sentence splitting
- Embedding: batch embedding with 2048 text limit per call
- Service: strategy registry, single/multi-strategy runners with per-strategy failure isolation
Why:
- Need to parse .docx/.doc files into DocumentTree + markdown
- Need API endpoints for document upload, processing, and deletion
Changes:
- Parser: .doc→.docx conversion via LibreOffice, XML-level extraction for table-heavy docs, heuristic heading detection
- Service: upload, process (delegates to chunking), delete orchestration
- Routes: POST /documents, POST /documents/{id}/process, DELETE /documents/{id}, GET /strategies
