Knowledge bases

4.7 Knowledge Bases

Kroov supports internal knowledge bases backed by PostgreSQL pgvector (and durable object storage: Azure Blob or GCS). Azure AI Search remains available as a provider KbBackend.

Runtime requirements: PostgreSQL + vector extension, KnowledgeBase:Internal:Enabled, embedding provider (Azure/Gemini with SupportsEmbeddings), storage provider configured. Otherwise KB admin APIs return 503.

Admin CRUD — KnowledgeBasesController (api/knowledge-bases) — AdminOnly

Method	Path	Purpose
GET	/api/knowledge-bases?projectId=	List
GET	/api/knowledge-bases/{id}	Detail
POST	/api/knowledge-bases	Create
PUT	/api/knowledge-bases/{id}	Update
DELETE	/api/knowledge-bases/{id}	Delete base + storage + chunks
PUT	/api/knowledge-bases/{id}/projects	Share with additional projects { "projectIds": [1,2] }
GET	/api/knowledge-bases/{id}/documents?page&pageSize&search&status	List documents
POST	/api/knowledge-bases/{id}/documents	Upload (multipart, field files) — pdf/docx/xlsx/xls/csv/txt
POST	/api/knowledge-bases/{id}/documents/{documentId}/reindex	Reindex
GET	/api/knowledge-bases/{id}/documents/{documentId}/content	Download original
DELETE	/api/knowledge-bases/{id}/documents/{documentId}	Delete document

Create / update body:

{
  "projectId": 1,
  "name": "Team Protocols",
  "embeddingProviderId": 3,
  "embeddingModel": "text-embedding-3-small",
  "chunkSize": 1000,
  "chunkOverlap": 100,
  "isActive": true
}

Document lifecycle: Pending → Extracting → Embedding → Indexed (or failed with error; reindex supported). Ingestion uses FOR UPDATE SKIP LOCKED leases across API replicas.

Upload example:

curl -X POST https://your-kroov-host/api/knowledge-bases/3/documents \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -F "files=@protocol.pdf" \
  -F "files=@checklist.docx"

Project picker — ProjectKnowledgeBasesController

Method	Path	Auth	Purpose
GET	/api/projects/{projectId}/knowledge-bases	JWT (project access)	Read-only list of own + shared bases for chat/agent UI

Using knowledge in inference

1. KnowledgeBase provider — create a provider of type KnowledgeBase with KbBackend=Internal and internalKnowledgeBaseId; query it like any other provider.
2. Chat grounding — on POST /api/ai/chat, pass knowledgeBaseIds: […] with a normal text model; retrieved chunks are injected as server context with [ref_id:N] citation markers.
3. Embeddings API — POST /v1/embeddings for the same embedding pipeline.
4. Scheduled tasks / sessions — pass allow-listed knowledgeBaseIds so knowledge_base_search may only search those bases (empty list = no restriction).

Blob URLs in citations are opened via /api/ai/download-blob or /api/ai/view-blob with the API key.

---