itpp-infrastructure/projects/scirium/docs/02-v1-scope.md

Scirium v1 Scope

Status: PLANNED Applies to: v1 (grounded cited Q&A only)

1. What v1 Ships

v1 is a read-only, grounded, cited question answering assistant. A staff member asks a question in chat. Scirium retrieves the relevant passages from that channel's scoped M365 document libraries and returns an answer with inline citations to the source documents.

v1 ships exactly one capability: grounded, cited Q&A. Nothing else.

Capability	In v1?	Notes
Grounded, cited Q&A	Yes	The core and only capability.
Read-only retrieval over scoped M365 libraries	Yes	SharePoint and OneDrive libraries named in the channel's scope.
Autonomous actions (send, write, create, update)	No	Zero. No writes to M365, no message posting beyond the answer, no integrations.
Report generation, content drafts, workflows	No	Deferred to v2 and later.
Patient records or PHI	No	Permanently out of scope, every version.

2. The v1 Contract

• Every answer cites its sources inline and in a Sources footer.
• If the answer is not in the knowledge base, Scirium says so instead of guessing.
• Scirium never writes to the source systems. The M365 connector holds read permission only.
• Every question and answer is logged for audit.

3. The 6-Step Message Flow

1. Staff post a question, either by @mentioning the agent in a channel or by DMing the bot.
2. Rocket.Chat fires an outgoing webhook to the orchestrator (channel path) or the bot listener delivers a DM event (DM path).
3. The orchestrator authenticates the request, then resolves tenant, channel, agent, and scope from the room and webhook path.
4. Retrieval: a pgvector semantic search over the channel's vector namespace returns candidate chunks, reranked to the top set. A below-threshold result falls back to Microsoft Graph search over the scope's libraries.
5. The orchestrator builds a prompt from the agent persona, the retrieved context with source markers, and the citation instruction, then calls admin-ai (DeepSeek V4 Pro primary with fallback).
6. The answer is posted back to Rocket.Chat as the agent bot, with inline citations and a Sources footer.

4. Retrieval Details

Step	Behavior
Primary	pgvector cosine search filtered by tenant_id and kb_scope_id in the same query.
Candidate set	Top 20 by score.
Rerank	Top 5 passed to the prompt.
Fallback	Below threshold or empty: Microsoft Graph /search/query over the scope's document_libraries.
Isolation	tenant_id and kb_scope_id filters are mandatory, so a chunk can never leak across channels or tenants.

5. Error Handling

Condition	v1 behavior
Retrieval empty or below threshold	Reply "I could not find an answer in the knowledge base for this question", no sources, never guess.
LLM timeout or error	Retry once on the fallback model, then a canned "could not reach the model" reply.
Channel has no agent or no scope	Configuration error reply (or silent no-op, per tenant config).
Webhook retry (duplicate)	Idempotency key deduplicates; the duplicate returns 200 and is dropped.
Post failure	Retry with backoff, then mark failed and surface a tenant alert.

6. Explicit v1 Exclusions

v1 does none of the following, and this is intentional:

• No actions. v1 cannot send email, create calendar items, update records, or write to any system.
• No writes to M365. The connector is read-only.
• No patient records or PHI, ever.
• No multi-domain answers. A channel answers only its own scope.
• No proactive messages. The bot replies only to a question addressed to it.
• No role escalation. An answer cannot grant itself new capabilities.

Everything on this list is either permanently excluded (PHI) or deferred to a later version behind the propose-approve-audit gate.