90 lines
3.5 KiB
Markdown
90 lines
3.5 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 RAGcore contract deliberately has no corpus-size or space-browse endpoint. It does
|
|
provide an exact identity lookup through `GET /v1/documents?source_id=...&external_id=...`.
|
|
Fleet Ops uses that documented read contract concurrently and with bounded per-request
|
|
timeouts for every managed source in the requested language. A document counts only when
|
|
RAGcore returns exactly one active document in the configured space with a published active
|
|
version. RAGcore's `content_sha256` represents its canonical parsed artifact rather than
|
|
the uploaded source bytes, so Fleet Ops deliberately does not compare that provider-owned
|
|
hash with its raw Markdown hash. Results are cached
|
|
for five minutes. This produces an independently verified `document_count` without changing
|
|
RAGcore or relabelling an upload/sync report as index evidence. If exact verification is
|
|
temporarily unavailable, `document_count` remains `null` and the sync report stays visibly
|
|
separate. Both the deterministic provider and a successful exact RAGcore check report
|
|
`statistics_state=verified`.
|
|
|
|
## 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.
|