83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
# 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 versioned Markdown files under `knowledge/procedures/` (currently eleven per supported
|
|
language) are the authoritative sources. Keep their IDs, versions and effective dates as
|
|
metadata.
|
|
|
|
## Index statistics and provenance
|
|
|
|
`GET /api/v1/knowledge/status` keeps three different measurements separate:
|
|
|
|
- `source_document_count`: authoritative procedure files available to Fleet Ops for the requested language;
|
|
- `reported_synced_document_count`, `reported_failed_document_count` and `last_sync_at`: the latest persisted result reported by the central n8n synchronization workflow;
|
|
- `document_count`: documents independently verified as indexed by the active provider.
|
|
|
|
The current RAGcore contract deliberately has no corpus-size or space-browse endpoint. For
|
|
the RAGcore provider, `document_count` therefore remains `null`; a successful upload report
|
|
is never relabelled as proof that indexing and publishing completed. The deterministic demo
|
|
provider can verify its in-memory corpus and reports `statistics_state=verified`. RAGcore
|
|
reports `sync_reported` only when a persisted workflow callback exists, otherwise
|
|
`not_reported`.
|
|
|
|
## 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.
|