Product Requirements Document — BORIS / Buurts Ecosysteem¶
Status: concept — wijzigingen via Pull Request, merge alleen door architect (Niels Postma). Dit document is de canonieke waarheid voor alle agents, stakeholdercommunicatie en technische beslissingen.
Executive Summary¶
BORIS — Buurts Ondersteunend en Responsief Informatie Systeem — is een intelligent AI-ecosysteem voor professionals in het sociaal domein. Het biedt zeven gespecialiseerde AI-agents die integreren met Microsoft 365 en de dagelijkse werkpraktijk van zorgprofessionals bij Buurts ondersteunen.
Het systeem is ontworpen rond drie kernprincipes: veiligheid boven snelheid (ETHOS governance), mens als eindverantwoordelijke (Human-in-the-Loop niet-onderhandelbaar), en kennisbehoud als collectief goed (KWP-model).
Pilotstatus: Kenniswerkplaats Autisme goedgekeurd op 12 maart 2026. Investeringsbesluit: Q4 2026 voor volledige uitrol.
| Indicator | Waarde |
|---|---|
| Tijdsbesparing per professional | 30–45 minuten per dag |
| Kwaliteitswinst begeleidingsplannen | +15% bij peer review |
| Terugverdientijd na live-gang | ±7–9 maanden |
| ROI over 3 jaar | 290% |
| Break-even | 7–8 maanden |
1. Probleemstelling¶
Het sociaal domein staat onder structurele druk. Bij Buurts vertaalt dit zich in:
Handelingsverlegenheid — medewerkers werken op de grens van hun kennis bij complexe casuïstiek (autisme, GGZ, LVB, jeugd). Zonder directe toegang tot gevalideerde kennis leidt dit tot zorgmijding of verkeerde verwijzingen.
Kennisfragmentatie — expertise is verspreid over systemen, mappen en de hoofden van ervaren collega's. Bij uitval of vertrek verdwijnt organisatiekennis.
Hoge werkdruk bij triage — het triageproces is sterk afhankelijk van individuele expertise en mondelinge overdracht. Geen gestructureerde kennisondersteuning beschikbaar.
Variabele dossiervoering — kwaliteit van begeleidingsplannen en verslagen varieert sterk tussen medewerkers. Geen structurele feedbackloop.
Administratieve druk — gemiddeld 30–45 minuten per dag gaat verloren aan administratie die niet direct bijdraagt aan de cliënt.
2. Visie & Kernprincipe¶
"BORIS is niet een digitaal product dat naast het werk staat: het is een vakkundige partner, een kennishub, een coach, een schrijver en een spiegel in één — altijd beschikbaar, altijd gebonden aan de normen en waarden van het vak."
Het systeem werkt als een twee-lagenmodel:
- Kennislaag — vectordatabase met gevalideerde kennis per domein (autisme, GGZ, LVB, jeugd, inkomen, wonen, werk), georganiseerd in Kenniswerkplaatsen (KWP's)
- Agentlaag — zeven gespecialiseerde agents die de kennislaag bevragen en verwerken, elk met een eigen rol en ETHOS-gebonden gedragsregels
3. Doelgroepen¶
| Doelgroep | Rol | Primaire behoefte |
|---|---|---|
| Sociaal werkers (kerngroep) | Dagelijks gebruiker | Directe kennisondersteuning bij triage en begeleiding |
| Teamleiders / PL's | Proceseigenaar | Overzicht kenniskwaliteit, teamontwikkeling |
| ICT & data-analisten | Beheer & integratie | API-toegang, dataschema's, beheerinterface |
| Beleidsmedewerkers | Verantwoording | Compliance, privacy, rapportages gemeente |
| Bestuurders | Beslissing | ROI, risico's, strategische fit |
| Cliënten (indirect) | Begunstigde | Betere, consistentere begeleiding |
4. De Zeven Agents¶
| Agent | Naam | Rol | Status |
|---|---|---|---|
| A1 | VERA | Vakkundige assistent — triage, protocol, kennisraadpleging | Geïmplementeerd (basis) |
| A2 | LUMEN | Strategische trenddetectie voor management | Gepland |
| A3 | CLAIR | Compliance & privacybewaker (AVG, EU AI Act, beroepscode) | Gepland |
| A4 | SCOUT | RAG retrieval-agent — semantisch zoeken in kennislaag | Geïmplementeerd |
| A5 | CURATOR | Kwaliteitsfilter — valideert en rangschikte kennischunks | Geïmplementeerd |
| A6 | HERALD | Communicatie & projectmanagement — stakeholderdocumenten | Geïmplementeerd |
| A7 | SCRIPTOR | Narratief-bewaker — kennisdocumenten, consistentie, audittrail | Gepland (Sprint F) |
Aanvullend: INWONER-agent (publiekgerichte vraagbeantwoording) en LDF-ASSISTENT (real-time taalniveau-aanpassing) zijn in de architectuur voorzien maar nog niet geprioriteerd.
5. ETHOS Governance¶
ETHOS is de constitutionele governance-laag van 26 artikelen die elke interactie met BORIS regelt. Kernartikelen:
- Art. 5 — Hub als Guardian Layer: alle agentuitvoer passeert de Hub
- Art. 12 — Ethical Mirror: het systeem signaleert ethische spanningen actief
- Art. 18 — Human-in-the-Loop: geen autonome publicatie of actie zonder menselijke accordering
- Art. 22 — Privacyzonering: RED (PII), YELLOW (geanonimiseerd), GREEN (publiek) — fysiek gescheiden
De safety-implementatie in code: safety/policy.py, safety/gates.py, agents/curator.py (similarity gate), agents/hub.py (no-context gate, Sprint 2.2).
6. Tech Stack¶
| Laag | Technologie | Versie | Keuze-rationale |
|---|---|---|---|
| API | FastAPI + Uvicorn | 0.110.1 | Async, hoge performance, Python-native |
| Data validation | Pydantic v2 | 2.6.4 | Strikte typing, serialisatie, BaseSettings |
| Vector store (default) | ChromaDB | 0.5.23 | Embedded, geen infra-overhead voor pilot |
| Vector store (productie) | Weaviate | 1.27.6 | Multi-tenancy, schaalbaarheid voor meerdere KWPs |
| Embeddings | sentence-transformers | 2.6.1 | Lokaal, geen API-afhankelijkheid, meertalig |
| LLM (productie) | Ollama + llama3.2 | — | Lokaal, vendor-free, AVG-compliant |
| LLM (test) | MockSynthesizer | — | Deterministisch, geen model-download vereist |
| MCP Server | Python MCP SDK | 1.0.0 | Officieel Anthropic, zelfde stack |
| SharePoint | MSAL + Graph API | 1.28.0 | Microsoft 365 integratie via dual-connector |
| Documentatie | MkDocs Material | — | Statische site, GitHub Pages, nl-talig |
| CI/CD | GitHub Actions | — | pytest + ruff + bandit + pip-audit |
Vendor-free principes: Alle core-componenten zijn open-source en lokaal uitvoerbaar. Geen cloud-LLM verplicht voor productiegebruik.
7. Systeemarchitectuur¶
[Claude Desktop / Cowork / eigen interface]
↓ MCP protocol (stdio)
[Buurts MCP Server — mcp_server/]
tools: knowledge_search, knowledge_ask, ingest_document, list_library
↓ intern HTTP (BackendClient)
[FastAPI backend — main.py]
↓
[HubOrchestrator — agents/hub.py] ← Guardian Layer (Art. 5 ETHOS)
├─ ScoutAgent — semantisch zoeken
├─ CuratorAgent — kwaliteitsfilter (similarity ≥ 0.5, UDS volledig)
├─ OutputValidator — deterministisch: readability, grounding, anti-collapse
└─ Synthesizer — MockSynthesizer / OllamaSynthesizer (config-gestuurd)
↓
[Safety Policy — safety/policy.py] ← GREEN / YELLOW / RED
↓
[ZonedVectorStore] ← ChromaDB (pilot) of Weaviate (productie)
├─ RED — PII, nooit bevraagd zonder expliciete autorisatie
├─ YELLOW — geanonimiseerd, HITL verplicht bij output
└─ GREEN — publieke kennis, directe output toegestaan
↓
[SmartChunker] ← 400 woorden, 10% overlap, semantische grenzen
[DocumentRegistry] ← SQLite, ingest-tracking
[SharePointConnector] ← MockConnector / GraphAPIConnector
Sprint 2.2 toevoegingen:
- OutputValidator na Synthesizer: source ref check, Flesch-Douma readability, contradiction detection, anti-collapse check
- Truth Priority Boost in Scout: chunks uit docs/truth/ + bron_type=PROTOCOL krijgen 1.25× score-boost
- No-context gate in Hub: blokkeert synthese bij 0 goedgekeurde chunks
8. Kenniswerkplaatsen (KWP-model)¶
Een KWP is een gedeelde kennishub voor een specifiek domein of werkplek. Elk KWP heeft:
- Eigen Weaviate tenant (bij productie) of ChromaDB-partitie
- Eigen RED/YELLOW/GREEN zone-scheiding
- Eigen domein-ID prefix (bijv. AUT-xxx voor Autisme, GGZ-xxx voor GGZ)
- Eigen team van "kenniscuratoren" die content reviewen en accorderen
Actieve KWPs:
| KWP | Domein | Status | Productiedatum |
|---|---|---|---|
| KWP-Autisme | Autisme-spectrum | Pilot goedgekeurd 12-03-2026 | Q3 2026 |
| KWP-GGZ | Geestelijke gezondheidszorg | Gepland | Q4 2026 |
| KWP-LVB | Licht verstandelijke beperking | Gepland | Q1 2027 |
| KWP-Jeugd | Jeugdzorg | Gepland | Q1 2027 |
9. Data Contract — UDSMetadata V2¶
Het Universal Domain Schema (UDS) is het verplichte metadata-contract voor alle kennischunks. Elke chunk die in de vectorstore wordt opgeslagen, moet volledig aan dit schema voldoen.
class UDSMetadata(BaseModel):
# V1 — verplicht
domain_id: str # patroon: ^[A-Z]{2,6}-\d{3}$ (bijv. AUT-001)
knowledge_domain: KnowledgeDomain # autisme | ggz | lvb | jeugd | inkomen | wonen | werk | algemeen
severity_scale: int # 1–5 (urgentie van de kennis)
target_audience: TargetAudience # professional | client | management
source: str # bestandspad of URL van de bron
chunk_id: str # UUID-gebaseerd uniek ID
# V2 — Sprint A
zone: DataZone # RED | YELLOW | GREEN
ldf_level: int # 0–20 (LDF scholingsniveau)
des_level: int # 0–20 (DES zorginhoudelijk niveau)
bron_type: BronType # protocol | handreiking | praktijk | extern
zrm_dimensies: List[str] # Zelfredzaamheid-matrix dimensies
domein: str # vrije tekst, aanvullend op knowledge_domain
# Sprint 2.2 — anti-model-collapse
generation_source: GenerationSource # human | ai_generated | ai_reviewed | hybrid
generation_model: Optional[str] # bijv. "llama3.2" of "herald-v1.0"
original_source_ids: List[str] # bron-chunk IDs (bij AI_GENERATED)
Regel: Agents mogen nooit chunks met generation_source=AI_GENERATED als enige primaire bron gebruiken voor nieuwe output.
10. Kwaliteitsborging¶
| Mechanisme | Waar | Wat het borgt |
|---|---|---|
| Ruff linter | CI + lokaal | Codekwaliteit, imports, fouten |
| Bandit | CI | Beveiligingsrisico's (-ll: medium+) |
| pytest | CI | 321+ tests, asyncio, mocked Ollama |
| pip-audit | CI | Bekende kwetsbaarheden in dependencies |
| Curator (similarity ≥ 0.5) | Runtime | Lage-kwaliteit chunks worden verworpen |
| OutputValidator | Runtime | Readability, source grounding, contradictions |
| HITL (YELLOW zone) | Runtime | Gevoelige output altijd door mens gereviewd |
| Flesch-Douma score | Runtime | B1-norm gehandhaafd voor doelgroepen |
| Truth Priority Boost | Runtime | docs/truth/ content preferent bij retrieval |
11. Openstaande Besluiten¶
| # | Vraag | Blokkeert | Verwacht |
|---|---|---|---|
| OB-1 | Ollama lokaal vs. cloud LLM voor productie? | Live-gang | Q3 2026 |
| OB-2 | MCP host productie: eigen UI of Claude Desktop? | Sprint D | Q2 2026 |
| OB-3 | Weaviate multi-tenancy: per KWP of per zone? | KWP-uitrol | Q3 2026 |
| OB-4 | LDF-level als actieve retrieval-filter? | Sprint F | Q2 2026 |
| OB-5 | Ethical Mirror (Art. 12): in code of via prompt? | Sprint D | Q2 2026 |
| OB-6 | Formeel investeringsbesluit uitrol | Productie | Q4 2026 |
12. Roadmap op Hoofdlijnen¶
| Sprint | Inhoud | Status |
|---|---|---|
| 0–10, A–C | Kerninfrastructuur: RAG, zones, MCP, CI, safety | ✅ Afgerond |
| Sprint B | SharePoint dual-connector, 2 nieuwe MCP tools | ✅ Afgerond |
| Sprint E | HERALD agent (9 doelgroepen, C1-C5, 69 tests) | ✅ Afgerond |
| Sprint 2.1 | Weaviate backend (factory pattern, migratiescript) | ✅ Afgerond |
| Sprint 2.2 | OutputValidator, Flesch-Douma, Provenance tagging, Truth boost | ✅ Afgerond |
| Sprint F | Scriptor agent — narratief-bewaker kennisdocumenten | 🔵 Gepland |
| Sprint G | MkDocs publicatie, schrijfagent content pipeline | 🔵 Lopend |
| Sprint H | BNS Causal Engine sidecar (pgmpy + NetworkX) | ⏸ Geparkeerd |
| Sprint D | Zorgmedewerker UI (eigen interface) | ⏸ Later |
Beheer: Niels Postma (architect). Wijzigingen via PR, merge door architect. Bronnen: BORIS_Businesscase_v2.0.md, BORIS_Methodisch_Kader_v1.0.md, docs/ai/ARCHITECTURE.md