Реалізація

Промпт для збірки для ШІ-агента: що саме реалізувати в підсистемі Knowledge, у якому порядку та за якими контрактами. Передай блок нижче агенту; розділи після нього — це референс, якого він має дотримуватися.

Ця сторінка — промпт для агента

У кожного розділу цих доків є сторінка Реалізація — точна, копійована постановка задачі, яку виконує агент. Спершу прочитай Огляд та LightRAG — вони джерело істини, на яке посилається цей промпт.

Промпт

РОЛЬ: Ти реалізуєш підсистему Knowledge в Agentfy.ai 2.0 (NestJS + Prisma + CleanSlice).

МЕТА: Дати кожному агенту власну запитувану базу знань — каталог магазину, документи та правила — на
бекенді LightRAG (graph-RAG), запущеному як ОКРЕМИЙ Python-сервіс. NestJS-слайс `agent/knowledge` —
ТОНКИЙ шлюз: CRUD баз знань і документів (метадані в Postgres), подача документів та проксіювання
видобутку. Ingestion/graph/query згортаються ВСЕРЕДИНІ LightRAG — це НЕ наші під-слайси. Агент дістає
видобуток ЧЕРЕЗ MCP (інструмент мозку), а не як частину мозку.

ПОСТАВКИ
1) Слайс `agent/knowledge` (api, L5) — структура CleanSlice:
   - domain/: IKnowledgeGateway (абстрактний — метадані KB/Document, на Prisma),
     IRagGateway (абстрактний — контракт LightRAG: insert/query/dropWorkspace),
     knowledge.service.ts (оркеструє обидва), knowledge.types.ts (IKnowledgeBaseData,
     IDocumentData, RetrievalModeTypes = naive|local|global|hybrid, DocumentStatusTypes), errors/.
   - data/: knowledge.gateway.ts (Prisma-реалізація IKnowledgeGateway),
     rag.gateway.ts (реалізація IRagGateway → делегує в LightRagRepository + RagMapper),
     lightRag.repository.ts (HTTP-клієнт, що обгортає API сервісу LightRAG — це РЕПОЗИТОРІЙ,
     а не Prisma-шлюз: він обгортає зовнішній SDK/API), knowledge.mapper.ts.
   - knowledge.prisma (KnowledgeBase, KnowledgeDocument), knowledge.controller.ts
     (@Controller('knowledge-bases'); Swagger operationId на кожному роуті для генерації SDK), dtos/.
2) Виставлення в MCP — видобуток як `@Tool` через `setup/mcp` (напр. knowledge_search). УВЕСЬ доступ
   до знань іде через MCP; `agent/knowledge` — єдиний, хто викликає LightRAG напряму. ДВА клієнти
   запитують один ендпоінт: МОЗОК (orchestrator, у процесі, у ході LLM-циклу) І WORKER (під час задачі,
   стукає в MCP-ендпоінт api зі своїм короткоживучим токеном сесії — без заходу через мозок). Обидва
   несуть той самий виведений на сервері workspace, тож ізоляція тримається для будь-якого клієнта.
3) Конвеєр завантаження — подача документа ставить бюджетовану задачу `ingestion` у `runtime/task`
   (BullMQ); консьюмер викликає insert у LightRAG і рухає KnowledgeDocument.status. НІКОЛИ не
   індексувати inline на шляху запиту. Інкрементально: переіндексувати лише змінені (дельти каталогу).
4) Деплой сервісу LightRAG — Helm-values для образу HKUDS `lightrag` на Postgres
   (pgvector + Apache AGE), пул екземплярів за ключем workspace. Узяти за основу чарт Ranch (див. референс).

КОНТРАКТИ: реалізуй саме ті рядки, енуми, клієнт-репозиторій і тип задачі, що в референсі нижче.
Дотримуйся конвенцій CleanSlice (gateway vs repository, абстрактні DI-токени з префіксом `I`, однинні
імена папок слайсів, енуми з суфіксом `Types`, camelCase DTO-файли, аліаси `#`, без `any` — `unknown` + guards).

БЕЗПЕКА (не обговорюється): workspace ЗАВЖДИ виводиться з автентифікованої команди/kb на боці api —
НІКОЛИ не приймай workspace від клієнта (порожній/підмінений = витік між тенантами). Workspace має бути
непорожнім. `api` — ЄДИНИЙ, хто викликає внутрішній сервіс LightRAG (мережева ізоляція, без публічного
ingress). Видалення KB зносить його workspace (delete-by-doc + drop графа AGE).

ПРИЙМАННЯ: див. чекліст унизу. Починай з обсягу v0.x MVP.

Референс — контракти для реалізації

Рядки бази знань і документа (Prisma, лише метадані)

Сам корпус живе в LightRAG; Postgres зберігає лише метадані + статус:

model KnowledgeBase {
  id        String   @id            // = `workspace` у LightRAG
  teamId    String                  // тенант; workspace виводиться з нього + id
  agentId   String?                 // null = база, спільна для команди
  name      String
  createdAt DateTime @default(now())
}

model KnowledgeDocument {
  id        String   @id
  baseId    String                  // → KnowledgeBase.id
  source    String                  // catalog | upload | url
  externalId String?                // напр. id товару OpenCart (для інкрементальної дельти)
  checksum  String?                 // пропустити переіндексацію, якщо не змінювалося
  status    String                  // pending | indexing | indexed | failed
  error     String?
  updatedAt DateTime @updatedAt
}

Режими видобутку

RetrievalModeTypes = naive | local | global | hybrid. Викликач (агент) обирає під запитання; дефолт hybrid. Дешеві запитання йдуть naive (чистий вектор) — ощадливий шлях з Огляду → масштабування.

MCP-клієнти — мозок і worker

Видобуток доступний лише через MCP (agent/knowledge виставляє @Tool через setup/mcp; api хостить ендпоінт). І мозок, і worker — клієнти:

Клієнт	Автентифікація	Шлях
Мозок (orchestrator)	у процесі	викликає MCP-інструмент напряму у ході LLM-циклу
Worker (руки)	короткоживучий токен сесії	стукає в MCP-ендпоінт api під час задачі; без заходу через мозок

Токен worker'а обмежує його його (agent, session), і api виводить workspace з нього — worker сам його не передає. Тож worker, запитуючи знання, отримує ту саму ізоляцію, що й мозок. (Це заміняє попередню нотатку «видобуток лише для мозку» з tool-split — видобуток через MCP відкритий обом; лише для мозку лишається матеріал секретів/KEK, який ніколи не потрапляє у worker.)

Репозиторій LightRAG (клієнт зовнішнього сервісу)

lightRag.repository.ts обгортає HTTP API LightRAG — у нього свої типи, він нічого не знає про домен і конвертується в доменні типи через RagMapper:

interface ILightRagRepository {
  insert(workspace: string, docs: RagDoc[]): Promise<void>;          // POST /insert
  query(workspace: string, q: string, mode: string): Promise<RagHit[]>; // POST /query
  dropWorkspace(workspace: string): Promise<void>;                   // знос KB
}

IRagGateway (domain) — абстрактний контракт; rag.gateway.ts (data) ловить помилки репозиторію/HTTP і конвертує їх у доменні помилки. workspace передає сервіс — виведений з автентифікованої KB, ніколи від клієнта.

Задача завантаження

ingestion (BullMQ, бюджетована): { baseId, documentIds[] } → консьюмер вантажить документи, викликає rag.insert(workspace, ...), рухає KnowledgeDocument.status, дотримується бюджету токенів на базу + ліміту швидкості. Живе в runtime/task; та сама підсистема черг, що у Worker.

Сервіс LightRAG (деплой)

HKUDS ghcr.io/hkuds/lightrag на Postgres pgvector + AGE, LIGHTRAG_{KV,VECTOR,GRAPH,DOC_STATUS}_STORAGE=PG*, зафіксована версія, фіксований EMBEDDING_DIM. Пул екземплярів за ключем workspace (лінива ініціалізація + витіснення за простоєм). Референс: cleanslice/ranch/k8s/platform/lightrag/* ~робочий — адаптуй його Helm-чарт/values. Див. LightRAG та GitOps.

Порядок задач

1. v0.x MVP — слайс agent/knowledge (CRUD KB/Document на Prisma) · LightRagRepository + IRagGateway (insert + query, hybrid) · MCP-інструмент knowledge_search · один workspace на KB. Задеплой сервіс LightRAG з чарта Ranch. Доводить створити базу → подати документ → агент запитує через MCP → заземлена відповідь.
2. + Асинхронне завантаження — перенести insert на задачу ingestion у BullMQ зі статусами; ніколи не inline.
3. + Інкрементально та бюджет — пропуск за checksum/externalId; бюджет токенів на базу + ліміт швидкості.
4. + Режими та дешевий шлях — виставити naive|local|global|hybrid; за замовчуванням дешево, граф де окупається.
5. + Життєвий цикл — видалення KB → dropWorkspace (delete-by-doc + drop графа AGE); прогрів/кеш при cold-start.

Критерії приймання

• [ ] Агент дістає заземлені факти зі своєї бази через MCP (knowledge_search), не вигадуючи.
• [ ] І мозок (у процесі), і запущений worker (через токен сесії) можуть запитувати базу через MCP з однаковою ізоляцією workspace.
• [ ] workspace виводиться на сервері з автентифікованої команди/kb; клієнт не може його задати.
• [ ] Один сервіс LightRAG обслуговує багато баз через екземпляри за workspace; без витоку між тенантами.
• [ ] Подача документа ставить задачу завантаження; шлях запиту не блокується на індексації.
• [ ] Незмінені документи (збігся checksum) пропускаються; переіндексуються лише дельти каталогу.
• [ ] LightRAG обгорнутий як Репозиторій (зовнішній API); agent/knowledge лишається тонким шлюзом.
• [ ] Видалення KB зносить його workspace (drop графа AGE); без осиротілих векторів/графа.

Дивіться також

• Огляд · LightRAG — джерело істини, на яке посилається промпт.
• Шари-слайси — де містяться agent/knowledge (L5) і runtime/task.
• Worker → Реалізація — споріднений промпт; та сама підсистема черг.
• Конвенції — gateway-vs-repository і правила CleanSlice, яких агент дотримується.
• Інфра → ресурси · GitOps — деплой сервісу LightRAG + Postgres.