Buurts Ecosysteem — Projectvisie¶
Visie¶
Kennisinfrastructuur als "Operating System" over SharePoint heen, voor een zorgorganisatie in het sociaal domein. Zorgmedewerkers krijgen via een intelligente laag toegang tot domeinkennis (Autisme, GGZ, LVB, Jeugd etc.) met ingebouwde veiligheid en HITL-bewaking.
Einddoel¶
- Implementatie in een zorgorganisatie (niet ALSDAN)
- Kennislaag draait over bestaande SharePoint installatie
- Toegankelijk via MCP-compatibele interfaces
- Domeinoverstijgend: één systeem voor alle kennisdomeinen
Stack¶
- Python 3.11, FastAPI, ChromaDB (3 zones), Pydantic v2, pytest
- Ollama (lokale LLM), Python MCP SDK
- GitHub Actions (CI), trunk-based git
Repo¶
github.com/ALS-DAN/buurts-ecosysteem
Rolverdeling¶
- Niels = architect, productowner
- Claude = projectleider, auditor, reviewtool
- Claude Desktop = technische sessies (filesystem MCP)
- claude.ai = strategie, architectuur, lange gesprekken
Sessie-instructie¶
⚠️ Obsoleet since Sprint C — Claude Desktop laadt nu automatisch
CLAUDE.mdbij het openen van de project-map. Geen handmatige instructie meer nodig.~~Begin elke Claude Desktop sessie met: "Lees docs/ai/SPRINT.md en hervat als projectleider"~~
Nieuw: Open project-map → Claude heeft directe context via
CLAUDE.md.
Status per sprint¶
| Sprint | Doel | Status |
|---|---|---|
| 0 | Repo setup, CI, basis structuur | ✅ Groen |
| 1 | RAG pipeline, ChromaDB, SharePoint connector | ✅ Groen |
| 2 | CuratorAgent, MockSynthesizer, HubOrchestrator | ✅ Groen |
| 3 | /ask endpoint, end-to-end pipeline | ✅ Groen |
| 4A | /rag/ingest + /ask werkend e2e | ✅ Groen |
| 5 | DocumentRegistry (SQLite), persistent ChromaDB, DI refactor | ✅ Groen |
| 6 | Multimodal ingest: PDF, DOCX, URL, YouTube | ✅ Groen |
| 7 | Audio ingest (Whisper optioneel), 142/142 tests | ✅ Groen |
| 8 | OllamaSynthesizer (echte LLM), config-driven strategy | ✅ Groen |
| 9 | API hardening: auth, rate limiting, logging, health | ✅ Groen |
| 10 | MCP server — MVP met safety-blok en audit logging | ✅ Groen |
| A | UDS V2, SmartChunker, ZonedVectorStore (zones) | ✅ Groen — 321/321 tests |
| C | Claude Desktop finetune: CLAUDE.md, .mcp.json, .claude/ | ✅ Groen |
| B | SharePoint integratie, MCP tools uitbreiding | 🔵 Gepland (geblokkeerd #1+#2) |
Architectuurprincipes¶
- Bestaande code niet aanraken tenzij expliciet besloten
- Test-first — geen feature zonder test
- Plan-first bij complexe taken — akkoord vereist voor implementatie
- Één sprint tegelijk — geen scope creep
- MCP als toegangspoort — FastAPI blijft de kennislaag
- Safety-blok in elke MCP response — zone, hitl_required, may_present_answer
- Namespace-conventie — buurts_* prefix voor alle MCP tools
Sessie log¶
Sessie 4 — 14 maart 2026¶
Sprint C — Claude Desktop Finetune
Aanleiding: Crashcourse Claude Desktop/Cowork + analyse ChatGPT-rapport over CLAUDE.md setup.
Geïmplementeerd:
- CLAUDE.md aangemaakt (root): auto-load projectcontext, rolverdeling, 3 modi, module-map, anti-patronen
- .mcp.json aangemaakt: buurts MCP server automatisch verbonden
- .claude/settings.json aangemaakt: allowlist pytest/uvicorn/buurts-tools
- .gitignore uitgebreid: __pycache__/, *.pyc, buurts-env/
- README.md gefixed: broken code block + MCP instructies + badge + kennisdomeinen
- docs/ai/ARCHITECTURE.md bijgewerkt: Sprint C staat, ZonedVectorStore, data flow diagram, module-referentie
- docs/ai/SPRINT_C.md aangemaakt: sprint definitie en retrospectief
- docs/ai/SPRINT.md bijgewerkt: Sprint C ✅, Sprint B geblokkeerd
Resultaat: Handmatige sessie-initiatie volledig geëlimineerd.
Sessie 3 — 14 maart 2026¶
Sprint A — UDS V2 + SmartChunker + ZonedVectorStore
Geïmplementeerd:
- DataZone enum (RED/YELLOW/GREEN) en BronType enum in entities.py
- UDSMetadata uitgebreid met V2 velden: zone, ldf_level, zrm_dimensies, des_level, domein, bron_type
- RetrievalRequest uitgebreid: ldf_level, zone filter
- CausalInferenceResult placeholder model (BNS Causal Engine)
- SmartChunker: semantisch chunken met alinea→koptekst→zin→woord fallback, 10% overlap
- get_chunker() factory op basis van config.CHUNK_STRATEGY
- ZonedVectorStore: drie geïsoleerde ChromaDB collections (red/yellow/green)
- scripts/migrate_uds_v2.py: dry-run migratiescript legacy → ZonedVectorStore
- 39 nieuwe tests — totaal 321/321 groen
- PR #3 gemerged naar main
Beslissingen genomen:
- Zone-routing op chunk-niveau (metadata.zone bepaalt ChromaDB collection)
- RED-zone isolatie: nooit bevraagd zonder expliciete zone=RED parameter
- SmartChunker als default strategy (CHUNK_STRATEGY="smart")
- EphemeralClient UUID-suffix fix voor test-isolatie
Sessie 2 — 10 maart 2026¶
Sprint 10 — MCP server MVP
Besloten:
- Namespace-conventie: buurts_knowledge_* (forward-compatible voor VERA/LUMEN/CLAIR)
- Safety-blok standaard in elke MCP response (GREEN/YELLOW/RED)
- RED zone: antwoord wordt niet getoond, alleen doorverwijzing
- Error responses altijd YELLOW zone (voorzichtigheidsprincipe)
- Audit logging per MCP aanroep
Geïmplementeerd: - mcp_server/ package (server.py, backend_client.py, tools.py) - 18 nieuwe tests, alle groen
Openstaande beslissingen¶
| # | Beslissing | Status |
|---|---|---|
| 1 | SharePoint connector: productie-klaar of nog mock? | ❓ Open — blokkeert Sprint B |
| 2 | MCP host voor productie: eigen Python agent of UI framework? | ❓ Open — blokkeert Sprint B/D |
| 3 | Ollama: lokaal draaien of cloud LLM voor productie? | ❓ Open — blokkeert Sprint D |
| 4 | LDF-level als metadata-veld toevoegen aan chunks? | ❓ Open — Sprint B |
| 5 | Ethical Mirror: implementatie in code of alleen via Claude prompt? | ❓ Open — Sprint D |