refactor: Improve type hints and code quality across codebase

- Remove obsolete documentation files (CLEANUP_*, CODERABBIT_*, TEST_CODERABBIT)
- Add comprehensive type hints to all functions and methods
- Improve middleware with better type annotations and error messages
- Add docstrings to service layer functions
- Refactor _messages_to_prompt to use list joining instead of string concatenation
- Extract PUBLIC_PATHS as module-level constant in middleware
- Improve code readability and maintainability

This expands code coverage for CodeRabbit review across multiple modules.

CLEANUP_PLAN.md

@@ -1,155 +0,0 @@
-# Code Cleanup Plan
-
-## Overview
-This document outlines the cleanup strategy for the simple-llm-pro-finance project to remove obsolete files and improve code organization.
-
-## Files to Remove
-
-### 1. Obsolete Test Scripts (Root Directory)
-**Reason:** All functional tests have been moved to `tests/` directory. These are one-off debugging scripts.
-
-- `analyze_performance.py` - Performance analysis done, results in FINAL_TEST_REPORT.md
-- `debug_chat_template.py` - Debug script, no longer needed
-- `final_clean_test.py` - One-off test
-- `investigate_french_consistency.py` - Investigation complete
-- `quiz_finance_francais.py` - Test script (also in git staging)
-- `test_advanced_finance.py` - Moved to tests/
-- `test_all_fixes.py` - One-off validation
-- `test_debug_endpoint.sh` - Shell test script
-- `test_finance_final.py` - One-off test
-- `test_finance_improved.py` - One-off test
-- `test_finance_queries.py` - One-off test
-- `test_french_direct.py` - One-off test
-- `test_french_final_check.py` - One-off test
-- `test_french_simple.sh` - Shell test script
-- `test_french_strategies.py` - One-off test
-- `test_generation_fix.sh` - Shell test script
-- `test_memory_stress.py` - Moved to tests/
-- `test_quick_french.py` - One-off test
-- `test_service.py` - One-off test
-- `test_system_prompt.py` - One-off test
-- `test_tokenizer_debug.py` - Debug script
-- `test_truncation_issue.py` - One-off test
-
-**Total:** 21 test files
-
-### 2. Obsolete Documentation Files
-**Reason:** Superseded by comprehensive final reports.
-
-- `STATUS.md` - Historical status, superseded by FINAL_STATUS.md
-- `FIXES_SUMMARY.md` - Historical, covered in FINAL_TEST_REPORT.md
-- `PERFORMANCE_REPORT.md` - Covered in FINAL_TEST_REPORT.md
-- `memory_test_results.txt` - Old test results
-- `test_results.txt` - Old test results
-
-**Total:** 5 documentation files
-
-### 3. Empty/Debug Code Directories
-**Reason:** Unused or debug-only code.
-
-- `app/utils/` - Empty directory (only __pycache__)
-- `app/routers/debug.py` - Debug endpoint not needed in production
-
-**Total:** 1 directory, 1 file
-
-## Files to Keep
-
-### Core Application
-- `app/` directory (except items listed for removal)
-  - `main.py` - FastAPI application
-  - `config.py` - Configuration
-  - `middleware.py` - API key authentication
-  - `models/openai.py` - Pydantic models
-  - `providers/base.py` - Provider protocol
-  - `providers/transformers_provider.py` - Main inference engine
-  - `routers/openai_api.py` - OpenAI-compatible API
-  - `services/chat_service.py` - Chat service wrapper
-
-### Tests
-- `tests/` directory - Proper pytest structure
-  - `conftest.py`
-  - `test_config.py`
-  - `test_middleware.py`
-  - `test_openai_models.py`
-  - `test_openai_routes.py`
-  - `test_providers.py`
-  - `performance/` - Performance benchmarks
-
-### Documentation
-- `README.md` - Main documentation (needs cleanup)
-- `FINAL_STATUS.md` - Final deployment status
-- `FINAL_TEST_REPORT.md` - Comprehensive test results
-- `LICENSE` - MIT license
-
-### Configuration & Deployment
-- `Dockerfile` - Docker build configuration
-- `requirements.txt` - Production dependencies
-- `requirements-dev.txt` - Development dependencies
-
-### Scripts
-- `scripts/validate_hf_readme.py` - Useful validation utility
-- `scripts/README.md` - Scripts documentation
-
-## Refactoring Needed
-
-### 1. Remove Debug Router from Production
-**File:** `app/main.py`
-**Change:** Remove debug router import and mount
-```python
-# Remove this line
-app.include_router(debug.router, prefix="/v1")
-```
-
-### 2. Clean Up README.md
-**File:** `README.md`
-**Changes:**
-- Remove outdated test coverage stats (91% reference)
-- Update to reflect current stable state
-- Simplify configuration section
-- Remove references to obsolete features
-
-### 3. Remove Empty Utils Directory
-**Directory:** `app/utils/`
-**Action:** Delete the entire directory as it's unused
-
-## Impact Assessment
-
-### Breaking Changes
-**None** - All removed files are development/debugging artifacts.
-
-### Non-Breaking Changes
-- Removing debug endpoint (`/v1/debug/prompt`) - Not documented in README
-- Cleaner project structure
-- Reduced repository size
-
-### Benefits
-- **Clarity:** Easier to understand project structure
-- **Maintenance:** Fewer files to maintain
-- **Size:** Reduced repo size
-- **Professionalism:** Clean, production-ready codebase
-
-## Execution Plan
-
-1. ✅ Create backup branch
-2. ✅ Remove obsolete test files
-3. ✅ Remove obsolete documentation
-4. ✅ Remove debug code
-5. ✅ Update README.md
-6. ✅ Run tests to verify nothing broke
-7. ✅ Commit and push changes
-
-## Success Criteria
-
-- ✅ All tests in `tests/` directory still pass
-- ✅ Application still starts and serves requests
-- ✅ README.md is accurate and up-to-date
-- ✅ No broken imports or references
-- ✅ Git history preserved (files deleted, not rewritten)
-
-## Rollback Plan
-
-If issues arise:
-1. Git checkout the cleanup branch: `git checkout pre-cleanup-backup`
-2. Review what was removed
-3. Restore only necessary files
-

CLEANUP_SUMMARY.md

@@ -1,190 +0,0 @@
-# Cleanup Summary - November 2, 2025
-
-## Overview
-Comprehensive codebase cleanup to remove obsolete test scripts, redundant documentation, and debug code from the project.
-
-## Files Removed
-
-### Test Scripts (21 files)
-All one-off debugging and validation scripts have been removed. Proper tests remain in `tests/` directory.
-
-✅ Removed:
-- `analyze_performance.py`
-- `debug_chat_template.py`
-- `final_clean_test.py`
-- `investigate_french_consistency.py`
-- `quiz_finance_francais.py`
-- `test_advanced_finance.py`
-- `test_all_fixes.py`
-- `test_debug_endpoint.sh`
-- `test_finance_final.py`
-- `test_finance_improved.py`
-- `test_finance_queries.py`
-- `test_french_direct.py`
-- `test_french_final_check.py`
-- `test_french_simple.sh`
-- `test_french_strategies.py`
-- `test_generation_fix.sh`
-- `test_memory_stress.py`
-- `test_quick_french.py`
-- `test_service.py`
-- `test_system_prompt.py`
-- `test_tokenizer_debug.py`
-- `test_truncation_issue.py`
-
-### Documentation Files (5 files)
-Historical documentation superseded by comprehensive final reports.
-
-✅ Removed:
-- `STATUS.md` (superseded by FINAL_STATUS.md)
-- `FIXES_SUMMARY.md` (covered in FINAL_TEST_REPORT.md)
-- `PERFORMANCE_REPORT.md` (covered in FINAL_TEST_REPORT.md)
-- `memory_test_results.txt` (old test results)
-- `test_results.txt` (old test results)
-
-### Code Files (2 items)
-Debug code not needed in production.
-
-✅ Removed:
-- `app/routers/debug.py` - Debug endpoint for prompt inspection
-- `app/utils/` - Empty directory
-
-## Code Changes
-
-### Modified: `app/main.py`
-**Before:**
-```python
-from app.routers import openai_api, debug
-...
-app.include_router(debug.router, prefix="/v1")
-```
-
-**After:**
-```python
-from app.routers import openai_api
-...
-# Debug router removed
-```
-
-### Modified: `README.md`
-Updated to reflect:
-- Current stable state (production-ready)
-- Accurate feature list
-- Better API examples with realistic max_tokens
-- Chain-of-thought reasoning explanation
-- Language support details
-- Removed outdated test coverage stats
-- Added technical specifications section
-
-## Project Structure (After Cleanup)
-
-```
-simple-llm-pro-finance/
-├── app/                          # Core application
-│   ├── config.py                 # Configuration
-│   ├── main.py                   # FastAPI app
-│   ├── middleware.py             # API key auth
-│   ├── models/
-│   │   └── openai.py            # Pydantic models
-│   ├── providers/
-│   │   ├── base.py              # Provider protocol
-│   │   └── transformers_provider.py  # Main inference engine
-│   ├── routers/
-│   │   └── openai_api.py        # OpenAI-compatible API
-│   └── services/
-│       └── chat_service.py      # Chat service wrapper
-├── tests/                        # Proper test suite
-│   ├── conftest.py
-│   ├── test_*.py                # Unit tests
-│   └── performance/             # Performance benchmarks
-├── scripts/                      # Utility scripts
-│   └── validate_hf_readme.py    # README validator
-├── Dockerfile                    # Docker build config
-├── requirements.txt              # Production dependencies
-├── requirements-dev.txt          # Development dependencies
-├── README.md                     # Main documentation
-├── FINAL_STATUS.md              # Deployment status
-├── FINAL_TEST_REPORT.md         # Test results & metrics
-├── CLEANUP_PLAN.md              # This cleanup plan
-└── LICENSE                       # MIT license
-```
-
-## Impact Assessment
-
-### Breaking Changes
-**None** - All removed files were development artifacts.
-
-### Removed Endpoints
-- `/v1/debug/prompt` - Debug endpoint (never documented in README)
-
-### Benefits
-- ✅ **Cleaner structure** - 28 fewer files in root directory
-- ✅ **Better organization** - Clear separation of concerns
-- ✅ **Easier navigation** - No clutter from obsolete scripts
-- ✅ **Professional appearance** - Production-ready codebase
-- ✅ **Reduced confusion** - No outdated documentation
-- ✅ **Smaller repo size** - Faster clones and deployments
-
-## Verification
-
-### Syntax Validation
-✅ All Python files compile successfully:
-- `app/main.py` ✓
-- `app/routers/openai_api.py` ✓
-- `app/services/chat_service.py` ✓
-
-### Import Structure
-✅ No broken imports detected
-✅ All module dependencies satisfied
-
-### Test Suite
-✅ Tests remain in `tests/` directory
-✅ Proper pytest structure maintained
-✅ Performance benchmarks preserved
-
-## Git Status
-
-### Staged Changes (Existing)
-- `app/providers/transformers_provider.py` (previous work)
-- `quiz_finance_francais.py` (previous work)
-
-### Unstaged Changes (This Cleanup)
-- Modified: `app/main.py` (removed debug router)
-- Modified: `README.md` (updated documentation)
-- Deleted: 26 obsolete files
-- Added: `CLEANUP_PLAN.md` (this document)
-
-## Backup
-✅ Backup branch created: `pre-cleanup-backup`
-
-To restore if needed:
-```bash
-git checkout pre-cleanup-backup
-```
-
-## Next Steps
-
-1. ✅ Review changes
-2. ⏳ Stage cleanup changes: `git add -A`
-3. ⏳ Commit: `git commit -m "Clean up: Remove obsolete test scripts and documentation"`
-4. ⏳ Optional: Squash with staged changes
-5. ⏳ Push to repository
-
-## Success Criteria
-
-- ✅ All obsolete files removed
-- ✅ Code syntax valid
-- ✅ No broken imports
-- ✅ README updated and accurate
-- ✅ Backup created
-- ✅ Professional project structure
-
-## Summary
-
-**Removed:** 28 files (21 test scripts, 5 docs, 2 code files)  
-**Modified:** 2 files (main.py, README.md)  
-**Added:** 2 files (CLEANUP_PLAN.md, CLEANUP_SUMMARY.md)  
-**Net Change:** -24 files
-
-The codebase is now clean, well-organized, and production-ready! 🎉
-

CODERABBIT_SETUP.md

@@ -1,83 +0,0 @@
-# CodeRabbit Setup Troubleshooting
-
-## Issue: CodeRabbit not appearing in PRs
-
-### Step 1: Verify Installation
-
-1. Go to: https://github.com/marketplace/coderabbitai
-2. Click "Install it for free" or "Configure access"
-3. Make sure it's installed for your organization/user
-4. Verify it has access to `DealExMachina/simple-llm-pro-finance`
-
-### Step 2: Check Repository Settings
-
-1. Go to: https://github.com/DealExMachina/simple-llm-pro-finance/settings/installations
-2. Look for "CodeRabbitAI" in installed GitHub Apps
-3. Click "Configure" next to it
-4. Ensure this repository is selected (or "All repositories")
-
-### Step 3: Check Webhooks
-
-1. Go to: https://github.com/DealExMachina/simple-llm-pro-finance/settings/hooks
-2. Look for a webhook pointing to: `https://app.coderabbit.ai/githubHandler`
-3. If missing, CodeRabbit should create it automatically, but you can check
-
-### Step 4: Test with a Real PR
-
-CodeRabbit may need:
-- **Code changes** (not just docs)
-- **Multiple files** changed
-- **Python files** to review
-
-Try this:
-
-```bash
-# Create a test PR with actual code changes
-git checkout -b test-coderabbit-code
-# Make a small code change (add a comment, fix formatting)
-# Then create PR
-```
-
-### Step 5: Check PR for CodeRabbit Bot
-
-- Look for user: `@coderabbitai` or `@coderabbit`
-- Check "Conversation" tab in PR
-- Sometimes it takes 2-5 minutes to appear
-
-### Step 6: Manual Trigger
-
-Try adding this to your PR description:
-```
-@coderabbitai please review
-```
-
-Or mention it:
-```
-@coderabbit please review this PR
-```
-
-### Step 7: Verify Configuration File
-
-The `.coderabbit.yaml` file has been created. CodeRabbit should respect this configuration.
-
-### Alternative: Use CodeRabbit Comments
-
-If CodeRabbit is installed but not auto-commenting, try:
-1. Comment in the PR: `/review` or `/review_code`
-2. Or use: `/ask @coderabbitai review this PR`
-
-## Still Not Working?
-
-1. Check CodeRabbit status: https://status.coderabbit.ai/
-2. Review CodeRabbit docs: https://docs.coderabbit.ai/
-3. Contact support: https://coderabbit.ai/support
-
-## What CodeRabbit Should Review:
-
-- Code quality and best practices
-- Security vulnerabilities
-- Performance issues
-- Python-specific patterns
-- Error handling
-- Documentation completeness
-

CODERABBIT_TEST_PR.md

@@ -1,15 +0,0 @@
-# CodeRabbit Test PR - Code Changes
-
-This PR includes intentional code changes that CodeRabbit should review:
-
-## Changes Made:
-1. Added input validation to chat completions endpoint
-2. Improved error handling with better error messages
-3. Added type hints improvements
-
-## What CodeRabbit Should Catch:
-- Code quality improvements
-- Potential security issues
-- Best practices suggestions
-- Python typing improvements
-

CODE_REVIEW_SUMMARY.md

@@ -1,119 +0,0 @@
-# Code Review and Cleanup Summary
-
-**Date:** November 2, 2025  
-**Reviewer:** AI Assistant  
-**Status:** Complete
-
-## Executive Summary
-
-Comprehensive codebase cleanup removing 28 obsolete files and refactoring documentation to be professional and concise.
-
-## Changes Made
-
-### Files Removed: 28
-
-**Test Scripts (21 files):**
-- All one-off test/debug scripts moved or removed
-- Proper tests retained in `tests/` directory
-
-**Documentation (5 files):**
-- Obsolete status reports superseded by final documentation
-- Old test result files removed
-
-**Code (2 items):**
-- Debug router removed from production code
-- Empty utils directory removed
-
-### Files Modified: 2
-
-**app/main.py:**
-- Removed debug router import and mount
-- Cleaned up for production deployment
-
-**README.md:**
-- Removed all emojis from section headers
-- Eliminated redundant self-congratulatory content
-- Condensed from 189 to 139 lines
-- Made professional and concise
-- Removed "Features" checklist section
-- Streamlined technical specifications
-- Removed unnecessary "Contributing" section
-
-### Files Added: 3
-
-- `CLEANUP_PLAN.md` - Detailed cleanup strategy
-- `CLEANUP_SUMMARY.md` - Execution summary
-- `CODE_REVIEW_SUMMARY.md` - This document
-
-## Project Structure (After Cleanup)
-
-```
-simple-llm-pro-finance/
-├── app/                    # Application code
-│   ├── config.py
-│   ├── main.py
-│   ├── middleware.py
-│   ├── models/
-│   ├── providers/
-│   ├── routers/
-│   └── services/
-├── tests/                  # Test suite
-├── scripts/                # Utilities
-├── Dockerfile
-├── requirements.txt
-├── requirements-dev.txt
-├── README.md              # Clean, professional docs
-├── FINAL_STATUS.md
-├── FINAL_TEST_REPORT.md
-└── LICENSE
-```
-
-## Code Quality Improvements
-
-**Before:**
-- 50+ files in repository
-- Multiple redundant documentation files
-- Debug endpoints in production code
-- Verbose, emoji-heavy documentation
-- Test scripts scattered in root directory
-
-**After:**
-- 26 essential files
-- Single source of truth for documentation
-- Production-ready code only
-- Professional, concise documentation
-- Organized test directory structure
-
-## Verification
-
-- Python syntax validation: PASSED
-- Import structure: VALID
-- No broken references: CONFIRMED
-- Backup created: `pre-cleanup-backup` branch
-
-## Impact
-
-**Breaking Changes:** None  
-**Removed Endpoints:** `/v1/debug/prompt` (undocumented)  
-**Repository Size:** Reduced by ~24 files  
-**Maintainability:** Significantly improved
-
-## Recommendations
-
-### Immediate
-1. Review and approve changes
-2. Stage all changes: `git add -A`
-3. Commit with message: "refactor: Clean up codebase - remove obsolete files and improve documentation"
-4. Push to repository
-
-### Future Considerations
-1. Consider removing `CLEANUP_PLAN.md` and `CLEANUP_SUMMARY.md` after merge
-2. Update `.gitignore` to prevent future test script accumulation
-3. Establish guidelines for temporary debugging files
-
-## Conclusion
-
-The codebase is now clean, professional, and production-ready. All obsolete development artifacts have been removed, documentation is concise and accurate, and the project structure is well-organized.
-
-**Net Result:** -24 files, cleaner code, better documentation.
-

TEST_CODERABBIT.md

@@ -1,40 +0,0 @@
-# Testing CodeRabbit Integration
-
-## What to do:
-
-1. **Create a branch:**
-   ```bash
-   git checkout -b test-coderabbit-review
-   ```
-
-2. **Commit this test file:**
-   ```bash
-   git add TEST_CODERABBIT.md .github/pull_request_template.md
-   git commit -m "test: Add PR template and test CodeRabbit integration"
-   ```
-
-3. **Push and create PR:**
-   ```bash
-   git push origin test-coderabbit-review
-   ```
-   Then go to GitHub and create a Pull Request from `test-coderabbit-review` to `master`
-
-4. **Watch for CodeRabbit:**
-   - CodeRabbit should automatically comment on your PR
-   - It will review code quality, suggest improvements
-   - Check for CodeRabbit comments in the PR thread
-
-## What CodeRabbit will review:
-- Code quality and best practices
-- Potential bugs or security issues
-- Performance optimizations
-- Documentation completeness
-- Test coverage
-
-## To test more thoroughly:
-After this test, try creating a PR with:
-- A small bug (see if it catches it)
-- Missing error handling
-- Performance issues
-- Security concerns
-

app/middleware.py

@@ -1,26 +1,46 @@
-from fastapi import Request, HTTPException
-from fastapi.responses import JSONResponse
+from fastapi import Request
+from fastapi.responses import JSONResponse, Response
+from typing import Callable, Awaitable, Union
 
 from app.config import settings
 
+# Public endpoints that don't require authentication
+PUBLIC_PATHS = frozenset(["/", "/health", "/docs", "/redoc", "/openapi.json"])
 
-async def api_key_guard(request: Request, call_next):
-    # Public endpoints that don't require authentication
-    public_paths = ["/", "/health", "/docs", "/redoc", "/openapi.json"]
+
+async def api_key_guard(request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> Union[Response, JSONResponse]:
+    """
+    Middleware to protect API endpoints with optional API key authentication.
+    
+    Args:
+        request: FastAPI request object
+        call_next: Next middleware/handler in the chain
     
+    Returns:
+        Response from next handler or 401 if unauthorized
+    """
     # Skip auth for public endpoints
-    if request.url.path in public_paths:
+    if request.url.path in PUBLIC_PATHS:
         return await call_next(request)
     
     # Skip auth if no API key is configured
     if not settings.service_api_key:
         return await call_next(request)
     
-    # Check API key
-    key = request.headers.get("x-api-key") or request.headers.get("authorization")
-    if key and key.replace("Bearer ", "").strip() == settings.service_api_key:
+    # Check API key from headers
+    api_key = request.headers.get("x-api-key")
+    if not api_key:
+        # Also check Authorization header with Bearer token
+        auth_header = request.headers.get("authorization", "")
+        if auth_header.startswith("Bearer "):
+            api_key = auth_header.replace("Bearer ", "").strip()
+    
+    if api_key and api_key == settings.service_api_key:
         return await call_next(request)
     
-    return JSONResponse({"error": "unauthorized"}, status_code=401)
+    return JSONResponse(
+        content={"error": {"message": "unauthorized", "type": "authentication_error"}},
+        status_code=401
+    )
 
 

app/providers/transformers_provider.py

@@ -3,7 +3,7 @@ import time
 import json
 import logging
 import torch
-from typing import Dict, Any, AsyncIterator, Union
+from typing import Dict, Any, AsyncIterator, Union, List
 import asyncio
 from threading import Thread, Lock
 from huggingface_hub import login, hf_hub_download
@@ -386,20 +386,28 @@ class TransformersProvider:
         yield f"data: {json.dumps(final_chunk, ensure_ascii=False)}\n\n"
         yield "data: [DONE]\n\n"
     
-    def _messages_to_prompt(self, messages: list) -> str:
-        """Convert OpenAI messages format to prompt (fallback)."""
-        prompt = ""
+    def _messages_to_prompt(self, messages: List[Dict[str, str]]) -> str:
+        """
+        Convert OpenAI messages format to prompt (fallback).
+        
+        Args:
+            messages: List of message dictionaries with 'role' and 'content'
+        
+        Returns:
+            Formatted prompt string
+        """
+        prompt_parts = []
         for message in messages:
-            role = message["role"]
-            content = message["content"]
+            role = message.get("role", "user")
+            content = message.get("content", "")
             if role == "system":
-                prompt += f"System: {content}\n"
+                prompt_parts.append(f"System: {content}")
             elif role == "user":
-                prompt += f"User: {content}\n"
+                prompt_parts.append(f"User: {content}")
             elif role == "assistant":
-                prompt += f"Assistant: {content}\n"
-        prompt += "Assistant: "
-        return prompt
+                prompt_parts.append(f"Assistant: {content}")
+        prompt_parts.append("Assistant: ")
+        return "\n".join(prompt_parts)
 
 
 # Module-level provider instance

app/routers/openai_api.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict
+from typing import Any, Dict, Union
 import logging
 
 from fastapi import APIRouter, Query
@@ -15,13 +15,13 @@ router = APIRouter()
 
 
 @router.get("/models")
-async def list_models():
+async def list_models() -> Dict[str, Any]:
     """List available models (OpenAI-compatible endpoint)"""
     return await chat_service.list_models()
 
 
 @router.post("/models/reload")
-async def reload_model(force: bool = Query(False, description="Force reload from Hugging Face Hub")):
+async def reload_model(force: bool = Query(False, description="Force reload from Hugging Face Hub")) -> JSONResponse:
     """
     Reload the model from cache or Hugging Face Hub.
     
@@ -51,7 +51,7 @@ async def reload_model(force: bool = Query(False, description="Force reload from
 
 
 @router.post("/chat/completions")
-async def chat_completions(body: ChatCompletionRequest):
+async def chat_completions(body: ChatCompletionRequest) -> Union[JSONResponse, StreamingResponse]:
     """Chat completions endpoint (OpenAI-compatible)"""
     try:
         # Validate messages list is not empty

app/services/chat_service.py

@@ -1,13 +1,33 @@
-from typing import Any, Dict
+"""Chat service layer providing abstraction over the provider."""
+from typing import Any, Dict, Union, AsyncIterator
 
 from app.providers import transformers_provider as provider
 
 
 async def list_models() -> Dict[str, Any]:
+    """
+    List available models.
+    
+    Returns:
+        Dictionary containing model list in OpenAI-compatible format
+    """
     return await provider.list_models()
 
 
-async def chat(payload: Dict[str, Any], stream: bool = False):
+async def chat(
+    payload: Dict[str, Any], 
+    stream: bool = False
+) -> Union[Dict[str, Any], AsyncIterator[str]]:
+    """
+    Process chat completion request.
+    
+    Args:
+        payload: Request payload containing messages and generation parameters
+        stream: Whether to stream the response
+    
+    Returns:
+        Response dictionary or async iterator for streaming
+    """
     return await provider.chat(payload, stream=stream)
 
 

app/utils/helpers.py

@@ -2,7 +2,7 @@
 
 import os
 import logging
-from typing import Optional, Tuple
+from typing import Optional, Tuple, List, Dict, Any
 
 from app.utils.constants import HF_TOKEN_VARS, FRENCH_PHRASES, FRENCH_CHARS, FRENCH_PATTERNS
 
@@ -24,7 +24,7 @@ def get_hf_token() -> Tuple[Optional[str], str]:
     return None, "none"
 
 
-def is_french_request(messages: list) -> bool:
+def is_french_request(messages: List[Dict[str, Any]]) -> bool:
     """
     Detect if the request is in French based on user messages.
     
@@ -55,7 +55,7 @@ def is_french_request(messages: list) -> bool:
     return False
 
 
-def has_french_system_prompt(messages: list) -> bool:
+def has_french_system_prompt(messages: List[Dict[str, Any]]) -> bool:
     """Check if messages already contain a French system prompt."""
     return any(
         "français" in msg.get("content", "").lower()