Skip to content

Commit 83b27be

Browse files
docs: complete v6.0 PostgreSQL Backend milestone
- Move 34 v6.0 requirements from Active to Validated in PROJECT.md - Update context section with v6.0 stats (675 tests, 73% coverage) - Add v6.0 key decisions (protocol abstraction, pgvector, async SQLAlchemy, RRF) - Mark v6.0 milestone as shipped in ROADMAP.md - All 10 phases (5-10) executed, verified, and UAT-approved Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 0846039 commit 83b27be

File tree

2 files changed

+54
-22
lines changed

2 files changed

+54
-22
lines changed

.planning/PROJECT.md

Lines changed: 51 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -56,20 +56,44 @@ Agent Brain is a local-first RAG (Retrieval-Augmented Generation) service that i
5656
-**TEST-05**: Provider health check endpoint — v3.0 (Feature 124)
5757
-**TEST-06**: Verified provider configuration documentation — v3.0 (Feature 124)
5858

59-
### Active
60-
61-
**Current Milestone: v6.0 PostgreSQL Backend**
59+
-**STOR-01**: Storage abstraction protocol (11 methods) — v6.0
60+
-**STOR-02**: Backend factory with env/YAML/default selection — v6.0
61+
-**STOR-03**: ChromaDB backend wraps existing vector_store/bm25_manager — v6.0
62+
-**STOR-04**: Contract tests for backend protocol compliance — v6.0
63+
-**STOR-05**: Legacy parameter backward compatibility — v6.0
64+
-**PGVEC-01**: pgvector extension for vector similarity search — v6.0
65+
-**PGVEC-02**: Cosine, L2, inner product distance metrics — v6.0
66+
-**PGVEC-03**: HNSW index with configurable m/ef_construction — v6.0
67+
-**PGVEC-04**: Embedding dimension validation — v6.0
68+
-**PGFTS-01**: tsvector full-text search with GIN index — v6.0
69+
-**PGFTS-02**: Weighted relevance (A/B/C) for title/summary/content — v6.0
70+
-**PGFTS-03**: Configurable language for stemming — v6.0
71+
-**PGFTS-04**: RRF hybrid fusion for vector + keyword results — v6.0
72+
-**INFRA-01**: Docker Compose for pgvector:pg16 development setup — v6.0
73+
-**INFRA-02**: Async connection pooling with SQLAlchemy — v6.0
74+
-**INFRA-03**: `/health/postgres` endpoint with pool metrics — v6.0
75+
-**INFRA-04**: Auto schema initialization on backend startup — v6.0
76+
-**INFRA-05**: Poetry extras for optional PostgreSQL dependencies — v6.0
77+
-**CONF-01**: YAML storage.backend + storage.postgres configuration — v6.0
78+
-**CONF-02**: Connection params (host, port, pool size, HNSW) — v6.0
79+
-**CONF-03**: DATABASE_URL env var override — v6.0
80+
-**V6TEST-01**: Contract tests with pytest markers + skip-without-DB — v6.0
81+
-**V6TEST-02**: CI PostgreSQL service container in GitHub Actions — v6.0
82+
-**V6TEST-03**: Backend wiring smoke tests (mock-based) — v6.0
83+
-**V6TEST-04**: Service-level PostgreSQL E2E tests — v6.0
84+
-**PLUG-01**: `/agent-brain-config` command for backend selection — v6.0
85+
-**PLUG-02**: YAML generation for PostgreSQL config — v6.0
86+
-**PLUG-03**: `/agent-brain-setup` with Docker detection — v6.0
87+
-**PLUG-04**: PostgreSQL error pattern recognition in setup agent — v6.0
88+
-**PLUG-05**: docker-compose.postgres.yml template — v6.0
89+
-**PLUG-06**: Plugin version bump to v5.0.0 — v6.0
90+
-**DOCS-01**: PostgreSQL setup guide — v6.0
91+
-**DOCS-02**: Full configuration reference — v6.0
92+
-**DOCS-03**: ChromaDB vs PostgreSQL performance tradeoffs guide — v6.0
6293

63-
**Goal:** Add PostgreSQL as a configurable storage backend with pgvector for vector search and tsvector for full-text search, running alongside ChromaDB as a dual-backend architecture.
94+
### Active
6495

65-
**Target features:**
66-
- Storage backend abstraction layer (ChromaDB default, PostgreSQL optional)
67-
- pgvector for vector similarity search
68-
- tsvector for full-text search (replaces BM25 when using PostgreSQL)
69-
- Hybrid retrieval (RRF fusion) works with PostgreSQL backend
70-
- Backend selection via YAML provider config
71-
- Docker Compose for local PostgreSQL + pgvector development setup
72-
- E2E tests for PostgreSQL backend
96+
No active milestone. Next: v7.0+ (AWS Bedrock / Vertex AI providers).
7397

7498
### Out of Scope
7599

@@ -85,17 +109,19 @@ Agent Brain is a local-first RAG (Retrieval-Augmented Generation) service that i
85109

86110
## Context
87111

88-
**Current State (v3.0 shipped 2026-02-10):**
89-
- 12,858 LOC server Python + 13,171 LOC tests
90-
- 505 tests passing, 70% coverage
112+
**Current State (v6.0 completed 2026-02-13):**
113+
- ~3,200 lines PostgreSQL backend code across 12+ files
114+
- 675 tests passing (153 PostgreSQL-specific), 73% server coverage
115+
- Dual-backend architecture: ChromaDB (default) + PostgreSQL (optional)
116+
- pgvector for vector search, tsvector for full-text search
91117
- 7 embedding/summarization/reranking providers supported
92-
- Full GraphRAG with schema-based entity types
93-
- CI with provider matrix testing
118+
- Full GraphRAG with schema-based entity types (ChromaDB only)
119+
- CI with provider matrix testing + PostgreSQL service container
94120

95121
**Technology Stack:**
96122
- Python 3.10+ with Poetry packaging
97123
- FastAPI + Uvicorn server
98-
- ChromaDB vector store
124+
- ChromaDB vector store (default) + PostgreSQL/pgvector (optional)
99125
- LlamaIndex for document processing
100126
- Pluggable providers: OpenAI, Anthropic, Ollama, Cohere, Gemini, Grok, SentenceTransformers
101127

@@ -129,6 +155,12 @@ Agent Brain is a local-first RAG (Retrieval-Augmented Generation) service that i
129155
| JSONL job queue over Redis | Local-first, no external dependencies | ✓ Good |
130156
| Minimal FastAPI app for health endpoint tests | Avoids ChromaDB initialization in test environment | ✓ Good |
131157
| CI matrix with conditional API key checks | Tests skip gracefully, config tests always run | ✓ Good |
158+
| StorageBackendProtocol abstraction | Clean separation, contract-testable, dual-backend support | ✓ Good |
159+
| pgvector + tsvector over BM25 for PostgreSQL | Native DB features, no separate index files, better scaling | ✓ Good |
160+
| Async SQLAlchemy for PostgreSQL connections | Non-blocking I/O, connection pooling built-in | ✓ Good |
161+
| RRF fusion for PostgreSQL hybrid search | Same algorithm as ChromaDB, consistent cross-backend behavior | ✓ Good |
162+
| GraphRAG stays ChromaDB-only | Avoids complexity, deferred to future milestone | ✓ Good |
163+
| Conditional ChromaDB init in main.py lifespan | PostgreSQL backend skips ChromaDB setup entirely | ✓ Good |
132164

133165
---
134-
*Last updated: 2026-02-12 after v6.0 milestone started*
166+
*Last updated: 2026-02-13 after v6.0 milestone completed*

.planning/ROADMAP.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
## Milestones
77

88
-**v3.0 Advanced RAG** — Phases 1-4 (shipped 2026-02-10)
9-
- 🚧 **v6.0 PostgreSQL Backend** — Phases 5-10 (gap closure in progress)
9+
- **v6.0 PostgreSQL Backend** — Phases 5-10 (shipped 2026-02-13)
1010

1111
## Phases
1212

@@ -22,7 +22,7 @@
2222

2323
</details>
2424

25-
### 🚧 v6.0 PostgreSQL Backend (Gap Closure)
25+
### v6.0 PostgreSQL Backend — SHIPPED 2026-02-13
2626

2727
**Milestone Goal:** Add PostgreSQL as a configurable storage backend with pgvector for vector search and tsvector for full-text search, running alongside ChromaDB as a dual-backend architecture.
2828

@@ -190,4 +190,4 @@ Feature 101: AST-aware code ingestion, code summaries
190190

191191
---
192192
*Roadmap created: 2026-02-07*
193-
*Last updated: 2026-02-13 — Phase 10 planned (1 plan)*
193+
*Last updated: 2026-02-13 — v6.0 milestone completed (all 10 phases shipped)*

0 commit comments

Comments
 (0)