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