|
| 1 | +# Add Engine Request DTO Model |
| 2 | + |
| 3 | +This document demonstrates how to use the new `AddEngineRequest` DTO model in the `add_engine_route.cpp`. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The `AddEngineRequest` model provides a structured way to handle JSON request parsing for the add engine endpoint, replacing manual JSON parsing with a type-safe, validated model approach. |
| 8 | + |
| 9 | +## Usage Example |
| 10 | + |
| 11 | +### Before (Manual JSON Parsing) |
| 12 | +```cpp |
| 13 | +// Old approach - manual JSON parsing |
| 14 | +auto j = json::parse(body); |
| 15 | +std::string engineId = j["engine_id"]; |
| 16 | +std::string modelPath = j["model_path"]; |
| 17 | +bool loadImmediately = j.value("load_immediately", true); |
| 18 | + |
| 19 | +if (j.contains("loading_parameters")) { |
| 20 | + auto loadParamsJson = j["loading_parameters"]; |
| 21 | + loadParams.n_ctx = loadParamsJson.value("n_ctx", 4096); |
| 22 | + // ... more manual parsing |
| 23 | +} |
| 24 | +``` |
| 25 | + |
| 26 | +### After (DTO Model Approach) |
| 27 | +```cpp |
| 28 | +// New approach - structured DTO model |
| 29 | +auto j = json::parse(body); |
| 30 | +AddEngineRequest request; |
| 31 | +request.from_json(j); |
| 32 | + |
| 33 | +if (!request.validate()) { |
| 34 | + // Handle validation error |
| 35 | + return; |
| 36 | +} |
| 37 | + |
| 38 | +// Access validated fields |
| 39 | +std::string engineId = request.engine_id; |
| 40 | +std::string modelPath = request.model_path; |
| 41 | +bool loadImmediately = request.load_immediately; |
| 42 | + |
| 43 | +// Convert to LoadingParameters struct |
| 44 | +LoadingParameters loadParams; |
| 45 | +loadParams.n_ctx = request.loading_parameters.n_ctx; |
| 46 | +loadParams.n_keep = request.loading_parameters.n_keep; |
| 47 | +// ... etc |
| 48 | +``` |
| 49 | + |
| 50 | +## JSON Schema |
| 51 | + |
| 52 | +The `AddEngineRequest` model expects JSON in the following format: |
| 53 | + |
| 54 | +```json |
| 55 | +{ |
| 56 | + "engine_id": "my-engine", |
| 57 | + "model_path": "/path/to/model.gguf", |
| 58 | + "load_immediately": true, |
| 59 | + "main_gpu_id": 0, |
| 60 | + "loading_parameters": { |
| 61 | + "n_ctx": 4096, |
| 62 | + "n_keep": 2048, |
| 63 | + "use_mlock": true, |
| 64 | + "use_mmap": true, |
| 65 | + "cont_batching": true, |
| 66 | + "warmup": false, |
| 67 | + "n_parallel": 1, |
| 68 | + "n_gpu_layers": 100, |
| 69 | + "n_batch": 2048, |
| 70 | + "n_ubatch": 512 |
| 71 | + } |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +## Validation |
| 76 | + |
| 77 | +The model includes comprehensive validation: |
| 78 | + |
| 79 | +### Required Fields |
| 80 | +- `engine_id` (non-empty string) |
| 81 | +- `model_path` (non-empty string) |
| 82 | + |
| 83 | +### Optional Fields with Defaults |
| 84 | +- `load_immediately` (boolean, default: true) |
| 85 | +- `main_gpu_id` (integer, default: 0, range: -1 to 15) |
| 86 | +- `loading_parameters` (object with nested validation) |
| 87 | + |
| 88 | +### Loading Parameters Validation |
| 89 | +- `n_ctx`: 1 to 1,000,000 |
| 90 | +- `n_keep`: 0 to n_ctx |
| 91 | +- `n_batch`: 1 to 8,192 |
| 92 | +- `n_ubatch`: 1 to n_batch |
| 93 | +- `n_parallel`: 1 to 16 |
| 94 | +- `n_gpu_layers`: 0 to 1,000 |
| 95 | + |
| 96 | +## Benefits |
| 97 | + |
| 98 | +1. **Type Safety**: Compile-time checking of field types |
| 99 | +2. **Validation**: Built-in parameter validation with detailed error messages |
| 100 | +3. **Maintainability**: Centralized request structure definition |
| 101 | +4. **Consistency**: Follows the same pattern as `CompletionRequest` model |
| 102 | +5. **Error Handling**: Structured exception handling for validation errors |
| 103 | +6. **Documentation**: Self-documenting code with clear field definitions |
| 104 | + |
| 105 | +## Files Created |
| 106 | + |
| 107 | +- `include/kolosal/models/add_engine_request_model.hpp` - Request DTO model |
| 108 | +- `include/kolosal/models/add_engine_response_model.hpp` - Response DTO model (optional) |
| 109 | + |
| 110 | +## Integration |
| 111 | + |
| 112 | +The model is integrated into `add_engine_route.cpp` with: |
| 113 | +- JSON parsing and validation |
| 114 | +- Type-safe field access |
| 115 | +- Structured error handling |
| 116 | +- Response generation using the validated model data |
0 commit comments