docs(H): H-DOC — API documentation updated with Phase H Knowledge endpoints (wiki, sources, evidence, extraction, lifecycle, ask, review)

2026-08-18 23:20:20 +02:00
parent a6e593dc40
commit 240a49321d
1 changed files with 45 additions and 0 deletions
@@ -720,3 +720,48 @@ HTTP and webhook steps block:

 ### Automated-Decision Guard (G-HUMAN-DEC)
 Workflow steps with `ai_use_case_metadata` containing `risk_level >= medium` or `requires_approval: true` or `auto_execute: false` require human approval before execution. High-risk actions (send_email, delete_entity, execute_payment, etc.) require review even at low risk levels.
+
+---
+
+## Phase H — Knowledge Endpoints
+
+### Wiki (H-WIKI, H-VER, H-LINK)
+| Method | Path | Description | Permission |
+|--------|------|-------------|-----------|
+| GET | `/api/v1/wiki/articles` | List articles (paginated, filterable) | `wiki:read` |
+| POST | `/api/v1/wiki/articles` | Create article | `wiki:write` |
+| GET | `/api/v1/wiki/articles/{id}` | Get article by ID | `wiki:read` |
+| PATCH | `/api/v1/wiki/articles/{id}` | Update article (creates version) | `wiki:write` |
+| DELETE | `/api/v1/wiki/articles/{id}` | Delete article (soft-delete) | `wiki:delete` |
+| GET | `/api/v1/wiki/articles/{id}/versions` | List article versions | `wiki:read` |
+| POST | `/api/v1/wiki/articles/{id}/versions/{version}/restore` | Restore article to version | `wiki:write` |
+| GET | `/api/v1/wiki/categories` | List categories | `wiki:read` |
+| POST | `/api/v1/wiki/categories` | Create category | `wiki:write` |
+
+### Knowledge Sources (H-SRC)
+4 source types: `wiki`, `dms`, `mail`, `communication`. Each provides content for RAG indexing via `fetch_source_content()`.
+
+### Evidence References (H-CITE)
+RAG/Knowledge results include structured `EvidenceReference` objects with:
+- `source_type`, `source_id`, `title`, `url` (deep link)
+- `snippet`, `confidence`, `metadata`
+- `to_workstream_block()` for Communication display
+
+### Knowledge Extraction (H-EXT, H-ENT, H-AUTO, H-CONF)
+- `extract_knowledge()`: LLM-based entity and relationship extraction
+- `auto_create_relationships()`: Creates high-confidence relationships in GraphRAG
+- Confidence threshold: 0.6 (low-confidence → review queue)
+- Entity types: person, company, project, location, date, other
+- Relationship types: works_for, related_to, has_email, part_of, etc.
+
+### Knowledge Lifecycle (H-EVT, H-DATA-LIFE, H-RET)
+- **Event triggers**: `mail.received`, `dms.file_uploaded`, `wiki.article_published`, `communication.message_created`
+- **Derived-data lifecycle**: Source deletion/correction propagates to graph relationships and agent memory
+- **Retention policy**: wiki=unlimited, dms=365d, mail=180d, communication=90d
+- **Cleanup**: ARQ cron job removes expired knowledge
+
+### Ask Knowledge (H-ASK)
+RAG queries with evidence cards via workstream. Returns answer + evidence references + workstream blocks.
+
+### Review Queue (H-REV)
+Low-confidence extracted relationships pending human review. Approve boosts confidence to 0.8, reject deletes.