Loading module
Resolving locale, route permissions, and workspace projection.
AI Assistant Current State
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
READ 2026-03-28T23:42:21.903Z
READ 2026-03-29T04:52:41.869Z
CORE STRICT SAFE DELETE AFTER RERUN REPORT
PUBLIC | DRAFT | v1.0.0
READ 2026-03-29T03:13:33.020Z
a persistent vector store for assistant knowledgea broad domain assistant that can ground answers across the whole platforma mature operational-memory retrieval layerThe 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:
- web UI sends a prompt to
/api/ai/ask
- the route classifies intent
- the route loads docs RAG runtime from
apps/web/lib/docsRagBootstrap.ts
- the route retrieves matches from the docs vector store
- the route optionally loads recent founder-chat memory
- the route produces a deterministic answer via
answerPositioningQuestion(...)
- the route records audit output and optionally persists chat messages
- 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
- already queryable
- already chunked for assistant retrieval
- already structured by registry and manifests
- 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
- already queryable
- already product-consumed
- already supports search, suggest, and chunk retrieval
- 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
- 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
- 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
- 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
- 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
- only conceptually present for assistant use
- 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
- partially implemented foundation, but missing as a mature assistant feature
- 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:
- keep the current assistant surface
- extend retrieval orchestration so
/api/ai/ask can query both:
- docs RAG runtime
- Butkhuzi norms/chunk search
- return source-labeled evidence and citations from both corpora
- keep audit and policy controls as they are
- only after that widen into evidence or operational data
- 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.
- 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.