Initial MobilityOps build pack (docs, contracts, scaffold)

2026-08-01 20:34:43 +02:00
commit 24188d9b10
71 changed files with 3412 additions and 0 deletions
@@ -0,0 +1,65 @@
+# RAGcore integration
+
+## Objective
+
+Use the existing central RAGcore project. MobilityOps must not implement embeddings, vector storage, chunking or its own answer-generation pipeline.
+
+## Namespace
+
+- tenant: `northstar-mobility-demo`
+- workspace: `mobilityops`
+- collection: `internal-procedures`
+
+These values are configurable.
+
+## Source documents
+
+The ten Markdown files under `knowledge/procedures/` are authoritative PoC sources. Keep their IDs, versions and effective dates as metadata.
+
+## Required adapter interface
+
+```python
+class KnowledgeProvider(Protocol):
+    async def health(self) -> KnowledgeHealth: ...
+    async def ask(self, question: str, actor: ActorContext) -> GroundedAnswer: ...
+    async def sync_manifest(self, documents: list[KnowledgeDocumentRef]) -> SyncResult: ...
+```
+
+Implement:
+
+- `RAGcoreKnowledgeProvider`;
+- `DemoKnowledgeProvider` using deterministic keyword/BM25-style local source retrieval only.
+
+The demo provider is a resilience/test adapter, not a second RAG platform. It must return extracted source passages and a template summary; it must not pretend to be generative AI.
+
+## Answer contract
+
+```json
+{
+  "answer": "...",
+  "evidence_state": "grounded | insufficient | unavailable",
+  "sources": [
+    {
+      "document_id": "damage-procedure",
+      "title": "Damage handling procedure",
+      "version": "1.3",
+      "section": "2. Immediate actions",
+      "excerpt": "..."
+    }
+  ],
+  "provider": "ragcore",
+  "correlation_id": "..."
+}
+```
+
+## Safety
+
+- send actor scope and tenant/workspace with each request;
+- enforce source allow-list for this PoC;
+- never fall back to general model knowledge silently;
+- no customer PII is indexed in RAGcore;
+- log question metadata and source IDs, not unnecessary full prompts.
+
+## Degraded mode
+
+When RAGcore is unreachable, return `unavailable` and keep all operational functions available. When evidence is weak, return `insufficient` with the best source matches and no fabricated procedure.