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

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

{
  "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.

3.5 KiB Raw Blame History