From fac3d1f269b0acc5b0d3aff101a8ebb4ae4ec300 Mon Sep 17 00:00:00 2001 From: Lasse Rune Hansen Date: Tue, 9 Jun 2026 18:10:52 +0200 Subject: [PATCH] docs(features): update AI Services plan with Mistral API Connector as Phase 0 - Add Phase 0: Mistral API Connector (2-3 hours) as first step - Update status to In Progress - Add MistralConnector to architecture diagram and components - Add connector-specific tasks to implementation plan - Add Mistral connector configuration examples - Add progress history entry - Update estimate from 10-16h to 12-18h Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- docs/features/ai-services.md | 86 ++++++++++++++++++++++++++++++------ 1 file changed, 72 insertions(+), 14 deletions(-) diff --git a/docs/features/ai-services.md b/docs/features/ai-services.md index 0846512..0004fea 100644 --- a/docs/features/ai-services.md +++ b/docs/features/ai-services.md @@ -1,9 +1,9 @@ # Feature: AI Services Integration -> **Status**: ⏳ Planned +> **Status**: 🚀 In Progress > **Priority**: High > **Complexity**: High -> **Estimate**: 10-16 hours +> **Estimate**: 12-18 hours > **Assignee**: - > **Created**: May 31, 2025 > **Target Completion**: - @@ -68,7 +68,8 @@ As a learner, I want AI-powered features like generated stories, speech recognit │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────┐ │ -│ │ Application Services │ │ +│ │ Connectors & Services │ │ +│ │ - MistralConnector (HTTP Client) │ │ │ │ - StoryGenerationService │ │ │ │ - WritingFeedbackService │ │ │ │ - VoskService (Speech Recognition) │ │ @@ -78,8 +79,10 @@ As a learner, I want AI-powered features like generated stories, speech recognit ``` ### Components Involved +- **Backend Connectors**: + - `IMistralConnector` / `MistralConnector` - HTTP client for Mistral API - **Backend Services**: - - `IMistralService` / `MistralService` - Text generation + - `IMistralService` / `MistralService` - Text generation (uses MistralConnector) - `IVoskService` / `VoskService` - Speech recognition - `ITtsService` / `TtsService` - Text-to-speech - **Configuration**: appsettings.json with AI settings @@ -123,6 +126,25 @@ As a learner, I want AI-powered features like generated stories, speech recognit ## 🚀 Implementation Plan +### Phase 0: Mistral API Connector (2-3 hours) +**Objective**: Create a reusable, testable connector for Mistral API that can be used by all Mistral-based services. + +- [ ] Create `Domain/Interfaces/IMistralConnector.cs` - Interface for Mistral API connector +- [ ] Create `Infrastructure/Services/MistralConnector.cs` - HTTP client implementation +- [ ] Implement request/response models (`MistralRequest.cs`, `MistralResponse.cs`) +- [ ] Add HTTP client configuration with base URL and timeout +- [ ] Implement retry logic with exponential backoff +- [ ] Add rate limiting at the connector level +- [ ] Add response caching mechanism +- [ ] Implement circuit breaker pattern for failure handling +- [ ] Create unit tests for MistralConnector + +**Deliverables:** +- Standalone Mistral API connector component +- Configurable via appsettings.json +- Resilient to API failures +- Testable with mocked HTTP client + ### Phase 1: Configuration & Interfaces (2 hours) - [ ] Add AI configuration section to appsettings.json - [ ] Create configuration classes (MistralConfig, VoskConfig, CoquiConfig) @@ -178,6 +200,19 @@ As a learner, I want AI-powered features like generated stories, speech recognit ## ✅ Tasks +### Backend - Mistral API Connector +- [ ] Create `Domain/Interfaces/IMistralConnector.cs` +- [ ] Create `Infrastructure/Services/MistralConnector.cs` +- [ ] Create `Application/Models/MistralRequest.cs` +- [ ] Create `Application/Models/MistralResponse.cs` +- [ ] Create `Application/Models/MistralErrorResponse.cs` +- [ ] Add HTTP client configuration in Program.cs +- [ ] Implement retry logic with exponential backoff +- [ ] Add rate limiting to connector +- [ ] Add response caching mechanism +- [ ] Implement circuit breaker pattern +- [ ] Create unit tests for MistralConnector + ### Backend - Configuration - [ ] Add Mistral settings to appsettings.json - [ ] Add Vosk settings to appsettings.json @@ -189,15 +224,12 @@ As a learner, I want AI-powered features like generated stories, speech recognit - [ ] Add health checks for AI services ### Backend - Mistral Service -- [ ] Create Domain/Interfaces/IMistralService.cs -- [ ] Create Infrastructure/Services/MistralService.cs -- [ ] Implement Mistral API client -- [ ] Create Models/MistralRequest.cs -- [ ] Create Models/MistralResponse.cs -- [ ] Add retry logic -- [ ] Add rate limiting -- [ ] Add response caching -- [ ] Write unit tests +- [ ] Create `Domain/Interfaces/IMistralService.cs` +- [ ] Create `Application/Services/MistralService.cs` (uses MistralConnector) +- [ ] Implement prompt templates for different use cases +- [ ] Add story generation functionality +- [ ] Add writing feedback functionality +- [ ] Write unit tests (with mocked MistralConnector) ### Backend - Vosk Service - [ ] Create Domain/Interfaces/IVoskService.cs @@ -785,9 +817,20 @@ public async Task RecognizeSpeech([FromBody] AudioRequest request | May 31, 2025 | Use Coqui TTS | Open-source, good quality, supports German | | May 31, 2025 | Self-host AI services | More control, no external API dependencies (except Mistral) | | May 31, 2025 | Use Python CLI wrappers | Easier integration with .NET, well-supported libraries | +| June 9, 2025 | Add Mistral API Connector | Create reusable connector before service implementation | ### Technical Notes +#### Mistral API Connector +The Mistral Connector is a standalone component that handles all HTTP communication with the Mistral API. It provides: +- HTTP client configuration with base URL and timeout +- Retry logic with exponential backoff +- Rate limiting at the connector level +- Response caching mechanism +- Circuit breaker pattern for failure handling + +This follows Clean Architecture: interface (`IMistralConnector`) in Domain layer, implementation (`MistralConnector`) in Infrastructure layer. + #### Vosk Configuration ```json { @@ -819,7 +862,21 @@ public async Task RecognizeSpeech([FromBody] AudioRequest request "BaseUrl": "https://api.mistral.ai/v1/", "DefaultModel": "mistral-medium", "TimeoutSeconds": 30, - "MaxRetries": 3 + "MaxRetries": 3, + "RateLimitPerMinute": 10, + "EnableCaching": true, + "CacheTTLMinutes": 60 + } +} +``` + +#### Mistral Connector Configuration +```json +{ + "MistralConnector": { + "HttpClientTimeoutSeconds": 60, + "CircuitBreakerFailureThreshold": 5, + "CircuitBreakerResetMinutes": 1 } } ``` @@ -875,6 +932,7 @@ public async Task RecognizeSpeech([FromBody] AudioRequest request | Date | Status Change | Notes | |------|---------------|-------| | May 31, 2025 | Created | Initial plan based on application-plan.md | +| June 9, 2025 | Updated | Added Phase 0: Mistral API Connector as first step | ---