# 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.