Documentation request
Based on original epic: #799
Description
Create a concise technical document describing the end-to-end intent flow in the Service-Module, covering data structures, storage/indexing, LLM classification, routing logic, entity handling, API contracts, and error propagation. The document must be precise, implementation-focused, and strictly technical.
Technical Documentation Checklist
Minimal set of technical points that must be documented
1. System Flow
- How intent data moves: Service-Module → Blob Storage → Indexer → LLM Classification → Routing → Service Execution.
- Dependencies on Ruuter, Training Module, and Client LLM.
2. Intent Data Specification
- Exact JSON schema (id, name, examples, entities, description).
- Required fields and validation rules.
- How data is serialized and stored.
3. Blob Storage & Indexing
- Storage path conventions and versioning.
- Triggering index updates after blob changes.
- Error handling and retry logic for both blob writes and indexer calls.
4. LLM Classification Contract
- Input format sent to LLM.
- Output schema:
{ "intent": "id or OOD", "entities": { } }
- Timeouts, malformed responses, fallback behaviour.
5. Routing Logic
- How intent → service mapping works.
- Rules:
- Valid intent → run service
- Unknown/inactive intent → fallback to client LLM
- OOD → fallback path
6. Entity Handling
- Required vs optional entities.
- Mapping extracted entities into service parameters.
- Validation, type rules, and fallback when entities are missing.
7. Logging & Error Model
-
Logged events: classification results, routing decisions, index updates.
-
Error propagation rules:
1. Blob Storage / Indexing
- Blob write failure → log
BLOB_WRITE_FAILED, return 500.
- Indexer failure → log
INDEX_TRIGGER_FAILED, return warning; intent saved but not indexed.
2. LLM Classification
- Timeout → log
LLM_TIMEOUT, fallback to client LLM.
- Malformed output → log
LLM_RESPONSE_MALFORMED, treat as OOD or return hard error.
3. Routing / Validation
- Unknown or inactive intent → log
INTENT_NOT_AVAILABLE, fallback to client LLM.
- Missing required entities → log
MISSING_REQUIRED_ENTITIES, do not run service, fallback.
4. Service Execution
- Downstream errors → log
SERVICE_EXECUTION_FAILED, return 500, no automatic retries.
8. API Contracts
Document only:
- Intent CRUD APIs
- Blob/indexing APIs
- Classification endpoint
- Routing/validation endpoint
Include:
- Method
- Path
- Request schema
- Response schema
Acceptance Criteria
Documentation request
Based on original epic: #799
Description
Create a concise technical document describing the end-to-end intent flow in the Service-Module, covering data structures, storage/indexing, LLM classification, routing logic, entity handling, API contracts, and error propagation. The document must be precise, implementation-focused, and strictly technical.
Technical Documentation Checklist
Minimal set of technical points that must be documented
1. System Flow
2. Intent Data Specification
3. Blob Storage & Indexing
4. LLM Classification Contract
{ "intent": "id or OOD", "entities": { } }5. Routing Logic
6. Entity Handling
7. Logging & Error Model
Logged events: classification results, routing decisions, index updates.
Error propagation rules:
1. Blob Storage / Indexing
BLOB_WRITE_FAILED, return 500.INDEX_TRIGGER_FAILED, return warning; intent saved but not indexed.2. LLM Classification
LLM_TIMEOUT, fallback to client LLM.LLM_RESPONSE_MALFORMED, treat as OOD or return hard error.3. Routing / Validation
INTENT_NOT_AVAILABLE, fallback to client LLM.MISSING_REQUIRED_ENTITIES, do not run service, fallback.4. Service Execution
SERVICE_EXECUTION_FAILED, return 500, no automatic retries.8. API Contracts
Document only:
Include:
Acceptance Criteria