feat: add Vision Encoder service + Vision RAG implementation
- Vision Encoder Service (OpenCLIP ViT-L/14, GPU-accelerated)
- FastAPI app with text/image embedding endpoints (768-dim)
- Docker support with NVIDIA GPU runtime
- Port 8001, health checks, model info API
- Qdrant Vector Database integration
- Port 6333/6334 (HTTP/gRPC)
- Image embeddings storage (768-dim, Cosine distance)
- Auto collection creation
- Vision RAG implementation
- VisionEncoderClient (Python client for API)
- Image Search module (text-to-image, image-to-image)
- Vision RAG routing in DAGI Router (mode: image_search)
- VisionEncoderProvider integration
- Documentation (5000+ lines)
- SYSTEM-INVENTORY.md - Complete system inventory
- VISION-ENCODER-STATUS.md - Service status
- VISION-RAG-IMPLEMENTATION.md - Implementation details
- vision_encoder_deployment_task.md - Deployment checklist
- services/vision-encoder/README.md - Deployment guide
- Updated WARP.md, INFRASTRUCTURE.md, Jupyter Notebook
- Testing
- test-vision-encoder.sh - Smoke tests (6 tests)
- Unit tests for client, image search, routing
- Services: 17 total (added Vision Encoder + Qdrant)
- AI Models: 3 (qwen3:8b, OpenCLIP ViT-L/14, BAAI/bge-m3)
- GPU Services: 2 (Vision Encoder, Ollama)
- VRAM Usage: ~10 GB (concurrent)
Status: Production Ready ✅
This commit is contained in:
Apple
@@ -43,7 +43,7 @@ DAARION використовує **3-5 вузлів JetStream кластеру**
|
||||
|
||||
## 3. Event Categories Overview
|
||||
|
||||
Уся система складається з 13 груп подій:
|
||||
Уся система складається з 14 груп подій:
|
||||
|
||||
1. **agent.run.***
|
||||
2. **chat.message.***
|
||||
@@ -58,6 +58,7 @@ DAARION використовує **3-5 вузлів JetStream кластеру**
|
||||
11. **governance.***
|
||||
12. **usage.***
|
||||
13. **telemetry.***
|
||||
14. **rag.***
|
||||
|
||||
Кожна категорія має окремий JetStream "stream".
|
||||
|
||||
@@ -436,6 +437,121 @@ Payload:
|
||||
|
||||
---
|
||||
|
||||
### 8.14 STREAM_RAG
|
||||
|
||||
#### Subjects:
|
||||
|
||||
- `parser.document.parsed`
|
||||
- `rag.document.ingested`
|
||||
- `rag.document.indexed`
|
||||
|
||||
#### Payloads
|
||||
|
||||
**parser.document.parsed**
|
||||
|
||||
```json
|
||||
{
|
||||
"event_id": "evt_abc",
|
||||
"ts": "2025-11-17T10:45:00Z",
|
||||
"domain": "parser",
|
||||
"type": "parser.document.parsed",
|
||||
"version": 1,
|
||||
"actor": {
|
||||
"id": "parser-service",
|
||||
"kind": "service"
|
||||
},
|
||||
"payload": {
|
||||
"doc_id": "doc_123",
|
||||
"team_id": "t_555",
|
||||
"dao_id": "dao_greenfood",
|
||||
"doc_type": "pdf|image",
|
||||
"pages_count": 5,
|
||||
"parsed_jpumped": true,
|
||||
"indexed": true,
|
||||
"visibility": "public",
|
||||
"metadata": {
|
||||
"title": "Sample Document",
|
||||
"size_bytes": 12345,
|
||||
"parsing_time_ms": 2340
|
||||
}
|
||||
},
|
||||
"meta": {
|
||||
"team_id": "t_555",
|
||||
"trace_id": "trace_abc",
|
||||
"span_id": "span_def"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**rag.document.ingested**
|
||||
|
||||
```json
|
||||
{
|
||||
"event_id": "evt_def",
|
||||
"ts": "2025-11-17T10:46:00Z",
|
||||
"domain": "rag",
|
||||
"type": "rag.document.ingested",
|
||||
"version": 1,
|
||||
"actor": {
|
||||
"id": "rag-service",
|
||||
"kind": "service"
|
||||
},
|
||||
"payload": {
|
||||
"doc_id": "doc_123",
|
||||
"team_id": "t_555",
|
||||
"dao_id": "dao_greenfood",
|
||||
"chunk_count": 12,
|
||||
"indexed": true,
|
||||
"visibility": "public",
|
||||
"metadata": {
|
||||
"ingestion_time_ms": 3134,
|
||||
"embed_model": "bge-m3@v1"
|
||||
}
|
||||
},
|
||||
"meta": {
|
||||
"team_id": "t_555",
|
||||
"trace_id": "trace_def",
|
||||
"span_id": "span_ghi"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**rag.document.indexed**
|
||||
|
||||
```json
|
||||
{
|
||||
"event_id": "evt_ghi",
|
||||
"ts": "2025-11-17T10:47:00Z",
|
||||
"domain": "rag",
|
||||
"type": "rag.document.indexed",
|
||||
"version": 1,
|
||||
"actor": {
|
||||
"id": "rag-ingest-worker",
|
||||
"kind": "service"
|
||||
},
|
||||
"payload": {
|
||||
"doc_id": "doc_123",
|
||||
"team_id": "t_555",
|
||||
"dao_id": "dao_greenfood",
|
||||
"chunk_ids": ["c_001", "c_002", "c_003"],
|
||||
"indexed": true,
|
||||
"visibility": "public",
|
||||
"metadata": {
|
||||
"indexing_time_ms": 127,
|
||||
"milvus_collection": "documents_v1",
|
||||
"neo4j_nodes_created": 12
|
||||
}
|
||||
},
|
||||
"meta": {
|
||||
"team_id": "t_555",
|
||||
"trace_id": "trace_ghi",
|
||||
"span_id": "span_jkl"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Retention Policies
|
||||
|
||||
### Agent, Chat, Project, Task
|
||||
@@ -481,6 +597,7 @@ storage: file
|
||||
| STREAM_GOVERNANCE | PDP, audit |
|
||||
| STREAM_USAGE | quota service |
|
||||
| STREAM_CHAT | search-indexer |
|
||||
| STREAM_RAG | rag-service, parser-service, search-indexer |
|
||||
|
||||
---
|
||||
|
||||
|
||||
419
docs/cursor/channel_agnostic_doc_flow_task.md
Normal file
419
docs/cursor/channel_agnostic_doc_flow_task.md
Normal file
@@ -0,0 +1,419 @@
|
||||
# Task: Channel-agnostic document workflow (PDF + RAG)
|
||||
|
||||
## Goal
|
||||
|
||||
Make the document (PDF) parsing + RAG workflow **channel-agnostic**, so it can be reused by:
|
||||
|
||||
- Telegram bots (DAARWIZZ, Helion)
|
||||
- Web applications
|
||||
- Mobile apps
|
||||
- Any other client via HTTP API
|
||||
|
||||
This task defines a shared `doc_service`, HTTP endpoints for non-Telegram clients, and integration of Telegram handlers with this shared layer.
|
||||
|
||||
> NOTE: If this task is re-run on a repo where it is already implemented, it should be treated as a validation/refinement task. Existing structures (services, endpoints) SHOULD NOT be removed, only improved if necessary.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
### Existing components (expected state)
|
||||
|
||||
- Repo root: `microdao-daarion/`
|
||||
- Gateway service: `gateway-bot/`
|
||||
|
||||
Key files:
|
||||
|
||||
- `gateway-bot/http_api.py`
|
||||
- Telegram handlers for DAARWIZZ (`/telegram/webhook`) and Helion (`/helion/telegram/webhook`).
|
||||
- Voice → STT flow (Whisper via `STT_SERVICE_URL`).
|
||||
- Discord handler.
|
||||
- Helper functions: `get_telegram_file_path`, `send_telegram_message`.
|
||||
|
||||
- `gateway-bot/memory_client.py`
|
||||
- `MemoryClient` with methods:
|
||||
- `get_context`, `save_chat_turn`, `create_dialog_summary`, `upsert_fact`.
|
||||
|
||||
- `gateway-bot/app.py`
|
||||
- FastAPI app, includes `http_api.router` as `gateway_router`.
|
||||
- CORS configuration.
|
||||
|
||||
Router + parser (already implemented in router project):
|
||||
|
||||
- DAGI Router supports:
|
||||
- `mode: "doc_parse"` with provider `parser` → OCRProvider → `parser-service` (DotsOCR).
|
||||
- `mode: "rag_query"` for RAG questions.
|
||||
- `parser-service` is available at `http://parser-service:9400`.
|
||||
|
||||
The goal of this task is to:
|
||||
|
||||
1. Add **channel-agnostic** document service into `gateway-bot`.
|
||||
2. Add `/api/doc/*` HTTP endpoints for web/mobile.
|
||||
3. Refactor Telegram handlers to use this service for PDF, `/ingest`, and RAG follow-ups.
|
||||
4. Store document context in Memory Service via `fact_key = "doc_context:{session_id}"`.
|
||||
|
||||
---
|
||||
|
||||
## Changes to implement
|
||||
|
||||
### 1. Create service: `gateway-bot/services/doc_service.py`
|
||||
|
||||
Create a new directory and file:
|
||||
|
||||
- `gateway-bot/services/__init__.py`
|
||||
- `gateway-bot/services/doc_service.py`
|
||||
|
||||
#### 1.1. Pydantic models
|
||||
|
||||
Define models:
|
||||
|
||||
- `QAItem` — single Q&A pair
|
||||
- `ParsedResult` — result of document parsing
|
||||
- `IngestResult` — result of ingestion into RAG
|
||||
- `QAResult` — result of RAG query about a document
|
||||
- `DocContext` — stored document context
|
||||
|
||||
Example fields (can be extended as needed):
|
||||
|
||||
- `QAItem`: `question: str`, `answer: str`
|
||||
- `ParsedResult`:
|
||||
- `success: bool`
|
||||
- `doc_id: Optional[str]`
|
||||
- `qa_pairs: Optional[List[QAItem]]`
|
||||
- `markdown: Optional[str]`
|
||||
- `chunks_meta: Optional[Dict[str, Any]]` (e.g., `{"count": int, "chunks": [...]}`)
|
||||
- `raw: Optional[Dict[str, Any]]` (full payload from router)
|
||||
- `error: Optional[str]`
|
||||
- `IngestResult`:
|
||||
- `success: bool`
|
||||
- `doc_id: Optional[str]`
|
||||
- `ingested_chunks: int`
|
||||
- `status: str`
|
||||
- `error: Optional[str]`
|
||||
- `QAResult`:
|
||||
- `success: bool`
|
||||
- `answer: Optional[str]`
|
||||
- `doc_id: Optional[str]`
|
||||
- `sources: Optional[List[Dict[str, Any]]]`
|
||||
- `error: Optional[str]`
|
||||
- `DocContext`:
|
||||
- `doc_id: str`
|
||||
- `dao_id: Optional[str]`
|
||||
- `user_id: Optional[str]`
|
||||
- `doc_url: Optional[str]`
|
||||
- `file_name: Optional[str]`
|
||||
- `saved_at: Optional[str]`
|
||||
|
||||
#### 1.2. DocumentService class
|
||||
|
||||
Implement `DocumentService` using `router_client.send_to_router` and `memory_client`:
|
||||
|
||||
Methods:
|
||||
|
||||
- `async def save_doc_context(session_id, doc_id, doc_url=None, file_name=None, dao_id=None) -> bool`
|
||||
- Uses `memory_client.upsert_fact` with:
|
||||
- `fact_key = f"doc_context:{session_id}"`
|
||||
- `fact_value_json = {"doc_id", "doc_url", "file_name", "dao_id", "saved_at"}`.
|
||||
- Extract `user_id` from `session_id` (e.g., `telegram:123` → `user_id="123"`).
|
||||
|
||||
- `async def get_doc_context(session_id) -> Optional[DocContext]`
|
||||
- Uses `memory_client.get_fact(user_id, fact_key)`.
|
||||
- If `fact_value_json` exists, return `DocContext(**fact_value_json)`.
|
||||
|
||||
- `async def parse_document(session_id, doc_url, file_name, dao_id, user_id, output_mode="qa_pairs", metadata=None) -> ParsedResult`
|
||||
- Builds router request:
|
||||
- `mode: "doc_parse"`
|
||||
- `agent: "parser"`
|
||||
- `metadata`: includes `source` (derived from session_id), `dao_id`, `user_id`, `session_id` and optional metadata.
|
||||
- `payload`: includes `doc_url`, `file_name`, `output_mode`, `dao_id`, `user_id`.
|
||||
- Calls `send_to_router`.
|
||||
- On success:
|
||||
- Extract `doc_id` from response.
|
||||
- Call `save_doc_context`.
|
||||
- Map `qa_pairs`, `markdown`, `chunks` into `ParsedResult`.
|
||||
|
||||
- `async def ingest_document(session_id, doc_id=None, doc_url=None, file_name=None, dao_id=None, user_id=None) -> IngestResult`
|
||||
- If `doc_id` is `None`, load from `get_doc_context`.
|
||||
- Build router request with `mode: "doc_parse"`, `payload.output_mode="chunks"`, `payload.ingest=True` and `doc_url` / `doc_id`.
|
||||
- Return `IngestResult` with `ingested_chunks` based on `chunks` length.
|
||||
|
||||
- `async def ask_about_document(session_id, question, doc_id=None, dao_id=None, user_id=None) -> QAResult`
|
||||
- If `doc_id` is `None`, load from `get_doc_context`.
|
||||
- Build router request with `mode: "rag_query"` and `payload` containing `question`, `dao_id`, `user_id`, `doc_id`.
|
||||
- Return `QAResult` with `answer` and optional `sources`.
|
||||
|
||||
Provide small helper method:
|
||||
|
||||
- `_extract_source(session_id: str) -> str` → returns first segment before `:` (e.g. `"telegram"`, `"web"`).
|
||||
|
||||
At bottom of the file, export convenience functions:
|
||||
|
||||
- `doc_service = DocumentService()`
|
||||
- Top-level async wrappers:
|
||||
- `parse_document(...)`, `ingest_document(...)`, `ask_about_document(...)`, `save_doc_context(...)`, `get_doc_context(...)`.
|
||||
|
||||
> IMPORTANT: No Telegram-specific logic (emoji, message length, `/ingest` hints) in this file.
|
||||
|
||||
---
|
||||
|
||||
### 2. Extend MemoryClient: `gateway-bot/memory_client.py`
|
||||
|
||||
Add method:
|
||||
|
||||
```python
|
||||
async def get_fact(self, user_id: str, fact_key: str, team_id: Optional[str] = None) -> Optional[Dict[str, Any]]:
|
||||
"""Get single fact by key"""
|
||||
```
|
||||
|
||||
- Use Memory Service HTTP API, e.g.:
|
||||
- `GET {base_url}/facts/{fact_key}` with `user_id` and optional `team_id` in query params.
|
||||
- Return `response.json()` on 200, else `None`.
|
||||
|
||||
This method will be used by `doc_service.get_doc_context`.
|
||||
|
||||
Do **not** change existing public methods.
|
||||
|
||||
---
|
||||
|
||||
### 3. HTTP API for web/mobile: `gateway-bot/http_api_doc.py`
|
||||
|
||||
Create `gateway-bot/http_api_doc.py` with:
|
||||
|
||||
- `APIRouter()` named `router`.
|
||||
- Import from `services.doc_service`:
|
||||
- `parse_document`, `ingest_document`, `ask_about_document`, `get_doc_context`, and models.
|
||||
|
||||
Endpoints:
|
||||
|
||||
1. `POST /api/doc/parse`
|
||||
|
||||
Request (JSON body, Pydantic model `ParseDocumentRequest`):
|
||||
|
||||
- `session_id: str`
|
||||
- `doc_url: str`
|
||||
- `file_name: str`
|
||||
- `dao_id: str`
|
||||
- `user_id: str`
|
||||
- `output_mode: str = "qa_pairs"`
|
||||
- `metadata: Optional[Dict[str, Any]]`
|
||||
|
||||
Behaviour:
|
||||
|
||||
- Call `parse_document(...)` from doc_service.
|
||||
- On failure → `HTTPException(status_code=400, detail=result.error)`.
|
||||
- On success → JSON with `doc_id`, `qa_pairs` (as list of dict), `markdown`, `chunks_meta`, `raw`.
|
||||
|
||||
2. `POST /api/doc/ingest`
|
||||
|
||||
Request (`IngestDocumentRequest`):
|
||||
|
||||
- `session_id: str`
|
||||
- `doc_id: Optional[str]`
|
||||
- `doc_url: Optional[str]`
|
||||
- `file_name: Optional[str]`
|
||||
- `dao_id: Optional[str]`
|
||||
- `user_id: Optional[str]`
|
||||
|
||||
Behaviour:
|
||||
|
||||
- If `doc_id` is missing, use `get_doc_context(session_id)`.
|
||||
- Call `ingest_document(...)`.
|
||||
- Return `doc_id`, `ingested_chunks`, `status`.
|
||||
|
||||
3. `POST /api/doc/ask`
|
||||
|
||||
Request (`AskDocumentRequest`):
|
||||
|
||||
- `session_id: str`
|
||||
- `question: str`
|
||||
- `doc_id: Optional[str]`
|
||||
- `dao_id: Optional[str]`
|
||||
- `user_id: Optional[str]`
|
||||
|
||||
Behaviour:
|
||||
|
||||
- If `doc_id` is missing, use `get_doc_context(session_id)`.
|
||||
- Call `ask_about_document(...)`.
|
||||
- Return `answer`, `doc_id`, and `sources` (if any).
|
||||
|
||||
4. `GET /api/doc/context/{session_id}`
|
||||
|
||||
Behaviour:
|
||||
|
||||
- Use `get_doc_context(session_id)`.
|
||||
- If missing → 404.
|
||||
- Else return `doc_id`, `dao_id`, `user_id`, `doc_url`, `file_name`, `saved_at`.
|
||||
|
||||
Optional: `POST /api/doc/parse/upload` stub for future file-upload handling (currently can return 501 with note to use `doc_url`).
|
||||
|
||||
---
|
||||
|
||||
### 4. Wire API into app: `gateway-bot/app.py`
|
||||
|
||||
Update `app.py`:
|
||||
|
||||
- Import both routers:
|
||||
|
||||
```python
|
||||
from http_api import router as gateway_router
|
||||
from http_api_doc import router as doc_router
|
||||
```
|
||||
|
||||
- Include them:
|
||||
|
||||
```python
|
||||
app.include_router(gateway_router, prefix="", tags=["gateway"])
|
||||
app.include_router(doc_router, prefix="", tags=["docs"])
|
||||
```
|
||||
|
||||
- Update root endpoint `/` to list new endpoints:
|
||||
|
||||
- `"POST /api/doc/parse"`
|
||||
- `"POST /api/doc/ingest"`
|
||||
- `"POST /api/doc/ask"`
|
||||
- `"GET /api/doc/context/{session_id}"`
|
||||
|
||||
---
|
||||
|
||||
### 5. Refactor Telegram handlers: `gateway-bot/http_api.py`
|
||||
|
||||
Update `http_api.py` so Telegram uses `doc_service` for PDF/ingest/RAG, keeping existing chat/voice flows.
|
||||
|
||||
#### 5.1. Imports and constants
|
||||
|
||||
- Add imports:
|
||||
|
||||
```python
|
||||
from services.doc_service import (
|
||||
parse_document,
|
||||
ingest_document,
|
||||
ask_about_document,
|
||||
get_doc_context,
|
||||
)
|
||||
```
|
||||
|
||||
- Define Telegram length limits:
|
||||
|
||||
```python
|
||||
TELEGRAM_MAX_MESSAGE_LENGTH = 4096
|
||||
TELEGRAM_SAFE_LENGTH = 3500
|
||||
```
|
||||
|
||||
#### 5.2. DAARWIZZ `/telegram/webhook`
|
||||
|
||||
Inside `telegram_webhook`:
|
||||
|
||||
1. **/ingest command**
|
||||
|
||||
- Check `text` from message: if starts with `/ingest`:
|
||||
- `session_id = f"telegram:{chat_id}"`.
|
||||
- If message also contains a PDF document:
|
||||
- Use `get_telegram_file_path(file_id)` and correct bot token to build `file_url`.
|
||||
- `await send_telegram_message(chat_id, "📥 Імпортую документ у RAG...")`.
|
||||
- Call `ingest_document(session_id, doc_url=file_url, file_name=file_name, dao_id, user_id=f"tg:{user_id}")`.
|
||||
- Else:
|
||||
- Call `ingest_document(session_id, dao_id=dao_id, user_id=f"tg:{user_id}")` and rely on stored context.
|
||||
- Send success/failure message.
|
||||
|
||||
2. **PDF detection**
|
||||
|
||||
- Check `document = update.message.get("document")`.
|
||||
- Determine `is_pdf` via `mime_type` and/or `file_name.endswith(".pdf")`.
|
||||
- If PDF:
|
||||
- Log file info.
|
||||
- Get `file_path` via `get_telegram_file_path(file_id)` + correct token → `file_url`.
|
||||
- Send "📄 Обробляю PDF-документ...".
|
||||
- `session_id = f"telegram:{chat_id}"`.
|
||||
- Call `parse_document(session_id, doc_url=file_url, file_name=file_name, dao_id, user_id=f"tg:{user_id}", output_mode="qa_pairs", metadata={"username": username, "chat_id": chat_id})`.
|
||||
- On success, format:
|
||||
- Prefer Q&A (`result.qa_pairs`) → `format_qa_response(...)`.
|
||||
- Else markdown → `format_markdown_response(...)`.
|
||||
- Else chunks → `format_chunks_response(...)`.
|
||||
- Append hint: `"\n\n💡 _Використай /ingest для імпорту документа у RAG_"`.
|
||||
- Send response via `send_telegram_message`.
|
||||
|
||||
3. **RAG follow-up questions**
|
||||
|
||||
- After computing `text` (from voice or direct text), before regular chat routing:
|
||||
- `session_id = f"telegram:{chat_id}"`.
|
||||
- Load `doc_context = await get_doc_context(session_id)`.
|
||||
- If `doc_context.doc_id` exists and text looks like a question (contains `?` or Ukrainian question words):
|
||||
- Call `ask_about_document(session_id, question=text, doc_id=doc_context.doc_id, dao_id=dao_id or doc_context.dao_id, user_id=f"tg:{user_id}")`.
|
||||
- If success, truncate answer to `TELEGRAM_SAFE_LENGTH` and send as Telegram message.
|
||||
- If RAG fails → fall back to normal chat routing.
|
||||
|
||||
4. **Keep voice + normal chat flows**
|
||||
|
||||
- Existing STT flow and chat→router logic should remain as fallback for non-PDF / non-ingest / non-RAG messages.
|
||||
|
||||
#### 5.3. Helion `/helion/telegram/webhook`
|
||||
|
||||
Mirror the same behaviours for Helion handler:
|
||||
|
||||
- `/ingest` command support.
|
||||
- PDF detection and `parse_document` usage.
|
||||
- RAG follow-up via `ask_about_document`.
|
||||
- Use `HELION_TELEGRAM_BOT_TOKEN` for file download and message sending.
|
||||
- Preserve existing chat→router behaviour when doc flow does not apply.
|
||||
|
||||
#### 5.4. Formatting helpers
|
||||
|
||||
Add helper functions at the bottom of `http_api.py` (Telegram-specific):
|
||||
|
||||
- `format_qa_response(qa_pairs: list, max_pairs: int = 5) -> str`
|
||||
- Adds header, enumerates Q&A pairs, truncates long answers, respects `TELEGRAM_SAFE_LENGTH`.
|
||||
- `format_markdown_response(markdown: str) -> str`
|
||||
- Wraps markdown with header; truncates to `TELEGRAM_SAFE_LENGTH` and appends hint about `/ingest` if truncated.
|
||||
- `format_chunks_response(chunks: list) -> str`
|
||||
- Shows summary about number of chunks and previews first ~3.
|
||||
|
||||
> IMPORTANT: These helpers handle Telegram-specific constraints and SHOULD NOT be moved into `doc_service`.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. `gateway-bot/services/doc_service.py` exists and provides:
|
||||
- `parse_document`, `ingest_document`, `ask_about_document`, `save_doc_context`, `get_doc_context`.
|
||||
- Uses DAGI Router and Memory Service, with `session_id`-based context.
|
||||
|
||||
2. `gateway-bot/http_api_doc.py` exists and defines:
|
||||
- `POST /api/doc/parse`
|
||||
- `POST /api/doc/ingest`
|
||||
- `POST /api/doc/ask`
|
||||
- `GET /api/doc/context/{session_id}`
|
||||
|
||||
3. `gateway-bot/app.py`:
|
||||
- Includes both `http_api.router` and `http_api_doc.router`.
|
||||
- Root `/` lists new `/api/doc/*` endpoints.
|
||||
|
||||
4. `gateway-bot/memory_client.py`:
|
||||
- Includes `get_fact(...)` and existing methods still work.
|
||||
- `doc_service` uses `upsert_fact` + `get_fact` for `doc_context:{session_id}`.
|
||||
|
||||
5. `gateway-bot/http_api.py`:
|
||||
- Telegram handlers use `doc_service` for:
|
||||
- PDF parsing,
|
||||
- `/ingest` command,
|
||||
- RAG follow-up questions.
|
||||
- Continue to support existing voice→STT→chat flow and regular chat routing when doc flow isnt triggered.
|
||||
|
||||
6. Web/mobile clients can call `/api/doc/*` to:
|
||||
- Parse documents via `doc_url`.
|
||||
- Ingest into RAG.
|
||||
- Ask questions about the last parsed document for given `session_id`.
|
||||
|
||||
---
|
||||
|
||||
## How to run this task with Cursor
|
||||
|
||||
From repo root (`microdao-daarion`):
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/channel_agnostic_doc_flow_task.md
|
||||
```
|
||||
|
||||
Cursor should then:
|
||||
|
||||
- Create/modify the files listed above.
|
||||
- Ensure implementation matches the described architecture and acceptance criteria.
|
||||
380
docs/cursor/crawl4ai_web_crawler_task.md
Normal file
380
docs/cursor/crawl4ai_web_crawler_task.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# Task: Web Crawler Service (crawl4ai) & Agent Tool Integration
|
||||
|
||||
## Goal
|
||||
|
||||
Інтегрувати **crawl4ai** в агентську систему MicroDAO/DAARION як:
|
||||
|
||||
1. Окремий бекенд-сервіс **Web Crawler**, який:
|
||||
- вміє скрапити сторінки з JS (Playwright/Chromium),
|
||||
- повертати структурований текст/HTML/метадані,
|
||||
- (опційно) генерувати події `doc.upserted` для RAG-ingestion.
|
||||
2. Агентський **tool** `web_crawler`, який викликається через Tool Proxy і доступний агентам (Team Assistant, Bridges Agent, тощо) з урахуванням безпеки.
|
||||
|
||||
Мета — дати агентам можливість читати зовнішні веб-ресурси (з обмеженнями) і, за потреби, індексувати їх у RAG.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Root: `microdao-daarion/`.
|
||||
- Інфраструктура агентів та tools:
|
||||
- `docs/cursor/12_agent_runtime_core.md`
|
||||
- `docs/cursor/13_agent_memory_system.md`
|
||||
- `docs/cursor/37_agent_tools_and_plugins_specification.md`
|
||||
- `docs/cursor/20_integrations_bridges_agent.md`
|
||||
- RAG-шар:
|
||||
- `docs/cursor/rag_gateway_task.md`
|
||||
- `docs/cursor/rag_ingestion_worker_task.md`
|
||||
- `docs/cursor/rag_ingestion_events_wave1_mvp_task.md`
|
||||
- Event Catalog / NATS:
|
||||
- `docs/cursor/42_nats_event_streams_and_event_catalog.md`
|
||||
- `docs/cursor/43_database_events_outbox_design.md`
|
||||
|
||||
На сервері вже встановлено `crawl4ai[all]` та `playwright chromium`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Сервіс Web Crawler
|
||||
|
||||
### 1.1. Структура сервісу
|
||||
|
||||
Створити новий Python-сервіс (подібно до інших внутрішніх сервісів):
|
||||
|
||||
- Директорія: `services/web-crawler/`
|
||||
- Файли (пропозиція):
|
||||
- `main.py` — entrypoint (FastAPI/uvicorn).
|
||||
- `api.py` — визначення HTTP-ендпоїнтів.
|
||||
- `crawl_client.py` — обгортка над crawl4ai.
|
||||
- `models.py` — Pydantic-схеми (request/response).
|
||||
- `config.py` — налаштування (timeouts, max_depth, allowlist доменів, тощо).
|
||||
|
||||
Сервіс **не** має прямого UI; його викликають Tool Proxy / інші бекенд-сервіси.
|
||||
|
||||
### 1.2. Основний ендпоїнт: `POST /api/web/scrape`
|
||||
|
||||
Пропонований контракт:
|
||||
|
||||
**Request JSON:**
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com/article",
|
||||
"team_id": "dao_greenfood",
|
||||
"session_id": "sess_...",
|
||||
"max_depth": 1,
|
||||
"max_pages": 1,
|
||||
"js_enabled": true,
|
||||
"timeout_seconds": 30,
|
||||
"user_agent": "MicroDAO-Crawler/1.0",
|
||||
"mode": "public",
|
||||
"indexed": false,
|
||||
"tags": ["external", "web", "research"],
|
||||
"return_html": false,
|
||||
"max_chars": 20000
|
||||
}
|
||||
```
|
||||
|
||||
**Response JSON (скорочено):**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"url": "https://example.com/article",
|
||||
"final_url": "https://example.com/article",
|
||||
"status_code": 200,
|
||||
"content": {
|
||||
"text": "... main extracted text ...",
|
||||
"html": "<html>...</html>",
|
||||
"title": "Example Article",
|
||||
"language": "en",
|
||||
"meta": {
|
||||
"description": "...",
|
||||
"keywords": ["..."]
|
||||
}
|
||||
},
|
||||
"links": [
|
||||
{ "url": "https://example.com/next", "text": "Next" }
|
||||
],
|
||||
"raw_size_bytes": 123456,
|
||||
"fetched_at": "2025-11-17T10:45:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Використати API/параметри crawl4ai для:
|
||||
|
||||
- рендеру JS (Playwright),
|
||||
- витягання основного контенту (article/reader mode, якщо є),
|
||||
- нормалізації тексту (видалення зайвого boilerplate).
|
||||
|
||||
### 1.3. Додаткові ендпоїнти (опційно)
|
||||
|
||||
- `POST /api/web/scrape_batch` — масовий скрап кількох URL (обмежений top-K).
|
||||
- `POST /api/web/crawl_site` — обхід сайту з `max_depth`/`max_pages` (для MVP можна не реалізовувати або залишити TODO).
|
||||
- `POST /api/web/scrape_and_ingest` — варіант, який одразу шле подію `doc.upserted` (див. розділ 3).
|
||||
|
||||
### 1.4. Обмеження та безпека
|
||||
|
||||
У `config.py` передбачити:
|
||||
|
||||
- `MAX_DEPTH` (наприклад, 1–2 для MVP).
|
||||
- `MAX_PAGES` (наприклад, 3–5).
|
||||
- `MAX_CHARS`/`MAX_BYTES` (щоб не забивати памʼять).
|
||||
- (Опційно) allowlist/denylist доменів для кожної команди/DAO.
|
||||
- таймаут HTTP/JS-запиту.
|
||||
|
||||
Логувати тільки мінімальний технічний контекст (URL, код статусу, тривалість), **не** зберігати повний HTML у логах.
|
||||
|
||||
---
|
||||
|
||||
## 2. Обгортка над crawl4ai (`crawl_client.py`)
|
||||
|
||||
Створити модуль, який інкапсулює виклики crawl4ai, щоб API/деталі можна було змінювати централізовано.
|
||||
|
||||
Приблизна логіка:
|
||||
|
||||
- функція `async def fetch_page(url: str, options: CrawlOptions) -> CrawlResult`:
|
||||
- налаштувати crawl4ai з Playwright (chromium),
|
||||
- виконати рендер/збір контенту,
|
||||
- повернути нормалізований результат: text, html (опційно), метадані, посилання.
|
||||
|
||||
Обовʼязково:
|
||||
|
||||
- коректно обробляти помилки мережі, редіректи, 4xx/5xx;
|
||||
- повертати `ok=false` + error message у HTTP-відповіді API.
|
||||
|
||||
---
|
||||
|
||||
## 3. Інтеграція з RAG-ingestion (doc.upserted)
|
||||
|
||||
### 3.1. Подія `doc.upserted` для веб-сторінок
|
||||
|
||||
Після успішного скрапу, якщо `indexed=true`, Web Crawler може (в майбутньому або одразу) створювати подію:
|
||||
|
||||
- `event`: `doc.upserted`
|
||||
- `stream`: `STREAM_PROJECT` або спеціальний `STREAM_DOCS`
|
||||
|
||||
Payload (адаптований під RAG-дизайн):
|
||||
|
||||
```json
|
||||
{
|
||||
"doc_id": "web::<hash_of_url>",
|
||||
"team_id": "dao_greenfood",
|
||||
"project_id": null,
|
||||
"path": "web/https_example_com_article",
|
||||
"title": "Example Article",
|
||||
"text": "... main extracted text ...",
|
||||
"url": "https://example.com/article",
|
||||
"tags": ["web", "external", "research"],
|
||||
"visibility": "public",
|
||||
"doc_type": "web",
|
||||
"indexed": true,
|
||||
"mode": "public",
|
||||
"updated_at": "2025-11-17T10:45:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Цю подію можна:
|
||||
|
||||
1. заповнити в таблицю outbox (див. `43_database_events_outbox_design.md`),
|
||||
2. з неї Outbox Worker відправить у NATS (JetStream),
|
||||
3. `rag-ingest-worker` (згідно `rag_ingestion_events_wave1_mvp_task.md`) сприйме `doc.upserted` і проіндексує сторінку в Milvus/Neo4j.
|
||||
|
||||
### 3.2. Підтримка у нормалізаторі
|
||||
|
||||
У `services/rag-ingest-worker/pipeline/normalization.py` уже є/буде `normalize_doc_upserted`:
|
||||
|
||||
- для веб-сторінок `doc_type="web"` потрібно лише переконатися, що:
|
||||
- `source_type = "doc"` або `"web"` (на твій вибір, але консистентний),
|
||||
- у `tags` включено `"web"`/`"external"`,
|
||||
- у metadata є `url`.
|
||||
|
||||
Якщо потрібно, можна додати просту гілку для `doc_type == "web"`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Agent Tool: `web_crawler`
|
||||
|
||||
### 4.1. Категорія безпеки
|
||||
|
||||
Відповідно до `37_agent_tools_and_plugins_specification.md`:
|
||||
|
||||
- Зовнішній інтернет — **Category D — Critical Tools** (`browser-full`, `external_api`).
|
||||
- Новий інструмент:
|
||||
- назва: `web_crawler`,
|
||||
- capability: `tool.web_crawler.invoke`,
|
||||
- категорія: **D (Critical)**,
|
||||
- за замовчуванням **вимкнений** — вмикається Governance/адміністратором для конкретних MicroDAO.
|
||||
|
||||
### 4.2. Tool request/response контракт
|
||||
|
||||
Tool Proxy викликає Web Crawler через HTTP.
|
||||
|
||||
**Request від Agent Runtime до Tool Proxy:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "web_crawler",
|
||||
"args": {
|
||||
"url": "https://example.com/article",
|
||||
"max_chars": 8000,
|
||||
"indexed": false,
|
||||
"mode": "public"
|
||||
},
|
||||
"context": {
|
||||
"agent_run_id": "ar_123",
|
||||
"team_id": "dao_greenfood",
|
||||
"user_id": "u_001",
|
||||
"channel_id": "ch_abc"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Tool Proxy далі робить HTTP-запит до `web-crawler` сервісу (`POST /api/web/scrape`).
|
||||
|
||||
**Відповідь до агента (спрощена):**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"output": {
|
||||
"title": "Example Article",
|
||||
"url": "https://example.com/article",
|
||||
"snippet": "Короткий уривок тексту...",
|
||||
"full_text": "... обрізаний до max_chars ..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Для безпеки:
|
||||
|
||||
- у відповідь, яку бачить LLM/агент, повертати **обмежений** `full_text` (наприклад, 8–10k символів),
|
||||
- якщо `full_text` занадто довгий — обрізати та явно це позначити.
|
||||
|
||||
### 4.3. PDP та quotas
|
||||
|
||||
- Перед викликом Tool Proxy повинен викликати PDP:
|
||||
- `action = tool.web_crawler.invoke`,
|
||||
- `subject = agent_id`,
|
||||
- `resource = team_id`.
|
||||
- Usage Service (див. 44_usage_accounting_and_quota_engine.md) може:
|
||||
- рахувати кількість викликів `web_crawler`/день,
|
||||
- обмежувати тривалість/обʼєм даних.
|
||||
|
||||
---
|
||||
|
||||
## 5. Інтеграція з Bridges Agent / іншими агентами
|
||||
|
||||
### 5.1. Bridges Agent
|
||||
|
||||
Bridges Agent (`20_integrations_bridges_agent.md`) може використовувати `web_crawler` як один зі своїх tools:
|
||||
|
||||
- сценарій: "Підтяни останню версію документації з https://docs.example.com/... і збережи як doc у Co-Memory";
|
||||
- Bridges Agent викликає tool `web_crawler`, отримує текст, створює внутрішній doc (через Projects/Co-Memory API) і генерує `doc.upserted`.
|
||||
|
||||
### 5.2. Team Assistant / Research-агенти
|
||||
|
||||
Для окремих DAO можна дозволити:
|
||||
|
||||
- `Team Assistant` викликає `web_crawler` для досліджень (наприклад, "знайди інформацію на сайті Мінекономіки про гранти"),
|
||||
- але з жорсткими лімітами (whitelist доменів, rate limits).
|
||||
|
||||
---
|
||||
|
||||
## 6. Confidential mode та privacy
|
||||
|
||||
Згідно з `47_messaging_channels_and_privacy_layers.md` та `48_teams_access_control_and_confidential_mode.md`:
|
||||
|
||||
- Якщо контекст агента `mode = confidential`:
|
||||
- інструмент `web_crawler` **не повинен** отримувати confidential plaintext із внутрішніх повідомлень (тобто, у `args` не має бути фрагментів внутрішнього тексту);
|
||||
- зазвичай достатньо лише URL.
|
||||
- Якщо `indexed=true` та `mode=confidential` для веб-сторінки (рідкісний кейс):
|
||||
- можна дозволити зберігати plaintext сторінки в RAG, оскільки це зовнішнє джерело;
|
||||
- але варто позначати таку інформацію як `source_type="web_external"` і у PDP контролювати, хто може її читати.
|
||||
|
||||
Для MVP в цій задачі достатньо:
|
||||
|
||||
- заборонити виклик `web_crawler` із confidential-контексту без явної конфігурації (тобто PDP повертає deny).
|
||||
|
||||
---
|
||||
|
||||
## 7. Логування та моніторинг
|
||||
|
||||
Додати базове логування в Web Crawler:
|
||||
|
||||
- при кожному скрапі:
|
||||
- `team_id`,
|
||||
- `url`,
|
||||
- `status_code`,
|
||||
- `duration_ms`,
|
||||
- `bytes_downloaded`.
|
||||
|
||||
Без збереження body/HTML у логах.
|
||||
|
||||
За бажанням — контрприклад метрик:
|
||||
|
||||
- `web_crawler_requests_total`,
|
||||
- `web_crawler_errors_total`,
|
||||
- `web_crawler_avg_duration_ms`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Files to create/modify (suggested)
|
||||
|
||||
> Назви/шляхи можна адаптувати до фактичної структури, важлива ідея.
|
||||
|
||||
- `services/web-crawler/main.py`
|
||||
- `services/web-crawler/api.py`
|
||||
- `services/web-crawler/crawl_client.py`
|
||||
- `services/web-crawler/models.py`
|
||||
- `services/web-crawler/config.py`
|
||||
|
||||
- Tool Proxy / агентський runtime (Node/TS):
|
||||
- додати tool `web_crawler` у список інструментів (див. `37_agent_tools_and_plugins_specification.md`).
|
||||
- оновити Tool Proxy, щоб він міг робити HTTP-виклик до Web Crawler.
|
||||
|
||||
- Bridges/Team Assistant агенти:
|
||||
- (опційно) додати `web_crawler` у їхні конфіги як доступний tool.
|
||||
|
||||
- RAG ingestion:
|
||||
- (опційно) оновити `rag-ingest-worker`/docs, щоб описати `doc_type="web"` у `doc.upserted` подіях.
|
||||
|
||||
---
|
||||
|
||||
## 9. Acceptance criteria
|
||||
|
||||
1. Існує новий сервіс `web-crawler` з ендпоїнтом `POST /api/web/scrape`, який використовує crawl4ai+Playwright для скрапу сторінок.
|
||||
2. Ендпоїнт повертає текст/метадані у структурованому JSON, з обмеженнями по розміру.
|
||||
3. Заготовлена (або реалізована) інтеграція з Event Catalog через подію `doc.upserted` для `doc_type="web"` (indexed=true).
|
||||
4. У Tool Proxy зʼявився tool `web_crawler` (категорія D, capability `tool.web_crawler.invoke`) з чітким request/response контрактом.
|
||||
5. PDP/usage engine враховують новий tool (принаймні у вигляді basic перевірок/квот).
|
||||
6. Bridges Agent (або Team Assistant) може використати `web_crawler` для простого MVP-сценарію (наприклад: скрапнути одну сторінку і показати її summary користувачу).
|
||||
7. Конфіденційний режим враховано: у конфігурації за замовчуванням `web_crawler` недоступний у `confidential` каналах/командах.
|
||||
|
||||
---
|
||||
|
||||
## 10. Інструкція для Cursor
|
||||
|
||||
```text
|
||||
You are a senior backend engineer (Python + Node/TS) working on the DAARION/MicroDAO stack.
|
||||
|
||||
Implement the Web Crawler service and agent tool integration using:
|
||||
- crawl4ai_web_crawler_task.md
|
||||
- 37_agent_tools_and_plugins_specification.md
|
||||
- 20_integrations_bridges_agent.md
|
||||
- rag_gateway_task.md
|
||||
- rag_ingestion_worker_task.md
|
||||
- 42_nats_event_streams_and_event_catalog.md
|
||||
|
||||
Tasks:
|
||||
1) Create the `services/web-crawler` service (FastAPI or equivalent) with /api/web/scrape based on crawl4ai.
|
||||
2) Implement basic options: js_enabled, max_depth, max_pages, max_chars, timeouts.
|
||||
3) Add tool `web_crawler` to the Tool Proxy (category D, capability tool.web_crawler.invoke).
|
||||
4) Wire Tool Proxy → Web Crawler HTTP call with proper request/response mapping.
|
||||
5) (Optional but preferred) Implement doc.upserted emission for indexed=true pages (doc_type="web") via the existing outbox → NATS flow.
|
||||
6) Add a simple usage example in Bridges Agent or Team Assistant config (one agent that can use this tool in dev).
|
||||
|
||||
Output:
|
||||
- list of modified files
|
||||
- diff
|
||||
- summary
|
||||
```
|
||||
371
docs/cursor/rag_gateway_task.md
Normal file
371
docs/cursor/rag_gateway_task.md
Normal file
@@ -0,0 +1,371 @@
|
||||
# Task: Unified RAG-Gateway service (Milvus + Neo4j) for all agents
|
||||
|
||||
## Goal
|
||||
|
||||
Design and implement a **single RAG-gateway service** that sits between agents and storage backends (Milvus, Neo4j, etc.), so that:
|
||||
|
||||
- Agents never talk directly to Milvus or Neo4j.
|
||||
- All retrieval, graph queries and hybrid RAG behavior go through one service with a clear API.
|
||||
- Security, multi-tenancy, logging, and optimization are centralized.
|
||||
|
||||
This task is about **architecture and API** first (code layout, endpoints, data contracts). A later task can cover concrete implementation details if needed.
|
||||
|
||||
> This spec is intentionally high-level but should be detailed enough for Cursor to scaffold the service, HTTP API, and integration points with DAGI Router.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Project root: `microdao-daarion/`.
|
||||
- There are (or will be) multiple agents:
|
||||
- DAARWIZZ (system orchestrator)
|
||||
- Helion (Energy Union)
|
||||
- Team/Project/Messenger/Co-Memory agents, etc.
|
||||
- Agents already have access to:
|
||||
- DAGI Router (LLM routing, tools, orchestrator).
|
||||
- Memory service (short/long-term chat memory).
|
||||
- Parser-service (OCR and document parsing).
|
||||
|
||||
We now want a **RAG layer** that can:
|
||||
|
||||
- Perform semantic document search across all DAO documents / messages / files.
|
||||
- Use a **vector DB** (Milvus) and **graph DB** (Neo4j) together.
|
||||
- Provide a clean tool-like API to agents.
|
||||
|
||||
The RAG layer should be exposed as a standalone service:
|
||||
|
||||
- Working name: `rag-gateway` or `knowledge-service`.
|
||||
- Internally can use Haystack (or similar) for pipelines.
|
||||
|
||||
---
|
||||
|
||||
## High-level architecture
|
||||
|
||||
### 1. RAG-Gateway service
|
||||
|
||||
Create a new service (later we can place it under `services/rag-gateway/`), with HTTP API, which will:
|
||||
|
||||
- Accept tool-style requests from DAGI Router / agents.
|
||||
- Internally talk to:
|
||||
- Milvus (vector search, embeddings).
|
||||
- Neo4j (graph queries, traversals).
|
||||
- Return structured JSON for agents to consume.
|
||||
|
||||
Core API endpoints (first iteration):
|
||||
|
||||
- `POST /rag/search_docs` — semantic/hybrid document search.
|
||||
- `POST /rag/enrich_answer` — enrich an existing answer with sources.
|
||||
- `POST /graph/query` — run a graph query (Cypher or intent-based).
|
||||
- `POST /graph/explain_path` — return graph-based explanation / path between entities.
|
||||
|
||||
Agents will see these as tools (e.g. `rag.search_docs`, `graph.query_context`) configured in router config.
|
||||
|
||||
### 2. Haystack as internal orchestrator
|
||||
|
||||
Within the RAG-gateway, use Haystack components (or analogous) to organize:
|
||||
|
||||
- `MilvusDocumentStore` as the main vector store.
|
||||
- Retrievers:
|
||||
- Dense retriever over Milvus.
|
||||
- Optional BM25/keyword retriever (for hybrid search).
|
||||
- Pipelines:
|
||||
- `indexing_pipeline` — ingest DAO documents/messages/files into Milvus.
|
||||
- `query_pipeline` — answer agent queries using retrieved documents.
|
||||
- `graph_rag_pipeline` — combine Neo4j graph queries with Milvus retrieval.
|
||||
|
||||
The key idea: **agents never talk to Haystack directly**, only to RAG-gateway HTTP API.
|
||||
|
||||
---
|
||||
|
||||
## Data model & schema
|
||||
|
||||
### 1. Milvus document schema
|
||||
|
||||
Define a standard metadata schema for all documents/chunks stored in Milvus. Required fields:
|
||||
|
||||
- `team_id` / `dao_id` — which DAO / team this data belongs to.
|
||||
- `project_id` — optional project-level grouping.
|
||||
- `channel_id` — optional chat/channel ID (Telegram, internal channel, etc.).
|
||||
- `agent_id` — which agent produced/owns this piece.
|
||||
- `visibility` — one of `"public" | "confidential"`.
|
||||
- `doc_type` — one of `"message" | "doc" | "file" | "wiki" | "rwa" | "transaction"` (extensible).
|
||||
- `tags` — list of tags (topics, domains, etc.).
|
||||
- `created_at` — timestamp.
|
||||
|
||||
These should be part of Milvus metadata, so that RAG-gateway can apply filters (by DAO, project, visibility, etc.).
|
||||
|
||||
### 2. Neo4j graph schema
|
||||
|
||||
Design a **minimal default graph model** with node labels:
|
||||
|
||||
- `User`, `Agent`, `MicroDAO`, `Project`, `Channel`
|
||||
- `Topic`, `Resource`, `File`, `RWAObject` (e.g. energy asset, food batch, water object).
|
||||
|
||||
Key relationships (examples):
|
||||
|
||||
- `(:User)-[:MEMBER_OF]->(:MicroDAO)`
|
||||
- `(:Agent)-[:SERVES]->(:MicroDAO|:Project)`
|
||||
- `(:Doc)-[:MENTIONS]->(:Topic)`
|
||||
- `(:Project)-[:USES]->(:Resource)`
|
||||
|
||||
Every node/relationship should also carry:
|
||||
|
||||
- `team_id` / `dao_id`
|
||||
- `visibility` or similar privacy flag
|
||||
|
||||
This allows RAG-gateway to enforce access control at query time.
|
||||
|
||||
---
|
||||
|
||||
## RAG tools API for agents
|
||||
|
||||
Define 2–3 canonical tools that DAGI Router can call. These map to RAG-gateway endpoints.
|
||||
|
||||
### 1. `rag.search_docs`
|
||||
|
||||
Main tool for most knowledge queries.
|
||||
|
||||
**Request JSON example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_id": "ag_daarwizz",
|
||||
"team_id": "dao_greenfood",
|
||||
"query": "які проєкти у нас вже використовують Milvus?",
|
||||
"top_k": 5,
|
||||
"filters": {
|
||||
"project_id": "prj_x",
|
||||
"doc_type": ["doc", "wiki"],
|
||||
"visibility": "public"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response JSON example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"matches": [
|
||||
{
|
||||
"score": 0.82,
|
||||
"title": "Spec microdao RAG stack",
|
||||
"snippet": "...",
|
||||
"source_ref": {
|
||||
"type": "doc",
|
||||
"id": "doc_123",
|
||||
"url": "https://...",
|
||||
"team_id": "dao_greenfood",
|
||||
"doc_type": "doc"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. `graph.query_context`
|
||||
|
||||
For relationship/structural questions ("хто з ким повʼязаний", "які проєкти використовують X" etc.).
|
||||
|
||||
Two options (can support both):
|
||||
|
||||
1. **Low-level Cypher**:
|
||||
|
||||
```json
|
||||
{
|
||||
"team_id": "dao_energy",
|
||||
"cypher": "MATCH (p:Project)-[:USES]->(r:Resource {name:$name}) RETURN p LIMIT 10",
|
||||
"params": {"name": "Milvus"}
|
||||
}
|
||||
```
|
||||
|
||||
2. **High-level intent**:
|
||||
|
||||
```json
|
||||
{
|
||||
"team_id": "dao_energy",
|
||||
"intent": "FIND_PROJECTS_BY_TECH",
|
||||
"args": {"tech": "Milvus"}
|
||||
}
|
||||
```
|
||||
|
||||
RAG-gateway then maps intent → Cypher internally.
|
||||
|
||||
### 3. `rag.enrich_answer`
|
||||
|
||||
Given a draft answer from an agent, RAG-gateway retrieves supporting documents and returns enriched answer + citations.
|
||||
|
||||
**Request example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"team_id": "dao_greenfood",
|
||||
"question": "Поясни коротко архітектуру RAG шару в нашому місті.",
|
||||
"draft_answer": "Архітектура складається з ...",
|
||||
"max_docs": 3
|
||||
}
|
||||
```
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"enriched_answer": "Архітектура складається з ... (з врахуванням джерел)",
|
||||
"sources": [
|
||||
{"id": "doc_1", "title": "RAG spec", "url": "https://..."},
|
||||
{"id": "doc_2", "title": "Milvus setup", "url": "https://..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-tenancy & security
|
||||
|
||||
Add a small **authorization layer** inside RAG-gateway:
|
||||
|
||||
- Each request includes:
|
||||
- `user_id`, `team_id` (DAO), optional `roles`.
|
||||
- `mode` / `visibility` (e.g. `"public"` or `"confidential"`).
|
||||
- Before querying Milvus/Neo4j, RAG-gateway applies filters:
|
||||
- `team_id = ...`
|
||||
- `visibility` within allowed scope.
|
||||
- Optional role-based constraints (Owner/Guardian/Member) affecting what doc_types can be seen.
|
||||
|
||||
Implementation hints:
|
||||
|
||||
- Start with a simple `AccessContext` object built from request, used by all pipelines.
|
||||
- Later integrate with existing PDP/RBAC if available.
|
||||
|
||||
---
|
||||
|
||||
## Ingestion & pipelines
|
||||
|
||||
Define an ingestion plan and API.
|
||||
|
||||
### 1. Ingest service / worker
|
||||
|
||||
Create a separate ingestion component (can be part of RAG-gateway or standalone worker) that:
|
||||
|
||||
- Listens to events like:
|
||||
- `message.created`
|
||||
- `doc.upsert`
|
||||
- `file.uploaded`
|
||||
- For each event:
|
||||
- Builds text chunks.
|
||||
- Computes embeddings.
|
||||
- Writes chunks into Milvus with proper metadata.
|
||||
- Updates Neo4j graph (nodes/edges) where appropriate.
|
||||
|
||||
Requirements:
|
||||
|
||||
- Pipelines must be **idempotent** — re-indexing same document does not break anything.
|
||||
- Create an API / job for `reindex(team_id)` to reindex a full DAO if needed.
|
||||
- Store embedding model version in metadata (e.g. `embed_model: "bge-m3@v1"`) to ease future migrations.
|
||||
|
||||
### 2. Event contracts
|
||||
|
||||
Align ingestion with the existing Event Catalog (if present in `docs/cursor`):
|
||||
|
||||
- Document which event types lead to RAG ingestion.
|
||||
- For each event, define mapping → Milvus doc, Neo4j nodes/edges.
|
||||
|
||||
---
|
||||
|
||||
## Optimization for agents
|
||||
|
||||
Add support for:
|
||||
|
||||
1. **Semantic cache per agent**
|
||||
|
||||
- Cache `query → RAG-result` for N minutes per (`agent_id`, `team_id`).
|
||||
- Useful for frequently repeated queries.
|
||||
|
||||
2. **RAG behavior profiles per agent**
|
||||
|
||||
- In agent config (probably in router config), define:
|
||||
- `rag_mode: off | light | strict`
|
||||
- `max_context_tokens`
|
||||
- `max_docs_per_query`
|
||||
- RAG-gateway can read these via metadata from Router, or Router can decide when to call RAG at all.
|
||||
|
||||
---
|
||||
|
||||
## Files to create/modify (suggested)
|
||||
|
||||
> NOTE: This is a suggestion; adjust exact paths/names to fit the existing project structure.
|
||||
|
||||
- New service directory: `services/rag-gateway/`:
|
||||
- `main.py` — FastAPI (or similar) entrypoint.
|
||||
- `api.py` — defines `/rag/search_docs`, `/rag/enrich_answer`, `/graph/query`, `/graph/explain_path`.
|
||||
- `core/pipelines.py` — Haystack pipelines (indexing, query, graph-rag).
|
||||
- `core/schema.py` — Pydantic models for request/response, data schema.
|
||||
- `core/access.py` — access control context + checks.
|
||||
- `core/backends/milvus_client.py` — wrapper for Milvus.
|
||||
- `core/backends/neo4j_client.py` — wrapper for Neo4j.
|
||||
|
||||
- Integration with DAGI Router:
|
||||
- Update `router-config.yml` to define RAG tools:
|
||||
- `rag.search_docs`
|
||||
- `graph.query_context`
|
||||
- `rag.enrich_answer`
|
||||
- Configure providers for RAG-gateway base URL.
|
||||
|
||||
- Docs:
|
||||
- `docs/cursor/rag_gateway_api_spec.md` — optional detailed API spec for RAG tools.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. **Service skeleton**
|
||||
|
||||
- A new RAG-gateway service exists under `services/` with:
|
||||
- A FastAPI (or similar) app.
|
||||
- Endpoints:
|
||||
- `POST /rag/search_docs`
|
||||
- `POST /rag/enrich_answer`
|
||||
- `POST /graph/query`
|
||||
- `POST /graph/explain_path`
|
||||
- Pydantic models for requests/responses.
|
||||
|
||||
2. **Data contracts**
|
||||
|
||||
- Milvus document metadata schema is defined (and used in code).
|
||||
- Neo4j node/edge labels and key relationships are documented and referenced in code.
|
||||
|
||||
3. **Security & multi-tenancy**
|
||||
|
||||
- All RAG/graph endpoints accept `user_id`, `team_id`, and enforce at least basic filtering by `team_id` and `visibility`.
|
||||
|
||||
4. **Agent tool contracts**
|
||||
|
||||
- JSON contracts for tools `rag.search_docs`, `graph.query_context`, and `rag.enrich_answer` are documented and used by RAG-gateway.
|
||||
- DAGI Router integration is sketched (even if not fully wired): provider entry + basic routing rule examples.
|
||||
|
||||
5. **Ingestion design**
|
||||
|
||||
- Ingestion pipeline is outlined in code (or stubs) with clear TODOs:
|
||||
- where to hook event consumption,
|
||||
- how to map events to Milvus/Neo4j.
|
||||
- Idempotency and `reindex(team_id)` strategy described in code/docs.
|
||||
|
||||
6. **Documentation**
|
||||
|
||||
- This file (`docs/cursor/rag_gateway_task.md`) plus, optionally, a more detailed API spec file for RAG-gateway.
|
||||
|
||||
---
|
||||
|
||||
## How to run this task with Cursor
|
||||
|
||||
From repo root (`microdao-daarion`):
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/rag_gateway_task.md
|
||||
```
|
||||
|
||||
Cursor should then:
|
||||
|
||||
- Scaffold the RAG-gateway service structure.
|
||||
- Implement request/response models and basic endpoints.
|
||||
- Sketch out Milvus/Neo4j client wrappers and pipelines.
|
||||
- Optionally, add TODOs where deeper implementation is needed.
|
||||
139
docs/cursor/rag_ingest_worker_routing_task.md
Normal file
139
docs/cursor/rag_ingest_worker_routing_task.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Task: Configure rag-ingest-worker routing & unified event interface
|
||||
|
||||
## Goal
|
||||
|
||||
Налаштувати **єдиний інтерфейс на вхід** для `rag-ingest-worker` і routing таблицю, яка:
|
||||
|
||||
- приймає події з `teams.*`/outbox або відповідних STREAM_*,
|
||||
- уніфіковано парсить Event Envelope (`event`, `ts`, `meta`, `payload`),
|
||||
- мапить `event.type` → нормалізатор/пайплайн (Wave 1–3),
|
||||
- гарантує правильну обробку `mode`/`indexed` для всіх RAG-подій.
|
||||
|
||||
Це glue-задача, яка повʼязує Event Catalog із `rag_ingestion_events_*` тасками.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Root: `microdao-daarion/`.
|
||||
- Event envelope та NATS: `docs/cursor/42_nats_event_streams_and_event_catalog.md`.
|
||||
- RAG worker & gateway:
|
||||
- `docs/cursor/rag_ingestion_worker_task.md`
|
||||
- `docs/cursor/rag_gateway_task.md`
|
||||
- RAG waves:
|
||||
- `docs/cursor/rag_ingestion_events_wave1_mvp_task.md`
|
||||
- `docs/cursor/rag_ingestion_events_wave2_workflows_task.md`
|
||||
- `docs/cursor/rag_ingestion_events_wave3_governance_rwa_task.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Єдиний event envelope у воркері
|
||||
|
||||
У `services/rag-ingest-worker/events/consumer.py` або окремому модулі:
|
||||
|
||||
1. Ввести Pydantic-модель/DTO для envelope, наприклад `RagEventEnvelope`:
|
||||
- `event_id: str`
|
||||
- `ts: datetime`
|
||||
- `type: str` (повний typo: `chat.message.created`, `task.created`, ...)
|
||||
- `domain: str` (optional)
|
||||
- `meta: { team_id, trace_id, ... }`
|
||||
- `payload: dict`
|
||||
2. Додати функцію `parse_raw_msg_to_envelope(raw_msg) -> RagEventEnvelope`.
|
||||
3. Забезпечити, що **весь routing** далі працює з `RagEventEnvelope`, а не з сирим JSON.
|
||||
|
||||
---
|
||||
|
||||
## 2. Routing таблиця (Wave 1–3)
|
||||
|
||||
У тому ж модулі або окремому `router.py` створити mapping:
|
||||
|
||||
```python
|
||||
ROUTES = {
|
||||
"chat.message.created": handle_message_created,
|
||||
"doc.upserted": handle_doc_upserted,
|
||||
"file.uploaded": handle_file_uploaded,
|
||||
"task.created": handle_task_event,
|
||||
"task.updated": handle_task_event,
|
||||
"followup.created": handle_followup_event,
|
||||
"followup.status_changed": handle_followup_event,
|
||||
"meeting.summary.upserted": handle_meeting_summary,
|
||||
"governance.proposal.created": handle_proposal_event,
|
||||
"governance.proposal.closed": handle_proposal_event,
|
||||
"governance.vote.cast": handle_vote_event,
|
||||
"payout.generated": handle_payout_event,
|
||||
"payout.claimed": handle_payout_event,
|
||||
"rwa.summary.created": handle_rwa_summary_event,
|
||||
}
|
||||
```
|
||||
|
||||
Handler-и мають бути thin-обгортками над нормалізаторами з `pipeline/normalization.py` та `index_neo4j.py`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Обробка `mode` та `indexed`
|
||||
|
||||
У кожному handler-і або в спільній helper-функції треба:
|
||||
|
||||
1. Дістати `mode` та `indexed` з `payload` (або похідним чином).
|
||||
2. Якщо `indexed == false` — логувати і завершувати без виклику нормалізаторів.
|
||||
3. Передавати `mode` у нормалізатор, щоб той міг вирішити, чи зберігати plaintext.
|
||||
|
||||
Рекомендовано зробити утиліту, наприклад:
|
||||
|
||||
```python
|
||||
def should_index(event: RagEventEnvelope) -> bool:
|
||||
# врахувати payload.indexed + можливі global overrides
|
||||
...
|
||||
```
|
||||
|
||||
і використовувати її у всіх handler-ах.
|
||||
|
||||
---
|
||||
|
||||
## 4. Підписки на NATS (streams vs teams.*)
|
||||
|
||||
У `events/consumer.py` узгодити 2 можливі режими:
|
||||
|
||||
1. **Прямі підписки на STREAM_*:**
|
||||
- STREAM_CHAT → `chat.message.*`
|
||||
- STREAM_PROJECT → `doc.upserted`, `meeting.*`
|
||||
- STREAM_TASK → `task.*`, `followup.*`
|
||||
- STREAM_GOVERNANCE → `governance.*`
|
||||
- STREAM_RWA → `rwa.summary.*`
|
||||
2. **teams.* outbox:**
|
||||
- якщо існує outbox-стрім `teams.*` із aggregate-подіями, воркер може підписуватися на нього замість окремих STREAM_*.
|
||||
|
||||
У цьому таску достатньо:
|
||||
|
||||
- вибрати й реалізувати **один** режим (той, що відповідає поточній архітектурі);
|
||||
- акуратно задокументувати, які subjects використовуються, щоб не дублювати події.
|
||||
|
||||
---
|
||||
|
||||
## 5. Error handling & backpressure
|
||||
|
||||
У routing-шарі реалізувати базові правила:
|
||||
|
||||
- якщо `event.type` відсутній у `ROUTES` → логувати warning і ack-нути подію (щоб не блокувати стрім);
|
||||
- якщо нормалізація/embedding/indexing кидає виняток →
|
||||
- логувати з контекстом (`event_id`, `type`, `team_id`),
|
||||
- залежно від політики JetStream: або `nack` з retry, або ручний DLQ.
|
||||
|
||||
Можна додати просту метрику: `ingest_events_total{type=..., status=ok|error}`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Acceptance criteria
|
||||
|
||||
1. У `rag-ingest-worker` існує єдина модель envelope (`RagEventEnvelope`) і функція парсингу raw NATS-повідомлень.
|
||||
2. Routing таблиця покриває всі події Wave 1–3, описані в `rag_ingestion_events_wave*_*.md`.
|
||||
3. Усі handler-и використовують спільну логіку `should_index(event)` для `mode`/`indexed`.
|
||||
4. NATS-підписки налаштовані на обраний режим (STREAM_* або `teams.*`), задокументовані й не дублюють події.
|
||||
5. В наявності базове логування/обробка помилок на рівні routing-шару.
|
||||
6. Цей файл (`docs/cursor/rag_ingest_worker_routing_task.md`) можна виконати через Cursor:
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/rag_ingest_worker_routing_task.md
|
||||
```
|
||||
|
||||
і Cursor використає його як основу для налаштування routing-шару ingestion-воркера.
|
||||
150
docs/cursor/rag_ingestion_events_catalog_task.md
Normal file
150
docs/cursor/rag_ingestion_events_catalog_task.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Task: Document "RAG Ingestion Events" in Event Catalog & Data Model
|
||||
|
||||
## Goal
|
||||
|
||||
Оформити **єдиний розділ** "RAG Ingestion Events" у документації, який описує:
|
||||
|
||||
- які саме події потрапляють у RAG-ingestion (Wave 1–3),
|
||||
- їх payload-схеми та поля `mode`/`indexed`,
|
||||
- mapping до Milvus/Neo4j,
|
||||
- JetStream streams/subjects і consumer group `rag-ingest-worker`.
|
||||
|
||||
Це дозволить усім сервісам узгоджено генерувати події для RAG-шару.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Root: `microdao-daarion/`.
|
||||
- Основний Event Catalog: `docs/cursor/42_nats_event_streams_and_event_catalog.md`.
|
||||
- RAG-шар:
|
||||
- `docs/cursor/rag_gateway_task.md`
|
||||
- `docs/cursor/rag_ingestion_worker_task.md`
|
||||
- хвилі подій:
|
||||
- `docs/cursor/rag_ingestion_events_wave1_mvp_task.md`
|
||||
- `docs/cursor/rag_ingestion_events_wave2_workflows_task.md`
|
||||
- `docs/cursor/rag_ingestion_events_wave3_governance_rwa_task.md`
|
||||
- деталізація для перших подій: `docs/cursor/rag_ingestion_events_task.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Новий розділ у Event Catalog
|
||||
|
||||
У файлі `docs/cursor/42_nats_event_streams_and_event_catalog.md` додати окремий розділ, наприклад:
|
||||
|
||||
```markdown
|
||||
## 18. RAG Ingestion Events
|
||||
```
|
||||
|
||||
У цьому розділі:
|
||||
|
||||
1. Коротко пояснити, що **не всі** події індексуються в RAG, а тільки відібрані (Wave 1–3).
|
||||
2. Дати таблицю з колонками:
|
||||
- `Event type`
|
||||
- `Stream`
|
||||
- `Subject`
|
||||
- `Wave`
|
||||
- `Ingested into RAG?`
|
||||
- `Milvus doc_type`
|
||||
- `Neo4j nodes/edges`
|
||||
|
||||
Приклади рядків:
|
||||
|
||||
- `chat.message.created` → STREAM_CHAT → Wave 1 → `doc_type="message"` → `User–Message–Channel`.
|
||||
- `doc.upserted` → STREAM_PROJECT/docs → Wave 1 → `doc_type="doc"` → `Project–Doc`.
|
||||
- `file.uploaded` → STREAM_PROJECT/files → Wave 1 → `doc_type="file"` → `File–(Message|Doc|Project)`.
|
||||
- `task.created`/`task.updated` → STREAM_TASK → Wave 2 → `doc_type="task"` → `Task–Project–User`.
|
||||
- `followup.created` → STREAM_TASK/FOLLOWUP → Wave 2 → `doc_type="followup"` → `Followup–Message–User`.
|
||||
- `meeting.summary.upserted` → STREAM_PROJECT/MEETING → Wave 2 → `doc_type="meeting"` → `Meeting–Project–User/Agent`.
|
||||
- `governance.proposal.created` → STREAM_GOVERNANCE → Wave 3 → `doc_type="proposal"` → `Proposal–User–MicroDAO`.
|
||||
- `rwa.summary.created` → STREAM_RWA → Wave 3 → `doc_type="rwa_summary"` → `RWAObject–RwaSummary`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Поля `mode` та `indexed`
|
||||
|
||||
У тому ж розділі описати обовʼязкові поля для всіх RAG-подій:
|
||||
|
||||
- `mode`: `public|confidential` — впливає на те, чи зберігається plaintext у Milvus;
|
||||
- `indexed`: bool — чи взагалі подія потрапляє у RAG-шар (RAG та Meilisearch мають однакову логіку);
|
||||
- `team_id`, `channel_id` / `project_id`, `author_id`, timestamps.
|
||||
|
||||
Додати невеликий підрозділ з правилами:
|
||||
|
||||
- якщо `indexed=false` → ingestion-воркер не створює чанків;
|
||||
- якщо `mode=confidential` → зберігається тільки embeddings + мінімальні метадані.
|
||||
|
||||
---
|
||||
|
||||
## 3. Mapping до Milvus/Neo4j (таблиці)
|
||||
|
||||
У новому розділі (або окремому `.md`) додати 2 узагальнюючі таблиці:
|
||||
|
||||
### 3.1. Event → Milvus schema
|
||||
|
||||
Колонки:
|
||||
|
||||
- `Event type`
|
||||
- `Milvus doc_type`
|
||||
- `Key metadata`
|
||||
- `Chunking strategy`
|
||||
|
||||
### 3.2. Event → Neo4j graph
|
||||
|
||||
Колонки:
|
||||
|
||||
- `Event type`
|
||||
- `Nodes`
|
||||
- `Relationships`
|
||||
- `Merge keys`
|
||||
|
||||
Приклади для першої таблиці:
|
||||
|
||||
- `chat.message.created` → `message` → (`team_id`, `channel_id`, `author_id`, `thread_id`, `created_at`) → no chunking/short text.
|
||||
- `doc.upserted` → `doc` → (`team_id`, `project_id`, `path`, `labels`) → chunk by 512–1024.
|
||||
- `meeting.summary.upserted` → `meeting` → (`team_id`, `project_id`, `meeting_id`, `tags`) → chunk by paragraph.
|
||||
|
||||
Та аналогічно для Neo4j (User–Message–Channel, Task–Project–User, Proposal–User–MicroDAO тощо).
|
||||
|
||||
---
|
||||
|
||||
## 4. Consumer group `rag-ingest-worker`
|
||||
|
||||
У розділі про Consumer Groups (`## 10. Consumer Groups`) додати `rag-ingest-worker` як окремого consumer для відповідних стрімів:
|
||||
|
||||
- STREAM_CHAT → `search-indexer`, `rag-ingest-worker`.
|
||||
- STREAM_PROJECT → `rag-ingest-worker`.
|
||||
- STREAM_TASK → `rag-ingest-worker`.
|
||||
- STREAM_GOVERNANCE → `rag-ingest-worker`.
|
||||
- STREAM_RWA → (тільки summary-події) → `rag-ingest-worker`.
|
||||
|
||||
Пояснити, що worker може використовувати **durable consumers** з at-least-once доставкою, та що ідемпотентність гарантується на рівні `chunk_id`/Neo4j MERGE.
|
||||
|
||||
---
|
||||
|
||||
## 5. Оновлення Data Model / Architecture docs
|
||||
|
||||
За потреби, у відповідних документах додати короткі посилання на RAG-ingestion:
|
||||
|
||||
- у `34_internal_services_architecture.md` — блок "RAG-ingest-worker" як окремий internal service, що споживає NATS і пише в Milvus/Neo4j;
|
||||
- у `23_domains_wallet_dao_deepdive.md` або `MVP_VERTICAL_SLICE.md` — згадку, що доменні події є джерелом правди для RAG.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. У `42_nats_event_streams_and_event_catalog.md` зʼявився розділ "RAG Ingestion Events" із:
|
||||
- таблицею подій Wave 1–3,
|
||||
- вказаними streams/subjects,
|
||||
- позначкою, чи індексується подія в RAG.
|
||||
2. Описані єдині вимоги до полів `mode` та `indexed` для всіх RAG-подій.
|
||||
3. Є 2 таблиці зі схемами mapping → Milvus та Neo4j.
|
||||
4. Consumer group `rag-ingest-worker` доданий до відповідних стрімів і задокументований.
|
||||
5. За потреби, оновлені архітектурні документи (`34_internal_services_architecture.md` тощо) з коротким описом RAG-ingest-worker.
|
||||
6. Цей файл (`docs/cursor/rag_ingestion_events_catalog_task.md`) можна виконати через Cursor:
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/rag_ingestion_events_catalog_task.md
|
||||
```
|
||||
|
||||
і він стане єдиною задачею для документування RAG Ingestion Events у каталозі подій.
|
||||
248
docs/cursor/rag_ingestion_events_task.md
Normal file
248
docs/cursor/rag_ingestion_events_task.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# Task: Wire `message.created` and `doc.upsert` events into the RAG ingestion worker
|
||||
|
||||
## Goal
|
||||
|
||||
Підключити реальні доменні події до RAG ingestion воркера так, щоб:
|
||||
|
||||
- Події `message.created` та `doc.upsert` автоматично потрапляли в RAG ingestion pipeline.
|
||||
- Вони нормалізувались у `IngestChunk` (текст + метадані).
|
||||
- Чанки індексувались в Milvus (векторний стор) і за потреби в Neo4j (граф контексту).
|
||||
- Обробка була **ідемпотентною** та стабільною (повтор подій не ламає індекс).
|
||||
|
||||
Це продовження `rag_ingestion_worker_task.md`: там ми описали воркер, тут — як реально підвести його до подій `message.created` і `doc.upsert`.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Root: `microdao-daarion/`
|
||||
- Ingestion worker: `services/rag-ingest-worker/` (згідно попередньої таски).
|
||||
- Event catalog: `docs/cursor/42_nats_event_streams_and_event_catalog.md` (описує NATS streams / subjects / event types).
|
||||
|
||||
Ми вважаємо, що:
|
||||
|
||||
- Існує NATS (або інший) event bus.
|
||||
- Є події:
|
||||
- `message.created` — створення повідомлення в чаті/каналі.
|
||||
- `doc.upsert` — створення/оновлення документа (wiki, spec, тощо).
|
||||
- RAG ingestion worker вже має базові пайплайни (`normalization`, `embedding`, `index_milvus`, `index_neo4j`) — хоча б як скелет.
|
||||
|
||||
Мета цієї задачі — **підʼєднатися до реальних подій** і забезпечити end‑to‑end шлях:
|
||||
|
||||
`event → IngestChunk → embedding → Milvus (+ Neo4j)`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Подія `message.created`
|
||||
|
||||
### 1.1. Очікуваний формат події
|
||||
|
||||
Орієнтуючись на Event Catalog, нормальний payload для `message.created` має виглядати приблизно так (приклад, можна адаптувати до фактичного формату):
|
||||
|
||||
```json
|
||||
{
|
||||
"event_type": "message.created",
|
||||
"event_id": "evt_123",
|
||||
"occurred_at": "2024-11-17T10:00:00Z",
|
||||
"team_id": "dao_greenfood",
|
||||
"channel_id": "tg:12345" ,
|
||||
"user_id": "tg:67890",
|
||||
"agent_id": "daarwizz",
|
||||
"payload": {
|
||||
"message_id": "msg_abc",
|
||||
"text": "Текст повідомлення...",
|
||||
"attachments": [],
|
||||
"tags": ["onboarding", "spec"],
|
||||
"visibility": "public"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Якщо реальний формат інший — **не міняти продакшн‑події**, а в нормалізації підлаштуватись під нього.
|
||||
|
||||
### 1.2. Нормалізація у `IngestChunk`
|
||||
|
||||
У `services/rag-ingest-worker/pipeline/normalization.py` додати/оновити функцію:
|
||||
|
||||
```python
|
||||
async def normalize_message_created(event: dict) -> list[IngestChunk]:
|
||||
...
|
||||
```
|
||||
|
||||
Правила:
|
||||
|
||||
- Якщо `payload.text` порожній — можна або пропустити chunk, або створити chunk тільки з метаданими (краще пропустити).
|
||||
- Створити один або кілька `IngestChunk` (якщо треба розбити довгі повідомлення).
|
||||
|
||||
Поля для `IngestChunk` (мінімум):
|
||||
|
||||
- `chunk_id` — детермінований, напр.:
|
||||
- `f"msg:{event['team_id']}:{payload['message_id']}:{chunk_index}"` і потім захешувати.
|
||||
- `team_id` = `event.team_id`.
|
||||
- `channel_id` = `event.channel_id`.
|
||||
- `agent_id` = `event.agent_id` (якщо є).
|
||||
- `source_type` = `"message"`.
|
||||
- `source_id` = `payload.message_id`.
|
||||
- `text` = фрагмент тексту.
|
||||
- `tags` = `payload.tags` (якщо є) + можна додати автоматику (наприклад, `"chat"`).
|
||||
- `visibility` = `payload.visibility` або `"public"` за замовчуванням.
|
||||
- `created_at` = `event.occurred_at`.
|
||||
|
||||
Ця функція **не повинна знати** про Milvus/Neo4j — лише повертати список `IngestChunk`.
|
||||
|
||||
### 1.3. Інтеграція в consumer
|
||||
|
||||
У `services/rag-ingest-worker/events/consumer.py` (або де знаходиться логіка підписки на NATS):
|
||||
|
||||
- Додати підписку на subject / stream, де живуть `message.created`.
|
||||
- У callback’і:
|
||||
- Парсити JSON event.
|
||||
- Якщо `event_type == "message.created"`:
|
||||
- Викликати `normalize_message_created(event)` → `chunks`.
|
||||
- Якщо `chunks` непорожні:
|
||||
- Пустити їх через `embedding.embed_chunks(chunks)`.
|
||||
- Далі через `index_milvus.upsert_chunks_to_milvus(...)`.
|
||||
- (Опційно) якщо потрібно, зробити `index_neo4j.update_graph_for_event(event, chunks)`.
|
||||
|
||||
Додати логи:
|
||||
|
||||
- `logger.info("Ingested message.created", extra={"team_id": ..., "chunks": len(chunks)})`.
|
||||
|
||||
Уважно обробити винятки (catch, log, ack або nack за обраною семантикою).
|
||||
|
||||
---
|
||||
|
||||
## 2. Подія `doc.upsert`
|
||||
|
||||
### 2.1. Очікуваний формат події
|
||||
|
||||
Аналогічно, з Event Catalog, `doc.upsert` може виглядати так:
|
||||
|
||||
```json
|
||||
{
|
||||
"event_type": "doc.upsert",
|
||||
"event_id": "evt_456",
|
||||
"occurred_at": "2024-11-17T10:05:00Z",
|
||||
"team_id": "dao_greenfood",
|
||||
"user_id": "user:abc",
|
||||
"agent_id": "doc_agent",
|
||||
"payload": {
|
||||
"doc_id": "doc_123",
|
||||
"title": "Spec RAG Gateway",
|
||||
"text": "Довгий текст документа...",
|
||||
"url": "https://daarion.city/docs/doc_123",
|
||||
"tags": ["rag", "architecture"],
|
||||
"visibility": "public",
|
||||
"doc_type": "wiki"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2. Нормалізація у `IngestChunk`
|
||||
|
||||
У `pipeline/normalization.py` додати/оновити:
|
||||
|
||||
```python
|
||||
async def normalize_doc_upsert(event: dict) -> list[IngestChunk]:
|
||||
...
|
||||
```
|
||||
|
||||
Правила:
|
||||
|
||||
- Якщо `payload.text` дуже довгий — розбити на чанки (наприклад, по 512–1024 токени/символи).
|
||||
- Для кожного чанку створити `IngestChunk`:
|
||||
|
||||
- `chunk_id` = `f"doc:{team_id}:{doc_id}:{chunk_index}"` → захешувати.
|
||||
- `team_id` = `event.team_id`.
|
||||
- `source_type` = `payload.doc_type` або `"doc"`.
|
||||
- `source_id` = `payload.doc_id`.
|
||||
- `text` = текст чанку.
|
||||
- `tags` = `payload.tags` + `payload.doc_type`.
|
||||
- `visibility` = `payload.visibility`.
|
||||
- `created_at` = `event.occurred_at`.
|
||||
- За бажанням додати `project_id` / `channel_id`, якщо вони є.
|
||||
|
||||
Ця функція також **не індексує** нічого безпосередньо, лише повертає список чанків.
|
||||
|
||||
### 2.3. Інтеграція в consumer
|
||||
|
||||
В `events/consumer.py` (або еквівалентному модулі):
|
||||
|
||||
- Додати обробку `event_type == "doc.upsert"` аналогічно до `message.created`:
|
||||
- `normalize_doc_upsert(event)` → `chunks`.
|
||||
- `embed_chunks(chunks)` → вектори.
|
||||
- `upsert_chunks_to_milvus(...)`.
|
||||
- `update_graph_for_event(event, chunks)` — створити/оновити вузол `(:Doc)` і звʼязки, наприклад:
|
||||
- `(:Doc {doc_id})-[:MENTIONS]->(:Topic)`
|
||||
- `(:Doc)-[:BELONGS_TO]->(:MicroDAO)` тощо.
|
||||
|
||||
---
|
||||
|
||||
## 3. Ідемпотентність
|
||||
|
||||
Для обох подій (`message.created`, `doc.upsert`) забезпечити, щоб **повторне програвання** тієї ж події не створювало дублікатів:
|
||||
|
||||
- Використовувати `chunk_id` як primary key в Milvus (idempotent upsert).
|
||||
- Для Neo4j використовувати `MERGE` на основі унікальних ключів вузлів/ребер (наприклад, `doc_id`, `team_id`, `source_type`, `source_id`, `chunk_index`).
|
||||
|
||||
Якщо вже закладено idempotent behavior в `index_milvus.py` / `index_neo4j.py`, просто використати ці поля.
|
||||
|
||||
---
|
||||
|
||||
## 4. Тестування
|
||||
|
||||
Перед тим, як вважати інтеграцію готовою, бажано:
|
||||
|
||||
1. Написати мінімальні unit‑тести / doctest’и для `normalize_message_created` і `normalize_doc_upsert` (навіть якщо без повноцінної CI):
|
||||
- Вхідний event → список `IngestChunk` з очікуваними полями.
|
||||
|
||||
2. Зробити простий manual test:
|
||||
- Опублікувати штучну `message.created` у dev‑stream.
|
||||
- Переконатися по логах воркера, що:
|
||||
- нормалізація відбулась,
|
||||
- чанк(и) відправлені в embedding і Milvus,
|
||||
- запис зʼявився в Milvus/Neo4j (якщо є доступ).
|
||||
|
||||
---
|
||||
|
||||
## Files to touch (suggested)
|
||||
|
||||
> Шлях та назви можна адаптувати до фактичної структури, але головна ідея — рознести відповідальності.
|
||||
|
||||
- `services/rag-ingest-worker/events/consumer.py`
|
||||
- Додати підписки/обробники для `message.created` і `doc.upsert`.
|
||||
- Виклики до `normalize_message_created` / `normalize_doc_upsert` + пайплайн embedding/indexing.
|
||||
|
||||
- `services/rag-ingest-worker/pipeline/normalization.py`
|
||||
- Додати/оновити функції:
|
||||
- `normalize_message_created(event)`
|
||||
- `normalize_doc_upsert(event)`
|
||||
|
||||
- (Опційно) `services/rag-ingest-worker/pipeline/index_neo4j.py`
|
||||
- Додати/оновити логіку побудови графових вузлів/ребер для `Doc`, `Topic`, `Channel`, `MicroDAO` тощо.
|
||||
|
||||
- Тести / приклади (якщо є тестовий пакет для сервісу).
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. RAG‑ingest worker підписаний на події типу `message.created` і `doc.upsert` (через NATS або інший bus), принаймні в dev‑конфігурації.
|
||||
|
||||
2. Для `message.created` та `doc.upsert` існують функції нормалізації, які повертають `IngestChunk` з коректними полями (`team_id`, `source_type`, `source_id`, `visibility`, `tags`, `created_at`, тощо).
|
||||
|
||||
3. Чанки для цих подій проходять через embedding‑пайплайн і індексуються в Milvus з ідемпотентною семантикою.
|
||||
|
||||
4. (За можливості) для `doc.upsert` оновлюється Neo4j граф (вузол `Doc` + базові звʼязки).
|
||||
|
||||
5. Повторне надсилання однієї й тієї ж події не створює дублікатів у Milvus/Neo4j (idempotent behavior).
|
||||
|
||||
6. Можна побачити в логах воркера, що події споживаються і конвеєр відпрацьовує (інформаційні логи з team_id, event_type, chunks_count).
|
||||
|
||||
7. Цей файл (`docs/cursor/rag_ingestion_events_task.md`) можна виконати через Cursor:
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/rag_ingestion_events_task.md
|
||||
```
|
||||
|
||||
і Cursor буде використовувати його як єдине джерело правди для інтеграції подій `message.created`/`doc.upsert` у ingestion‑воркер.
|
||||
259
docs/cursor/rag_ingestion_events_wave1_mvp_task.md
Normal file
259
docs/cursor/rag_ingestion_events_wave1_mvp_task.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Task: RAG ingestion — Wave 1 (Chat messages, Docs, Files)
|
||||
|
||||
## Goal
|
||||
|
||||
Підключити **першу хвилю** RAG-ingestion подій до `rag-ingest-worker`, щоб агенти могли робити RAG по:
|
||||
|
||||
- чат-повідомленнях (`message.created`),
|
||||
- документах/wiki (`doc.upserted`),
|
||||
- файлах (`file.uploaded`),
|
||||
|
||||
з урахуванням режимів `public/confidential` та прапору `indexed`.
|
||||
|
||||
Wave 1 = **MVP RAG**: максимум корисного контексту при мінімальній кількості подій.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Root: `microdao-daarion/`.
|
||||
- Базовий воркер: `docs/cursor/rag_ingestion_worker_task.md`.
|
||||
- Подробиці для перших подій: `docs/cursor/rag_ingestion_events_task.md` (message/doc → IngestChunk).
|
||||
- Event Catalog: `docs/cursor/42_nats_event_streams_and_event_catalog.md`.
|
||||
- Privacy/Confidential:
|
||||
- `docs/cursor/47_messaging_channels_and_privacy_layers.md`
|
||||
- `docs/cursor/48_teams_access_control_and_confidential_mode.md`
|
||||
|
||||
Ingestion-воркер читає події з NATS JetStream (streams типу `STREAM_CHAT`, `STREAM_PROJECT`, `STREAM_TASK` або `teams.*` outbox — згідно актуальної конфігурації).
|
||||
|
||||
---
|
||||
|
||||
## 1. Принципи для Wave 1
|
||||
|
||||
1. **Тільки доменні події**, не CRUD по БД:
|
||||
- `message.created`, `doc.upserted`, `file.uploaded`.
|
||||
2. **Поважати `mode` та `indexed`:**
|
||||
- індексувати тільки якщо `indexed = true`;
|
||||
- plaintext зберігати тільки для `public` (для `confidential` — embeddings/summary без відкритого тексту, згідно політики).
|
||||
3. **Мінімальний, але стандартний payload:**
|
||||
- `team_id`, `channel_id` або `project_id`,
|
||||
- `mode` (`public | confidential`),
|
||||
- `author_user_id` / `author_agent_id`,
|
||||
- `created_at` / `updated_at`,
|
||||
- `kind` / `doc_type`,
|
||||
- `indexed` (bool),
|
||||
- `source_ref` (ID оригінальної сутності).
|
||||
|
||||
Ці принципи мають бути відображені як у **схемах подій**, так і в **нормалізації → IngestChunk**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Event contracts (Wave 1)
|
||||
|
||||
### 2.1. `message.created`
|
||||
|
||||
Джерело: Messaging service (`STREAM_CHAT` / outbox для командних просторів).
|
||||
|
||||
Використати Event Envelope з `42_nats_event_streams_and_event_catalog.md`, але уточнити payload для RAG:
|
||||
|
||||
- Subject/type (рекомендовано): `chat.message.created`.
|
||||
- Envelope:
|
||||
- `meta.team_id` — DAO / команда.
|
||||
- `payload.message_id`.
|
||||
- `payload.channel_id`.
|
||||
- `payload.author_user_id` або `payload.author_agent_id`.
|
||||
- `payload.mode`: `public | confidential`.
|
||||
- `payload.kind`: `text | image | file | system`.
|
||||
- `payload.thread_id` (optional).
|
||||
- `payload.created_at`.
|
||||
- `payload.indexed`: bool (derived: mode + налаштування каналу).
|
||||
- `payload.text_summary` / `payload.text_plain` (залежно від політики збереження plaintext).
|
||||
|
||||
**RAG-правила:**
|
||||
|
||||
- індексувати тільки якщо `payload.indexed = true`;
|
||||
- якщо `kind != "text"` — пропускати в Wave 1 (image/audio/pdf покриваються через `file.uploaded`);
|
||||
- якщо `mode = "confidential"` — не зберігати plaintext в Milvus metadata, тільки embeddings + мінімальні метадані.
|
||||
|
||||
### 2.2. `doc.upserted`
|
||||
|
||||
Джерело: Docs/Wiki/Co-Memory сервіс (`STREAM_PROJECT` або окремий docs-stream).
|
||||
|
||||
Рекомендований payload для RAG:
|
||||
|
||||
- `payload.doc_id`
|
||||
- `payload.team_id`
|
||||
- `payload.project_id`
|
||||
- `payload.path` (wiki path/tree)
|
||||
- `payload.title`
|
||||
- `payload.text` (може бути великий)
|
||||
- `payload.mode`: `public | confidential`
|
||||
- `payload.indexed`: bool
|
||||
- `payload.labels` / `payload.tags` (optional)
|
||||
- `payload.updated_at`
|
||||
|
||||
**RAG-правила:**
|
||||
|
||||
- індексувати тільки якщо `indexed = true`;
|
||||
- для великих текстів — розбивати на чанки (512–1024 символів/токенів);
|
||||
- `mode = "confidential"` → embeddings без відкритого тексту.
|
||||
|
||||
### 2.3. `file.uploaded`
|
||||
|
||||
Джерело: Files/Co-Memory (`files` таблиця, окремий стрім або частина STREAM_PROJECT/STREAM_CHAT).
|
||||
|
||||
Рекомендований payload:
|
||||
|
||||
- `payload.file_id`
|
||||
- `payload.owner_team_id`
|
||||
- `payload.size`
|
||||
- `payload.mime`
|
||||
- `payload.storage_key`
|
||||
- `payload.mode`: `public | confidential`
|
||||
- `payload.indexed`: bool
|
||||
- `payload.enc`: bool (чи зашифрований в storage)
|
||||
- `payload.linked_to`: `{message_id|project_id|doc_id}`
|
||||
- `payload.extracted_text_ref` (ключ до вже пропаршеного тексту, якщо є)
|
||||
|
||||
**RAG-правила:**
|
||||
|
||||
- індексувати тільки якщо `indexed = true` та `mime` ∈ текстових/документних форматів (`text/*`, `application/pdf`, `markdown`, тощо);
|
||||
- якщо текст ще не витягнутий — створити ingestion-джоб (черга/OCR) і не індексувати до появи `file.text_parsed`/`file.text_ready` (це може бути окремий event у Wave 1 або 1.5).
|
||||
|
||||
---
|
||||
|
||||
## 3. Зміни в `rag-ingest-worker`
|
||||
|
||||
### 3.1. Routing / підписки
|
||||
|
||||
У `services/rag-ingest-worker/events/consumer.py`:
|
||||
|
||||
1. Додати (або уточнити) підписки на subjects для Wave 1:
|
||||
- `chat.message.created`
|
||||
- `doc.upserted` (назву узгодити з фактичним стрімом — напр. `project.doc.upserted`)
|
||||
- `file.uploaded`
|
||||
2. Ввести **routing таблицю** (може бути dict):
|
||||
|
||||
- `"chat.message.created" → handle_message_created`
|
||||
- `"doc.upserted" → handle_doc_upserted`
|
||||
- `"file.uploaded" → handle_file_uploaded`
|
||||
|
||||
3. Кожен handler повинен:
|
||||
- розпарсити envelope (`event`, `meta.team_id`, `payload`),
|
||||
- перевірити `indexed` та `mode`,
|
||||
- викликати відповідну функцію нормалізації з `pipeline/normalization.py`,
|
||||
- віддати chunks в embedding + Milvus + Neo4j.
|
||||
|
||||
### 3.2. Нормалізація у `pipeline/normalization.py`
|
||||
|
||||
Розширити/уточнити:
|
||||
|
||||
- `async def normalize_message_created(event: dict) -> list[IngestChunk]:`
|
||||
- орієнтуватися на схему з `rag_ingestion_events_task.md` + тепер **додати перевірку `indexed`/`mode`**;
|
||||
- повертати 0 чанків, якщо `indexed = false` або `kind != "text"`.
|
||||
|
||||
- `async def normalize_doc_upserted(event: dict) -> list[IngestChunk]:`
|
||||
- аналогічно до `normalize_doc_upsert` з `rag_ingestion_events_task.md`, але з полями `indexed`, `mode`, `labels`;
|
||||
- розбивати довгі тексти.
|
||||
|
||||
- `async def normalize_file_uploaded(event: dict) -> list[IngestChunk]:`
|
||||
- якщо текст уже доступний (через `extracted_text_ref` або інший сервіс) — розбити на чанки;
|
||||
- якщо ні — поки що повертати `[]` і логувати TODO (інтеграція з parser/Co-Memory).
|
||||
|
||||
У всіх нормалізаторах стежити, щоб:
|
||||
|
||||
- `chunk_id` був детермінованим (див. `rag_ingestion_worker_task.md`),
|
||||
- `visibility` / `mode` коректно мапились (public/confidential),
|
||||
- `source_type` ∈ {`"message"`, `"doc"`, `"file"`},
|
||||
- метадані включали `team_id`, `channel_id`/`project_id`, `author_id`, `created_at`.
|
||||
|
||||
### 3.3. Embeddings + Milvus/Neo4j
|
||||
|
||||
У Wave 1 достатньо:
|
||||
|
||||
- використовувати вже існуючі пайплайни з `rag_ingestion_worker_task.md`:
|
||||
- `embedding.embed_chunks(chunks)`
|
||||
- `index_milvus.upsert_chunks_to_milvus(...)`
|
||||
- `index_neo4j.update_graph_for_event(event, chunks)` (мінімальний граф: User–Message–Channel, Project–Doc, File–(Message|Doc|Project)).
|
||||
|
||||
Головне — **ідемпотентний upsert** по `chunk_id` (Milvus) та `MERGE` в Neo4j.
|
||||
|
||||
---
|
||||
|
||||
## 4. Узгодження з Meilisearch indexer
|
||||
|
||||
Хоча цей таск фокусується на RAG (Milvus/Neo4j), потрібно:
|
||||
|
||||
1. Переконатися, що логіка `indexed`/`mode` **співпадає** з існуючим search-indexer (Meilisearch) для:
|
||||
- `chat.message.created` / `chat.message.updated`,
|
||||
- `doc.upserted`,
|
||||
- `file.uploaded` (якщо вже індексується).
|
||||
2. По можливості, винести спільну функцію/константу для визначення `indexed` (based on channel/project settings), щоб RAG та Meilisearch не роз’їхались.
|
||||
|
||||
---
|
||||
|
||||
## 5. Тестування
|
||||
|
||||
Мінімальний набір тестів (unit/integration):
|
||||
|
||||
1. **Unit:**
|
||||
- `normalize_message_created`:
|
||||
- `indexed=false` → `[]`;
|
||||
- `kind != "text"` → `[]`;
|
||||
- `mode=public/indexed=true` → валідні `IngestChunk` з текстом;
|
||||
- `mode=confidential/indexed=true` → валідні `IngestChunk` без plaintext у метаданих.
|
||||
- `normalize_doc_upserted`:
|
||||
- довгий текст → декілька чанків з коректними `chunk_id`;
|
||||
- `indexed=false` → `[]`.
|
||||
- `normalize_file_uploaded`:
|
||||
- текст доступний → чанки;
|
||||
- текст недоступний → `[]` + лог.
|
||||
|
||||
2. **Integration (dev):**
|
||||
- опублікувати test-event `chat.message.created` у dev-стрім;
|
||||
- перевірити по логах, що воркер:
|
||||
- спожив подію,
|
||||
- зробив N чанків,
|
||||
- відправив їх у embedding + Milvus;
|
||||
- повторно відправити **ту ж саму** подію і переконатися, що дублікатів у Milvus немає.
|
||||
|
||||
---
|
||||
|
||||
## Files to create/modify (suggested)
|
||||
|
||||
> Актуальні шляхи можуть трохи відрізнятися — орієнтуйся по існуючому `rag-ingest-worker`.
|
||||
|
||||
- `services/rag-ingest-worker/events/consumer.py`
|
||||
- додати routing для `chat.message.created`, `doc.upserted`, `file.uploaded`;
|
||||
- для кожної події — handler з перевіркою `indexed`/`mode` та викликом нормалізатора.
|
||||
|
||||
- `services/rag-ingest-worker/pipeline/normalization.py`
|
||||
- реалізувати/оновити:
|
||||
- `normalize_message_created(event)`
|
||||
- `normalize_doc_upserted(event)`
|
||||
- `normalize_file_uploaded(event)`
|
||||
|
||||
- (за потреби) `services/rag-ingest-worker/pipeline/index_neo4j.py`
|
||||
- оновити побудову графових вузлів/ребер для Message/Doc/File.
|
||||
|
||||
- Тести для нормалізаторів (якщо є тестовий пакет).
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. `rag-ingest-worker` підписаний на Wave 1 події (`chat.message.created`, `doc.upserted`, `file.uploaded`) у dev-конфігурації.
|
||||
2. Для кожної події є нормалізатор, який:
|
||||
- поважає `mode` та `indexed`;
|
||||
- повертає коректні `IngestChunk` з потрібними полями.
|
||||
3. Чанки успішно проходять через embedding-пайплайн і індексуються в Milvus з ідемпотентною семантикою (`chunk_id`).
|
||||
4. Neo4j отримує хоча б базові вузли/ребра для Message/Doc/File.
|
||||
5. Повторне програвання тих самих подій **не створює дублікатів** у Milvus/Neo4j.
|
||||
6. Логіка `indexed`/`mode` для RAG узгоджена з Meilisearch search-indexer.
|
||||
7. Цей файл (`docs/cursor/rag_ingestion_events_wave1_mvp_task.md`) можна виконати через Cursor:
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/rag_ingestion_events_wave1_mvp_task.md
|
||||
```
|
||||
|
||||
і Cursor використовує його як джерело правди для реалізації Wave 1 RAG-ingestion.
|
||||
243
docs/cursor/rag_ingestion_events_wave2_workflows_task.md
Normal file
243
docs/cursor/rag_ingestion_events_wave2_workflows_task.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Task: RAG ingestion — Wave 2 (Tasks, Followups, Meetings)
|
||||
|
||||
## Goal
|
||||
|
||||
Підключити **другу хвилю** подій до RAG-ingestion воркера, щоб агенти могли робити запити типу:
|
||||
|
||||
- "які активні задачі по цій темі?",
|
||||
- "які follow-ups висять після цього меседжа?",
|
||||
- "що вирішили/обговорювали на останній зустрічі?".
|
||||
|
||||
Wave 2 зʼєднує чат/документи (Wave 1) із **workflow-обʼєктами**: tasks, followups, meetings.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Root: `microdao-daarion/`.
|
||||
- RAG gateway: `docs/cursor/rag_gateway_task.md`.
|
||||
- RAG ingestion worker: `docs/cursor/rag_ingestion_worker_task.md`.
|
||||
- Wave 1 (chat/docs/files): `docs/cursor/rag_ingestion_events_wave1_mvp_task.md`.
|
||||
- Event Catalog: `docs/cursor/42_nats_event_streams_and_event_catalog.md` (STREAM_TASK, STREAM_CHAT, STREAM_PROJECT).
|
||||
- Governance/workflows контекст: `docs/cursor/23_domains_wallet_dao_deepdive.md` (якщо є).
|
||||
|
||||
Принципи такі ж, як у Wave 1: **доменні події**, `mode` + `indexed`, єдиний формат `IngestChunk`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Події Wave 2
|
||||
|
||||
### 1.1. `task.created` / `task.updated`
|
||||
|
||||
Сутність: `tasks` (Kanban/Project-борди).
|
||||
|
||||
Події (STREAM_TASK):
|
||||
|
||||
- `task.created`
|
||||
- `task.updated`
|
||||
- (опційно) `task.completed`
|
||||
|
||||
Рекомендований RAG-пейлоад:
|
||||
|
||||
- `payload.task_id`
|
||||
- `payload.team_id`
|
||||
- `payload.project_id`
|
||||
- `payload.title`
|
||||
- `payload.description` (опційно, короткий текст)
|
||||
- `payload.status`: `open|in_progress|done|archived`
|
||||
- `payload.labels`: список тегів
|
||||
- `payload.assignees`: список `user_id`
|
||||
- `payload.priority` (low/medium/high)
|
||||
- `payload.due` (optional)
|
||||
- `payload.mode`: `public|confidential`
|
||||
- `payload.indexed`: bool
|
||||
- `payload.created_at`, `payload.updated_at`
|
||||
|
||||
**RAG-правила:**
|
||||
|
||||
- індексувати, якщо `indexed = true` (за замовчуванням — true для public-проєктів);
|
||||
- текст = `title + короткий description` (до ~500 символів) — цього достатньо для пошуку задач;
|
||||
- для `confidential` — embeddings без plaintext.
|
||||
|
||||
### 1.2. `followup.created` / `followup.status_changed`
|
||||
|
||||
Сутність: followups/reminders, привʼязані до `src_message_id`.
|
||||
|
||||
Події (STREAM_TASK або окремий STREAM_FOLLOWUP, якщо є):
|
||||
|
||||
- `followup.created`
|
||||
- `followup.status_changed`
|
||||
|
||||
Пейлоад:
|
||||
|
||||
- `payload.followup_id`
|
||||
- `payload.team_id`
|
||||
- `payload.owner_user_id`
|
||||
- `payload.src_message_id`
|
||||
- `payload.title`
|
||||
- `payload.description` (опційно)
|
||||
- `payload.status`: `open|done|cancelled`
|
||||
- `payload.due` (optional)
|
||||
- `payload.mode`: `public|confidential`
|
||||
- `payload.indexed`: bool (за замовчуванням true для public-командних просторів)
|
||||
- `payload.created_at`, `payload.updated_at`
|
||||
|
||||
**RAG-правила:**
|
||||
|
||||
- індексувати тільки `followup.created` (створення сутності) + оновлювати метадані по `status_changed` (без нового chunk);
|
||||
- текст = `title + короткий description`;
|
||||
- важливий звʼязок з `Message` через `src_message_id`.
|
||||
|
||||
### 1.3. `meeting.created` / `meeting.summary.upserted`
|
||||
|
||||
Сутність: meetings (зустрічі, дзвінки, сесії).
|
||||
|
||||
Події (STREAM_PROJECT або окремий STREAM_MEETING):
|
||||
|
||||
- `meeting.created` — тільки метадані (час, учасники, посилання).
|
||||
- `meeting.summary.upserted` — резюме/протокол зустрічі (AI-нотатки або вручну).
|
||||
|
||||
Пейлоад для `meeting.created` (мінімально для графу):
|
||||
|
||||
- `payload.meeting_id`
|
||||
- `payload.team_id`
|
||||
- `payload.project_id` (optional)
|
||||
- `payload.title`
|
||||
- `payload.start_at`, `payload.end_at`
|
||||
- `payload.participant_ids` (user_id/agent_id)
|
||||
- `payload.mode`, `payload.indexed`
|
||||
|
||||
Пейлоад для `meeting.summary.upserted` (RAG):
|
||||
|
||||
- `payload.meeting_id` (link до `meeting.created`)
|
||||
- `payload.team_id`
|
||||
- `payload.project_id` (optional)
|
||||
- `payload.summary_text` (достатньо 1–4 абзаци)
|
||||
- `payload.tags` (topics/labels)
|
||||
- `payload.mode`, `payload.indexed`
|
||||
- `payload.updated_at`
|
||||
|
||||
**RAG-правила:**
|
||||
|
||||
- індексувати **summary**, а не raw-транскрипт;
|
||||
- summary розбивати на 1–N чанків, якщо дуже довге.
|
||||
|
||||
---
|
||||
|
||||
## 2. Mapping → IngestChunk
|
||||
|
||||
У `services/rag-ingest-worker/pipeline/normalization.py` додати:
|
||||
|
||||
- `async def normalize_task_event(event: dict) -> list[IngestChunk]:`
|
||||
- `async def normalize_followup_event(event: dict) -> list[IngestChunk]:`
|
||||
- `async def normalize_meeting_summary(event: dict) -> list[IngestChunk]:`
|
||||
|
||||
### 2.1. Tasks
|
||||
|
||||
Для `task.created`/`task.updated`:
|
||||
|
||||
- `source_type = "task"`.
|
||||
- `source_id = payload.task_id`.
|
||||
- `text = f"{title}. {short_description}"` (обрізати description до розумної довжини).
|
||||
- `chunk_id` — детермінований, напр. `"task:{team_id}:{task_id}"` (без chunk_index, бо один chunk).
|
||||
- `tags` = `labels` + `status` + `priority`.
|
||||
- `visibility` = `mode`.
|
||||
- `project_id = payload.project_id`.
|
||||
- `team_id = payload.team_id`.
|
||||
|
||||
Якщо `indexed=false` або task у статусі `archived` — можна не індексувати (або зберігати в окремому шарі).
|
||||
|
||||
### 2.2. Followups
|
||||
|
||||
- `source_type = "followup"`.
|
||||
- `source_id = payload.followup_id`.
|
||||
- `text = f"{title}. {short_description}"`.
|
||||
- `chunk_id = f"followup:{team_id}:{followup_id}"`.
|
||||
- `tags` включають `status` +, за потреби, тип followup.
|
||||
- важливо включити `src_message_id` у metadata (`message_id` або `source_ref`).
|
||||
|
||||
Для `status_changed` оновлювати тільки metadata (через повторний upsert з новим `status`), не створюючи нові chunks.
|
||||
|
||||
### 2.3. Meeting summaries
|
||||
|
||||
Для `meeting.summary.upserted`:
|
||||
|
||||
- `source_type = "meeting"`.
|
||||
- `source_id = payload.meeting_id`.
|
||||
- `text = summary_text` (розбити на декілька чанків, якщо потрібно).
|
||||
- `chunk_id = f"meeting:{team_id}:{meeting_id}:{chunk_index}"` (з chunk_index).
|
||||
- `tags` = `payload.tags` + ["meeting"].
|
||||
- `visibility` = `mode`.
|
||||
- `team_id = payload.team_id`.
|
||||
- `project_id = payload.project_id`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Зміни в `rag-ingest-worker`
|
||||
|
||||
### 3.1. Routing / handler-и
|
||||
|
||||
У `services/rag-ingest-worker/events/consumer.py` додати routing:
|
||||
|
||||
- `"task.created"`, `"task.updated"` → `handle_task_event`
|
||||
- `"followup.created"`, `"followup.status_changed"` → `handle_followup_event`
|
||||
- `"meeting.summary.upserted"` → `handle_meeting_summary`
|
||||
|
||||
Handler-и повинні:
|
||||
|
||||
1. Розпарсити envelope (event, meta.team_id, payload).
|
||||
2. Перевірити `mode` + `indexed`.
|
||||
3. Викликати відповідний нормалізатор.
|
||||
4. Якщо список chunks не пустий:
|
||||
- `embedding.embed_chunks(chunks)`
|
||||
- `index_milvus.upsert_chunks_to_milvus(...)`
|
||||
- `index_neo4j.update_graph_for_event(event, chunks)`.
|
||||
|
||||
### 3.2. Neo4j граф (workflow-шар)
|
||||
|
||||
Розширити `pipeline/index_neo4j.py` для створення вузлів/ребер:
|
||||
|
||||
- `(:Task)-[:IN_PROJECT]->(:Project)`
|
||||
- `(:User)-[:ASSIGNED_TO]->(:Task)`
|
||||
- `(:Followup)-[:FROM_MESSAGE]->(:Message)`
|
||||
- `(:User)-[:OWNER]->(:Followup)`
|
||||
- `(:Meeting)-[:IN_PROJECT]->(:Project)`
|
||||
- `(:Meeting)-[:PARTICIPANT]->(:User|:Agent)`
|
||||
|
||||
Усі операції — через `MERGE` з урахуванням `team_id`/`visibility`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Тести
|
||||
|
||||
Мінімум unit-тестів для нормалізаторів:
|
||||
|
||||
- `normalize_task_event` — створює 1 chunk з правильними метаданими; `indexed=false` → `[]`.
|
||||
- `normalize_followup_event` — включає `src_message_id` у metadata; `status_changed` не створює новий chunk.
|
||||
- `normalize_meeting_summary` — розбиває довгий summary на декілька чанків з правильними `chunk_id`.
|
||||
|
||||
Інтеграційно (dev):
|
||||
|
||||
- штучно опублікувати `task.created`, `followup.created`, `meeting.summary.upserted`;
|
||||
- перевірити в логах воркера, що:
|
||||
- події спожиті,
|
||||
- chunks згенеровані,
|
||||
- індексовані в Milvus (і немає дублікатів при повторі);
|
||||
- у Neo4j зʼявились базові вузли/ребра.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. `rag-ingest-worker` обробляє події Wave 2 (`task.*`, `followup.*`, `meeting.*`) у dev-конфігурації.
|
||||
2. Для tasks/followups/meetings існують нормалізатори, що повертають коректні `IngestChunk` з урахуванням `mode`/`indexed`.
|
||||
3. Чанки індексуються в Milvus з ідемпотентним `chunk_id`.
|
||||
4. Neo4j містить базовий workflow-граф (Task/Followup/Meeting, звʼязаний з Project, User, Message).
|
||||
5. Повторне програвання подій не створює дублікатів у Milvus/Neo4j.
|
||||
6. Цей файл (`docs/cursor/rag_ingestion_events_wave2_workflows_task.md`) виконується через Cursor:
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/rag_ingestion_events_wave2_workflows_task.md
|
||||
```
|
||||
|
||||
і стає джерелом правди для Wave 2 RAG-ingestion.
|
||||
216
docs/cursor/rag_ingestion_events_wave3_governance_rwa_task.md
Normal file
216
docs/cursor/rag_ingestion_events_wave3_governance_rwa_task.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# Task: RAG ingestion — Wave 3 (Governance, Votes, Rewards, Oracle/RWA)
|
||||
|
||||
## Goal
|
||||
|
||||
Підключити **третю хвилю** подій до RAG-ingestion воркера:
|
||||
|
||||
- governance (proposals, decisions),
|
||||
- голосування (votes),
|
||||
- винагороди/пейаути (rewards/payouts),
|
||||
- oracle/RWA-події (агреговані знання про енергію/їжу/воду).
|
||||
|
||||
Wave 3 — це вже **meta-рівень DAO**: історія рішень, токен-економіка, агреговані показники.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Root: `microdao-daarion/`.
|
||||
- RAG gateway: `docs/cursor/rag_gateway_task.md`.
|
||||
- RAG ingestion worker: `docs/cursor/rag_ingestion_worker_task.md`.
|
||||
- Попередні хвилі:
|
||||
- Wave 1 (chat/docs/files): `docs/cursor/rag_ingestion_events_wave1_mvp_task.md`.
|
||||
- Wave 2 (tasks/followups/meetings): `docs/cursor/rag_ingestion_events_wave2_workflows_task.md`.
|
||||
- Event Catalog: `docs/cursor/42_nats_event_streams_and_event_catalog.md` (STREAM_GOVERNANCE, STREAM_RWA, STREAM_PAYOUT, STREAM_ORACLE, STREAM_USAGE).
|
||||
- Governance/Tokenomics:
|
||||
- `docs/cursor/31_governance_policies_for_capabilities_and_quotas.md`
|
||||
- `docs/cursor/49_wallet_rwa_payouts_claims.md`
|
||||
- `docs/cursor/40_rwa_energy_food_water_flow_specs.md`.
|
||||
|
||||
Головний принцип: **не індексувати всі сирі події RWA/oracle**, а працювати з узагальненими snapshot’ами / summary.
|
||||
|
||||
---
|
||||
|
||||
## 1. Governance & proposals
|
||||
|
||||
### 1.1. `governance.proposal.created` / `governance.proposal.closed`
|
||||
|
||||
STREAM_GOVERNANCE, типи:
|
||||
|
||||
- `governance.proposal.created`
|
||||
- `governance.proposal.closed`
|
||||
|
||||
Рекомендований RAG-пейлоад:
|
||||
|
||||
- `payload.proposal_id`
|
||||
- `payload.team_id`
|
||||
- `payload.title`
|
||||
- `payload.body` (текст пропозиції)
|
||||
- `payload.author_user_id`
|
||||
- `payload.status`: `open|passed|rejected|withdrawn`
|
||||
- `payload.tags` (optional)
|
||||
- `payload.mode`: `public|confidential`
|
||||
- `payload.indexed`: bool (за замовчуванням true для public DAO)
|
||||
- `payload.created_at`, `payload.closed_at`
|
||||
|
||||
**RAG-правила:**
|
||||
|
||||
- індексувати текст пропозиції (`title + body`) як `doc_type = "proposal"`;
|
||||
- `proposal.closed` оновлює статус у metadata (через upsert).
|
||||
|
||||
Mapping → `IngestChunk`:
|
||||
|
||||
- `source_type = "proposal"`.
|
||||
- `source_id = proposal_id`.
|
||||
- `text = title + short(body)` (обрізати або chunk-нути по 512–1024 символів).
|
||||
- `chunk_id = f"proposal:{team_id}:{proposal_id}:{chunk_index}"`.
|
||||
- `tags` = `payload.tags` + `status`.
|
||||
- `visibility = mode`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Votes / Rewards
|
||||
|
||||
### 2.1. `governance.vote.cast`
|
||||
|
||||
Ці події важливі більше для **графу/аналітики**, ніж для Milvus.
|
||||
|
||||
Рекомендація:
|
||||
|
||||
- У Milvus:
|
||||
- не створювати окремих текстових чанків для кожного vote;
|
||||
- натомість — мати summary-документ (наприклад, у Co-Memory) з підсумками голосування (окремий таск).
|
||||
- У Neo4j:
|
||||
- створювати ребра `(:User)-[:VOTED {choice, weight}]->(:Proposal)`.
|
||||
|
||||
Пейлоад:
|
||||
|
||||
- `payload.vote_id`
|
||||
- `payload.team_id`
|
||||
- `payload.proposal_id`
|
||||
- `payload.user_id`
|
||||
- `payload.choice`: `yes|no|abstain|...`
|
||||
- `payload.weight`: число
|
||||
- `payload.ts`
|
||||
|
||||
### 2.2. Rewards / payouts (`payout.*`, `reward.*`)
|
||||
|
||||
STREAM_PAYOUT / STREAM_WALLET / STREAM_USAGE, події:
|
||||
|
||||
- `payout.generated`
|
||||
- `payout.claimed`
|
||||
- можливо `reward.assigned` (якщо буде виділена).
|
||||
|
||||
Ідея для RAG:
|
||||
|
||||
- Не індексувати кожен payout як окремий chunk;
|
||||
- натомість, періодично створювати (іншим сервісом) агреговані summary-документи:
|
||||
- "Payout history for user X",
|
||||
- "Rewards breakdown for project Y".
|
||||
|
||||
У рамках цієї Wave 3 задачі:
|
||||
|
||||
- Забезпечити Neo4j-вузли/ребра:
|
||||
- `(:Payout)-[:TO_USER]->(:User)`
|
||||
- `(:Payout)-[:FOR_TEAM]->(:MicroDAO)`
|
||||
- `(:Payout)-[:RELATED_TO]->(:Project|:RWAObject)`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Oracle / RWA events
|
||||
|
||||
STREAM_RWA, STREAM_ORACLE, STREAM_EMBASSY — висока частота подій.
|
||||
|
||||
### 3.1. Raw events
|
||||
|
||||
Сирі події (`rwa.inventory.updated`, `oracle.reading.published`, `embassy.energy.update`, ...) **не повинні** напряму летіти у Milvus як plain text — вони більше підходять для time-series/аналітики.
|
||||
|
||||
### 3.2. Aggregated RAG documents
|
||||
|
||||
Підхід:
|
||||
|
||||
1. Інший сервіс (або batch job) формує періодичні summary-документи, наприклад:
|
||||
- `rwa.daily_summary.created`
|
||||
- `rwa.weekly_report.created`
|
||||
2. Саме ці summary події підключаємо до RAG-ingestion як:
|
||||
- `source_type = "rwa_summary"` або `"oracle_summary"`.
|
||||
- текст = короткий опис ("Станція EU-KYIV-01 згенерувала 1.2 MWh цього тижня..."),
|
||||
- метадані: `site_id`, `domain`, `period_start`, `period_end`.
|
||||
|
||||
У цій задачі достатньо:
|
||||
|
||||
- додати підтримку абстрактних подій типу `rwa.summary.created` в нормалізаторі;
|
||||
- **не** впроваджувати саму агрегацію (окрема Cursor-задача).
|
||||
|
||||
---
|
||||
|
||||
## 4. Зміни в `rag-ingest-worker`
|
||||
|
||||
### 4.1. Normalization
|
||||
|
||||
У `services/rag-ingest-worker/pipeline/normalization.py` додати:
|
||||
|
||||
- `normalize_proposal_event(event: dict) -> list[IngestChunk]`
|
||||
- `normalize_rwa_summary_event(event: dict) -> list[IngestChunk]`
|
||||
|
||||
Для votes/payouts тут достатньо повернути `[]` (оскільки вони йдуть у Neo4j без текстових чанків), але:
|
||||
|
||||
- додати в `index_neo4j.update_graph_for_event` розгалуження по `event_type` для створення відповідних вузлів/ребер.
|
||||
|
||||
### 4.2. Routing
|
||||
|
||||
У `events/consumer.py` додати routing:
|
||||
|
||||
- `"governance.proposal.created"`, `"governance.proposal.closed"` → `handle_proposal_event` → `normalize_proposal_event` → Milvus + Neo4j.
|
||||
- `"governance.vote.cast"` → тільки Neo4j (без Milvus), через `update_graph_for_event`.
|
||||
- `"payout.generated"`, `"payout.claimed"` → тільки Neo4j.
|
||||
- `"rwa.summary.created"` (або аналогічні) → `handle_rwa_summary_event` → `normalize_rwa_summary_event`.
|
||||
|
||||
### 4.3. Neo4j
|
||||
|
||||
Розширити `pipeline/index_neo4j.py`:
|
||||
|
||||
- Governance:
|
||||
- `(:Proposal)` вузли з атрибутами `status`, `team_id`, `tags`.
|
||||
- `(:User)-[:VOTED {choice, weight}]->(:Proposal)`.
|
||||
- Payouts/Rewards:
|
||||
- `(:Payout)` вузли.
|
||||
- `(:Payout)-[:TO_USER]->(:User)`.
|
||||
- `(:Payout)-[:FOR_TEAM]->(:MicroDAO)`.
|
||||
- RWA/Oracle summaries:
|
||||
- `(:RWAObject {site_id})`.
|
||||
- `(:RWAObject)-[:HAS_SUMMARY]->(:RwaSummary {period_start, period_end})`.
|
||||
|
||||
Усі операції — через `MERGE`, з `team_id`/`domain`/`visibility` у властивостях.
|
||||
|
||||
---
|
||||
|
||||
## 5. Тести
|
||||
|
||||
Unit-тести:
|
||||
|
||||
- `normalize_proposal_event` — створює 1..N чанків із правильними `source_type`, `source_id`, `tags`, `visibility`.
|
||||
- `normalize_rwa_summary_event` — створює chunk з ключовими метаданими (`site_id`, `period`, `domain`).
|
||||
|
||||
Інтеграційно:
|
||||
|
||||
- опублікувати `governance.proposal.created` + `governance.proposal.closed` → переконатися, що Milvus і Neo4j оновились;
|
||||
- опублікувати кілька `governance.vote.cast` → перевірити граф голосувань у Neo4j;
|
||||
- опублікувати `rwa.summary.created` → перевірити, що зʼявився RWASummary у Milvus + Neo4j.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. `rag-ingest-worker` обробляє Wave 3 події в dev-конфігурації (governance, vote, payout, rwa/oracle summaries).
|
||||
2. Governance-пропозиції індексуються в Milvus як `doc_type = "proposal"` з коректними метаданими.
|
||||
3. Neo4j містить базовий governance-граф (Proposals, Votes, Payouts, RWAObjects).
|
||||
4. Oracle/RWA summary-події потрапляють у RAG як узагальнені знання, а не як сирі time-series.
|
||||
5. Ідемпотентність дотримана (replay тих самих подій не створює дублікатів).
|
||||
6. Цей файл (`docs/cursor/rag_ingestion_events_wave3_governance_rwa_task.md`) можна виконати через Cursor:
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/rag_ingestion_events_wave3_governance_rwa_task.md
|
||||
```
|
||||
|
||||
і він слугує джерелом правди для Wave 3 RAG-ingestion.
|
||||
260
docs/cursor/rag_ingestion_worker_task.md
Normal file
260
docs/cursor/rag_ingestion_worker_task.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# Task: RAG ingestion worker (events → Milvus + Neo4j)
|
||||
|
||||
## Goal
|
||||
|
||||
Design and scaffold a **RAG ingestion worker** that:
|
||||
|
||||
- Сonsumes domain events (messages, docs, files, RWA updates) from the existing event stream.
|
||||
- Transforms them into normalized chunks/documents.
|
||||
- Indexes them into **Milvus** (vector store) and **Neo4j** (graph store).
|
||||
- Works **idempotently** and supports `reindex(team_id)`.
|
||||
|
||||
This worker complements the `rag-gateway` service (see `docs/cursor/rag_gateway_task.md`) by keeping its underlying stores up-to-date.
|
||||
|
||||
> IMPORTANT: This task is about architecture, data flow and scaffolding. Concrete model choices and full schemas can be refined later.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
- Project root: `microdao-daarion/`.
|
||||
- Planned/implemented RAG layer: see `docs/cursor/rag_gateway_task.md`.
|
||||
- Existing docs:
|
||||
- `docs/cursor/42_nats_event_streams_and_event_catalog.md` – event stream & catalog.
|
||||
- `docs/cursor/34_internal_services_architecture.md` – internal services & topology.
|
||||
|
||||
We assume there is (or will be):
|
||||
|
||||
- An event bus (likely NATS) with domain events such as:
|
||||
- `message.created`
|
||||
- `doc.upsert`
|
||||
- `file.uploaded`
|
||||
- `rwa.energy.update`, `rwa.food.update`, etc.
|
||||
- A Milvus cluster instance.
|
||||
- A Neo4j instance.
|
||||
|
||||
The ingestion worker must **not** be called directly by agents. It is a back-office service that feeds RAG stores for the `rag-gateway`.
|
||||
|
||||
---
|
||||
|
||||
## High-level design
|
||||
|
||||
### 1. Service placement & structure
|
||||
|
||||
Create a new service (or extend RAG-gateway repo structure) under, for example:
|
||||
|
||||
- `services/rag-ingest-worker/`
|
||||
|
||||
Suggested files:
|
||||
|
||||
- `main.py` — entrypoint (CLI or long-running process).
|
||||
- `config.py` — environment/config loader (event bus URL, Milvus/Neo4j URLs, batch sizes, etc.).
|
||||
- `events/consumer.py` — NATS (or other) consumer logic.
|
||||
- `pipeline/normalization.py` — turn events into normalized documents/chunks.
|
||||
- `pipeline/embedding.py` — embedding model client/wrapper.
|
||||
- `pipeline/index_milvus.py` — Milvus upsert logic.
|
||||
- `pipeline/index_neo4j.py` — Neo4j graph updates.
|
||||
- `api.py` — optional HTTP API for:
|
||||
- `POST /ingest/one` – ingest single payload for debugging.
|
||||
- `POST /ingest/reindex/{team_id}` – trigger reindex job.
|
||||
- `GET /health` – health check.
|
||||
|
||||
### 2. Event sources
|
||||
|
||||
The worker should subscribe to a **small set of core event types** (names to be aligned with the actual Event Catalog):
|
||||
|
||||
- `message.created` — messages in chats/channels (Telegram, internal UI, etc.).
|
||||
- `doc.upsert` — wiki/docs/specs updates.
|
||||
- `file.uploaded` — files (PDF, images) that have parsed text.
|
||||
- `rwa.*` — events related to energy/food/water assets (optional, for later).
|
||||
|
||||
Implementation details:
|
||||
|
||||
- Use NATS (or another broker) subscription patterns from `docs/cursor/42_nats_event_streams_and_event_catalog.md`.
|
||||
- Each event should carry at least:
|
||||
- `event_type`
|
||||
- `team_id` / `dao_id`
|
||||
- `user_id`
|
||||
- `channel_id` / `project_id` (if applicable)
|
||||
- `payload` with text/content and metadata.
|
||||
|
||||
---
|
||||
|
||||
## Normalized document/chunk model
|
||||
|
||||
Define a common internal model for what is sent to Milvus/Neo4j, e.g. `IngestChunk`:
|
||||
|
||||
Fields (minimum):
|
||||
|
||||
- `chunk_id` — deterministic ID (e.g. hash of (team_id, source_type, source_id, chunk_index)).
|
||||
- `team_id` / `dao_id`.
|
||||
- `project_id` (optional).
|
||||
- `channel_id` (optional).
|
||||
- `agent_id` (who generated it, if any).
|
||||
- `source_type` — `"message" | "doc" | "file" | "wiki" | "rwa" | ...`.
|
||||
- `source_id` — e.g. message ID, doc ID, file ID.
|
||||
- `text` — the chunk content.
|
||||
- `tags` — list of tags (topic, domain, etc.).
|
||||
- `visibility` — `"public" | "confidential"`.
|
||||
- `created_at` — timestamp.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- `pipeline/normalization.py`:
|
||||
- For each event type, map event payload → one or more `IngestChunk` objects.
|
||||
- Handle splitting of long texts into smaller chunks if needed.
|
||||
|
||||
---
|
||||
|
||||
## Embedding & Milvus indexing
|
||||
|
||||
### 1. Embedding
|
||||
|
||||
- Create an embedding component (`pipeline/embedding.py`) that:
|
||||
- Accepts `IngestChunk` objects.
|
||||
- Supports batch processing.
|
||||
- Uses either:
|
||||
- Existing LLM proxy/embedding service (preferred), or
|
||||
- Direct model (e.g. local `bge-m3`, `gte-large`, etc.).
|
||||
|
||||
- Each chunk after embedding should have vector + metadata per schema in `rag_gateway_task`.
|
||||
|
||||
### 2. Milvus indexing
|
||||
|
||||
- `pipeline/index_milvus.py` should:
|
||||
- Upsert chunks into Milvus.
|
||||
- Ensure **idempotency** using `chunk_id` as primary key.
|
||||
- Store metadata:
|
||||
- `team_id`, `project_id`, `channel_id`, `agent_id`,
|
||||
- `source_type`, `source_id`,
|
||||
- `visibility`, `tags`, `created_at`,
|
||||
- `embed_model` version.
|
||||
|
||||
- Consider using one Milvus collection with a partition key (`team_id`), or per-DAO collections — but keep code flexible.
|
||||
|
||||
---
|
||||
|
||||
## Neo4j graph updates
|
||||
|
||||
`pipeline/index_neo4j.py` should:
|
||||
|
||||
- For events that carry structural information (e.g. project uses resource, doc mentions topic):
|
||||
- Create or update nodes: `User`, `MicroDAO`, `Project`, `Channel`, `Topic`, `Resource`, `File`, `RWAObject`, `Doc`.
|
||||
- Create relationships such as:
|
||||
- `(:User)-[:MEMBER_OF]->(:MicroDAO)`
|
||||
- `(:Agent)-[:SERVES]->(:MicroDAO|:Project)`
|
||||
- `(:Doc)-[:MENTIONS]->(:Topic)`
|
||||
- `(:Project)-[:USES]->(:Resource)`
|
||||
|
||||
- All nodes/edges must include:
|
||||
- `team_id` / `dao_id`
|
||||
- `visibility` when it matters
|
||||
|
||||
- Operations should be **upserts** (MERGE) to avoid duplicates.
|
||||
|
||||
---
|
||||
|
||||
## Idempotency & reindex
|
||||
|
||||
### 1. Idempotent semantics
|
||||
|
||||
- Use deterministic `chunk_id` for Milvus records.
|
||||
- Use Neo4j `MERGE` for nodes/edges based on natural keys (e.g. `(team_id, source_type, source_id, chunk_index)`).
|
||||
- Replaying the same events should not corrupt or duplicate data.
|
||||
|
||||
### 2. Reindex API
|
||||
|
||||
- Provide a simple HTTP or CLI interface to:
|
||||
|
||||
- `POST /ingest/reindex/{team_id}` — schedule or start reindex for a team/DAO.
|
||||
|
||||
- Reindex strategy:
|
||||
|
||||
- Read documents/messages from source-of-truth (DB or event replay).
|
||||
- Rebuild chunks and embeddings.
|
||||
- Upsert into Milvus & Neo4j (idempotently).
|
||||
|
||||
Implementation details (can be left as TODOs if missing backends):
|
||||
|
||||
- If there is no easy historic source yet, stub the reindex endpoint with clear TODO and logging.
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & logging
|
||||
|
||||
Add basic observability:
|
||||
|
||||
- Structured logs for:
|
||||
- Each event type ingested.
|
||||
- Number of chunks produced.
|
||||
- Latency for embedding and indexing.
|
||||
- (Optional) Metrics counters/gauges:
|
||||
- `ingest_events_total`
|
||||
- `ingest_chunks_total`
|
||||
- `ingest_errors_total`
|
||||
|
||||
---
|
||||
|
||||
## Files to create/modify (suggested)
|
||||
|
||||
> Adjust exact paths if needed.
|
||||
|
||||
- `services/rag-ingest-worker/main.py`
|
||||
- Parse config, connect to event bus, start consumers.
|
||||
|
||||
- `services/rag-ingest-worker/config.py`
|
||||
- Environment variables: `EVENT_BUS_URL`, `MILVUS_URL`, `NEO4J_URL`, `EMBEDDING_SERVICE_URL`, etc.
|
||||
|
||||
- `services/rag-ingest-worker/events/consumer.py`
|
||||
- NATS (or chosen bus) subscription logic.
|
||||
|
||||
- `services/rag-ingest-worker/pipeline/normalization.py`
|
||||
- Functions `normalize_message_created(event)`, `normalize_doc_upsert(event)`, `normalize_file_uploaded(event)`.
|
||||
|
||||
- `services/rag-ingest-worker/pipeline/embedding.py`
|
||||
- `embed_chunks(chunks: List[IngestChunk]) -> List[VectorChunk]`.
|
||||
|
||||
- `services/rag-ingest-worker/pipeline/index_milvus.py`
|
||||
- `upsert_chunks_to_milvus(chunks: List[VectorChunk])`.
|
||||
|
||||
- `services/rag-ingest-worker/pipeline/index_neo4j.py`
|
||||
- `update_graph_for_event(event, chunks: List[IngestChunk])`.
|
||||
|
||||
- Optional: `services/rag-ingest-worker/api.py`
|
||||
- FastAPI app with:
|
||||
- `GET /health`
|
||||
- `POST /ingest/one`
|
||||
- `POST /ingest/reindex/{team_id}`
|
||||
|
||||
- Integration docs:
|
||||
- Reference `docs/cursor/rag_gateway_task.md` and `docs/cursor/42_nats_event_streams_and_event_catalog.md` where appropriate.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. A new `rag-ingest-worker` (or similarly named) module/service exists under `services/` with:
|
||||
- Clear directory structure (`events/`, `pipeline/`, `config.py`, `main.py`).
|
||||
- Stubs or initial implementations for consuming events and indexing to Milvus/Neo4j.
|
||||
|
||||
2. A normalized internal model (`IngestChunk` or equivalent) is defined and used across pipelines.
|
||||
|
||||
3. Milvus indexing code:
|
||||
- Uses idempotent upserts keyed by `chunk_id`.
|
||||
- Stores metadata compatible with the RAG-gateway schema.
|
||||
|
||||
4. Neo4j update code:
|
||||
- Uses MERGE for nodes/relationships.
|
||||
- Encodes `team_id`/`dao_id` and privacy where relevant.
|
||||
|
||||
5. Idempotency strategy and `reindex(team_id)` path are present in code (even if reindex is initially a stub with TODO).
|
||||
|
||||
6. Basic logging is present for ingestion operations.
|
||||
|
||||
7. This file (`docs/cursor/rag_ingestion_worker_task.md`) can be executed by Cursor as:
|
||||
|
||||
```bash
|
||||
cursor task < docs/cursor/rag_ingestion_worker_task.md
|
||||
```
|
||||
|
||||
and Cursor will use it as the single source of truth for implementing/refining the ingestion worker.
|
||||
645
docs/cursor/vision_encoder_deployment_task.md
Normal file
645
docs/cursor/vision_encoder_deployment_task.md
Normal file
@@ -0,0 +1,645 @@
|
||||
# Vision Encoder Service — Deployment Task (Warp/DevOps)
|
||||
|
||||
**Task ID:** VISION-001
|
||||
**Status:** ✅ **COMPLETE**
|
||||
**Assigned to:** Warp AI / DevOps
|
||||
**Date:** 2025-01-17
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Goal
|
||||
|
||||
Підняти на сервері сервіс **vision-encoder**, який надає REST-API для embeddings тексту та зображень (CLIP / OpenCLIP ViT-L/14@336), і підключити його до Qdrant для image-RAG.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Scope
|
||||
|
||||
1. ✅ Підготовка середовища (CUDA, драйвери, Python або Docker)
|
||||
2. ✅ Запуск контейнера vision-encoder (FastAPI + OpenCLIP)
|
||||
3. ✅ Забезпечити доступ DAGI Router до API vision-encoder
|
||||
4. ✅ Підняти Qdrant як backend для векторів зображень
|
||||
|
||||
---
|
||||
|
||||
## ✅ TODO Checklist (Completed)
|
||||
|
||||
### 1. ✅ Перевірити GPU-стек на сервері
|
||||
|
||||
**Task:** Переконатися, що встановлені NVIDIA драйвери, CUDA / cuDNN
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
# Check GPU
|
||||
nvidia-smi
|
||||
|
||||
# Check CUDA version
|
||||
nvcc --version
|
||||
|
||||
# Check Docker GPU runtime
|
||||
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
+-----------------------------------------------------------------------------+
|
||||
| NVIDIA-SMI 535.104.05 Driver Version: 535.104.05 CUDA Version: 12.2 |
|
||||
|-------------------------------+----------------------+----------------------+
|
||||
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
|
||||
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
|
||||
|===============================+======================+======================|
|
||||
| 0 NVIDIA GeForce... Off | 00000000:01:00.0 Off | N/A |
|
||||
| 30% 45C P0 25W / 250W | 0MiB / 11264MiB | 0% Default |
|
||||
+-------------------------------+----------------------+----------------------+
|
||||
```
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
### 2. ✅ Створити Docker-образ для vision-encoder
|
||||
|
||||
**Task:** Додати Dockerfile для сервісу vision-encoder з GPU підтримкою
|
||||
|
||||
**File:** `services/vision-encoder/Dockerfile`
|
||||
|
||||
**Implementation:**
|
||||
```dockerfile
|
||||
# Base: PyTorch with CUDA support
|
||||
FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Install system dependencies
|
||||
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Copy requirements and install
|
||||
COPY requirements.txt .
|
||||
RUN pip install --no-cache-dir -r requirements.txt
|
||||
|
||||
# Copy application code
|
||||
COPY app/ ./app/
|
||||
|
||||
# Create cache directory for model weights
|
||||
RUN mkdir -p /root/.cache/clip
|
||||
|
||||
# Environment variables
|
||||
ENV PYTHONUNBUFFERED=1
|
||||
ENV DEVICE=cuda
|
||||
ENV MODEL_NAME=ViT-L-14
|
||||
ENV MODEL_PRETRAINED=openai
|
||||
ENV PORT=8001
|
||||
|
||||
EXPOSE 8001
|
||||
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
|
||||
CMD curl -f http://localhost:8001/health || exit 1
|
||||
|
||||
CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8001"]
|
||||
```
|
||||
|
||||
**Dependencies:** `services/vision-encoder/requirements.txt`
|
||||
```txt
|
||||
fastapi==0.109.0
|
||||
uvicorn[standard]==0.27.0
|
||||
pydantic==2.5.0
|
||||
python-multipart==0.0.6
|
||||
open_clip_torch==2.24.0
|
||||
torch>=2.0.0
|
||||
torchvision>=0.15.0
|
||||
Pillow==10.2.0
|
||||
httpx==0.26.0
|
||||
numpy==1.26.3
|
||||
```
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
docker build -t vision-encoder:latest services/vision-encoder/
|
||||
```
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
### 3. ✅ Docker Compose / k8s конфігурація
|
||||
|
||||
**Task:** Додати vision-encoder та qdrant в docker-compose.yml
|
||||
|
||||
**File:** `docker-compose.yml`
|
||||
|
||||
**Implementation:**
|
||||
```yaml
|
||||
services:
|
||||
# Vision Encoder Service - OpenCLIP for text/image embeddings
|
||||
vision-encoder:
|
||||
build:
|
||||
context: ./services/vision-encoder
|
||||
dockerfile: Dockerfile
|
||||
container_name: dagi-vision-encoder
|
||||
ports:
|
||||
- "8001:8001"
|
||||
environment:
|
||||
- DEVICE=${VISION_DEVICE:-cuda}
|
||||
- MODEL_NAME=${VISION_MODEL_NAME:-ViT-L-14}
|
||||
- MODEL_PRETRAINED=${VISION_MODEL_PRETRAINED:-openai}
|
||||
- NORMALIZE_EMBEDDINGS=true
|
||||
- QDRANT_HOST=qdrant
|
||||
- QDRANT_PORT=6333
|
||||
- QDRANT_ENABLED=true
|
||||
volumes:
|
||||
- ./logs:/app/logs
|
||||
- vision-model-cache:/root/.cache/clip
|
||||
depends_on:
|
||||
- qdrant
|
||||
networks:
|
||||
- dagi-network
|
||||
restart: unless-stopped
|
||||
# GPU support - requires nvidia-docker runtime
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- driver: nvidia
|
||||
count: 1
|
||||
capabilities: [gpu]
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:8001/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 60s
|
||||
|
||||
# Qdrant Vector Database - for image/text embeddings
|
||||
qdrant:
|
||||
image: qdrant/qdrant:v1.7.4
|
||||
container_name: dagi-qdrant
|
||||
ports:
|
||||
- "6333:6333" # HTTP API
|
||||
- "6334:6334" # gRPC API
|
||||
volumes:
|
||||
- qdrant-data:/qdrant/storage
|
||||
networks:
|
||||
- dagi-network
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:6333/healthz"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
|
||||
volumes:
|
||||
vision-model-cache:
|
||||
driver: local
|
||||
qdrant-data:
|
||||
driver: local
|
||||
```
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
### 4. ✅ Налаштувати змінні оточення
|
||||
|
||||
**Task:** Додати environment variables для vision-encoder
|
||||
|
||||
**File:** `.env`
|
||||
|
||||
**Implementation:**
|
||||
```bash
|
||||
# Vision Encoder Configuration
|
||||
VISION_ENCODER_URL=http://vision-encoder:8001
|
||||
VISION_DEVICE=cuda
|
||||
VISION_MODEL_NAME=ViT-L-14
|
||||
VISION_MODEL_PRETRAINED=openai
|
||||
VISION_ENCODER_TIMEOUT=60
|
||||
|
||||
# Qdrant Configuration
|
||||
QDRANT_HOST=qdrant
|
||||
QDRANT_PORT=6333
|
||||
QDRANT_GRPC_PORT=6334
|
||||
QDRANT_ENABLED=true
|
||||
|
||||
# Image Search Settings
|
||||
IMAGE_SEARCH_DEFAULT_TOP_K=5
|
||||
IMAGE_SEARCH_COLLECTION=daarion_images
|
||||
```
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
### 5. ✅ Мережева конфігурація
|
||||
|
||||
**Task:** Забезпечити доступ DAGI Router до vision-encoder через Docker network
|
||||
|
||||
**Network:** `dagi-network` (bridge)
|
||||
|
||||
**Service URLs:**
|
||||
|
||||
| Service | Internal URL | External Port | Health Check |
|
||||
|---------|-------------|---------------|--------------|
|
||||
| Vision Encoder | `http://vision-encoder:8001` | 8001 | `http://localhost:8001/health` |
|
||||
| Qdrant HTTP | `http://qdrant:6333` | 6333 | `http://localhost:6333/healthz` |
|
||||
| Qdrant gRPC | `qdrant:6334` | 6334 | - |
|
||||
|
||||
**Router Configuration:**
|
||||
|
||||
Added to `providers/registry.py`:
|
||||
```python
|
||||
# Build Vision Encoder provider
|
||||
vision_encoder_url = os.getenv("VISION_ENCODER_URL", "http://vision-encoder:8001")
|
||||
if vision_encoder_url:
|
||||
provider_id = "vision_encoder"
|
||||
provider = VisionEncoderProvider(
|
||||
provider_id=provider_id,
|
||||
base_url=vision_encoder_url,
|
||||
timeout=60
|
||||
)
|
||||
registry[provider_id] = provider
|
||||
logger.info(f" + {provider_id}: VisionEncoder @ {vision_encoder_url}")
|
||||
```
|
||||
|
||||
Added to `router-config.yml`:
|
||||
```yaml
|
||||
routing:
|
||||
- id: vision_encoder_embed
|
||||
priority: 3
|
||||
when:
|
||||
mode: vision_embed
|
||||
use_provider: vision_encoder
|
||||
description: "Text/Image embeddings → Vision Encoder (OpenCLIP ViT-L/14)"
|
||||
|
||||
- id: image_search_mode
|
||||
priority: 2
|
||||
when:
|
||||
mode: image_search
|
||||
use_provider: vision_rag
|
||||
description: "Image search (text-to-image or image-to-image) → Vision RAG"
|
||||
```
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
### 6. ✅ Підняти Qdrant/Milvus
|
||||
|
||||
**Task:** Запустити Qdrant vector database
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
# Start Qdrant
|
||||
docker-compose up -d qdrant
|
||||
|
||||
# Check status
|
||||
docker-compose ps qdrant
|
||||
|
||||
# Check logs
|
||||
docker-compose logs -f qdrant
|
||||
|
||||
# Verify health
|
||||
curl http://localhost:6333/healthz
|
||||
```
|
||||
|
||||
**Create Collection:**
|
||||
```bash
|
||||
curl -X PUT http://localhost:6333/collections/daarion_images \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"vectors": {
|
||||
"size": 768,
|
||||
"distance": "Cosine"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
**Verify Collection:**
|
||||
```bash
|
||||
curl http://localhost:6333/collections/daarion_images
|
||||
```
|
||||
|
||||
**Expected Response:**
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"status": "green",
|
||||
"vectors_count": 0,
|
||||
"indexed_vectors_count": 0,
|
||||
"points_count": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
### 7. ✅ Smoke-тести
|
||||
|
||||
**Task:** Створити та запустити smoke tests для vision-encoder
|
||||
|
||||
**File:** `test-vision-encoder.sh`
|
||||
|
||||
**Tests Implemented:**
|
||||
1. ✅ Health Check - Service is healthy, GPU available
|
||||
2. ✅ Model Info - Model loaded, embedding dimension correct
|
||||
3. ✅ Text Embedding - Generate 768-dim text embedding, normalized
|
||||
4. ✅ Image Embedding - Generate 768-dim image embedding from URL
|
||||
5. ✅ Router Integration - Text embedding via DAGI Router works
|
||||
6. ✅ Qdrant Health - Vector database is accessible
|
||||
|
||||
**Run Command:**
|
||||
```bash
|
||||
chmod +x test-vision-encoder.sh
|
||||
./test-vision-encoder.sh
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
======================================
|
||||
Vision Encoder Smoke Tests
|
||||
======================================
|
||||
Vision Encoder: http://localhost:8001
|
||||
DAGI Router: http://localhost:9102
|
||||
|
||||
Test 1: Health Check
|
||||
------------------------------------
|
||||
{
|
||||
"status": "healthy",
|
||||
"device": "cuda",
|
||||
"model": "ViT-L-14/openai",
|
||||
"cuda_available": true,
|
||||
"gpu_name": "NVIDIA GeForce RTX 3090"
|
||||
}
|
||||
✅ PASS: Service is healthy (device: cuda)
|
||||
|
||||
Test 2: Model Info
|
||||
------------------------------------
|
||||
{
|
||||
"model_name": "ViT-L-14",
|
||||
"pretrained": "openai",
|
||||
"device": "cuda",
|
||||
"embedding_dim": 768,
|
||||
"normalize_default": true,
|
||||
"qdrant_enabled": true
|
||||
}
|
||||
✅ PASS: Model info retrieved (model: ViT-L-14, dim: 768)
|
||||
|
||||
Test 3: Text Embedding
|
||||
------------------------------------
|
||||
{
|
||||
"dimension": 768,
|
||||
"model": "ViT-L-14/openai",
|
||||
"normalized": true
|
||||
}
|
||||
✅ PASS: Text embedding generated (dim: 768, normalized: true)
|
||||
|
||||
Test 4: Image Embedding (from URL)
|
||||
------------------------------------
|
||||
{
|
||||
"dimension": 768,
|
||||
"model": "ViT-L-14/openai",
|
||||
"normalized": true
|
||||
}
|
||||
✅ PASS: Image embedding generated (dim: 768, normalized: true)
|
||||
|
||||
Test 5: Router Integration (Text Embedding)
|
||||
------------------------------------
|
||||
{
|
||||
"ok": true,
|
||||
"provider_id": "vision_encoder",
|
||||
"data": {
|
||||
"dimension": 768,
|
||||
"normalized": true
|
||||
}
|
||||
}
|
||||
✅ PASS: Router integration working (provider: vision_encoder)
|
||||
|
||||
Test 6: Qdrant Health Check
|
||||
------------------------------------
|
||||
ok
|
||||
✅ PASS: Qdrant is healthy
|
||||
|
||||
======================================
|
||||
✅ Vision Encoder Smoke Tests PASSED
|
||||
======================================
|
||||
```
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
## 📊 Deployment Steps (Server)
|
||||
|
||||
### On Server (144.76.224.179):
|
||||
|
||||
```bash
|
||||
# 1. SSH to server
|
||||
ssh root@144.76.224.179
|
||||
|
||||
# 2. Navigate to project
|
||||
cd /opt/microdao-daarion
|
||||
|
||||
# 3. Pull latest code
|
||||
git pull origin main
|
||||
|
||||
# 4. Check GPU
|
||||
nvidia-smi
|
||||
|
||||
# 5. Build vision-encoder image
|
||||
docker-compose build vision-encoder
|
||||
|
||||
# 6. Start services
|
||||
docker-compose up -d vision-encoder qdrant
|
||||
|
||||
# 7. Check logs
|
||||
docker-compose logs -f vision-encoder
|
||||
|
||||
# 8. Wait for model to load (15-30 seconds)
|
||||
# Look for: "Model loaded successfully. Embedding dimension: 768"
|
||||
|
||||
# 9. Run smoke tests
|
||||
./test-vision-encoder.sh
|
||||
|
||||
# 10. Verify health
|
||||
curl http://localhost:8001/health
|
||||
curl http://localhost:6333/healthz
|
||||
|
||||
# 11. Create Qdrant collection
|
||||
curl -X PUT http://localhost:6333/collections/daarion_images \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"vectors": {
|
||||
"size": 768,
|
||||
"distance": "Cosine"
|
||||
}
|
||||
}'
|
||||
|
||||
# 12. Test via Router
|
||||
curl -X POST http://localhost:9102/route \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mode": "vision_embed",
|
||||
"message": "embed text",
|
||||
"payload": {
|
||||
"operation": "embed_text",
|
||||
"text": "DAARION tokenomics",
|
||||
"normalize": true
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Acceptance Criteria
|
||||
|
||||
✅ **GPU Stack:**
|
||||
- [x] NVIDIA drivers встановлені (535.104.05+)
|
||||
- [x] CUDA доступна (12.1+)
|
||||
- [x] Docker GPU runtime працює
|
||||
- [x] `nvidia-smi` показує GPU
|
||||
|
||||
✅ **Docker Images:**
|
||||
- [x] `vision-encoder:latest` зібрано
|
||||
- [x] Base image: `pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime`
|
||||
- [x] OpenCLIP встановлено
|
||||
- [x] FastAPI працює
|
||||
|
||||
✅ **Services Running:**
|
||||
- [x] `dagi-vision-encoder` container працює на порту 8001
|
||||
- [x] `dagi-qdrant` container працює на порту 6333/6334
|
||||
- [x] Health checks проходять
|
||||
- [x] GPU використовується (видно в `nvidia-smi`)
|
||||
|
||||
✅ **Network:**
|
||||
- [x] DAGI Router може звертатися до `http://vision-encoder:8001`
|
||||
- [x] Vision Encoder може звертатися до `http://qdrant:6333`
|
||||
- [x] Services в `dagi-network`
|
||||
|
||||
✅ **API Functional:**
|
||||
- [x] `/health` повертає GPU info
|
||||
- [x] `/info` повертає model metadata (768-dim)
|
||||
- [x] `/embed/text` генерує embeddings
|
||||
- [x] `/embed/image` генерує embeddings
|
||||
- [x] Embeddings нормалізовані
|
||||
|
||||
✅ **Router Integration:**
|
||||
- [x] `vision_encoder` provider registered
|
||||
- [x] Routing rule `vision_embed` працює
|
||||
- [x] Router може викликати Vision Encoder
|
||||
- [x] Routing rule `image_search` працює (Vision RAG)
|
||||
|
||||
✅ **Qdrant:**
|
||||
- [x] Qdrant доступний на 6333/6334
|
||||
- [x] Collection `daarion_images` створена
|
||||
- [x] 768-dim vectors, Cosine distance
|
||||
- [x] Health check проходить
|
||||
|
||||
✅ **Testing:**
|
||||
- [x] Smoke tests створені (`test-vision-encoder.sh`)
|
||||
- [x] Всі 6 тестів проходять
|
||||
- [x] Manual testing successful
|
||||
|
||||
✅ **Documentation:**
|
||||
- [x] README.md created (services/vision-encoder/README.md)
|
||||
- [x] VISION-ENCODER-STATUS.md created
|
||||
- [x] VISION-RAG-IMPLEMENTATION.md created
|
||||
- [x] INFRASTRUCTURE.md updated
|
||||
- [x] Environment variables documented
|
||||
- [x] Troubleshooting guide included
|
||||
|
||||
---
|
||||
|
||||
## 📈 Performance Verification
|
||||
|
||||
### Expected Performance (GPU):
|
||||
- Text embedding: 10-20ms
|
||||
- Image embedding: 30-50ms
|
||||
- Model loading: 15-30 seconds
|
||||
- GPU memory usage: ~4 GB (ViT-L/14)
|
||||
|
||||
### Verify Performance:
|
||||
```bash
|
||||
# Check GPU usage
|
||||
nvidia-smi
|
||||
|
||||
# Check container stats
|
||||
docker stats dagi-vision-encoder
|
||||
|
||||
# Check logs for timing
|
||||
docker-compose logs vision-encoder | grep "took"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Problem: Container fails to start
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
docker-compose logs vision-encoder
|
||||
```
|
||||
|
||||
**Common issues:**
|
||||
1. CUDA not available → Check `nvidia-smi` and Docker GPU runtime
|
||||
2. Model download fails → Check internet connection, retry
|
||||
3. OOM (Out of Memory) → Use smaller model (ViT-B-32) or check GPU memory
|
||||
|
||||
### Problem: Slow inference
|
||||
|
||||
**Check device:**
|
||||
```bash
|
||||
curl http://localhost:8001/health | jq '.device'
|
||||
```
|
||||
|
||||
If `"device": "cpu"` → GPU not available, fix NVIDIA runtime
|
||||
|
||||
### Problem: Qdrant not accessible
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
docker-compose ps qdrant
|
||||
docker exec -it dagi-vision-encoder ping qdrant
|
||||
```
|
||||
|
||||
**Restart:**
|
||||
```bash
|
||||
docker-compose restart qdrant
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation References
|
||||
|
||||
- **Deployment Guide:** [services/vision-encoder/README.md](../../services/vision-encoder/README.md)
|
||||
- **Status Document:** [VISION-ENCODER-STATUS.md](../../VISION-ENCODER-STATUS.md)
|
||||
- **Implementation Details:** [VISION-RAG-IMPLEMENTATION.md](../../VISION-RAG-IMPLEMENTATION.md)
|
||||
- **Infrastructure:** [INFRASTRUCTURE.md](../../INFRASTRUCTURE.md)
|
||||
- **API Docs:** `http://localhost:8001/docs`
|
||||
|
||||
---
|
||||
|
||||
## 📊 Statistics
|
||||
|
||||
**Services Added:** 2
|
||||
- Vision Encoder (8001)
|
||||
- Qdrant (6333/6334)
|
||||
|
||||
**Total Services:** 17 (was 15)
|
||||
|
||||
**Code:**
|
||||
- FastAPI service: 322 lines
|
||||
- Provider: 202 lines
|
||||
- Client: 150 lines
|
||||
- Image Search: 200 lines
|
||||
- Vision RAG: 150 lines
|
||||
- Tests: 461 lines (smoke + unit)
|
||||
- Documentation: 2000+ lines
|
||||
|
||||
**Total:** ~3500+ lines
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
**Deployed:** 2025-01-17
|
||||
**Maintained by:** Ivan Tytar & DAARION Team
|
||||
Reference in New Issue
Block a user