Scope

This document is a grounded inventory of the current AI assistant and RAG foundation already present in this repository as of Sprint inventory review. It describes code and documentation truth, not aspirational architecture.

Executive Verdict

The repo already contains the beginnings of a real AI-native assistant stack, but it is not yet a broad general assistant.

What is already real:

• a user-facing assistant UI in apps/web
• a working /api/ai/ask backend route
• a docs-backed RAG retrieval path
• a real AI gateway package with model registry and audit logging
• a real conversation memory package
• a strong domain knowledge substrate in Butkhuzi norms search/suggest/chunk search

What is not yet true:

• a generalized multi-source assistant that combines docs, norms, evidence, audit history, and operational data in one retrieval pipeline
• a persistent vector store for assistant knowledge
• a broad domain assistant that can ground answers across the whole platform
• a mature operational-memory retrieval layer

The current implementation is best described as:

• implemented assistant surface
• implemented docs RAG foundation
• implemented Butkhuzi norms retrieval foundation
• partial memory/audit foundation
• fragmented broader assistant architecture

Current Assistant Architecture

The most concrete current assistant path is:

1. web UI sends a prompt to /api/ai/ask
2. the route classifies intent
3. the route loads docs RAG runtime from apps/web/lib/docsRagBootstrap.ts
4. the route retrieves matches from the docs vector store
5. the route optionally loads recent founder-chat memory
6. the route produces a deterministic answer via answerPositioningQuestion(...)
7. the route records audit output and optionally persists chat messages

Important truth:

• the current user-facing answer path is not primarily model-generated
• the OpenAI gateway is implemented, but in the current route it is used for metrics/observability support rather than as the main answer producer
• the assistant is therefore real, but narrow and controlled

Inventory

| Item | Location | Verified | State | Surface Type | Current Truth | | --- | --- | --- | --- | --- | --- | | Assistant chat widget and drawer | apps/web/src/components/ai/* and apps/web/src/ui/components/ActionRail.tsx | VERIFIED | IMPLEMENTED | PRODUCT SURFACE | Real user-facing assistant UI is mounted in the product shell. | | AI ask endpoint | apps/web/src/app/api/ai/ask/route.ts | VERIFIED | IMPLEMENTED | INFRA SURFACE / PRODUCT SURFACE | Real assistant backend route with intent classification, docs retrieval, memory access, answer assembly, and audit logging. | | AI status endpoint | apps/web/src/app/api/ai/status/route.ts | VERIFIED | IMPLEMENTED | INFRA SURFACE | Exposes docs RAG provider, document count, chunk count, and embedding mode. | | AI audit endpoints | apps/web/src/app/api/ai/audit/* | VERIFIED | IMPLEMENTED | INFRA SURFACE | Admin-visible AI audit read and verification surface exists. | | AI gateway and model registry | packages/ai-layer/src/gateway/* | VERIFIED | IMPLEMENTED | INFRA SURFACE | Real OpenAI request path, allowlist, rate limiting, token/cost tracking, and model registry. | | Current answer engine | packages/ai-layer/src/assistants/positioning/answer.ts | VERIFIED | IMPLEMENTED | INFRA SURFACE | Deterministic evidence-based responder, not a broad tool-using assistant. | | Intent classifier | packages/ai-layer/src/intent/classifier.ts | VERIFIED | IMPLEMENTED | INFRA SURFACE | Real classifier for greeting, governance, strategic, unknown. | | Docs RAG bootstrap | apps/web/lib/docsRagBootstrap.ts | VERIFIED | IMPLEMENTED | INFRA SURFACE | Loads docs, chunks them, embeds them, and serves retrieval from an in-memory vector store. | | RAG pipeline primitives | packages/ai-layer/src/rag/* | VERIFIED | IMPLEMENTED | INFRA SURFACE | Chunking, embeddings, vector store, retrieval filters, citations, ranking helpers. | | Conversation memory storage | packages/memory-layer/* | VERIFIED | IMPLEMENTED | INFRA SURFACE | Real DB-backed founder chat sessions/messages persistence. | | Memory retrieval/ranking beyond recency | packages/memory-layer/* | VERIFIED | PARTIAL | INFRA SURFACE | Recent-message recall exists, but richer semantic or long-horizon memory retrieval is not present. | | Repo/code context provider | packages/ai-layer/src/code/* | VERIFIED | PARTIAL | INFRA SURFACE | Interfaces/helpers exist, but no verified product path uses them as a real assistant repo-context layer. | | Butkhuzi norms retrieval | services/svc-butkhuzi/*, services/api/src/routes/butkhuzi.ts, apps/web/src/portal/api.ts | VERIFIED | IMPLEMENTED | KNOWLEDGE SURFACE | Strong domain corpus with list, suggest, chunk search, upsert, rebuild. | | Butkhuzi product consumption | apps/web/src/app/[locale]/(portal)/kes/page.tsx, apps/web/src/app/snip-manual/page.tsx | VERIFIED | IMPLEMENTED | PRODUCT SURFACE / KNOWLEDGE SURFACE | Norms and chunk search are already consumed in real product workflows. | | Document registry | apps/web/src/lib/docs/documentRegistry.ts | VERIFIED | IMPLEMENTED | KNOWLEDGE SURFACE | Structured document catalog with metadata suitable for retrieval and filtering. | | Document manifest metadata | docs/_manifest/* | VERIFIED | IMPLEMENTED | KNOWLEDGE SURFACE / DOC-ONLY | Rich structured metadata for procedures, tags, audiences, governance links. | | Governance docs portal | apps/web/src/components/docs/DocsPortalPage.tsx | VERIFIED | IMPLEMENTED | PRODUCT SURFACE / KNOWLEDGE SURFACE | Docs are already rendered, filtered, role-scoped, and acknowledged in product UI. | | Document access log | apps/web/src/lib/docs/documentAccessLog.ts | VERIFIED | IMPLEMENTED | KNOWLEDGE SURFACE / INFRA SURFACE | Read/acknowledgement history exists, but not yet integrated as assistant retrieval context. | | AI governance policy source | docs/10_normative/KVARY_AI_* | VERIFIED | IMPLEMENTED | DOC-ONLY / KNOWLEDGE SURFACE | Clear policy and audit/memory guardrails exist and are queryable through docs RAG. | | Evidence storage | services/svc-tenders/src/evidenceStorage.ts and web evidence APIs | VERIFIED | IMPLEMENTED | KNOWLEDGE SURFACE / INFRA SURFACE | Evidence objects exist operationally, but assistant-oriented indexing/retrieval is not yet implemented. | | KES traceability UI | apps/web/src/features/kesTrace/* | VERIFIED | PARTIAL | UI-ONLY / KNOWLEDGE SURFACE | Traceability surface exists, but current data is generated/fixture-like rather than a verified assistant knowledge backend. | | Event history as assistant source | services/*/kafka/*, event docs | VERIFIED | PARTIAL | KNOWLEDGE SURFACE / INFRA SURFACE | Real event backbone exists, but no general assistant retrieval interface over it was verified. | | Embeddings-backed persistent knowledge store | repo-wide | VERIFIED | MISSING | INFRA SURFACE | Embeddings exist, but no generalized persistent vector DB or cross-domain assistant retrieval store was verified. |

What Domains Are Already Usable As Assistant Knowledge Sources

Strongest usable sources now

1. Management-system documentation and governance content

Current status:

• already queryable
• already chunked for assistant retrieval
• already structured by registry and manifests

Why it is strong:

• the docs portal already treats documents as managed product content
• document metadata already includes category, role visibility, status, and governance relationships
• AI governance, audit, memory, architecture, and procedure docs are already accessible through the docs RAG runtime

This is currently the most mature assistant-ready corpus in the repo.

2. Butkhuzi norms corpus

Current status:

• already queryable
• already product-consumed
• already supports search, suggest, and chunk retrieval

Why it is strong:

• it is a real domain knowledge service with structured persistence
• it already exposes routes suited to assistant grounding
• the repo explicitly documents chunk/RAG support as intended for semantic search and assistant UX

This is currently the strongest non-doc domain knowledge source for an assistant.

Usable but less mature sources

3. AI audit history

Current status:

• partially queryable

Why:

• the audit log and verification chain are implemented
• there are read endpoints
• but this is governance/traceability support, not yet an assistant retrieval substrate for general user answers

4. Document access / acknowledgement history

Current status:

• partially queryable

Why:

• view and acknowledgement entries are structured
• they could support “who has seen what” or operational memory prompts later
• no verified assistant flow uses this as retrieval context today

5. Evidence and declarations

Current status:

• partially queryable

Why:

• evidence storage and evidence API paths exist
• but there is no verified assistant-oriented indexing, chunking, or ranking pipeline over evidence bodies or attachments

6. Structured operational service data

Current status:

• partially queryable

Why:

• many services expose structured APIs
• some of that data could support assistant answers
• but there is no unified assistant retrieval layer across service data today

Present conceptually but not yet assistant-ready

7. Event-derived history and operational memory

Current status:

• only conceptually present for assistant use

Why:

• the platform has event-driven architecture, outbox, consumers, DLQ, and audit traces
• but no verified assistant-facing retrieval abstraction over that history was found

8. Generic long-term assistant memory

Current status:

• partially implemented foundation, but missing as a mature assistant feature

Why:

• founder chat persistence exists
• there is no verified semantic memory retrieval, memory summarization, or domain-aware memory grounding path

Implemented vs Implied vs Missing

Clearly implemented

• assistant UI in apps/web
• /api/ai/ask
• docs RAG bootstrap and retrieval
• AI gateway package and model registry
• AI audit chain and admin audit endpoints
• memory session/message persistence
• document registry and document manifests
• Butkhuzi norms list/suggest/search/rebuild/upsert surfaces

Only partial or fragmented

• model-based answer generation as the primary user-facing answer path
• multi-source retrieval across docs plus norms plus evidence plus operational data
• assistant memory beyond recent founder chat recall
• event-history retrieval for assistant use
• evidence retrieval/indexing for assistant use
• traceability as a trustworthy assistant knowledge source

Clearly missing

• generalized persistent vector store across assistant knowledge domains
• unified source-ranking and source-fusion layer for multiple corpora
• broad assistant orchestration across service data, norms, docs, evidence, and event history
• a verified assistant architecture that can ground answers across the full operating system of the platform

Current Assistant Direction

Based on code truth, the platform is not “fully AI-native” yet, but it is no longer at zero.

The current direction is best described as:

• docs-RAG-ready
• Butkhuzi-norms-ready
• memory-enabled in a narrow founder-chat sense
• audit-governed
• still fragmented as a general assistant platform

The repo already has enough real pieces to justify assistant development, but the right framing is not “generic chatbot.” The right framing is a grounded knowledge assistant built from:

• management-system docs and governance procedures
• Butkhuzi norms and semantic chunk search
• selected structured operational context
• explicit policy/audit controls

Most Realistic Next Practical Development Direction

Primary recommendation

Build the next assistant step as a multi-source retrieval hardening pass centered on docs plus Butkhuzi, not as a generic new chat UI.

Concretely, the strongest next move is:

1. keep the current assistant surface
2. extend retrieval orchestration so /api/ai/ask can query both:
   • docs RAG runtime
   • Butkhuzi norms/chunk search
3. return source-labeled evidence and citations from both corpora
4. keep audit and policy controls as they are
5. only after that widen into evidence or operational data

Why this is strongest:

• the UI already exists
• the docs RAG path already exists
• Butkhuzi already provides the strongest structured domain knowledge surface
• the repo already signals that Butkhuzi chunk search is for semantic search and assistant UX
• this avoids inventing a broad AI platform before the actual sources are normalized

Secondary recommendation

If the team wants a narrower first product slice, build a management-system documentation assistant first.

That would lean on:

• document registry
• docs manifests
• governance procedures
• AI governance policies
• document access and acknowledgement metadata

This is lower risk than broad assistant work and could become the cleanest production-grade assistant slice quickly.

What should not be the next move

• not generic LLM chat polish without source expansion
• not a full event-history assistant yet
• not evidence-first RAG before evidence indexing exists
• not pretending the current answer path is already a mature autonomous assistant

Bottom Line

The repo already contains a real assistant foundation. It is strongest today in two knowledge areas:

• managed platform/governance documentation
• Butkhuzi norms and chunk search

The next practical direction should therefore be a grounded docs + Butkhuzi retrieval assistant with source-aware citations, not a broad speculative AI rewrite.