Add document converter, seeder data structure, and project wiki
- ai-service/convert.py: converts Office/PDF files to markdown with frontmatter - database/seeders/data/: folder structure for themas, projects, documents, etc. - database/seeders/data/raw/: drop zone for Office/PDF files to convert - wiki/: project architecture, concepts, and knowledge graph documentation - Remove unused Laravel example tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
80
wiki/concepts/ai-integration.md
Normal file
80
wiki/concepts/ai-integration.md
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: AI Integration
|
||||
created: 2026-04-08
|
||||
updated: 2026-04-08
|
||||
status: speculative
|
||||
tags: [concept, ai, rag, langgraph, embeddings]
|
||||
sources: [ai-service/app/main.py, ai-service/requirements.txt, docker-compose.yml]
|
||||
---
|
||||
|
||||
# AI Integration
|
||||
|
||||
## Current State
|
||||
|
||||
The AI service is a **Python FastAPI stub** with placeholder endpoints. No actual AI processing is wired up yet.
|
||||
|
||||
### Implemented (stub only)
|
||||
|
||||
| Endpoint | Method | Status |
|
||||
|---|---|---|
|
||||
| `GET /health` | Health check | Working |
|
||||
| `POST /api/chat` | Chat with context | Stub — returns placeholder text |
|
||||
| `POST /api/summarize` | Generate summaries | Stub — returns placeholder text |
|
||||
| `POST /api/search` | Semantic search | Stub — returns empty results |
|
||||
|
||||
### Request/Response Models (Pydantic)
|
||||
|
||||
```
|
||||
ChatRequest: message, project_id?, conversation_history[]
|
||||
ChatResponse: reply, project_id?
|
||||
SummarizeRequest: content, project_id?, summary_type?
|
||||
SummarizeResponse: summary, project_id?
|
||||
SearchRequest: query, project_id?, limit?
|
||||
SearchResponse: results[{id, content, score, metadata}], query
|
||||
```
|
||||
|
||||
## Planned Architecture
|
||||
|
||||
```
|
||||
Laravel App ↔ HTTP ↔ Python AI-Service (FastAPI)
|
||||
├── LangGraph Orchestrator
|
||||
│ ├── Router / Classifier
|
||||
│ └── Agent graph (state machine)
|
||||
├── Anthropic Claude (LLM)
|
||||
├── pgvector (embeddings / similarity search)
|
||||
└── Tools:
|
||||
├── DB query (project data, commitments, phases)
|
||||
├── Document retrieval (semantic search)
|
||||
└── Embedding generation
|
||||
```
|
||||
|
||||
## RAG Pipeline (planned)
|
||||
|
||||
### Sources
|
||||
- Project descriptions and phase notes
|
||||
- Documents (uploaded files, meeting notes)
|
||||
- Lessons learned
|
||||
- Decisions and their rationale
|
||||
- Knowledge articles
|
||||
|
||||
### Embedding Strategy
|
||||
- **Storage**: pgvector extension on PostgreSQL 16
|
||||
- **Models**: Document and KennisArtikel already have `embedding` vector columns
|
||||
- **Update triggers**: On document create/update, on project phase change
|
||||
- **Chunking**: Per document type and size
|
||||
|
||||
### Agent Skills (from CLAUDE.md)
|
||||
| Agent | Autonomy | Purpose |
|
||||
|---|---|---|
|
||||
| Project Assistant | Low | Answer questions about specific projects |
|
||||
| Knowledge Assistant | Low | Search and surface knowledge articles |
|
||||
| Document Assistant | Medium | Summarize, compare, extract from documents |
|
||||
| System Tasks | High | Background indexing, embedding updates |
|
||||
|
||||
## Content Governance Rules
|
||||
|
||||
1. AI-generated content always labeled ("AI-suggestie", "Concept")
|
||||
2. Human confirmation required before AI content gains system status
|
||||
3. All AI interactions logged (request, response, tools used, sources cited)
|
||||
4. Source attribution mandatory in AI responses
|
||||
5. Confidence indicators when certainty is low
|
||||
76
wiki/concepts/innovation-lifecycle.md
Normal file
76
wiki/concepts/innovation-lifecycle.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Innovation Lifecycle
|
||||
created: 2026-04-08
|
||||
updated: 2026-04-08
|
||||
status: evolving
|
||||
tags: [concept, lifecycle, phases, governance]
|
||||
sources: [app/Enums/FaseType.php, app/Enums/ProjectStatus.php, app/Services/ProjectService.php]
|
||||
---
|
||||
|
||||
# Innovation Lifecycle
|
||||
|
||||
Every innovation project at the R&D lab follows a 9-phase lifecycle, from initial signal to final evaluation. The platform enforces this via `FaseType` and `ProjectStatus` enums with transactional phase transitions.
|
||||
|
||||
## Phases
|
||||
|
||||
```
|
||||
signaal → verkenning → concept → experiment → pilot → besluitvorming → overdracht_bouwen → overdracht_beheer → evaluatie
|
||||
```
|
||||
|
||||
| # | Phase | Dutch | Purpose |
|
||||
|---|---|---|---|
|
||||
| 1 | Signal | Signaal | Initial idea or observation captured |
|
||||
| 2 | Exploration | Verkenning | Research and feasibility assessment |
|
||||
| 3 | Concept | Concept | Design a proposed solution |
|
||||
| 4 | Experiment | Experiment | Small-scale test of the concept |
|
||||
| 5 | Pilot | Pilot | Larger-scale test in production environment |
|
||||
| 6 | Decision | Besluitvorming | Go/no-go decision by governance |
|
||||
| 7 | Handover to Build | Overdracht bouwen | Transfer to development/implementation team |
|
||||
| 8 | Handover to Operations | Overdracht beheer | Transfer to operational team for maintenance |
|
||||
| 9 | Evaluation | Evaluatie | Post-handover review and lessons learned |
|
||||
|
||||
## Special Statuses
|
||||
|
||||
These are Project-only statuses (not lifecycle phases):
|
||||
|
||||
| Status | Purpose |
|
||||
|---|---|
|
||||
| Geparkeerd | Temporarily halted — can resume later |
|
||||
| Gestopt | Permanently stopped — documented why |
|
||||
| Afgerond | Successfully completed the full lifecycle |
|
||||
|
||||
## Phase Transition Logic
|
||||
|
||||
Phase transitions go through `ProjectService::transitionPhase()` in a database transaction:
|
||||
|
||||
1. Close current active phase (set status → `afgerond`, set `einddatum`)
|
||||
2. Create new phase record (via `FaseType::tryFrom()` mapping)
|
||||
3. Update project status
|
||||
4. Write audit log entry with `from` and `to` states
|
||||
|
||||
Key constraint: `FaseType::tryFrom($newStatus->value)` — the first 9 ProjectStatus values map 1:1 to FaseType. Special statuses (geparkeerd, gestopt, afgerond) do not create new Fase records.
|
||||
|
||||
## Park and Stop
|
||||
|
||||
- **Park** (`ProjectService::park()`): closes active phase with reason in `opmerkingen`, sets status to `geparkeerd`
|
||||
- **Stop** (`ProjectService::stop()`): same mechanics, sets status to `gestopt`
|
||||
- Both log the transition reason in the audit trail
|
||||
|
||||
## Audit Trail
|
||||
|
||||
Every phase transition, park, or stop creates an `AuditLog` record:
|
||||
|
||||
```php
|
||||
AuditLog::create([
|
||||
'user_id' => Auth::id(),
|
||||
'action' => "project.phase_transition",
|
||||
'entity_type' => 'project',
|
||||
'entity_id' => $project->id,
|
||||
'payload' => ['from' => 'signaal', 'to' => 'verkenning'],
|
||||
]);
|
||||
```
|
||||
|
||||
## Metro Map Representation
|
||||
|
||||
- **Level 1**: Project status shown as station dot color (green=completed, cyan=active, yellow=parked, red=stopped)
|
||||
- **Level 2**: Each lifecycle phase is a station on the project's "lifecycle" line, with active phase highlighted
|
||||
Reference in New Issue
Block a user