rahim237cm commited on
Commit
9cf9a2a
·
0 Parent(s):

chore: initial standalone backend for JuriX API (Render)

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. .env.example +42 -0
  2. .gitignore +52 -0
  3. Dockerfile +69 -0
  4. README.md +659 -0
  5. alembic.ini +116 -0
  6. alembic/env.py +81 -0
  7. alembic/script.py.mako +24 -0
  8. alembic/versions/001_initial_schema.py +97 -0
  9. alembic/versions/002_add_rag_tables.py +69 -0
  10. alembic/versions/003_add_persona_analytics.py +130 -0
  11. alembic/versions/004_add_processing_status.py +36 -0
  12. alembic/versions/005_add_category_icon.py +26 -0
  13. alembic/versions/006_add_display_order.py +27 -0
  14. alembic/versions/0b21fb6a3651_add_user_model_and_update_relationships.py +141 -0
  15. alembic/versions/1e5feee465ba_merge_heads.py +24 -0
  16. alembic/versions/3f0760423953_add_file_tracking_real.py +62 -0
  17. alembic/versions/668e3740d3b5_add_page_number_to_articles.py +24 -0
  18. alembic/versions/7a8b9c0d1e2f_enable_pgvector.py +65 -0
  19. app/__init__.py +0 -0
  20. app/api/__init__.py +0 -0
  21. app/api/dependencies/__init__.py +5 -0
  22. app/api/routes/__init__.py +0 -0
  23. app/api/routes/admin.py +335 -0
  24. app/api/routes/analytics.py +291 -0
  25. app/api/routes/articles.py +167 -0
  26. app/api/routes/batch_upload.py +302 -0
  27. app/api/routes/categories.py +600 -0
  28. app/api/routes/classifier.py +392 -0
  29. app/api/routes/language.py +284 -0
  30. app/api/routes/laws.py +810 -0
  31. app/api/routes/ocr.py +206 -0
  32. app/api/routes/personas.py +708 -0
  33. app/api/routes/rag.py +353 -0
  34. app/api/routes/search.py +668 -0
  35. app/api/routes/upload.py +248 -0
  36. app/core/__init__.py +0 -0
  37. app/core/auth.py +188 -0
  38. app/core/celery_app.py +50 -0
  39. app/core/config.py +70 -0
  40. app/core/database.py +160 -0
  41. app/core/dependencies.py +151 -0
  42. app/main.py +77 -0
  43. app/models/__init__.py +30 -0
  44. app/models/conversation.py +224 -0
  45. app/models/law.py +245 -0
  46. app/models/user.py +107 -0
  47. app/schemas/file_upload.py +238 -0
  48. app/schemas/law.py +467 -0
  49. app/schemas/ocr.py +213 -0
  50. app/schemas/persona.py +428 -0
.env.example ADDED
@@ -0,0 +1,42 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ============================================================
2
+ # JuriX Backend — Environment Variables
3
+ # Copy this file to .env and fill in your values.
4
+ # ============================================================
5
+
6
+ # ---- Application ----
7
+ ENVIRONMENT=development
8
+ DEBUG=true
9
+
10
+ # ---- Neon PostgreSQL (pgvector) ----
11
+ # Get this from your Neon project dashboard → Connection string
12
+ # ⚠️ Add ?sslmode=require at the end for production
13
+ DATABASE_URL=postgresql+asyncpg://user:password@ep-xxx-yyy.eu-central-1.aws.neon.tech/neondb?sslmode=require
14
+
15
+ # ---- Upstash Redis ----
16
+ # Get this from your Upstash console → REST API or Redis URL
17
+ # Use rediss:// (with SSL) for Upstash
18
+ REDIS_URL=rediss://:your-upstash-password@your-endpoint.upstash.io:6379
19
+
20
+ # ---- Gemini API (Google AI Studio) ----
21
+ GEMINI_API_KEY=your-gemini-api-key-here
22
+ GEMINI_MODEL=gemini-3-flash
23
+ GEMINI_EMBEDDING_MODEL=models/gemini-embedding-001
24
+
25
+ # ---- LlamaParse (LlamaCloud) ----
26
+ LLAMA_CLOUD_API_KEY=llx-your-llama-parse-key-here
27
+
28
+ # ---- Meilisearch ----
29
+ # If self-hosted:
30
+ MEILISEARCH_URL=http://localhost:7700
31
+ MEILISEARCH_KEY=your-meilisearch-master-key
32
+
33
+ # ---- Security ----
34
+ # Generate with: openssl rand -hex 32
35
+ SECRET_KEY=generate-a-strong-random-key-here
36
+ ALGORITHM=HS256
37
+ ACCESS_TOKEN_EXPIRE_MINUTES=30
38
+
39
+ # ---- CORS ----
40
+ # Vercel frontend URL(s), comma-separated (no trailing slash)
41
+ # Example: https://jurix.vercel.app,https://www.jurix.cm
42
+ ALLOWED_ORIGINS=https://jurix.vercel.app
.gitignore ADDED
@@ -0,0 +1,52 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.pyo
5
+ *.pyd
6
+ .Python
7
+ *.egg-info/
8
+ dist/
9
+ build/
10
+
11
+ # Virtual envs
12
+ .venv/
13
+ venv/
14
+ env/
15
+
16
+ # Environment files (never commit secrets)
17
+ .env
18
+ .env.local
19
+ .env.*.local
20
+
21
+ # Testing
22
+ .pytest_cache/
23
+ htmlcov/
24
+ .coverage
25
+ coverage.xml
26
+
27
+ # ML models (large binary files — store elsewhere or use git LFS)
28
+ models/fasttext/
29
+ models/*.bin
30
+ models/*.pkl
31
+
32
+ # Temporary data
33
+ data/
34
+ debug_output.txt
35
+ article_content.txt
36
+ final_verification.txt
37
+ models.txt
38
+ verification_report.txt
39
+ nul
40
+
41
+ # IDE
42
+ .vscode/
43
+ .idea/
44
+ .qodo/
45
+ pyrefly.toml
46
+
47
+ # Docker
48
+ *.dockerignore
49
+
50
+ # OS
51
+ .DS_Store
52
+ Thumbs.db
Dockerfile ADDED
@@ -0,0 +1,69 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # JuriX Backend — Production Dockerfile
2
+ # Python 3.11 avec support ML (scikit-learn, spaCy, fastText)
3
+
4
+ FROM python:3.11-slim
5
+
6
+ LABEL maintainer="JuriX Team <support@jurix.cm>"
7
+ LABEL description="JuriX v2.1 Backend API"
8
+ LABEL version="2.1.0"
9
+
10
+ # System dependencies
11
+ RUN apt-get update && apt-get install -y --no-install-recommends \
12
+ gcc \
13
+ g++ \
14
+ curl \
15
+ git \
16
+ wget \
17
+ ca-certificates \
18
+ && rm -rf /var/lib/apt/lists/*
19
+
20
+ WORKDIR /app
21
+
22
+ # Copy dependency files first (for Docker layer caching)
23
+ COPY pyproject.toml poetry.lock* ./
24
+
25
+ # Install Poetry and dependencies
26
+ RUN pip install --no-cache-dir --upgrade pip && \
27
+ pip install --no-cache-dir poetry==1.7.1
28
+
29
+ RUN poetry config virtualenvs.create false
30
+ RUN poetry install --no-dev --no-interaction --no-ansi
31
+
32
+ # Copy application code
33
+ COPY . .
34
+
35
+ # Download spaCy models
36
+ RUN python -m spacy download fr_core_news_sm --quiet || echo "fr model download failed" && \
37
+ python -m spacy download en_core_web_sm --quiet || echo "en model download failed"
38
+
39
+ # Create required directories
40
+ RUN mkdir -p /app/models/spacy /app/models/fasttext /app/logs /app/data
41
+
42
+ # Download fastText language identification model
43
+ RUN if [ ! -f /app/models/fasttext/lid.176.bin ]; then \
44
+ echo "Downloading fastText model..." && \
45
+ wget -q https://dl.fbaipublicfiles.com/fasttext/supervised-models/lid.176.bin \
46
+ -O /app/models/fasttext/lid.176.bin || \
47
+ echo "fastText model download failed - will skip language detection"; \
48
+ fi
49
+
50
+ # Non-root user for security
51
+ RUN useradd -m -u 1000 -s /bin/bash jurix && \
52
+ chown -R jurix:jurix /app
53
+
54
+ USER jurix
55
+
56
+ # Runtime env vars
57
+ ENV PYTHONUNBUFFERED=1 \
58
+ PYTHONDONTWRITEBYTECODE=1 \
59
+ PYTHONPATH=/app \
60
+ ML_MODELS_PATH=/app/models \
61
+ LOG_LEVEL=INFO
62
+
63
+ # Render provides PORT env var — use it directly
64
+ # Use 1 worker on Render Starter (512 MB RAM); scale up on paid plans
65
+ CMD uvicorn app.main:app \
66
+ --host 0.0.0.0 \
67
+ --port ${PORT:-8000} \
68
+ --workers 1 \
69
+ --log-level info
README.md ADDED
@@ -0,0 +1,659 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # JuriX Backend v2.1
2
+
3
+ Backend API pour la plateforme juridique camerounaise JuriX.
4
+
5
+ ## 🚀 Quick Start
6
+
7
+ ### Prérequis
8
+
9
+ - Python 3.11+
10
+ - PostgreSQL 15+ avec pgvector
11
+ - Redis 7.2+
12
+ - Meilisearch 1.5+
13
+ - Ollama avec mistral:7b
14
+
15
+ ### Installation
16
+
17
+ ```bash
18
+ # Cloner le projet
19
+ cd backend
20
+
21
+ # Installer les dépendances
22
+ pip install -r requirements.txt
23
+ # OU avec Poetry
24
+ poetry install
25
+
26
+ # Télécharger les modèles NLP (requis pour détection de langue)
27
+ python scripts/download_models.py
28
+
29
+ # Configurer les variables d'environnement
30
+ cp .env.example .env
31
+ # Éditer .env avec vos paramètres
32
+
33
+ # Lancer les migrations
34
+ alembic upgrade head
35
+
36
+ # Démarrer le serveur
37
+ uvicorn app.main:app --reload
38
+ ```
39
+
40
+ L'API sera disponible sur `http://localhost:8000`
41
+
42
+ Documentation interactive: `http://localhost:8000/docs`
43
+
44
+ ## 📦 Modules Implémentés
45
+
46
+ ### ✅ Module 1: Détection Automatique de Langue
47
+
48
+ Service de détection automatique de langue pour documents juridiques.
49
+
50
+ **Architecture:** Triple-méthode ensemble avec vote majoritaire
51
+ - **Méthodes:** langdetect + spaCy + fastText
52
+ - **Précision:** >99% sur documents juridiques
53
+ - **Performance:** <1s pour textes jusqu'à 5000 caractères
54
+ - **Langues:** Français + Anglais (extensible)
55
+
56
+ #### Setup
57
+
58
+ ```bash
59
+ # 1. Télécharger les modèles NLP
60
+ python scripts/download_models.py
61
+
62
+ # Ceci télécharge:
63
+ # - spaCy fr_core_news_sm (~60MB)
64
+ # - spaCy en_core_web_sm (~60MB)
65
+ # - fastText lid.176.bin (~130MB)
66
+ # Total: ~250MB
67
+
68
+ # 2. Vérifier l'installation
69
+ python -c "from app.services.language_detector import LanguageDetector; d = LanguageDetector(); print(d.health_check())"
70
+ ```
71
+
72
+ #### Usage Programmatique
73
+
74
+ ```python
75
+ from app.services.language_detector import LanguageDetector
76
+
77
+ # Créer instance (charge les modèles)
78
+ detector = LanguageDetector()
79
+
80
+ # Détecter langue
81
+ text = """
82
+ Article 1. La présente loi régit les conditions de création
83
+ des sociétés commerciales au Cameroun conformément au droit OHADA.
84
+ """
85
+
86
+ result = detector.detect(text)
87
+
88
+ print(result)
89
+ # {
90
+ # 'language': 'fr',
91
+ # 'confidence': 0.98,
92
+ # 'method_votes': {
93
+ # 'langdetect': 'fr',
94
+ # 'spacy': 'fr',
95
+ # 'fasttext': 'fr'
96
+ # },
97
+ # 'consensus': True,
98
+ # 'processing_time_ms': 450,
99
+ # 'text_length': 156
100
+ # }
101
+ ```
102
+
103
+ #### Usage API
104
+
105
+ ```bash
106
+ # Détecter langue d'un texte
107
+ curl -X POST http://localhost:8000/api/v1/language/detect \
108
+ -H "Content-Type: application/json" \
109
+ -d '{
110
+ "text": "Article 1. La présente loi régit les sociétés commerciales au Cameroun.",
111
+ "min_confidence": 0.80
112
+ }'
113
+
114
+ # Réponse:
115
+ # {
116
+ # "language": "fr",
117
+ # "confidence": 0.98,
118
+ # "method_votes": {
119
+ # "langdetect": "fr",
120
+ # "spacy": "fr",
121
+ # "fasttext": "fr"
122
+ # },
123
+ # "consensus": true,
124
+ # "processing_time_ms": 450,
125
+ # "text_length": 75
126
+ # }
127
+
128
+ # Health check
129
+ curl http://localhost:8000/api/v1/language/health
130
+
131
+ # Réponse:
132
+ # {
133
+ # "service": "LanguageDetector",
134
+ # "status": "healthy",
135
+ # "models": {
136
+ # "spacy_fr": "✅ OK",
137
+ # "spacy_en": "✅ OK",
138
+ # "fasttext": "✅ OK"
139
+ # }
140
+ # }
141
+ ```
142
+
143
+ #### Tests
144
+
145
+ ```bash
146
+ # Tests unitaires (5 tests de base + edge cases)
147
+ pytest backend/tests/test_services/test_language_detector.py -v
148
+
149
+ # Avec coverage
150
+ pytest backend/tests/test_services/test_language_detector.py -v \
151
+ --cov=backend/app/services/language_detector \
152
+ --cov-report=html
153
+
154
+ # Génération tests Qodo (auto, ~25 tests)
155
+ qodo test generate backend/app/services/language_detector.py --max-tests 25
156
+
157
+ # Tous les tests
158
+ pytest backend/tests/test_services/test_language_detector.py -v
159
+ ```
160
+
161
+ #### Troubleshooting
162
+
163
+ **❌ Erreur: "No module named spacy"**
164
+ ```bash
165
+ pip install spacy langdetect fasttext-wheel scikit-learn
166
+ ```
167
+
168
+ **❌ Erreur: "Can't find model 'fr_core_news_sm'"**
169
+ ```bash
170
+ python scripts/download_models.py
171
+ # OU manuellement:
172
+ python -m spacy download fr_core_news_sm
173
+ python -m spacy download en_core_web_sm
174
+ ```
175
+
176
+ **❌ Erreur: "fastText model not found"**
177
+ ```bash
178
+ # Télécharger manuellement
179
+ wget https://dl.fbaipublicfiles.com/fasttext/supervised-models/lid.176.bin \
180
+ -O backend/models/fasttext/lid.176.bin
181
+ ```
182
+
183
+ **❌ Performance lente (>2s)**
184
+ - Vérifier que ThreadPoolExecutor est utilisé (parallélisme)
185
+ - Réduire la longueur du texte (sampling automatique à 5000 chars)
186
+ - Utiliser singleton pattern (éviter rechargement modèles)
187
+
188
+ **❌ Précision faible (<95%)**
189
+ - Vérifier longueur texte (minimum 100 chars recommandé)
190
+ - Textes bilingues donnent confiance plus basse (normal)
191
+ - Vérifier que les 3 modèles sont correctement chargés
192
+
193
+ ## 🧪 Tests
194
+
195
+ ### Lancer les tests
196
+
197
+ ```bash
198
+ # Tous les tests
199
+ pytest backend/tests/ -v
200
+
201
+ # Tests spécifiques
202
+ pytest backend/tests/test_services/test_language_detector.py -v
203
+
204
+ # Avec coverage
205
+ pytest backend/tests/ -v --cov=backend/app --cov-report=html
206
+
207
+ # Tests de performance
208
+ pytest backend/tests/test_services/test_language_detector.py::TestLanguageDetectorPerformance -v
209
+ ```
210
+
211
+ ### Structure des tests
212
+
213
+ ```
214
+ backend/tests/
215
+ ├── test_main.py # Tests de base (health check, root)
216
+ ├── test_services/
217
+ │ └── test_language_detector.py # Tests détection langue (32 tests)
218
+ ├── test_api/
219
+ │ └── (à venir)
220
+ ├── test_tasks/
221
+ │ └── (à venir)
222
+ ├── integration/
223
+ │ └── (à venir)
224
+ └── performance/
225
+ └── (à venir)
226
+ ```
227
+
228
+ ## 📊 Code Quality
229
+
230
+ ### Linting & Formatting
231
+
232
+ ```bash
233
+ # Black (formatting)
234
+ black backend/app backend/tests
235
+
236
+ # Ruff (linting)
237
+ ruff check backend/app backend/tests
238
+
239
+ # MyPy (type checking)
240
+ mypy backend/app/services/language_detector.py
241
+
242
+ # Pylint
243
+ pylint backend/app/services/language_detector.py
244
+ ```
245
+
246
+ ### Coverage Target
247
+
248
+ - **Overall:** >80%
249
+ - **Services:** >85%
250
+ - **Critical paths:** >95%
251
+
252
+ ## 🐳 Docker
253
+
254
+ ```bash
255
+ # Build image
256
+ docker build -t jurix-backend:v2.1 -f docker/Dockerfile.prod .
257
+
258
+ # Run avec docker-compose
259
+ docker-compose up -d
260
+
261
+ # Vérifier logs
262
+ docker-compose logs -f api
263
+
264
+ # Health check
265
+ curl http://localhost:8000/health
266
+ curl http://localhost:8000/api/v1/language/health
267
+ ```
268
+
269
+ ## 📁 Structure du Projet
270
+
271
+ ```
272
+ backend/
273
+ ├── app/
274
+ │ ├── __init__.py
275
+ │ ├── main.py # Point d'entrée FastAPI
276
+ │ ├── core/
277
+ │ │ ├── config.py # Configuration (Settings)
278
+ │ │ └── dependencies.py # Dependency injection
279
+ │ ├── api/
280
+ │ │ ├── routes/
281
+ │ │ │ └── language.py # ✅ Endpoints détection langue
282
+ │ │ └── dependencies/
283
+ │ ├── services/
284
+ │ │ └── language_detector.py # ✅ Service détection langue
285
+ │ ├── models/ # ORM models (SQLAlchemy)
286
+ │ ├── tasks/ # Celery tasks
287
+ │ └── utils/ # Utilitaires
288
+ ├── models/ # Modèles NLP
289
+ │ ├── spacy/
290
+ │ │ ├── fr_core_news_sm/
291
+ │ │ └── en_core_web_sm/
292
+ │ └── fasttext/
293
+ │ └── lid.176.bin
294
+ ├── scripts/
295
+ │ └── download_models.py # ✅ Script téléchargement modèles
296
+ ├── tests/
297
+ │ ├── test_main.py
298
+ │ └── test_services/
299
+ │ └── test_language_detector.py # ✅ 32 tests
300
+ ├── alembic/ # Migrations DB
301
+ │ ├── env.py
302
+ │ └── versions/
303
+ │ └── 001_initial_schema.py
304
+ ├── pyproject.toml # Dependencies (Poetry)
305
+ ├── requirements.txt # Dependencies (pip)
306
+ └── README.md # This file
307
+ ```
308
+
309
+ ## 🔧 Configuration
310
+
311
+ Variables d'environnement (.env):
312
+
313
+ ```bash
314
+ # App
315
+ APP_NAME="JuriX API"
316
+ VERSION="2.1.0"
317
+ DEBUG=True
318
+ ENVIRONMENT="development"
319
+
320
+ # Database
321
+ DATABASE_URL="postgresql://jurix:password@localhost:5432/jurix_db"
322
+
323
+ # Redis
324
+ REDIS_URL="redis://:password@localhost:6379/0"
325
+
326
+ # Meilisearch
327
+ MEILISEARCH_URL="http://localhost:7700"
328
+ MEILISEARCH_KEY="master_key"
329
+
330
+ # Ollama
331
+ OLLAMA_URL="http://localhost:11434"
332
+ OLLAMA_MODEL="mistral:7b"
333
+
334
+ # Security
335
+ SECRET_KEY="your_secret_key_here"
336
+ ALGORITHM="HS256"
337
+ ACCESS_TOKEN_EXPIRE_MINUTES=30
338
+
339
+ # Qodo (Tests auto-générés)
340
+ QODO_API_KEY="your_qodo_api_key"
341
+
342
+ # CORS
343
+ CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]
344
+ ```
345
+
346
+ ## 📝 API Documentation
347
+
348
+ Documentation interactive disponible sur:
349
+ - **Swagger UI:** http://localhost:8000/docs
350
+ - **ReDoc:** http://localhost:8000/redoc
351
+
352
+ ### Endpoints Principaux
353
+
354
+ #### Language Detection
355
+
356
+ ```
357
+ POST /api/v1/language/detect
358
+ GET /api/v1/language/health
359
+ ```
360
+
361
+ #### À venir
362
+
363
+ ```
364
+ POST /api/v1/laws # Créer loi
365
+ GET /api/v1/laws # Lister lois
366
+ GET /api/v1/laws/{id} # Détail loi
367
+ POST /api/v1/search # Recherche
368
+ POST /api/v1/chatbot/ask # Question RAG
369
+ GET /api/v1/categories # Catégories
370
+ GET /health # Health check global
371
+ ```
372
+
373
+ ### ✅ Module 3: Extraction d'Articles
374
+
375
+ Utilitaire d'extraction automatique d'articles pour documents juridiques camerounais.
376
+
377
+ **Architecture:** Regex-based pattern matching avec détection automatique
378
+ - **Patterns supportés:** Article X, Art. X, Article premier/première
379
+ - **Numérotation hiérarchique:** Support 1.1, 1.2.3 (parent_id)
380
+ - **Précision:** >95% sur documents légaux camerounais
381
+ - **Performance:** <500ms pour 1000 articles
382
+ - **Validation:** Minimum 3 articles requis (configurable)
383
+
384
+ #### Usage Programmatique
385
+
386
+ ```python
387
+ from app.utils.text_chunker import extract_articles
388
+
389
+ # Texte juridique
390
+ law_text = """
391
+ LOI N° 2023-001 DU 15 JANVIER 2023
392
+
393
+ Article 1. Objet de la loi
394
+ La présente loi régit les sociétés commerciales au Cameroun.
395
+
396
+ Article 2. Champ d'application
397
+ Les dispositions s'appliquent à toutes les sociétés.
398
+
399
+ Article 3. Définitions
400
+ Au sens de la présente loi, on entend par société...
401
+ """
402
+
403
+ # Extraire articles
404
+ articles = extract_articles(law_text)
405
+
406
+ print(f"Nombre d'articles: {len(articles)}")
407
+
408
+ for article in articles:
409
+ print(f"Article {article['number']}: {article['title']}")
410
+ print(f" Contenu: {article['content'][:50]}...")
411
+ print(f" Mots: {article['word_count']}, Chars: {article['char_count']}")
412
+ print(f" Parent: {article['parent_id']}, Position: {article['position']}")
413
+ print()
414
+
415
+ # Résultat:
416
+ # Nombre d'articles: 3
417
+ # Article 1: Objet de la loi
418
+ # Contenu: La présente loi régit les sociétés commerciales...
419
+ # Mots: 9, Chars: 58
420
+ # Parent: None, Position: 0
421
+ # ...
422
+ ```
423
+
424
+ #### Paramètres d'Extraction
425
+
426
+ ```python
427
+ # Paramètres personnalisés
428
+ articles = extract_articles(
429
+ text=law_text,
430
+ min_article_length=10, # Minimum 10 caractères par article
431
+ preserve_formatting=False, # Nettoyer espaces multiples
432
+ strict=True # Erreur si <3 articles
433
+ )
434
+
435
+ # Mode non-strict (pour documents incomplets)
436
+ articles = extract_articles(
437
+ text=draft_law_text,
438
+ strict=False # Accepte <3 articles
439
+ )
440
+ ```
441
+
442
+ #### Patterns Supportés
443
+
444
+ ```python
445
+ # ✅ Article X.
446
+ "Article 1. Dispositions générales"
447
+ "Article 2: Champ d'application"
448
+
449
+ # ✅ Art. X
450
+ "Art. 1. Titre"
451
+ "Art 1: Titre"
452
+
453
+ # ✅ Article premier/première
454
+ "Article premier. Objet de la loi"
455
+ "Article première. Disposition initiale"
456
+
457
+ # ✅ Numérotation hiérarchique
458
+ "Article 1.1. Sous-article"
459
+ "Article 1.2.3. Sous-sous-article"
460
+
461
+ # ❌ Non supportés (à venir Phase 2)
462
+ "Section I. Titre de section"
463
+ "Chapitre II. Titre de chapitre"
464
+ "Alinéa 1. Paragraphe"
465
+ ```
466
+
467
+ #### Intégration Pipeline
468
+
469
+ ```python
470
+ # Dans process_law task
471
+ from app.utils.text_chunker import extract_articles, ArticleExtractionError
472
+
473
+ def process_law_task(law_id: int):
474
+ """Traiter document juridique uploadé."""
475
+
476
+ # 1. Récupérer loi
477
+ law = db.query(Law).filter(Law.id == law_id).first()
478
+
479
+ # 2. Extraire articles
480
+ try:
481
+ articles = extract_articles(law.content_fr)
482
+
483
+ # Validation
484
+ if len(articles) < 3:
485
+ raise ValueError(f"Minimum 3 articles requis, {len(articles)} trouvés")
486
+
487
+ # 3. Sauvegarder en DB
488
+ for article_data in articles:
489
+ db_article = Article(
490
+ law_id=law_id,
491
+ number=article_data['number'],
492
+ title=article_data['title'],
493
+ content=article_data['content'],
494
+ order=article_data['position'],
495
+ # parent_id sera ajouté en Phase 2
496
+ )
497
+ db.add(db_article)
498
+
499
+ db.commit()
500
+ logger.info(f"✅ {len(articles)} articles extraits pour loi #{law_id}")
501
+
502
+ except ArticleExtractionError as e:
503
+ logger.error(f"❌ Extraction échouée: {e}")
504
+ raise
505
+ ```
506
+
507
+ #### Format de Retour
508
+
509
+ Chaque article extrait contient:
510
+
511
+ ```python
512
+ {
513
+ 'number': '1', # VARCHAR(20) - Numéro article
514
+ 'title': 'Dispositions générales', # VARCHAR(200) - Titre (optionnel)
515
+ 'content': 'La présente loi...', # TEXT - Contenu article
516
+ 'position': 0, # INT - Ordre dans document (0-indexed)
517
+ 'parent_id': None, # VARCHAR(20) - Parent pour hiérarchie (1.1 → '1')
518
+ 'section': None, # VARCHAR(50) - Section/Chapitre (Phase 2)
519
+ 'word_count': 45, # INT - Nombre de mots
520
+ 'char_count': 234 # INT - Nombre de caractères
521
+ }
522
+ ```
523
+
524
+ #### Tests
525
+
526
+ ```bash
527
+ # Tests unitaires (23 tests de base)
528
+ pytest backend/tests/test_utils/test_text_chunker.py -v
529
+
530
+ # Classes de tests:
531
+ # - TestBasicExtraction: 3 tests (patterns standards)
532
+ # - TestHierarchicalNumbering: 2 tests (numérotation imbriquée)
533
+ # - TestValidation: 7 tests (validation stricte)
534
+ # - TestEdgeCases: 5 tests (cas limites)
535
+ # - TestStatistics: 2 tests (compteurs)
536
+ # - TestPositioning: 1 test (ordre séquentiel)
537
+ # - TestMinimumArticleLength: 2 tests (filtrage longueur)
538
+ # - TestMultiplePatterns: 1 test (patterns mixtes)
539
+
540
+ # Tests d'intégration (7 tests)
541
+ pytest backend/tests/test_integration/test_article_extraction_integration.py -v
542
+
543
+ # Avec coverage (cible: >90%)
544
+ pytest backend/tests/test_utils/test_text_chunker.py -v \
545
+ --cov=app.utils.text_chunker \
546
+ --cov-report=term-missing
547
+
548
+ # Résultat attendu:
549
+ # ====== 23 passed, 96% coverage ======
550
+ ```
551
+
552
+ #### Validation Rules
553
+
554
+ **Input:**
555
+ - Minimum: 200 caractères
556
+ - Maximum: 5,000,000 caractères (5MB)
557
+ - Minimum 3 articles requis (strict=True)
558
+
559
+ **Article:**
560
+ - Contenu: 10-50,000 caractères
561
+ - Numéro: 1-20 caractères
562
+ - Titre: 0-200 caractères (optionnel)
563
+
564
+ **Errors:**
565
+
566
+ ```python
567
+ # ValueError: Texte invalide
568
+ extract_articles("") # → "Le texte ne peut pas être vide"
569
+ extract_articles("x" * 50) # → "Texte trop court (50 chars, minimum 200)"
570
+
571
+ # ArticleExtractionError: Extraction échouée
572
+ extract_articles("Long text without articles...")
573
+ # → "Aucun pattern d'article détecté"
574
+
575
+ extract_articles("Article 1...\nArticle 2...", strict=True)
576
+ # → "Minimum 3 articles requis, 2 trouvés"
577
+ ```
578
+
579
+ #### Troubleshooting
580
+
581
+ **❌ Erreur: "Aucun pattern d'article détecté"**
582
+ - Vérifier format: "Article 1." ou "Art. 1"
583
+ - Patterns supportés: numérique (1, 2, 3) ou textuel (premier, première)
584
+
585
+ **❌ Erreur: "Minimum 3 articles requis"**
586
+ ```python
587
+ # Option 1: Mode non-strict
588
+ articles = extract_articles(text, strict=False)
589
+
590
+ # Option 2: Ajouter plus d'articles au document
591
+ ```
592
+
593
+ **❌ Articles trop courts filtrés**
594
+ ```python
595
+ # Réduire min_article_length
596
+ articles = extract_articles(text, min_article_length=5) # Default: 10
597
+ ```
598
+
599
+ **❌ Titres mal détectés**
600
+ - Titres doivent être <100 caractères et sur première ligne
601
+ - Format attendu: "Article 1. Titre court\nContenu..."
602
+
603
+ **❌ Hiérarchie non reconnue**
604
+ - Format requis: numérotation à points (1.1, 1.2.3)
605
+ - parent_id extrait automatiquement (1.2.3 → parent='1.2')
606
+
607
+ #### Performance
608
+
609
+ Benchmarks (Windows 11, Python 3.11):
610
+
611
+ | Document | Articles | Temps | Performance |
612
+ |----------|----------|-------|-------------|
613
+ | Petit (10 articles) | 10 | <50ms | ✅ |
614
+ | Moyen (100 articles) | 100 | <100ms | ✅ |
615
+ | Large (1000 articles) | 1000 | <500ms | ✅ |
616
+
617
+ ```bash
618
+ # Test de performance
619
+ pytest backend/tests/test_integration/test_article_extraction_integration.py::TestArticleExtractionIntegration::test_performance_target_met -v
620
+
621
+ # Résultat:
622
+ # test_performance_target_met PASSED [100%]
623
+ # Extraction took 0.045s (target: <0.5s for 100 articles) ✅
624
+ ```
625
+
626
+ ## 🚀 Prochaines Étapes
627
+
628
+ ### Module 2: Classification Automatique (Section 5.6)
629
+ Service de catégorisation automatique de documents juridiques.
630
+
631
+ ### Module 4: Filtre Multilingue (Section 6.9)
632
+ Filtrage automatique des lois par langue détectée.
633
+
634
+ ### Module 5: Pipeline Complet (Section 4.2)
635
+ Intégration Celery pour traitement automatique des documents.
636
+
637
+ ## 📄 License
638
+
639
+ Propriétaire - JuriX Team © 2025
640
+
641
+ ## 👥 Équipe
642
+
643
+ - **Développeurs:** JuriX Dev Team
644
+ - **Architecte:** Senior Software Engineer
645
+ - **QA:** Qodo AI Test Generation
646
+
647
+ ## 📞 Support
648
+
649
+ Pour questions ou problèmes:
650
+ 1. Vérifier documentation: `http://localhost:8000/docs`
651
+ 2. Consulter logs: `docker-compose logs -f api`
652
+ 3. Lancer health checks: `curl http://localhost:8000/api/v1/language/health`
653
+ 4. Créer issue sur repository GitHub
654
+
655
+ ---
656
+
657
+ **Version:** 2.1.0
658
+ **Dernière mise à jour:** 2025-01-05
659
+ **Status:** ✅ LanguageDetector + ArticleSplitter Complets (30/30 tests passing, 96% coverage)
alembic.ini ADDED
@@ -0,0 +1,116 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # A generic, single database configuration.
2
+
3
+ [alembic]
4
+ # path to migration scripts
5
+ script_location = alembic
6
+
7
+ # template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
8
+ # Uncomment the line below if you want the files to be prepended with date and time
9
+ # file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
10
+
11
+ # sys.path path, will be prepended to sys.path if present.
12
+ # defaults to the current working directory.
13
+ prepend_sys_path = .
14
+
15
+ # timezone to use when rendering the date within the migration file
16
+ # as well as the filename.
17
+ # If specified, requires the python-dateutil library that can be
18
+ # installed by adding `alembic[tz]` to the pip requirements
19
+ # string value is passed to dateutil.tz.gettz()
20
+ # leave blank for localtime
21
+ # timezone =
22
+
23
+ # max length of characters to apply to the
24
+ # "slug" field
25
+ # truncate_slug_length = 40
26
+
27
+ # set to 'true' to run the environment during
28
+ # the 'revision' command, regardless of autogenerate
29
+ # revision_environment = false
30
+
31
+ # set to 'true' to allow .pyc and .pyo files without
32
+ # a source .py file to be detected as revisions in the
33
+ # versions/ directory
34
+ # sourceless = false
35
+
36
+ # version location specification; This defaults
37
+ # to alembic/versions. When using multiple version
38
+ # directories, initial revisions must be specified with --version-path.
39
+ # The path separator used here should be the separator specified by "version_path_separator" below.
40
+ # version_locations = %(here)s/bar:%(here)s/bat:alembic/versions
41
+
42
+ # version path separator; As mentioned above, this is the character used to split
43
+ # version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
44
+ # If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
45
+ # Valid values for version_path_separator are:
46
+ #
47
+ # version_path_separator = :
48
+ # version_path_separator = ;
49
+ # version_path_separator = space
50
+ version_path_separator = os # Use os.pathsep. Default configuration used for new projects.
51
+
52
+ # set to 'true' to search source files recursively
53
+ # in each "version_locations" directory
54
+ # new in Alembic version 1.10
55
+ # recursive_version_locations = false
56
+
57
+ # the output encoding used when revision files
58
+ # are written from script.py.mako
59
+ # output_encoding = utf-8
60
+
61
+ # URL is set programmatically in alembic/env.py from DATABASE_URL environment variable
62
+ # Do NOT hardcode connection strings here — use env vars instead
63
+ sqlalchemy.url = placeholder://not-used
64
+
65
+
66
+ [post_write_hooks]
67
+ # post_write_hooks defines scripts or Python functions that are run
68
+ # on newly generated revision scripts. See the documentation for further
69
+ # detail and examples
70
+
71
+ # format using "black" - use the console_scripts runner, against the "black" entrypoint
72
+ # hooks = black
73
+ # black.type = console_scripts
74
+ # black.entrypoint = black
75
+ # black.options = -l 79 REVISION_SCRIPT_FILENAME
76
+
77
+ # lint with attempts to fix using "ruff" - use the exec runner, execute a binary
78
+ # hooks = ruff
79
+ # ruff.type = exec
80
+ # ruff.executable = %(here)s/.venv/bin/ruff
81
+ # ruff.options = --fix REVISION_SCRIPT_FILENAME
82
+
83
+ # Logging configuration
84
+ [loggers]
85
+ keys = root,sqlalchemy,alembic
86
+
87
+ [handlers]
88
+ keys = console
89
+
90
+ [formatters]
91
+ keys = generic
92
+
93
+ [logger_root]
94
+ level = WARN
95
+ handlers = console
96
+ qualname =
97
+
98
+ [logger_sqlalchemy]
99
+ level = WARN
100
+ handlers =
101
+ qualname = sqlalchemy.engine
102
+
103
+ [logger_alembic]
104
+ level = INFO
105
+ handlers =
106
+ qualname = alembic
107
+
108
+ [handler_console]
109
+ class = StreamHandler
110
+ args = (sys.stderr,)
111
+ level = NOTSET
112
+ formatter = generic
113
+
114
+ [formatter_generic]
115
+ format = %(levelname)-5.5s [%(name)s] %(message)s
116
+ datefmt = %H:%M:%S
alembic/env.py ADDED
@@ -0,0 +1,81 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from logging.config import fileConfig
2
+ import os
3
+
4
+ from sqlalchemy import engine_from_config, pool
5
+
6
+ from alembic import context
7
+
8
+ # this is the Alembic Config object, which provides
9
+ # access to the values within the .ini file in use.
10
+ config = context.config
11
+
12
+ # Interpret the config file for Python logging.
13
+ # This line sets up loggers basically.
14
+ if config.config_file_name is not None:
15
+ fileConfig(config.config_file_name)
16
+
17
+ # add your model's MetaData object here
18
+ # for 'autogenerate' support
19
+ from app.core.database import Base
20
+ from app.models import Article, Category, Conversation, Law, Message, User
21
+
22
+ target_metadata = Base.metadata
23
+
24
+ # Override sqlalchemy.url from environment variable.
25
+ # Neon gives postgresql+asyncpg:// URLs — convert to psycopg2-compatible for migrations.
26
+ _db_url = os.environ.get("DATABASE_URL", "")
27
+ if _db_url:
28
+ # Alembic needs a sync driver: swap asyncpg with psycopg2
29
+ _db_url = _db_url.replace("postgresql+asyncpg://", "postgresql://")
30
+ _db_url = _db_url.replace("postgres://", "postgresql://") # Neon sometimes gives bare postgres://
31
+ config.set_main_option("sqlalchemy.url", _db_url)
32
+
33
+
34
+ def run_migrations_offline() -> None:
35
+ """Run migrations in 'offline' mode.
36
+
37
+ This configures the context with just a URL
38
+ and not an Engine, though an Engine is acceptable
39
+ here as well. By skipping the Engine creation
40
+ we don't even need a DBAPI to be available.
41
+
42
+ Calls to context.execute() here emit the given string to the
43
+ script output.
44
+
45
+ """
46
+ url = config.get_main_option("sqlalchemy.url")
47
+ context.configure(
48
+ url=url,
49
+ target_metadata=target_metadata,
50
+ literal_binds=True,
51
+ dialect_opts={"paramstyle": "named"},
52
+ )
53
+
54
+ with context.begin_transaction():
55
+ context.run_migrations()
56
+
57
+
58
+ def run_migrations_online() -> None:
59
+ """Run migrations in 'online' mode.
60
+
61
+ In this scenario we need to create an Engine
62
+ and associate a connection with the context.
63
+
64
+ """
65
+ connectable = engine_from_config(
66
+ config.get_section(config.config_ini_section, {}),
67
+ prefix="sqlalchemy.",
68
+ poolclass=pool.NullPool,
69
+ )
70
+
71
+ with connectable.connect() as connection:
72
+ context.configure(connection=connection, target_metadata=target_metadata)
73
+
74
+ with context.begin_transaction():
75
+ context.run_migrations()
76
+
77
+
78
+ if context.is_offline_mode():
79
+ run_migrations_offline()
80
+ else:
81
+ run_migrations_online()
alembic/script.py.mako ADDED
@@ -0,0 +1,24 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """${message}
2
+
3
+ Revision ID: ${up_revision}
4
+ Revises: ${down_revision | comma,n}
5
+ Create Date: ${create_date}
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+ ${imports if imports else ""}
11
+
12
+ # revision identifiers, used by Alembic.
13
+ revision = ${repr(up_revision)}
14
+ down_revision = ${repr(down_revision)}
15
+ branch_labels = ${repr(branch_labels)}
16
+ depends_on = ${repr(depends_on)}
17
+
18
+
19
+ def upgrade() -> None:
20
+ ${upgrades if upgrades else "pass"}
21
+
22
+
23
+ def downgrade() -> None:
24
+ ${downgrades if downgrades else "pass"}
alembic/versions/001_initial_schema.py ADDED
@@ -0,0 +1,97 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Initial schema
2
+
3
+ Revision ID: 001
4
+ Revises:
5
+ Create Date: 2025-01-03
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+ from sqlalchemy.dialects import postgresql
11
+ from pgvector.sqlalchemy import Vector
12
+
13
+
14
+ # revision identifiers, used by Alembic.
15
+ revision = '001'
16
+ down_revision = None
17
+ branch_labels = None
18
+ depends_on = None
19
+
20
+
21
+ def upgrade() -> None:
22
+ # Categories table
23
+ op.create_table(
24
+ 'categories',
25
+ sa.Column('id', sa.Integer(), nullable=False),
26
+ sa.Column('name', sa.String(100), nullable=False),
27
+ sa.Column('description', sa.Text(), nullable=True),
28
+ sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
29
+ sa.PrimaryKeyConstraint('id')
30
+ )
31
+
32
+ # Laws table avec colonnes v2.1
33
+ op.create_table(
34
+ 'laws',
35
+ sa.Column('id', sa.Integer(), nullable=False),
36
+ sa.Column('reference', sa.String(100), nullable=False, unique=True),
37
+ sa.Column('title', sa.String(500), nullable=False),
38
+ sa.Column('type', sa.String(50), nullable=False),
39
+ sa.Column('category_id', sa.Integer(), nullable=True),
40
+ # v2.1 Colonnes détection automatique
41
+ sa.Column('language', sa.String(2), nullable=True), # 'fr' | 'en'
42
+ sa.Column('language_confidence', sa.Float(), nullable=True),
43
+ sa.Column('detected_language', sa.String(2), nullable=True),
44
+ sa.Column('suggested_categories', postgresql.ARRAY(sa.Integer()), nullable=True),
45
+ sa.Column('category_confidence', sa.Float(), nullable=True),
46
+ # Autres colonnes
47
+ sa.Column('content', sa.Text(), nullable=False),
48
+ sa.Column('publication_date', sa.Date(), nullable=True),
49
+ sa.Column('status', sa.String(20), nullable=False, server_default='draft'),
50
+ sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
51
+ sa.Column('updated_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
52
+ sa.PrimaryKeyConstraint('id'),
53
+ sa.ForeignKeyConstraint(['category_id'], ['categories.id'])
54
+ )
55
+
56
+ # Articles table
57
+ op.create_table(
58
+ 'articles',
59
+ sa.Column('id', sa.Integer(), nullable=False),
60
+ sa.Column('law_id', sa.Integer(), nullable=False),
61
+ sa.Column('number', sa.String(20), nullable=False),
62
+ sa.Column('title', sa.String(200), nullable=True),
63
+ sa.Column('content', sa.Text(), nullable=False),
64
+ sa.Column('embedding', Vector(3072), nullable=True), # pgvector 3072-dim Gemini
65
+ sa.Column('order', sa.Integer(), nullable=False),
66
+ sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
67
+ sa.PrimaryKeyConstraint('id'),
68
+ sa.ForeignKeyConstraint(['law_id'], ['laws.id'], ondelete='CASCADE')
69
+ )
70
+
71
+ # Index
72
+ op.create_index('idx_laws_language', 'laws', ['language'])
73
+ op.create_index('idx_laws_category', 'laws', ['category_id'])
74
+ op.create_index('idx_articles_law', 'articles', ['law_id'])
75
+
76
+ # Insertion catégories initiales
77
+ op.execute("""
78
+ INSERT INTO categories (name, description) VALUES
79
+ ('Droit Civil', 'Lois relatives au droit civil'),
80
+ ('Droit Pénal', 'Lois relatives au droit pénal'),
81
+ ('Droit Commercial', 'Lois relatives au commerce'),
82
+ ('Droit du Travail', 'Lois relatives au travail'),
83
+ ('Droit Fiscal', 'Lois relatives à la fiscalité'),
84
+ ('Droit Administratif', 'Lois relatives à l''administration'),
85
+ ('Droit de la Famille', 'Lois relatives à la famille'),
86
+ ('Droit des Affaires', 'Lois relatives aux affaires'),
87
+ ('Droit Constitutionnel', 'Constitution et lois constitutionnelles'),
88
+ ('Procédure Civile', 'Procédures judiciaires civiles'),
89
+ ('Procédure Pénale', 'Procédures judiciaires pénales'),
90
+ ('Droit OHADA', 'Actes uniformes OHADA')
91
+ """)
92
+
93
+
94
+ def downgrade() -> None:
95
+ op.drop_table('articles')
96
+ op.drop_table('laws')
97
+ op.drop_table('categories')
alembic/versions/002_add_rag_tables.py ADDED
@@ -0,0 +1,69 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Add RAG conversation tables
2
+
3
+ Revision ID: 002
4
+ Revises: 001
5
+ Create Date: 2026-01-10
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+
11
+
12
+ # revision identifiers, used by Alembic.
13
+ revision = '002'
14
+ down_revision = '001'
15
+ branch_labels = None
16
+ depends_on = None
17
+
18
+
19
+ def upgrade() -> None:
20
+ # Create conversations table
21
+ op.create_table(
22
+ 'conversations',
23
+ sa.Column('id', sa.Integer(), nullable=False),
24
+ sa.Column('session_id', sa.String(100), nullable=False),
25
+ sa.Column('user_id', sa.Integer(), nullable=True),
26
+ sa.Column('persona', sa.String(50), nullable=False),
27
+ sa.Column('language', sa.String(2), nullable=False, server_default='fr'),
28
+ sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('now()')),
29
+ sa.Column('updated_at', sa.DateTime(), nullable=False, server_default=sa.text('now()')),
30
+ sa.PrimaryKeyConstraint('id'),
31
+ # Note: Foreign key to users table commented out until users table is implemented
32
+ # sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='SET NULL'),
33
+ )
34
+
35
+ # Create indexes for conversations
36
+ op.create_index('idx_conversations_session_id', 'conversations', ['session_id'], unique=True)
37
+ op.create_index('idx_conversations_id', 'conversations', ['id'])
38
+
39
+ # Create messages table
40
+ op.create_table(
41
+ 'messages',
42
+ sa.Column('id', sa.Integer(), nullable=False),
43
+ sa.Column('conversation_id', sa.Integer(), nullable=False),
44
+ sa.Column('role', sa.String(20), nullable=False),
45
+ sa.Column('content', sa.Text(), nullable=False),
46
+ sa.Column('sources', sa.JSON(), nullable=True),
47
+ sa.Column('confidence', sa.Float(), nullable=True),
48
+ sa.Column('retrieval_time_ms', sa.Integer(), nullable=True),
49
+ sa.Column('generation_time_ms', sa.Integer(), nullable=True),
50
+ sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('now()')),
51
+ sa.PrimaryKeyConstraint('id'),
52
+ sa.ForeignKeyConstraint(['conversation_id'], ['conversations.id'], ondelete='CASCADE'),
53
+ )
54
+
55
+ # Create indexes for messages
56
+ op.create_index('idx_messages_conversation_id', 'messages', ['conversation_id'])
57
+ op.create_index('idx_messages_id', 'messages', ['id'])
58
+ op.create_index('idx_messages_created_at', 'messages', [sa.text('created_at DESC')])
59
+
60
+
61
+ def downgrade() -> None:
62
+ op.drop_index('idx_messages_created_at', table_name='messages')
63
+ op.drop_index('idx_messages_id', table_name='messages')
64
+ op.drop_index('idx_messages_conversation_id', table_name='messages')
65
+ op.drop_table('messages')
66
+
67
+ op.drop_index('idx_conversations_id', table_name='conversations')
68
+ op.drop_index('idx_conversations_session_id', table_name='conversations')
69
+ op.drop_table('conversations')
alembic/versions/003_add_persona_analytics.py ADDED
@@ -0,0 +1,130 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Add persona analytics tables
2
+
3
+ Revision ID: 003
4
+ Revises: 002
5
+ Create Date: 2026-01-11
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+
11
+
12
+ # revision identifiers, used by Alembic.
13
+ revision = '003'
14
+ down_revision = '002'
15
+ branch_labels = None
16
+ depends_on = None
17
+
18
+
19
+ def upgrade() -> None:
20
+ # Create persona_stats table - Aggregated daily statistics
21
+ op.create_table(
22
+ 'persona_stats',
23
+ sa.Column('id', sa.Integer(), nullable=False),
24
+ sa.Column('persona', sa.String(50), nullable=False),
25
+ sa.Column('date', sa.Date(), nullable=False),
26
+
27
+ # Usage Metrics
28
+ sa.Column('total_questions', sa.Integer(), nullable=False, server_default='0'),
29
+ sa.Column('total_conversations', sa.Integer(), nullable=False, server_default='0'),
30
+ sa.Column('unique_sessions', sa.Integer(), nullable=False, server_default='0'),
31
+
32
+ # Performance Metrics
33
+ sa.Column('avg_confidence', sa.Float(), nullable=False, server_default='0.0'),
34
+ sa.Column('avg_retrieval_time_ms', sa.Integer(), nullable=False, server_default='0'),
35
+ sa.Column('avg_generation_time_ms', sa.Integer(), nullable=False, server_default='0'),
36
+ sa.Column('avg_total_time_ms', sa.Integer(), nullable=False, server_default='0'),
37
+
38
+ # Engagement Metrics
39
+ sa.Column('avg_messages_per_conversation', sa.Float(), nullable=False, server_default='0.0'),
40
+ sa.Column('avg_session_duration_seconds', sa.Integer(), nullable=False, server_default='0'),
41
+
42
+ # Quality Metrics
43
+ sa.Column('helpful_count', sa.Integer(), nullable=False, server_default='0'),
44
+ sa.Column('unhelpful_count', sa.Integer(), nullable=False, server_default='0'),
45
+ sa.Column('satisfaction_rate', sa.Float(), nullable=False, server_default='0.0'),
46
+
47
+ # Metadata
48
+ sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('now()')),
49
+ sa.Column('updated_at', sa.DateTime(), nullable=False, server_default=sa.text('now()')),
50
+
51
+ sa.PrimaryKeyConstraint('id'),
52
+ sa.UniqueConstraint('persona', 'date', name='uq_persona_date')
53
+ )
54
+
55
+ # Create indexes for persona_stats
56
+ op.create_index('idx_persona_stats_persona_date', 'persona_stats', ['persona', sa.text('date DESC')])
57
+ op.create_index('idx_persona_stats_date', 'persona_stats', [sa.text('date DESC')])
58
+
59
+ # Create message_feedback table - User ratings on responses
60
+ op.create_table(
61
+ 'message_feedback',
62
+ sa.Column('id', sa.Integer(), nullable=False),
63
+ sa.Column('message_id', sa.Integer(), nullable=False),
64
+ sa.Column('helpful', sa.Boolean(), nullable=False),
65
+ sa.Column('rating', sa.Integer(), nullable=True),
66
+ sa.Column('comment', sa.Text(), nullable=True),
67
+ sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('now()')),
68
+
69
+ sa.PrimaryKeyConstraint('id'),
70
+ sa.ForeignKeyConstraint(['message_id'], ['messages.id'], ondelete='CASCADE'),
71
+ sa.UniqueConstraint('message_id', name='uq_message_feedback_message_id'),
72
+ sa.CheckConstraint('rating >= 1 AND rating <= 5', name='ck_rating_range')
73
+ )
74
+
75
+ # Create indexes for message_feedback
76
+ op.create_index('idx_message_feedback_message_id_helpful', 'message_feedback', ['message_id', 'helpful'])
77
+ op.create_index('idx_message_feedback_created_at', 'message_feedback', [sa.text('created_at DESC')])
78
+ op.create_index('idx_message_feedback_helpful', 'message_feedback', ['helpful'])
79
+
80
+ # Create persona_interactions table - Per-session analytics
81
+ op.create_table(
82
+ 'persona_interactions',
83
+ sa.Column('id', sa.Integer(), nullable=False),
84
+ sa.Column('conversation_id', sa.Integer(), nullable=False),
85
+ sa.Column('persona', sa.String(50), nullable=False),
86
+ sa.Column('language', sa.String(2), nullable=False),
87
+
88
+ # Interaction Counts
89
+ sa.Column('question_count', sa.Integer(), nullable=False, server_default='0'),
90
+ sa.Column('answer_count', sa.Integer(), nullable=False, server_default='0'),
91
+
92
+ # Performance
93
+ sa.Column('avg_confidence', sa.Float(), nullable=False, server_default='0.0'),
94
+ sa.Column('total_response_time_ms', sa.Integer(), nullable=False, server_default='0'),
95
+
96
+ # Persona Behavior
97
+ sa.Column('personas_used', sa.JSON(), nullable=True),
98
+ sa.Column('persona_switches', sa.Integer(), nullable=False, server_default='0'),
99
+
100
+ # Metadata
101
+ sa.Column('created_at', sa.DateTime(), nullable=False, server_default=sa.text('now()')),
102
+ sa.Column('updated_at', sa.DateTime(), nullable=False, server_default=sa.text('now()')),
103
+
104
+ sa.PrimaryKeyConstraint('id'),
105
+ sa.ForeignKeyConstraint(['conversation_id'], ['conversations.id'], ondelete='CASCADE')
106
+ )
107
+
108
+ # Create indexes for persona_interactions
109
+ op.create_index('idx_persona_interactions_persona_created', 'persona_interactions', ['persona', sa.text('created_at DESC')])
110
+ op.create_index('idx_persona_interactions_conversation_id', 'persona_interactions', ['conversation_id'])
111
+ op.create_index('idx_persona_interactions_created_at', 'persona_interactions', [sa.text('created_at DESC')])
112
+
113
+
114
+ def downgrade() -> None:
115
+ # Drop persona_interactions table
116
+ op.drop_index('idx_persona_interactions_created_at', table_name='persona_interactions')
117
+ op.drop_index('idx_persona_interactions_conversation_id', table_name='persona_interactions')
118
+ op.drop_index('idx_persona_interactions_persona_created', table_name='persona_interactions')
119
+ op.drop_table('persona_interactions')
120
+
121
+ # Drop message_feedback table
122
+ op.drop_index('idx_message_feedback_helpful', table_name='message_feedback')
123
+ op.drop_index('idx_message_feedback_created_at', table_name='message_feedback')
124
+ op.drop_index('idx_message_feedback_message_id_helpful', table_name='message_feedback')
125
+ op.drop_table('message_feedback')
126
+
127
+ # Drop persona_stats table
128
+ op.drop_index('idx_persona_stats_date', table_name='persona_stats')
129
+ op.drop_index('idx_persona_stats_persona_date', table_name='persona_stats')
130
+ op.drop_table('persona_stats')
alembic/versions/004_add_processing_status.py ADDED
@@ -0,0 +1,36 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Add processing status fields to laws table
2
+
3
+ Revision ID: 004
4
+ Revises: 003
5
+ Create Date: 2026-01-13
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+
11
+
12
+ # revision identifiers, used by Alembic.
13
+ revision = '004'
14
+ down_revision = '003'
15
+ branch_labels = None
16
+ depends_on = None
17
+
18
+
19
+ def upgrade() -> None:
20
+ # Add processing status tracking fields to laws table
21
+ op.add_column('laws', sa.Column('processing_progress', sa.Integer(), nullable=True))
22
+ op.add_column('laws', sa.Column('processing_error', sa.Text(), nullable=True))
23
+ op.add_column('laws', sa.Column('processing_started_at', sa.DateTime(), nullable=True))
24
+
25
+ # Create index for processing_progress for efficient filtering
26
+ op.create_index('idx_laws_processing_progress', 'laws', ['processing_progress'])
27
+
28
+
29
+ def downgrade() -> None:
30
+ # Drop index
31
+ op.drop_index('idx_laws_processing_progress', table_name='laws')
32
+
33
+ # Drop columns
34
+ op.drop_column('laws', 'processing_started_at')
35
+ op.drop_column('laws', 'processing_error')
36
+ op.drop_column('laws', 'processing_progress')
alembic/versions/005_add_category_icon.py ADDED
@@ -0,0 +1,26 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Add icon field to categories table
2
+
3
+ Revision ID: 005
4
+ Revises: 1e5feee465ba
5
+ Create Date: 2026-01-13
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+
11
+
12
+ # revision identifiers, used by Alembic.
13
+ revision = '005'
14
+ down_revision = '1e5feee465ba'
15
+ branch_labels = None
16
+ depends_on = None
17
+
18
+
19
+ def upgrade() -> None:
20
+ # Add icon field to categories table
21
+ op.add_column('categories', sa.Column('icon', sa.String(10), nullable=True))
22
+
23
+
24
+ def downgrade() -> None:
25
+ # Drop icon column
26
+ op.drop_column('categories', 'icon')
alembic/versions/006_add_display_order.py ADDED
@@ -0,0 +1,27 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Add display_order to categories
2
+
3
+ Revision ID: 006
4
+ Revises: 005
5
+ Create Date: 2026-01-14
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+
11
+
12
+ # revision identifiers, used by Alembic.
13
+ revision = '006'
14
+ down_revision = '005'
15
+ branch_labels = None
16
+ depends_on = None
17
+
18
+
19
+ def upgrade() -> None:
20
+ op.add_column('categories', sa.Column('display_order', sa.Integer(), nullable=True, server_default='0'))
21
+ # Make it non-nullable after setting defaults
22
+ op.execute("UPDATE categories SET display_order = id WHERE display_order IS NULL")
23
+ op.alter_column('categories', 'display_order', nullable=False)
24
+
25
+
26
+ def downgrade() -> None:
27
+ op.drop_column('categories', 'display_order')
alembic/versions/0b21fb6a3651_add_user_model_and_update_relationships.py ADDED
@@ -0,0 +1,141 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Add User model and update relationships
2
+
3
+ Revision ID: 0b21fb6a3651
4
+ Revises: 003
5
+ Create Date: 2026-01-12 07:03:08.986151
6
+
7
+ """
8
+
9
+ import pgvector.sqlalchemy
10
+ import sqlalchemy as sa
11
+ from sqlalchemy.dialects import postgresql
12
+
13
+ from alembic import op
14
+
15
+ # revision identifiers, used by Alembic.
16
+ revision = "0b21fb6a3651"
17
+ down_revision = "003"
18
+ branch_labels = None
19
+ depends_on = None
20
+
21
+
22
+ def upgrade() -> None:
23
+ # ### commands auto generated by Alembic - please adjust! ###
24
+ op.create_table(
25
+ "users",
26
+ sa.Column("id", sa.Integer(), nullable=False),
27
+ sa.Column("email", sa.String(length=255), nullable=False),
28
+ sa.Column("username", sa.String(length=100), nullable=False),
29
+ sa.Column("hashed_password", sa.String(length=255), nullable=False),
30
+ sa.Column("full_name", sa.String(length=255), nullable=True),
31
+ sa.Column(
32
+ "role", sa.String(length=50), nullable=False, comment="Role: user, admin, superadmin"
33
+ ),
34
+ sa.Column("is_active", sa.Boolean(), nullable=False),
35
+ sa.Column("is_verified", sa.Boolean(), nullable=False),
36
+ sa.Column("created_at", sa.DateTime(), nullable=False),
37
+ sa.Column("updated_at", sa.DateTime(), nullable=False),
38
+ sa.Column("last_login_at", sa.DateTime(), nullable=True),
39
+ sa.PrimaryKeyConstraint("id"),
40
+ )
41
+ op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
42
+ op.create_index(op.f("ix_users_id"), "users", ["id"], unique=False)
43
+ op.create_index(op.f("ix_users_role"), "users", ["role"], unique=False)
44
+ op.create_index(op.f("ix_users_username"), "users", ["username"], unique=True)
45
+ # Keep embedding as VECTOR type (don't convert to JSON)
46
+ op.create_index(op.f("ix_articles_id"), "articles", ["id"], unique=False)
47
+ op.create_index(op.f("ix_articles_law_id"), "articles", ["law_id"], unique=False)
48
+ op.create_index(op.f("ix_categories_id"), "categories", ["id"], unique=False)
49
+ op.drop_index(op.f("idx_conversations_id"), table_name="conversations")
50
+ op.drop_index(op.f("idx_conversations_session_id"), table_name="conversations")
51
+ op.create_index("idx_conversations_session_id", "conversations", ["session_id"], unique=False)
52
+ op.create_index(op.f("ix_conversations_id"), "conversations", ["id"], unique=False)
53
+ op.create_index(
54
+ op.f("ix_conversations_session_id"), "conversations", ["session_id"], unique=True
55
+ )
56
+ op.create_index(op.f("ix_conversations_user_id"), "conversations", ["user_id"], unique=False)
57
+ op.create_foreign_key(None, "conversations", "users", ["user_id"], ["id"], ondelete="SET NULL")
58
+ # Keep suggested_categories as ARRAY type (don't convert to JSON)
59
+ op.drop_constraint(op.f("laws_reference_key"), "laws", type_="unique")
60
+ op.create_index("idx_laws_reference", "laws", ["reference"], unique=False)
61
+ op.create_index("idx_laws_status", "laws", ["status"], unique=False)
62
+ op.create_index(op.f("ix_laws_category_id"), "laws", ["category_id"], unique=False)
63
+ op.create_index(op.f("ix_laws_id"), "laws", ["id"], unique=False)
64
+ op.create_index(op.f("ix_laws_language"), "laws", ["language"], unique=False)
65
+ op.create_index(op.f("ix_laws_reference"), "laws", ["reference"], unique=True)
66
+ op.create_index(op.f("ix_laws_status"), "laws", ["status"], unique=False)
67
+ op.create_index(op.f("ix_message_feedback_id"), "message_feedback", ["id"], unique=False)
68
+ op.drop_index(op.f("idx_messages_id"), table_name="messages")
69
+ op.create_index(
70
+ op.f("ix_messages_conversation_id"), "messages", ["conversation_id"], unique=False
71
+ )
72
+ op.create_index(op.f("ix_messages_created_at"), "messages", ["created_at"], unique=False)
73
+ op.create_index(op.f("ix_messages_id"), "messages", ["id"], unique=False)
74
+ op.create_index(
75
+ op.f("ix_persona_interactions_conversation_id"),
76
+ "persona_interactions",
77
+ ["conversation_id"],
78
+ unique=False,
79
+ )
80
+ op.create_index(
81
+ op.f("ix_persona_interactions_id"), "persona_interactions", ["id"], unique=False
82
+ )
83
+ op.create_index(op.f("ix_persona_stats_id"), "persona_stats", ["id"], unique=False)
84
+ # ### end Alembic commands ###
85
+
86
+
87
+ def downgrade() -> None:
88
+ # ### commands auto generated by Alembic - please adjust! ###
89
+ op.drop_index(op.f("ix_persona_stats_id"), table_name="persona_stats")
90
+ op.drop_index(op.f("ix_persona_interactions_id"), table_name="persona_interactions")
91
+ op.drop_index(
92
+ op.f("ix_persona_interactions_conversation_id"), table_name="persona_interactions"
93
+ )
94
+ op.drop_index(op.f("ix_messages_id"), table_name="messages")
95
+ op.drop_index(op.f("ix_messages_created_at"), table_name="messages")
96
+ op.drop_index(op.f("ix_messages_conversation_id"), table_name="messages")
97
+ op.create_index(op.f("idx_messages_id"), "messages", ["id"], unique=False)
98
+ op.drop_index(op.f("ix_message_feedback_id"), table_name="message_feedback")
99
+ op.drop_index(op.f("ix_laws_status"), table_name="laws")
100
+ op.drop_index(op.f("ix_laws_reference"), table_name="laws")
101
+ op.drop_index(op.f("ix_laws_language"), table_name="laws")
102
+ op.drop_index(op.f("ix_laws_id"), table_name="laws")
103
+ op.drop_index(op.f("ix_laws_category_id"), table_name="laws")
104
+ op.drop_index("idx_laws_status", table_name="laws")
105
+ op.drop_index("idx_laws_reference", table_name="laws")
106
+ op.create_unique_constraint(
107
+ op.f("laws_reference_key"), "laws", ["reference"], postgresql_nulls_not_distinct=False
108
+ )
109
+ op.alter_column(
110
+ "laws",
111
+ "suggested_categories",
112
+ existing_type=sa.JSON(),
113
+ type_=postgresql.ARRAY(sa.INTEGER()),
114
+ existing_nullable=True,
115
+ )
116
+ op.drop_constraint(None, "conversations", type_="foreignkey")
117
+ op.drop_index(op.f("ix_conversations_user_id"), table_name="conversations")
118
+ op.drop_index(op.f("ix_conversations_session_id"), table_name="conversations")
119
+ op.drop_index(op.f("ix_conversations_id"), table_name="conversations")
120
+ op.drop_index("idx_conversations_session_id", table_name="conversations")
121
+ op.create_index(
122
+ op.f("idx_conversations_session_id"), "conversations", ["session_id"], unique=True
123
+ )
124
+ op.create_index(op.f("idx_conversations_id"), "conversations", ["id"], unique=False)
125
+ op.drop_index(op.f("ix_categories_id"), table_name="categories")
126
+ op.drop_index(op.f("ix_articles_law_id"), table_name="articles")
127
+ op.drop_index(op.f("ix_articles_id"), table_name="articles")
128
+ op.alter_column(
129
+ "articles",
130
+ "embedding",
131
+ existing_type=sa.JSON(),
132
+ type_=pgvector.sqlalchemy.vector.VECTOR(dim=768),
133
+ existing_nullable=True,
134
+ )
135
+ op.drop_index(op.f("ix_users_username"), table_name="users")
136
+ op.drop_index(op.f("ix_users_role"), table_name="users")
137
+ op.drop_index(op.f("ix_users_id"), table_name="users")
138
+ op.drop_index(op.f("ix_users_email"), table_name="users")
139
+ op.drop_table("users")
140
+ op.drop_table("users")
141
+ # ### end Alembic commands ###
alembic/versions/1e5feee465ba_merge_heads.py ADDED
@@ -0,0 +1,24 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """merge_heads
2
+
3
+ Revision ID: 1e5feee465ba
4
+ Revises: 004, 0b21fb6a3651
5
+ Create Date: 2026-01-13 16:01:59.279535
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+
11
+
12
+ # revision identifiers, used by Alembic.
13
+ revision = '1e5feee465ba'
14
+ down_revision = ('004', '0b21fb6a3651')
15
+ branch_labels = None
16
+ depends_on = None
17
+
18
+
19
+ def upgrade() -> None:
20
+ pass
21
+
22
+
23
+ def downgrade() -> None:
24
+ pass
alembic/versions/3f0760423953_add_file_tracking_real.py ADDED
@@ -0,0 +1,62 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """add_file_tracking_real
2
+
3
+ Revision ID: 3f0760423953
4
+ Revises: 006
5
+ Create Date: 2026-01-15 04:34:38.060616
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+ from sqlalchemy.dialects import postgresql
11
+
12
+ # revision identifiers, used by Alembic.
13
+ """add_file_tracking_real
14
+
15
+ Revision ID: 3f0760423953
16
+ Revises: 006
17
+ Create Date: 2026-01-15 04:34:38.060616
18
+
19
+ """
20
+ from alembic import op
21
+ import sqlalchemy as sa
22
+ from sqlalchemy.dialects import postgresql
23
+
24
+ # revision identifiers, used by Alembic.
25
+ revision = '3f0760423953'
26
+ down_revision = '006'
27
+ branch_labels = None
28
+ depends_on = None
29
+
30
+
31
+ def upgrade() -> None:
32
+ # ### commands auto generated by Alembic - please adjust! ###
33
+ # op.alter_column('articles', 'embedding',
34
+ # existing_type=pgvector.sqlalchemy.vector.VECTOR(dim=768),
35
+ # type_=sa.JSON(),
36
+ # existing_nullable=True)
37
+ op.add_column('laws', sa.Column('file_id', sa.String(length=100), nullable=True))
38
+ op.add_column('laws', sa.Column('original_filename', sa.String(length=500), nullable=True))
39
+ # op.alter_column('laws', 'suggested_categories',
40
+ # existing_type=postgresql.ARRAY(sa.INTEGER()),
41
+ # type_=sa.JSON(),
42
+ # existing_nullable=True)
43
+ # op.drop_index(op.f('idx_laws_processing_progress'), table_name='laws')
44
+ op.create_index(op.f('ix_laws_file_id'), 'laws', ['file_id'], unique=False)
45
+ # ### end Alembic commands ###
46
+
47
+
48
+ def downgrade() -> None:
49
+ # ### commands auto generated by Alembic - please adjust! ###
50
+ op.drop_index(op.f('ix_laws_file_id'), table_name='laws')
51
+ # op.create_index(op.f('idx_laws_processing_progress'), 'laws', ['processing_progress'], unique=False)
52
+ # op.alter_column('laws', 'suggested_categories',
53
+ # existing_type=sa.JSON(),
54
+ # type_=postgresql.ARRAY(sa.INTEGER()),
55
+ # existing_nullable=True)
56
+ op.drop_column('laws', 'original_filename')
57
+ op.drop_column('laws', 'file_id')
58
+ # op.alter_column('articles', 'embedding',
59
+ # existing_type=sa.JSON(),
60
+ # type_=pgvector.sqlalchemy.vector.VECTOR(dim=768),
61
+ # existing_nullable=True)
62
+ # ### end Alembic commands ###
alembic/versions/668e3740d3b5_add_page_number_to_articles.py ADDED
@@ -0,0 +1,24 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Add page_number to articles
2
+
3
+ Revision ID: 668e3740d3b5
4
+ Revises: 3f0760423953
5
+ Create Date: 2026-01-21 03:44:42.433227
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+
11
+ # revision identifiers, used by Alembic.
12
+ revision = '668e3740d3b5'
13
+ down_revision = '3f0760423953'
14
+ branch_labels = None
15
+ depends_on = None
16
+
17
+
18
+ def upgrade() -> None:
19
+ # Add page_number column to articles table
20
+ op.add_column('articles', sa.Column('page_number', sa.Integer(), nullable=True))
21
+
22
+
23
+ def downgrade() -> None:
24
+ op.drop_column('articles', 'page_number')
alembic/versions/7a8b9c0d1e2f_enable_pgvector.py ADDED
@@ -0,0 +1,65 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Enable pgvector and migrate embeddings column
2
+
3
+ Revision ID: 7a8b9c0d1e2f
4
+ Revises: 668e3740d3b5
5
+ Create Date: 2026-01-27 13:10:00.000000
6
+
7
+ """
8
+ from alembic import op
9
+ import sqlalchemy as sa
10
+ from pgvector.sqlalchemy import Vector
11
+
12
+ # revision identifiers, used by Alembic.
13
+ revision = '7a8b9c0d1e2f'
14
+ down_revision = '668e3740d3b5'
15
+ branch_labels = None
16
+ depends_on = None
17
+
18
+
19
+ def upgrade() -> None:
20
+ """
21
+ Enable pgvector extension and migrate embedding column.
22
+
23
+ Steps:
24
+ 1. Enable pgvector extension
25
+ 2. Convert embedding column to Vector(3072) for Gemini embeddings
26
+
27
+ Note: No vector index is created because 3072 dimensions exceeds
28
+ pgvector's 2000-dimension limit for HNSW/IVFFlat indexes.
29
+ Sequential scan is acceptable for <20k articles.
30
+ """
31
+ # Step 1: Enable pgvector extension
32
+ op.execute('CREATE EXTENSION IF NOT EXISTS vector')
33
+
34
+ # Step 2: Convert embedding column type to vector(3072)
35
+ # 3072 dimensions = native Gemini gemini-embedding-001 output
36
+ op.execute("""
37
+ ALTER TABLE articles
38
+ ALTER COLUMN embedding
39
+ TYPE vector(3072)
40
+ USING NULL::vector(3072)
41
+ """)
42
+
43
+
44
+ def downgrade() -> None:
45
+ """
46
+ Rollback pgvector changes.
47
+
48
+ Steps:
49
+ 1. Drop HNSW index
50
+ 2. Convert embedding column back to JSON
51
+ 3. Drop pgvector extension (if no other tables use it)
52
+ """
53
+ # Step 1: Drop index
54
+ op.execute('DROP INDEX IF EXISTS idx_articles_embedding_cosine')
55
+
56
+ # Step 2: Convert back to JSON
57
+ op.execute("""
58
+ ALTER TABLE articles
59
+ ALTER COLUMN embedding
60
+ TYPE json
61
+ USING NULL::json
62
+ """)
63
+
64
+ # Step 3: Drop extension (commented out for safety - may affect other tables)
65
+ # op.execute('DROP EXTENSION IF EXISTS vector')
app/__init__.py ADDED
File without changes
app/api/__init__.py ADDED
File without changes
app/api/dependencies/__init__.py ADDED
@@ -0,0 +1,5 @@
 
 
 
 
 
 
1
+ """API dependencies."""
2
+
3
+ from app.core.database import get_db
4
+
5
+ __all__ = ["get_db"]
app/api/routes/__init__.py ADDED
File without changes
app/api/routes/admin.py ADDED
@@ -0,0 +1,335 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API routes for Admin operations.
3
+
4
+ Endpoints:
5
+ - GET /api/v1/admin/users - List users
6
+ - POST /api/v1/admin/users - Create user
7
+ - PUT /api/v1/admin/users/{id} - Update user
8
+ - DELETE /api/v1/admin/users/{id} - Delete user
9
+ - GET /api/v1/admin/system - System information
10
+
11
+ Author: JuriX Development Team
12
+ Date: 2026-01-11
13
+ """
14
+
15
+ import logging
16
+ import platform
17
+ from datetime import datetime
18
+ from typing import Dict, List
19
+
20
+ from fastapi import APIRouter, Depends, HTTPException, status
21
+ from pydantic import BaseModel, EmailStr, Field
22
+ from sqlalchemy.ext.asyncio import AsyncSession
23
+
24
+ from app.core.database import get_db, health_check_db
25
+
26
+ logger = logging.getLogger(__name__)
27
+
28
+ router = APIRouter(prefix="/api/v1/admin", tags=["Admin"])
29
+
30
+
31
+ # ==================== SCHEMAS ====================
32
+
33
+
34
+ class UserCreate(BaseModel):
35
+ """Schema for creating a user."""
36
+
37
+ email: EmailStr = Field(..., description="User email")
38
+ username: str = Field(..., min_length=3, max_length=50, description="Username")
39
+ role: str = Field(default="user", description="User role (user or admin)")
40
+ is_active: bool = Field(default=True, description="User active status")
41
+
42
+
43
+ class UserUpdate(BaseModel):
44
+ """Schema for updating a user."""
45
+
46
+ email: EmailStr | None = None
47
+ username: str | None = Field(None, min_length=3, max_length=50)
48
+ role: str | None = None
49
+ is_active: bool | None = None
50
+
51
+
52
+ class UserResponse(BaseModel):
53
+ """Schema for user response."""
54
+
55
+ id: int
56
+ email: str
57
+ username: str
58
+ role: str
59
+ is_active: bool
60
+ created_at: datetime
61
+
62
+
63
+ # ==================== MOCK USER STORAGE ====================
64
+ # TODO: Replace with actual database model
65
+
66
+
67
+ _mock_users = [
68
+ {
69
+ "id": 1,
70
+ "email": "admin@jurix.cm",
71
+ "username": "admin",
72
+ "role": "admin",
73
+ "is_active": True,
74
+ "created_at": datetime.now(),
75
+ },
76
+ {
77
+ "id": 2,
78
+ "email": "user@jurix.cm",
79
+ "username": "user1",
80
+ "role": "user",
81
+ "is_active": True,
82
+ "created_at": datetime.now(),
83
+ },
84
+ ]
85
+
86
+ _next_user_id = 3
87
+
88
+
89
+ # ==================== AUTHENTICATION ====================
90
+
91
+
92
+ async def get_current_admin():
93
+ """
94
+ Dependency for admin authentication.
95
+
96
+ TODO: Implement actual JWT authentication.
97
+ For now, returns mock admin user.
98
+ """
99
+ return {"id": 1, "role": "admin", "username": "admin"}
100
+
101
+
102
+ # ==================== USER MANAGEMENT ====================
103
+
104
+
105
+ @router.get("/users", response_model=List[UserResponse])
106
+ async def list_users(
107
+ skip: int = 0,
108
+ limit: int = 100,
109
+ current_admin: dict = Depends(get_current_admin),
110
+ ) -> List[UserResponse]:
111
+ """
112
+ List all users (admin only).
113
+
114
+ **Parameters:**
115
+ - skip: Number of records to skip
116
+ - limit: Maximum records to return
117
+
118
+ **Returns:**
119
+ - List of users
120
+
121
+ **Requires:** Admin authentication
122
+ """
123
+ logger.info(f"📋 GET /admin/users - skip={skip}, limit={limit}")
124
+
125
+ users = _mock_users[skip : skip + limit]
126
+ return users
127
+
128
+
129
+ @router.post("/users", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
130
+ async def create_user(
131
+ user: UserCreate,
132
+ current_admin: dict = Depends(get_current_admin),
133
+ ) -> UserResponse:
134
+ """
135
+ Create a new user (admin only).
136
+
137
+ **Parameters:**
138
+ - email: User email (unique)
139
+ - username: Username (unique)
140
+ - role: User role (user or admin)
141
+ - is_active: Active status
142
+
143
+ **Returns:**
144
+ - Created user
145
+
146
+ **Raises:**
147
+ - 409: Email or username already exists
148
+
149
+ **Requires:** Admin authentication
150
+ """
151
+ global _next_user_id
152
+
153
+ assert user is not None, "UserCreate must not be None"
154
+ assert isinstance(user.email, str) and len(user.email) > 0, "Email must be a non-empty string"
155
+ assert isinstance(user.username, str) and len(user.username) >= 3, "Username must be at least 3 characters"
156
+
157
+ logger.info(f"➕ POST /admin/users - Creating user: {user.email}")
158
+
159
+ # Check for duplicate email or username
160
+ for existing_user in _mock_users:
161
+ if existing_user["email"] == user.email:
162
+ raise HTTPException(
163
+ status_code=status.HTTP_409_CONFLICT,
164
+ detail=f"Email already exists: {user.email}",
165
+ )
166
+ if existing_user["username"] == user.username:
167
+ raise HTTPException(
168
+ status_code=status.HTTP_409_CONFLICT,
169
+ detail=f"Username already exists: {user.username}",
170
+ )
171
+
172
+ # Create new user
173
+ new_user = {
174
+ "id": _next_user_id,
175
+ "email": user.email,
176
+ "username": user.username,
177
+ "role": user.role,
178
+ "is_active": user.is_active,
179
+ "created_at": datetime.now(),
180
+ }
181
+
182
+ _mock_users.append(new_user)
183
+ _next_user_id += 1
184
+
185
+ logger.info(f"✅ User created: ID={new_user['id']}, email={new_user['email']}")
186
+ return new_user
187
+
188
+
189
+ @router.put("/users/{user_id}", response_model=UserResponse)
190
+ async def update_user(
191
+ user_id: int,
192
+ user_update: UserUpdate,
193
+ current_admin: dict = Depends(get_current_admin),
194
+ ) -> UserResponse:
195
+ """
196
+ Update a user (admin only).
197
+
198
+ **Parameters:**
199
+ - user_id: User ID
200
+ - Partial update fields
201
+
202
+ **Returns:**
203
+ - Updated user
204
+
205
+ **Raises:**
206
+ - 404: User not found
207
+
208
+ **Requires:** Admin authentication
209
+ """
210
+ assert isinstance(user_id, int) and user_id > 0, "user_id must be a positive integer"
211
+ assert user_update is not None, "UserUpdate must not be None"
212
+
213
+ logger.info(f"✏️ PUT /admin/users/{user_id}")
214
+
215
+ # Find user
216
+ user = next((u for u in _mock_users if u["id"] == user_id), None)
217
+
218
+ if not user:
219
+ raise HTTPException(
220
+ status_code=status.HTTP_404_NOT_FOUND,
221
+ detail=f"User not found: {user_id}",
222
+ )
223
+
224
+ # Update fields
225
+ update_data = user_update.model_dump(exclude_unset=True)
226
+ for field, value in update_data.items():
227
+ user[field] = value
228
+
229
+ logger.info(f"✅ User {user_id} updated")
230
+ return user
231
+
232
+
233
+ @router.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
234
+ async def delete_user(
235
+ user_id: int,
236
+ current_admin: dict = Depends(get_current_admin),
237
+ ):
238
+ """
239
+ Delete a user (admin only).
240
+
241
+ **Parameters:**
242
+ - user_id: User ID
243
+
244
+ **Returns:**
245
+ - 204 No Content
246
+
247
+ **Raises:**
248
+ - 404: User not found
249
+
250
+ **Requires:** Admin authentication
251
+ """
252
+ assert isinstance(user_id, int) and user_id > 0, "user_id must be a positive integer"
253
+
254
+ logger.info(f"🗑️ DELETE /admin/users/{user_id}")
255
+
256
+ # Find user
257
+ user = next((u for u in _mock_users if u["id"] == user_id), None)
258
+
259
+ if not user:
260
+ raise HTTPException(
261
+ status_code=status.HTTP_404_NOT_FOUND,
262
+ detail=f"User not found: {user_id}",
263
+ )
264
+
265
+ # Remove user
266
+ _mock_users.remove(user)
267
+
268
+ logger.info(f"✅ User {user_id} deleted")
269
+ return None
270
+
271
+
272
+ # ==================== SYSTEM INFORMATION ====================
273
+
274
+
275
+ @router.get("/system")
276
+ async def get_system_info(
277
+ db: AsyncSession = Depends(get_db),
278
+ current_admin: dict = Depends(get_current_admin),
279
+ ) -> Dict:
280
+ """
281
+ Get system information (admin only).
282
+
283
+ **Returns:**
284
+ - Database status
285
+ - System info
286
+ - Service health
287
+ - Version info
288
+
289
+ **Requires:** Admin authentication
290
+ """
291
+ logger.info("🖥️ GET /admin/system")
292
+
293
+ # Check database health
294
+ db_healthy = await health_check_db()
295
+
296
+ return {
297
+ "system": {
298
+ "platform": platform.system(),
299
+ "platform_version": platform.version(),
300
+ "python_version": platform.python_version(),
301
+ "hostname": platform.node(),
302
+ },
303
+ "database": {
304
+ "status": "healthy" if db_healthy else "unhealthy",
305
+ "connected": db_healthy,
306
+ },
307
+ "services": {
308
+ "api": "running",
309
+ "search": "running",
310
+ "rag": "running",
311
+ },
312
+ "version": {
313
+ "api": "2.1.0",
314
+ "build": "production",
315
+ },
316
+ "timestamp": datetime.now().isoformat(),
317
+ }
318
+
319
+
320
+ # ==================== HEALTH CHECK ====================
321
+
322
+
323
+ @router.get("/health")
324
+ async def health_check() -> Dict:
325
+ """
326
+ Check admin service health.
327
+
328
+ **Returns:**
329
+ - Service status
330
+ """
331
+ return {
332
+ "service": "Admin",
333
+ "status": "healthy",
334
+ "timestamp": datetime.now().isoformat(),
335
+ }
app/api/routes/analytics.py ADDED
@@ -0,0 +1,291 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API routes for Analytics and Statistics.
3
+
4
+ Endpoints:
5
+ - GET /api/v1/analytics/overview - Dashboard overview
6
+ - GET /api/v1/analytics/laws - Law statistics
7
+ - GET /api/v1/analytics/search - Search analytics
8
+ - GET /api/v1/analytics/usage - Usage metrics
9
+
10
+ Author: JuriX Development Team
11
+ Date: 2026-01-11
12
+ """
13
+
14
+ import logging
15
+ from datetime import datetime, timedelta
16
+ from typing import Dict, List
17
+
18
+ from fastapi import APIRouter, Depends, Query
19
+ from sqlalchemy import func, select
20
+ from sqlalchemy.ext.asyncio import AsyncSession
21
+
22
+ from app.core.database import get_db
23
+ from app.models.law import Law
24
+
25
+ logger = logging.getLogger(__name__)
26
+
27
+ router = APIRouter(prefix="/api/v1/analytics", tags=["Analytics"])
28
+
29
+
30
+ # ==================== DASHBOARD OVERVIEW ====================
31
+
32
+
33
+ @router.get("/overview")
34
+ async def get_overview(
35
+ db: AsyncSession = Depends(get_db),
36
+ ) -> Dict:
37
+ """
38
+ Get dashboard overview with key metrics.
39
+
40
+ **Returns:**
41
+ - Total laws count
42
+ - Laws by language
43
+ - Laws by status
44
+ - Recent activity
45
+
46
+ **Example Response:**
47
+ ```json
48
+ {
49
+ "total_laws": 150,
50
+ "by_language": {"fr": 120, "en": 30},
51
+ "by_status": {"active": 145, "archived": 5},
52
+ "recent_laws": 10
53
+ }
54
+ ```
55
+ """
56
+ logger.info("📊 GET /analytics/overview")
57
+
58
+ try:
59
+ # Total laws
60
+ total_query = select(func.count(Law.id))
61
+ total_result = await db.execute(total_query)
62
+ total_laws = total_result.scalar()
63
+
64
+ # Laws by language
65
+ lang_query = select(
66
+ Law.language,
67
+ func.count(Law.id)
68
+ ).group_by(Law.language)
69
+ lang_result = await db.execute(lang_query)
70
+ by_language = {row[0]: row[1] for row in lang_result.all()}
71
+
72
+ # Laws by status
73
+ status_query = select(
74
+ Law.status,
75
+ func.count(Law.id)
76
+ ).group_by(Law.status)
77
+ status_result = await db.execute(status_query)
78
+ by_status = {row[0]: row[1] for row in status_result.all()}
79
+
80
+ # Recent laws (last 30 days)
81
+ thirty_days_ago = datetime.now() - timedelta(days=30)
82
+ recent_query = select(func.count(Law.id)).where(
83
+ Law.created_at >= thirty_days_ago
84
+ )
85
+ recent_result = await db.execute(recent_query)
86
+ recent_laws = recent_result.scalar()
87
+
88
+ return {
89
+ "total_laws": total_laws or 0,
90
+ "by_language": by_language,
91
+ "by_status": by_status,
92
+ "recent_laws": recent_laws or 0,
93
+ "timestamp": datetime.now().isoformat(),
94
+ }
95
+
96
+ except Exception as e:
97
+ logger.error(f"❌ Error getting overview: {e}", exc_info=True)
98
+ return {
99
+ "total_laws": 0,
100
+ "by_language": {},
101
+ "by_status": {},
102
+ "recent_laws": 0,
103
+ "error": str(e),
104
+ }
105
+
106
+
107
+ # ==================== LAW STATISTICS ====================
108
+
109
+
110
+ @router.get("/laws")
111
+ async def get_law_statistics(
112
+ db: AsyncSession = Depends(get_db),
113
+ ) -> Dict:
114
+ """
115
+ Get detailed law statistics.
116
+
117
+ **Returns:**
118
+ - Laws by language (FR/EN)
119
+ - Laws by type (loi, décret, etc.)
120
+ - Average content length
121
+ - Publication trends
122
+
123
+ **Example Response:**
124
+ ```json
125
+ {
126
+ "by_language": {"fr": 120, "en": 30},
127
+ "by_type": {"loi": 80, "décret": 50, "ordonnance": 20},
128
+ "avg_content_length": 5000,
129
+ "total": 150
130
+ }
131
+ ```
132
+ """
133
+ logger.info("📊 GET /analytics/laws")
134
+
135
+ try:
136
+ # Laws by language
137
+ lang_query = select(
138
+ Law.language,
139
+ func.count(Law.id)
140
+ ).group_by(Law.language)
141
+ lang_result = await db.execute(lang_query)
142
+ by_language = {row[0]: row[1] for row in lang_result.all()}
143
+
144
+ # Laws by type
145
+ type_query = select(
146
+ Law.type,
147
+ func.count(Law.id)
148
+ ).group_by(Law.type)
149
+ type_result = await db.execute(type_query)
150
+ by_type = {row[0]: row[1] for row in type_result.all()}
151
+
152
+ # Average content length
153
+ avg_query = select(func.avg(func.length(Law.content)))
154
+ avg_result = await db.execute(avg_query)
155
+ avg_length = avg_result.scalar() or 0
156
+
157
+ # Total
158
+ total_query = select(func.count(Law.id))
159
+ total_result = await db.execute(total_query)
160
+ total = total_result.scalar()
161
+
162
+ return {
163
+ "by_language": by_language,
164
+ "by_type": by_type,
165
+ "avg_content_length": int(avg_length),
166
+ "total": total or 0,
167
+ "timestamp": datetime.now().isoformat(),
168
+ }
169
+
170
+ except Exception as e:
171
+ logger.error(f"❌ Error getting law statistics: {e}", exc_info=True)
172
+ return {
173
+ "by_language": {},
174
+ "by_type": {},
175
+ "avg_content_length": 0,
176
+ "total": 0,
177
+ "error": str(e),
178
+ }
179
+
180
+
181
+ # ==================== SEARCH ANALYTICS ====================
182
+
183
+
184
+ @router.get("/search")
185
+ async def get_search_analytics() -> Dict:
186
+ """
187
+ Get search analytics.
188
+
189
+ **Returns:**
190
+ - Search modes usage (text/semantic/hybrid)
191
+ - Average response time
192
+ - Popular queries (mock data for now)
193
+
194
+ **Note:** This is a simplified version. In production,
195
+ integrate with actual search logs.
196
+
197
+ **Example Response:**
198
+ ```json
199
+ {
200
+ "modes_usage": {
201
+ "text": 100,
202
+ "semantic": 50,
203
+ "hybrid": 200
204
+ },
205
+ "avg_response_time_ms": 150,
206
+ "total_searches": 350
207
+ }
208
+ ```
209
+ """
210
+ logger.info("📊 GET /analytics/search")
211
+
212
+ # TODO: Integrate with actual search logs
213
+ # For now, return mock data
214
+ return {
215
+ "modes_usage": {
216
+ "text": 100,
217
+ "semantic": 50,
218
+ "hybrid": 200,
219
+ },
220
+ "avg_response_time_ms": 150,
221
+ "total_searches": 350,
222
+ "timestamp": datetime.now().isoformat(),
223
+ "note": "Mock data - integrate with search logs in production",
224
+ }
225
+
226
+
227
+ # ==================== USAGE METRICS ====================
228
+
229
+
230
+ @router.get("/usage")
231
+ async def get_usage_metrics() -> Dict:
232
+ """
233
+ Get API usage metrics.
234
+
235
+ **Returns:**
236
+ - API calls per endpoint
237
+ - Peak usage times
238
+ - Active users (mock data for now)
239
+
240
+ **Note:** This is a simplified version. In production,
241
+ integrate with API gateway logs or monitoring system.
242
+
243
+ **Example Response:**
244
+ ```json
245
+ {
246
+ "api_calls": {
247
+ "/api/v1/laws": 500,
248
+ "/api/v1/search": 350,
249
+ "/api/v1/rag": 200
250
+ },
251
+ "total_calls": 1050,
252
+ "active_users": 25
253
+ }
254
+ ```
255
+ """
256
+ logger.info("📊 GET /analytics/usage")
257
+
258
+ # TODO: Integrate with API gateway logs or monitoring
259
+ # For now, return mock data
260
+ return {
261
+ "api_calls": {
262
+ "/api/v1/laws": 500,
263
+ "/api/v1/search": 350,
264
+ "/api/v1/rag": 200,
265
+ "/api/v1/upload": 100,
266
+ },
267
+ "total_calls": 1150,
268
+ "active_users": 25,
269
+ "peak_hours": [9, 10, 14, 15, 16],
270
+ "timestamp": datetime.now().isoformat(),
271
+ "note": "Mock data - integrate with monitoring system in production",
272
+ }
273
+
274
+
275
+ # ==================== HEALTH CHECK ====================
276
+
277
+
278
+ @router.get("/health")
279
+ async def health_check() -> Dict:
280
+ """
281
+ Check analytics service health.
282
+
283
+ **Returns:**
284
+ - Service status
285
+ - Database connectivity
286
+ """
287
+ return {
288
+ "service": "Analytics",
289
+ "status": "healthy",
290
+ "timestamp": datetime.now().isoformat(),
291
+ }
app/api/routes/articles.py ADDED
@@ -0,0 +1,167 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Article extraction API endpoint (utility).
3
+
4
+ For testing/debugging article extraction on arbitrary text.
5
+ """
6
+
7
+ from fastapi import APIRouter, HTTPException
8
+ from pydantic import BaseModel, Field
9
+ from typing import List, Dict, Any
10
+ import time
11
+
12
+ from app.utils.text_chunker import extract_articles, ArticleExtractionError
13
+
14
+
15
+ router = APIRouter(prefix="/api/v1/articles", tags=["articles"])
16
+
17
+
18
+ class ExtractRequest(BaseModel):
19
+ """Request model for article extraction."""
20
+ text: str = Field(..., min_length=200, max_length=1_000_000, description="Legal document text")
21
+ min_article_length: int = Field(default=10, ge=5, le=1000, description="Minimum article length in characters")
22
+ preserve_formatting: bool = Field(default=False, description="Preserve original formatting")
23
+ strict: bool = Field(default=True, description="Strict validation (require minimum 3 articles)")
24
+
25
+ class Config:
26
+ json_schema_extra = {
27
+ "example": {
28
+ "text": "Article 1. Dispositions générales\nLa présente loi régit...\n\nArticle 2. Champ d'application\nLes dispositions s'appliquent...\n\nArticle 3. Définitions\nAu sens de la présente loi...",
29
+ "min_article_length": 10,
30
+ "preserve_formatting": False,
31
+ "strict": True
32
+ }
33
+ }
34
+
35
+
36
+ class ArticleResult(BaseModel):
37
+ """Single extracted article."""
38
+ number: str
39
+ title: str | None
40
+ content: str
41
+ position: int
42
+ parent_id: str | None
43
+ section: str | None
44
+ word_count: int
45
+ char_count: int
46
+
47
+
48
+ class ExtractResponse(BaseModel):
49
+ """Response model for article extraction."""
50
+ articles: List[Dict[str, Any]]
51
+ count: int
52
+ processing_time_ms: int
53
+
54
+ class Config:
55
+ json_schema_extra = {
56
+ "example": {
57
+ "articles": [
58
+ {
59
+ "number": "1",
60
+ "title": "Dispositions générales",
61
+ "content": "La présente loi régit...",
62
+ "position": 0,
63
+ "parent_id": None,
64
+ "section": None,
65
+ "word_count": 45,
66
+ "char_count": 234
67
+ }
68
+ ],
69
+ "count": 3,
70
+ "processing_time_ms": 125
71
+ }
72
+ }
73
+
74
+
75
+ class HealthResponse(BaseModel):
76
+ """Health check response."""
77
+ service: str
78
+ status: str
79
+ version: str
80
+
81
+
82
+ @router.post("/extract", response_model=ExtractResponse, summary="Extract articles from legal text")
83
+ async def extract_articles_endpoint(request: ExtractRequest) -> ExtractResponse:
84
+ """
85
+ Extract articles from legal document text.
86
+
87
+ This utility endpoint allows testing/debugging of article extraction
88
+ on arbitrary legal text without uploading full documents.
89
+
90
+ **Supported Patterns:**
91
+ - Article X. / Article X:
92
+ - Art. X / Art X.
93
+ - Article premier / Article première
94
+ - Hierarchical: Article 1.1, Article 1.2.3
95
+
96
+ **Validation:**
97
+ - Text length: 200 characters - 1MB
98
+ - Minimum 3 articles (if strict=True)
99
+ - Articles must have minimum length
100
+
101
+ **Returns:**
102
+ - List of extracted articles with metadata
103
+ - Processing time in milliseconds
104
+ - Total article count
105
+ """
106
+ assert request is not None, "Extract request must not be None"
107
+ assert isinstance(request.text, str) and len(request.text) >= 200, "Text must be at least 200 characters"
108
+
109
+ try:
110
+ start = time.time()
111
+
112
+ articles = extract_articles(
113
+ text=request.text,
114
+ min_article_length=request.min_article_length,
115
+ preserve_formatting=request.preserve_formatting,
116
+ strict=request.strict
117
+ )
118
+
119
+ elapsed_ms = int((time.time() - start) * 1000)
120
+
121
+ return ExtractResponse(
122
+ articles=articles,
123
+ count=len(articles),
124
+ processing_time_ms=elapsed_ms
125
+ )
126
+
127
+ except ValueError as e:
128
+ raise HTTPException(
129
+ status_code=400,
130
+ detail={
131
+ "error": "Invalid input",
132
+ "message": str(e),
133
+ "type": "ValueError"
134
+ }
135
+ )
136
+ except ArticleExtractionError as e:
137
+ raise HTTPException(
138
+ status_code=422,
139
+ detail={
140
+ "error": "Extraction failed",
141
+ "message": str(e),
142
+ "type": "ArticleExtractionError"
143
+ }
144
+ )
145
+ except Exception as e:
146
+ raise HTTPException(
147
+ status_code=500,
148
+ detail={
149
+ "error": "Internal server error",
150
+ "message": f"Unexpected error: {str(e)}",
151
+ "type": type(e).__name__
152
+ }
153
+ )
154
+
155
+
156
+ @router.get("/health", response_model=HealthResponse, summary="Health check")
157
+ async def health_check() -> HealthResponse:
158
+ """
159
+ Health check for article extraction service.
160
+
161
+ Returns service status and version information.
162
+ """
163
+ return HealthResponse(
164
+ service="ArticleExtractor",
165
+ status="healthy",
166
+ version="1.0.0"
167
+ )
app/api/routes/batch_upload.py ADDED
@@ -0,0 +1,302 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Batch upload router with WebSocket support for real-time progress tracking.
3
+
4
+ Handles:
5
+ - Batch PDF upload (multiple files)
6
+ - Real-time progress updates via WebSocket
7
+ - Status tracking (PENDING → PROCESSING → PUBLISHED/REFUSED)
8
+ """
9
+
10
+ from fastapi import APIRouter, UploadFile, File, WebSocket, WebSocketDisconnect, HTTPException, Depends
11
+ from sqlalchemy.ext.asyncio import AsyncSession
12
+ from sqlalchemy import select, and_
13
+ from typing import List
14
+ import asyncio
15
+ import json
16
+ import uuid
17
+ from datetime import datetime
18
+
19
+ from app.core.database import get_db
20
+ from app.models.law import Law
21
+ from app.tasks.process_law import process_law_sync
22
+ from app.core.config import settings
23
+
24
+ router = APIRouter(prefix="/admin/batch", tags=["batch-upload"])
25
+
26
+ # WebSocket connection manager
27
+ class ConnectionManager:
28
+ def __init__(self):
29
+ self.active_connections: dict[str, WebSocket] = {}
30
+
31
+ async def connect(self, session_id: str, websocket: WebSocket):
32
+ await websocket.accept()
33
+ self.active_connections[session_id] = websocket
34
+
35
+ def disconnect(self, session_id: str):
36
+ if session_id in self.active_connections:
37
+ del self.active_connections[session_id]
38
+
39
+ async def send_progress(self, session_id: str, data: dict):
40
+ if session_id in self.active_connections:
41
+ try:
42
+ await self.active_connections[session_id].send_json(data)
43
+ except:
44
+ self.disconnect(session_id)
45
+
46
+ manager = ConnectionManager()
47
+
48
+
49
+ @router.websocket("/ws/{session_id}")
50
+ async def websocket_endpoint(websocket: WebSocket, session_id: str):
51
+ """
52
+ WebSocket endpoint for real-time upload progress.
53
+
54
+ Client receives JSON messages:
55
+ {
56
+ "type": "progress",
57
+ "law_id": 123,
58
+ "filename": "law.pdf",
59
+ "progress": 45,
60
+ "status": "processing",
61
+ "message": "Extracting text..."
62
+ }
63
+ """
64
+ assert session_id and isinstance(session_id, str), "session_id must be a non-empty string"
65
+ await manager.connect(session_id, websocket)
66
+ MAX_KEEPALIVE_CYCLES = 3600 # ~1 hour at 1s keepalive cadence (NASA Rule 2: bounded loops)
67
+ try:
68
+ for _ in range(MAX_KEEPALIVE_CYCLES):
69
+ # Keep connection alive, bounded to prevent infinite hang
70
+ await websocket.receive_text()
71
+ # Gracefully close after max cycles
72
+ await websocket.close(code=1000, reason="Session timeout (max keepalive reached)")
73
+ except WebSocketDisconnect:
74
+ pass
75
+ finally:
76
+ manager.disconnect(session_id)
77
+
78
+
79
+ @router.post("/upload")
80
+ async def batch_upload(
81
+ files: List[UploadFile] = File(...),
82
+ session_id: str = None,
83
+ db: AsyncSession = Depends(get_db)
84
+ ):
85
+ """
86
+ Batch upload multiple PDF files.
87
+
88
+ Args:
89
+ files: List of PDF files to upload
90
+ session_id: WebSocket session ID for progress updates
91
+
92
+ Returns:
93
+ {
94
+ "session_id": "uuid",
95
+ "total_files": 10,
96
+ "created_laws": [{"id": 1, "filename": "law1.pdf"}, ...]
97
+ }
98
+ """
99
+ assert files is not None and len(files) > 0, "At least one file must be uploaded"
100
+ assert all(hasattr(f, 'filename') for f in files), "All uploaded items must be valid files"
101
+
102
+ # Generate session ID if not provided
103
+ if not session_id:
104
+ session_id = str(uuid.uuid4())
105
+
106
+ # Validate files
107
+ for file in files:
108
+ if not file.filename.endswith('.pdf'):
109
+ raise HTTPException(400, f"File {file.filename} is not a PDF")
110
+
111
+ # Check file size
112
+ file.file.seek(0, 2) # Seek to end
113
+ size = file.file.tell()
114
+ file.file.seek(0) # Reset
115
+
116
+ if size > settings.MAX_UPLOAD_SIZE:
117
+ raise HTTPException(400, f"File {file.filename} exceeds {settings.MAX_UPLOAD_SIZE / 1024 / 1024}MB limit")
118
+
119
+ created_laws = []
120
+
121
+ # Process each file
122
+ for idx, file in enumerate(files):
123
+ try:
124
+ # Send progress update
125
+ await manager.send_progress(session_id, {
126
+ "type": "upload_progress",
127
+ "current": idx + 1,
128
+ "total": len(files),
129
+ "filename": file.filename,
130
+ "status": "uploading"
131
+ })
132
+
133
+ # Read file content
134
+ content = await file.read()
135
+
136
+ # Create law entry with PENDING status
137
+ law = Law(
138
+ reference=f"PENDING-{uuid.uuid4().hex[:8]}",
139
+ title=f"PENDING-{uuid.uuid4().hex[:8]}",
140
+ type="loi",
141
+ content="", # Will be filled by processing
142
+ status="pending",
143
+ processing_progress=0,
144
+ processing_started_at=None
145
+ )
146
+
147
+ db.add(law)
148
+ await db.flush() # Get ID
149
+
150
+ # Save file temporarily
151
+ from pathlib import Path
152
+ from app.services.file_upload_service import get_upload_service
153
+
154
+ upload_service = get_upload_service()
155
+ file_id = str(uuid.uuid4())
156
+ file_path = upload_service.storage_path / f"{file_id}.pdf"
157
+
158
+ with open(file_path, "wb") as f:
159
+ f.write(content)
160
+
161
+ created_laws.append({
162
+ "id": law.id,
163
+ "filename": file.filename,
164
+ "file_id": file_id,
165
+ "status": "pending"
166
+ })
167
+
168
+ # Send creation confirmation
169
+ await manager.send_progress(session_id, {
170
+ "type": "file_created",
171
+ "law_id": law.id,
172
+ "filename": file.filename,
173
+ "status": "pending"
174
+ })
175
+
176
+ except Exception as e:
177
+ await manager.send_progress(session_id, {
178
+ "type": "error",
179
+ "filename": file.filename,
180
+ "error": str(e)
181
+ })
182
+
183
+ await db.commit()
184
+
185
+ # Start background processing for all files
186
+ asyncio.create_task(process_batch(created_laws, session_id, db))
187
+
188
+ return {
189
+ "session_id": session_id,
190
+ "total_files": len(files),
191
+ "created_laws": created_laws
192
+ }
193
+
194
+
195
+ async def process_batch(laws: List[dict], session_id: str, db: AsyncSession):
196
+ """
197
+ Background task to process all uploaded files.
198
+ """
199
+ for law_data in laws:
200
+ try:
201
+ law_id = law_data["id"]
202
+ file_id = law_data["file_id"]
203
+
204
+ # Update status to PROCESSING
205
+ result = await db.execute(select(Law).where(Law.id == law_id))
206
+ law = result.scalar_one_or_none()
207
+
208
+ if law:
209
+ law.status = "processing"
210
+ law.processing_progress = 0
211
+ law.processing_started_at = datetime.utcnow()
212
+ await db.commit()
213
+
214
+ # Send processing start
215
+ await manager.send_progress(session_id, {
216
+ "type": "processing_start",
217
+ "law_id": law_id,
218
+ "filename": law_data["filename"],
219
+ "status": "processing"
220
+ })
221
+
222
+ # Call processing pipeline (synchronous)
223
+ # We'll need to update process_law_sync to emit progress
224
+ result = process_law_sync(law_id, file_id)
225
+
226
+ # Update final status
227
+ if result.get("status") == "completed":
228
+ law.status = "published"
229
+ law.processing_progress = 100
230
+ else:
231
+ law.status = "refused"
232
+ law.processing_error = str(result.get("errors", []))
233
+
234
+ await db.commit()
235
+
236
+ # Send completion
237
+ await manager.send_progress(session_id, {
238
+ "type": "processing_complete",
239
+ "law_id": law_id,
240
+ "filename": law_data["filename"],
241
+ "status": law.status,
242
+ "progress": 100
243
+ })
244
+
245
+ except Exception as e:
246
+ # Mark as refused
247
+ law.status = "refused"
248
+ law.processing_error = str(e)
249
+ await db.commit()
250
+
251
+ await manager.send_progress(session_id, {
252
+ "type": "processing_error",
253
+ "law_id": law_id,
254
+ "filename": law_data["filename"],
255
+ "error": str(e)
256
+ })
257
+
258
+
259
+ @router.get("/status")
260
+ async def get_batch_status(
261
+ status: str = None,
262
+ db: AsyncSession = Depends(get_db)
263
+ ):
264
+ """
265
+ Get all laws with optional status filter.
266
+
267
+ Args:
268
+ status: Filter by status (pending, processing, published, refused)
269
+
270
+ Returns:
271
+ List of laws with their processing status
272
+ """
273
+ assert status is None or isinstance(status, str), "Status filter must be a string or None"
274
+ assert status is None or status in ("pending", "processing", "published", "refused"), \
275
+ f"Invalid status: {status}. Must be one of: pending, processing, published, refused"
276
+
277
+ query = select(Law)
278
+
279
+ if status:
280
+ query = query.where(Law.status == status)
281
+
282
+ query = query.order_by(Law.created_at.desc())
283
+
284
+ result = await db.execute(query)
285
+ laws = result.scalars().all()
286
+
287
+ return {
288
+ "total": len(laws),
289
+ "laws": [
290
+ {
291
+ "id": law.id,
292
+ "title": law.title,
293
+ "reference": law.reference,
294
+ "status": law.status,
295
+ "processing_progress": law.processing_progress,
296
+ "processing_error": law.processing_error,
297
+ "created_at": law.created_at.isoformat() if law.created_at else None,
298
+ "processing_started_at": law.processing_started_at.isoformat() if law.processing_started_at else None
299
+ }
300
+ for law in laws
301
+ ]
302
+ }
app/api/routes/categories.py ADDED
@@ -0,0 +1,600 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API Routes for Category Management (Service 8).
3
+
4
+ Endpoints:
5
+ - POST /api/v1/categories - Create category
6
+ - GET /api/v1/categories - List categories
7
+ - GET /api/v1/categories/{id} - Get single category
8
+ - PUT /api/v1/categories/{id} - Update category
9
+ - DELETE /api/v1/categories/{id} - Delete category
10
+ - GET /api/v1/categories/{id}/stats - Get category statistics
11
+ - GET /api/v1/categories/stats/all - Get all category statistics
12
+ - GET /api/v1/categories/mapping/id-to-name - Get ID → Name mapping
13
+ - GET /api/v1/categories/mapping/name-to-id - Get Name → ID mapping
14
+ - GET /api/v1/categories/health - Health check
15
+
16
+ Author: JuriX Team
17
+ Version: 2.1.0
18
+ """
19
+
20
+ import logging
21
+ from typing import List, Dict
22
+ from fastapi import APIRouter, Depends, HTTPException, status, Query
23
+ from sqlalchemy.ext.asyncio import AsyncSession
24
+
25
+ from app.core.database import get_db
26
+ from app.services.category_service import (
27
+ CategoryService,
28
+ CategoryNotFoundError,
29
+ DuplicateCategoryNameError,
30
+ CategoryInUseError,
31
+ CategoryServiceError
32
+ )
33
+ from app.schemas.law import CategoryCreate, CategoryUpdate, CategoryResponse, CategoryStats
34
+
35
+ # Configure logger
36
+ logger = logging.getLogger(__name__)
37
+
38
+ # Create router
39
+ router = APIRouter(
40
+ prefix="/api/v1/categories",
41
+ tags=["categories"],
42
+ responses={
43
+ 400: {"description": "Bad Request - Validation error"},
44
+ 404: {"description": "Not Found - Category doesn't exist"},
45
+ 409: {"description": "Conflict - Category in use or duplicate name"},
46
+ 500: {"description": "Internal Server Error"}
47
+ }
48
+ )
49
+
50
+
51
+ # ============================================================================
52
+ # CRUD ENDPOINTS
53
+ # ============================================================================
54
+
55
+ @router.post(
56
+ "",
57
+ response_model=CategoryResponse,
58
+ status_code=status.HTTP_201_CREATED,
59
+ summary="Create a new category"
60
+ )
61
+ async def create_category(
62
+ category_data: CategoryCreate,
63
+ db: AsyncSession = Depends(get_db)
64
+ ) -> CategoryResponse:
65
+ """
66
+ Create a new legal category.
67
+
68
+ **Parameters:**
69
+ - **name**: Category name (unique, 1-100 characters)
70
+ - **description**: Optional description
71
+
72
+ **Returns:**
73
+ - Created category with ID and metadata
74
+
75
+ **Raises:**
76
+ - 400: Invalid input data
77
+ - 409: Category name already exists
78
+ - 500: Server error
79
+ """
80
+ assert category_data is not None, "CategoryCreate must not be None"
81
+ assert isinstance(category_data.name, str) and len(category_data.name) > 0, "Category name must be a non-empty string"
82
+
83
+ try:
84
+ logger.info(f"📥 POST /categories - Creating: {category_data.name}")
85
+ service = CategoryService(db)
86
+ category = await service.create_category(category_data)
87
+
88
+ # Build response
89
+ law_count = await service._get_law_count_for_category(category.id)
90
+ response = CategoryResponse(
91
+ id=category.id,
92
+ name=category.name,
93
+ description=category.description,
94
+ created_at=category.created_at,
95
+ law_count=law_count
96
+ )
97
+
98
+ logger.info(f"✅ Category created: {category.name} (ID: {category.id})")
99
+ return response
100
+
101
+ except DuplicateCategoryNameError as e:
102
+ logger.warning(f"⚠️ Duplicate category name: {e}")
103
+ raise HTTPException(
104
+ status_code=status.HTTP_409_CONFLICT,
105
+ detail=str(e)
106
+ )
107
+ except CategoryServiceError as e:
108
+ logger.error(f"❌ Service error: {e}")
109
+ raise HTTPException(
110
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
111
+ detail=f"Failed to create category: {str(e)}"
112
+ )
113
+
114
+
115
+ @router.get(
116
+ "",
117
+ response_model=List[CategoryResponse],
118
+ summary="List all categories"
119
+ )
120
+ async def list_categories(
121
+ skip: int = Query(0, ge=0, description="Number of records to skip"),
122
+ limit: int = Query(100, ge=1, le=1000, description="Maximum records to return"),
123
+ db: AsyncSession = Depends(get_db)
124
+ ) -> List[CategoryResponse]:
125
+ """
126
+ List all legal categories with law counts.
127
+
128
+ **Parameters:**
129
+ - **skip**: Pagination offset (default: 0)
130
+ - **limit**: Max results (default: 100, max: 1000)
131
+
132
+ **Returns:**
133
+ - List of categories ordered by name
134
+ - Each category includes law_count
135
+
136
+ **Example Response:**
137
+ ```json
138
+ [
139
+ {
140
+ "id": 1,
141
+ "name": "Droit Civil",
142
+ "description": "Civil law",
143
+ "created_at": "2024-01-01T00:00:00",
144
+ "law_count": 45
145
+ }
146
+ ]
147
+ ```
148
+ """
149
+ try:
150
+ logger.info(f"📥 GET /categories (skip={skip}, limit={limit})")
151
+ service = CategoryService(db)
152
+ categories = await service.list_categories(skip=skip, limit=limit)
153
+
154
+ # DEBUG: Print first category details
155
+ if categories:
156
+ first = categories[0]
157
+ logger.info(f"DEBUG: First category: ID={first.id}, Name={first.name}, Icon={getattr(first, 'icon', 'MISSING')}")
158
+
159
+ logger.info(f"✅ Returning {len(categories)} categories")
160
+ return categories
161
+
162
+ except CategoryServiceError as e:
163
+ logger.error(f"❌ Service error: {e}")
164
+ raise HTTPException(
165
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
166
+ detail=f"Failed to list categories: {str(e)}"
167
+ )
168
+
169
+
170
+ @router.get(
171
+ "/{category_id}",
172
+ response_model=CategoryResponse,
173
+ summary="Get a single category"
174
+ )
175
+ async def get_category(
176
+ category_id: int,
177
+ db: AsyncSession = Depends(get_db)
178
+ ) -> CategoryResponse:
179
+ """
180
+ Get a category by ID.
181
+
182
+ **Parameters:**
183
+ - **category_id**: Category ID
184
+
185
+ **Returns:**
186
+ - Category details with law count
187
+
188
+ **Raises:**
189
+ - 404: Category not found
190
+ - 500: Server error
191
+ """
192
+ assert isinstance(category_id, int) and category_id > 0, "Category ID must be a positive integer"
193
+
194
+ try:
195
+ logger.info(f"�� GET /categories/{category_id}")
196
+ service = CategoryService(db)
197
+ category = await service.get_category(category_id)
198
+
199
+ # Build response
200
+ law_count = await service._get_law_count_for_category(category.id)
201
+ response = CategoryResponse(
202
+ id=category.id,
203
+ name=category.name,
204
+ description=category.description,
205
+ icon=category.icon,
206
+ created_at=category.created_at,
207
+ law_count=law_count
208
+ )
209
+
210
+ logger.info(f"✅ Category found: {category.name}")
211
+ return response
212
+
213
+ except CategoryNotFoundError as e:
214
+ logger.warning(f"⚠️ Category not found: {e}")
215
+ raise HTTPException(
216
+ status_code=status.HTTP_404_NOT_FOUND,
217
+ detail=str(e)
218
+ )
219
+ except CategoryServiceError as e:
220
+ logger.error(f"❌ Service error: {e}")
221
+ raise HTTPException(
222
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
223
+ detail=f"Failed to fetch category: {str(e)}"
224
+ )
225
+
226
+
227
+ @router.put(
228
+ "/{category_id}",
229
+ response_model=CategoryResponse,
230
+ summary="Update a category"
231
+ )
232
+ async def update_category(
233
+ category_id: int,
234
+ category_data: CategoryUpdate,
235
+ db: AsyncSession = Depends(get_db)
236
+ ) -> CategoryResponse:
237
+ """
238
+ Update a category.
239
+
240
+ **Parameters:**
241
+ - **category_id**: Category ID
242
+ - **name**: New name (optional)
243
+ - **description**: New description (optional)
244
+
245
+ **Returns:**
246
+ - Updated category
247
+
248
+ **Raises:**
249
+ - 404: Category not found
250
+ - 409: New name conflicts with existing category
251
+ - 500: Server error
252
+ """
253
+ assert isinstance(category_id, int) and category_id > 0, "category_id must be a positive integer"
254
+ assert category_data is not None, "CategoryUpdate must not be None"
255
+
256
+ try:
257
+ logger.info(f"📥 PUT /categories/{category_id}")
258
+ service = CategoryService(db)
259
+ category = await service.update_category(category_id, category_data)
260
+
261
+ # Build response
262
+ law_count = await service._get_law_count_for_category(category.id)
263
+ response = CategoryResponse(
264
+ id=category.id,
265
+ name=category.name,
266
+ description=category.description,
267
+ created_at=category.created_at,
268
+ law_count=law_count
269
+ )
270
+
271
+ logger.info(f"✅ Category updated: {category.name}")
272
+ return response
273
+
274
+ except CategoryNotFoundError as e:
275
+ logger.warning(f"⚠️ Category not found: {e}")
276
+ raise HTTPException(
277
+ status_code=status.HTTP_404_NOT_FOUND,
278
+ detail=str(e)
279
+ )
280
+ except DuplicateCategoryNameError as e:
281
+ logger.warning(f"⚠️ Duplicate category name: {e}")
282
+ raise HTTPException(
283
+ status_code=status.HTTP_409_CONFLICT,
284
+ detail=str(e)
285
+ )
286
+ except CategoryServiceError as e:
287
+ logger.error(f"❌ Service error: {e}")
288
+ raise HTTPException(
289
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
290
+ detail=f"Failed to update category: {str(e)}"
291
+ )
292
+
293
+
294
+ @router.delete(
295
+ "/{category_id}",
296
+ status_code=status.HTTP_204_NO_CONTENT,
297
+ summary="Delete a category"
298
+ )
299
+ async def delete_category(
300
+ category_id: int,
301
+ force: bool = Query(False, description="Force delete even if laws are associated"),
302
+ db: AsyncSession = Depends(get_db)
303
+ ):
304
+ """
305
+ Delete a category.
306
+
307
+ **Parameters:**
308
+ - **category_id**: Category ID
309
+ - **force**: If true, deletes category even if laws are associated
310
+ (laws will have category_id set to NULL)
311
+
312
+ **Returns:**
313
+ - 204 No Content on success
314
+
315
+ **Raises:**
316
+ - 404: Category not found
317
+ - 409: Category has associated laws and force=false
318
+ - 500: Server error
319
+
320
+ **Warning:**
321
+ Using force=true will set category_id to NULL for all associated laws.
322
+ Use with caution in production!
323
+ """
324
+ assert isinstance(category_id, int) and category_id > 0, "category_id must be a positive integer"
325
+
326
+ try:
327
+ logger.info(f"📥 DELETE /categories/{category_id} (force={force})")
328
+ service = CategoryService(db)
329
+ await service.delete_category(category_id, force=force)
330
+
331
+ logger.info(f"✅ Category deleted: ID {category_id}")
332
+ return None # 204 No Content
333
+
334
+ except CategoryNotFoundError as e:
335
+ logger.warning(f"⚠️ Category not found: {e}")
336
+ raise HTTPException(
337
+ status_code=status.HTTP_404_NOT_FOUND,
338
+ detail=str(e)
339
+ )
340
+ except CategoryInUseError as e:
341
+ logger.warning(f"⚠️ Category in use: {e}")
342
+ raise HTTPException(
343
+ status_code=status.HTTP_409_CONFLICT,
344
+ detail=str(e)
345
+ )
346
+ except CategoryServiceError as e:
347
+ logger.error(f"❌ Service error: {e}")
348
+ raise HTTPException(
349
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
350
+ detail=f"Failed to delete category: {str(e)}"
351
+ )
352
+
353
+
354
+ # ============================================================================
355
+ # STATISTICS ENDPOINTS
356
+ # ============================================================================
357
+
358
+ @router.get(
359
+ "/{category_id}/stats",
360
+ response_model=CategoryStats,
361
+ summary="Get category statistics"
362
+ )
363
+ async def get_category_stats(
364
+ category_id: int,
365
+ db: AsyncSession = Depends(get_db)
366
+ ) -> CategoryStats:
367
+ """
368
+ Get statistics for a single category.
369
+
370
+ **Parameters:**
371
+ - **category_id**: Category ID
372
+
373
+ **Returns:**
374
+ - Category statistics (law count, percentage)
375
+
376
+ **Example Response:**
377
+ ```json
378
+ {
379
+ "category_id": 1,
380
+ "category_name": "Droit Civil",
381
+ "law_count": 45,
382
+ "percentage": 26.47
383
+ }
384
+ ```
385
+
386
+ **Raises:**
387
+ - 404: Category not found
388
+ - 500: Server error
389
+ """
390
+ try:
391
+ logger.info(f"📥 GET /categories/{category_id}/stats")
392
+ service = CategoryService(db)
393
+ stats = await service.get_category_stats(category_id)
394
+
395
+ logger.info(f"✅ Stats returned: {stats.law_count} laws ({stats.percentage:.2f}%)")
396
+ return stats
397
+
398
+ except CategoryNotFoundError as e:
399
+ logger.warning(f"⚠️ Category not found: {e}")
400
+ raise HTTPException(
401
+ status_code=status.HTTP_404_NOT_FOUND,
402
+ detail=str(e)
403
+ )
404
+ except CategoryServiceError as e:
405
+ logger.error(f"❌ Service error: {e}")
406
+ raise HTTPException(
407
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
408
+ detail=f"Failed to fetch category stats: {str(e)}"
409
+ )
410
+
411
+
412
+ @router.get(
413
+ "/stats/all",
414
+ response_model=List[CategoryStats],
415
+ summary="Get statistics for all categories"
416
+ )
417
+ async def get_all_category_stats(
418
+ db: AsyncSession = Depends(get_db)
419
+ ) -> List[CategoryStats]:
420
+ """
421
+ Get statistics for all categories.
422
+
423
+ **Returns:**
424
+ - List of category statistics ordered by law count (descending)
425
+ - Each includes: category ID, name, law count, percentage
426
+
427
+ **Example Response:**
428
+ ```json
429
+ [
430
+ {
431
+ "category_id": 1,
432
+ "category_name": "Droit Civil",
433
+ "law_count": 45,
434
+ "percentage": 26.47
435
+ },
436
+ {
437
+ "category_id": 2,
438
+ "category_name": "Droit Pénal",
439
+ "law_count": 38,
440
+ "percentage": 22.35
441
+ }
442
+ ]
443
+ ```
444
+
445
+ **Use Case:**
446
+ - Dashboard analytics
447
+ - Category distribution charts
448
+ - Admin overview
449
+ """
450
+ try:
451
+ logger.info("📥 GET /categories/stats/all")
452
+ service = CategoryService(db)
453
+ stats_list = await service.get_all_category_stats()
454
+
455
+ logger.info(f"✅ Stats returned for {len(stats_list)} categories")
456
+ return stats_list
457
+
458
+ except CategoryServiceError as e:
459
+ logger.error(f"❌ Service error: {e}")
460
+ raise HTTPException(
461
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
462
+ detail=f"Failed to fetch all category stats: {str(e)}"
463
+ )
464
+
465
+
466
+ # ============================================================================
467
+ # MAPPING UTILITY ENDPOINTS
468
+ # ============================================================================
469
+
470
+ @router.get(
471
+ "/mapping/id-to-name",
472
+ response_model=Dict[int, str],
473
+ summary="Get ID → Name mapping"
474
+ )
475
+ async def get_id_to_name_mapping(
476
+ db: AsyncSession = Depends(get_db)
477
+ ) -> Dict[int, str]:
478
+ """
479
+ Get ID → Name mapping for all categories.
480
+
481
+ **Returns:**
482
+ - Dictionary mapping category IDs to names
483
+
484
+ **Example Response:**
485
+ ```json
486
+ {
487
+ "1": "Droit Civil",
488
+ "2": "Droit Pénal",
489
+ "3": "Droit Commercial"
490
+ }
491
+ ```
492
+
493
+ **Use Case:**
494
+ - Fast lookups without database queries
495
+ - Frontend dropdown populations
496
+ - DocumentClassifier integration
497
+ """
498
+ try:
499
+ logger.info("📥 GET /categories/mapping/id-to-name")
500
+ service = CategoryService(db)
501
+ mapping = await service.get_category_mapping()
502
+
503
+ logger.info(f"✅ Mapping returned: {len(mapping)} categories")
504
+ return mapping
505
+
506
+ except CategoryServiceError as e:
507
+ logger.error(f"❌ Service error: {e}")
508
+ raise HTTPException(
509
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
510
+ detail=f"Failed to fetch ID → Name mapping: {str(e)}"
511
+ )
512
+
513
+
514
+ @router.get(
515
+ "/mapping/name-to-id",
516
+ response_model=Dict[str, int],
517
+ summary="Get Name → ID mapping"
518
+ )
519
+ async def get_name_to_id_mapping(
520
+ db: AsyncSession = Depends(get_db)
521
+ ) -> Dict[str, int]:
522
+ """
523
+ Get Name → ID mapping for all categories.
524
+
525
+ **Returns:**
526
+ - Dictionary mapping category names to IDs
527
+
528
+ **Example Response:**
529
+ ```json
530
+ {
531
+ "Droit Civil": 1,
532
+ "Droit Pénal": 2,
533
+ "Droit Commercial": 3
534
+ }
535
+ ```
536
+
537
+ **Use Case:**
538
+ - Reverse lookups by name
539
+ - Category name validation
540
+ - Import/export utilities
541
+ """
542
+ try:
543
+ logger.info("📥 GET /categories/mapping/name-to-id")
544
+ service = CategoryService(db)
545
+ mapping = await service.get_reverse_category_mapping()
546
+
547
+ logger.info(f"✅ Reverse mapping returned: {len(mapping)} categories")
548
+ return mapping
549
+
550
+ except CategoryServiceError as e:
551
+ logger.error(f"❌ Service error: {e}")
552
+ raise HTTPException(
553
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
554
+ detail=f"Failed to fetch Name → ID mapping: {str(e)}"
555
+ )
556
+
557
+
558
+ # ============================================================================
559
+ # HEALTH CHECK
560
+ # ============================================================================
561
+
562
+ @router.get(
563
+ "/health",
564
+ response_model=Dict[str, str],
565
+ summary="Health check"
566
+ )
567
+ async def health_check(
568
+ db: AsyncSession = Depends(get_db)
569
+ ) -> Dict[str, str]:
570
+ """
571
+ Check CategoryService health.
572
+
573
+ **Returns:**
574
+ - Service status and metadata
575
+
576
+ **Example Response:**
577
+ ```json
578
+ {
579
+ "service": "CategoryService",
580
+ "status": "healthy",
581
+ "version": "2.1.0",
582
+ "timestamp": "2024-01-11T12:00:00"
583
+ }
584
+ ```
585
+ """
586
+ try:
587
+ logger.debug("📥 GET /categories/health")
588
+ service = CategoryService(db)
589
+ health = service.health_check()
590
+
591
+ logger.debug("✅ Health check passed")
592
+ return health
593
+
594
+ except Exception as e:
595
+ logger.error(f"❌ Health check failed: {e}")
596
+ return {
597
+ "service": "CategoryService",
598
+ "status": "unhealthy",
599
+ "error": str(e)
600
+ }
app/api/routes/classifier.py ADDED
@@ -0,0 +1,392 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API Routes pour catégorisation de documents juridiques.
3
+
4
+ Endpoints:
5
+ - POST /api/v1/classifier/classify - Classifie un document
6
+ - GET /api/v1/classifier/health - Vérifie santé du service
7
+ - GET /api/v1/classifier/categories - Liste toutes les catégories
8
+
9
+ Usage:
10
+ curl -X POST http://localhost:8000/api/v1/classifier/classify \
11
+ -H "Content-Type: application/json" \
12
+ -d '{"text": "Article 1. La SARL est une société commerciale..."}'
13
+ """
14
+
15
+ from typing import Dict, Any, List
16
+ import logging
17
+
18
+ from fastapi import APIRouter, Depends, HTTPException, status
19
+ from pydantic import BaseModel, Field, validator
20
+
21
+ from app.core.dependencies import get_document_classifier
22
+ from app.services.document_classifier import DocumentClassifier, DocumentClassificationError
23
+
24
+ logger = logging.getLogger(__name__)
25
+
26
+ # Router configuration
27
+ router = APIRouter(
28
+ prefix="/api/v1/classifier",
29
+ tags=["classifier"],
30
+ responses={
31
+ 500: {"description": "Erreur interne du service de classification"}
32
+ }
33
+ )
34
+
35
+
36
+ # ==================== MODELS ====================
37
+
38
+ class ClassifyDocumentRequest(BaseModel):
39
+ """Requête de classification de document."""
40
+
41
+ text: str = Field(
42
+ ...,
43
+ min_length=50,
44
+ max_length=50000,
45
+ description="Texte du document à classifier (50-50000 caractères)",
46
+ example="Article 1. Les sociétés commerciales sont régies par l'acte uniforme OHADA. La SARL doit avoir un capital social minimum."
47
+ )
48
+
49
+ language: str = Field(
50
+ default="fr",
51
+ description="Langue du document ('fr' ou 'en')",
52
+ example="fr"
53
+ )
54
+
55
+ top_k: int = Field(
56
+ default=3,
57
+ ge=1,
58
+ le=12,
59
+ description="Nombre de suggestions à retourner (1-12)",
60
+ example=3
61
+ )
62
+
63
+ min_confidence: float = Field(
64
+ default=0.0,
65
+ ge=0.0,
66
+ le=1.0,
67
+ description="Seuil de confiance minimum (0-1)",
68
+ example=0.0
69
+ )
70
+
71
+ @validator('text')
72
+ def text_not_empty(cls, v):
73
+ """Valide que le texte n'est pas vide."""
74
+ if not v or not v.strip():
75
+ raise ValueError("Le texte ne peut pas être vide")
76
+ return v
77
+
78
+ @validator('language')
79
+ def language_valid(cls, v):
80
+ """Valide que la langue est supportée."""
81
+ if v not in ['fr', 'en']:
82
+ raise ValueError("Langue doit être 'fr' ou 'en'")
83
+ return v
84
+
85
+ class Config:
86
+ json_schema_extra = {
87
+ "example": {
88
+ "text": "Article 1. La SARL est régie par l'acte uniforme OHADA relatif au droit des sociétés commerciales. Le capital social est divisé en parts sociales.",
89
+ "language": "fr",
90
+ "top_k": 3,
91
+ "min_confidence": 0.0
92
+ }
93
+ }
94
+
95
+
96
+ class CategorySuggestion(BaseModel):
97
+ """Suggestion de catégorie avec confiance."""
98
+
99
+ category_id: int = Field(
100
+ ...,
101
+ ge=1,
102
+ le=12,
103
+ description="ID de la catégorie (1-12)",
104
+ example=4
105
+ )
106
+
107
+ category_name: str = Field(
108
+ ...,
109
+ description="Nom de la catégorie",
110
+ example="Droit Commercial OHADA"
111
+ )
112
+
113
+ confidence: float = Field(
114
+ ...,
115
+ ge=0.0,
116
+ le=1.0,
117
+ description="Score de confiance (0-1)",
118
+ example=0.92
119
+ )
120
+
121
+ method: str = Field(
122
+ ...,
123
+ description="Méthode utilisée ('keyword', 'ml', 'hybrid')",
124
+ example="keyword"
125
+ )
126
+
127
+ class Config:
128
+ json_schema_extra = {
129
+ "example": {
130
+ "category_id": 4,
131
+ "category_name": "Droit Commercial OHADA",
132
+ "confidence": 0.92,
133
+ "method": "keyword"
134
+ }
135
+ }
136
+
137
+
138
+ class ClassifyDocumentResponse(BaseModel):
139
+ """Réponse de classification."""
140
+
141
+ suggestions: List[CategorySuggestion] = Field(
142
+ ...,
143
+ description="Liste des suggestions classées par confiance décroissante"
144
+ )
145
+
146
+ processing_time_ms: int = Field(
147
+ ...,
148
+ description="Temps de traitement en millisecondes",
149
+ example=125
150
+ )
151
+
152
+ class Config:
153
+ json_schema_extra = {
154
+ "example": {
155
+ "suggestions": [
156
+ {
157
+ "category_id": 4,
158
+ "category_name": "Droit Commercial OHADA",
159
+ "confidence": 0.92,
160
+ "method": "keyword"
161
+ },
162
+ {
163
+ "category_id": 12,
164
+ "category_name": "Droit des Affaires",
165
+ "confidence": 0.68,
166
+ "method": "keyword"
167
+ },
168
+ {
169
+ "category_id": 2,
170
+ "category_name": "Droit Civil",
171
+ "confidence": 0.45,
172
+ "method": "keyword"
173
+ }
174
+ ],
175
+ "processing_time_ms": 125
176
+ }
177
+ }
178
+
179
+
180
+ class HealthResponse(BaseModel):
181
+ """Réponse du health check."""
182
+
183
+ service: str = Field(..., example="DocumentClassifier")
184
+ status: str = Field(..., example="healthy")
185
+ mode: str = Field(..., example="keywords-only")
186
+ ml_model_loaded: bool = Field(..., example=False)
187
+ vectorizer_loaded: bool = Field(..., example=False)
188
+ categories_count: int = Field(..., example=12)
189
+ version: str = Field(..., example="1.0.0-mvp")
190
+
191
+
192
+ class Category(BaseModel):
193
+ """Catégorie juridique."""
194
+
195
+ id: int = Field(..., ge=1, le=12, example=4)
196
+ name: str = Field(..., example="Droit Commercial OHADA")
197
+
198
+
199
+ class CategoriesResponse(BaseModel):
200
+ """Liste des catégories disponibles."""
201
+
202
+ categories: List[Category] = Field(
203
+ ...,
204
+ description="Liste des 12 catégories juridiques"
205
+ )
206
+
207
+
208
+ # ==================== ENDPOINTS ====================
209
+
210
+ @router.post(
211
+ "/classify",
212
+ response_model=ClassifyDocumentResponse,
213
+ status_code=status.HTTP_200_OK,
214
+ summary="Classifier un document juridique",
215
+ description="""
216
+ Classifie un document juridique dans une ou plusieurs des 12 catégories.
217
+
218
+ **Méthodes:**
219
+ - Phase 1 (MVP): Keywords-only (70-75% précision)
220
+ - Phase 3: Hybrid 40% keywords + 60% ML (87% top-1, 96% top-3)
221
+
222
+ **Catégories disponibles:**
223
+ 1. Droit Constitutionnel
224
+ 2. Droit Civil
225
+ 3. Droit Pénal
226
+ 4. Droit Commercial OHADA
227
+ 5. Droit du Travail
228
+ 6. Droit Fiscal
229
+ 7. Droit Administratif
230
+ 8. Droit Foncier
231
+ 9. Droit de la Famille
232
+ 10. Droit de l'Environnement
233
+ 11. Droit International
234
+ 12. Droit des Affaires
235
+
236
+ **Performance:**
237
+ - Temps de réponse: <500ms (MVP), <2s (ML)
238
+ - Top-k suggestions classées par confiance décroissante
239
+ """
240
+ )
241
+ async def classify_document(
242
+ request: ClassifyDocumentRequest,
243
+ classifier: DocumentClassifier = Depends(get_document_classifier)
244
+ ) -> ClassifyDocumentResponse:
245
+ """
246
+ Classifie un document juridique.
247
+
248
+ Args:
249
+ request: Requête avec texte et paramètres
250
+ classifier: Instance du classifier (injectée)
251
+
252
+ Returns:
253
+ Suggestions de catégories avec scores de confiance
254
+
255
+ Raises:
256
+ HTTPException 400: Texte invalide
257
+ HTTPException 500: Erreur interne de classification
258
+ """
259
+ assert request is not None, "ClassifyDocumentRequest must not be None"
260
+ assert isinstance(request.text, str) and len(request.text) >= 50, "Text must be at least 50 characters"
261
+
262
+ try:
263
+ import time
264
+ start_time = time.time()
265
+
266
+ # Classification
267
+ results = classifier.classify(
268
+ text=request.text,
269
+ language=request.language,
270
+ top_k=request.top_k,
271
+ min_confidence=request.min_confidence
272
+ )
273
+
274
+ # Formatter réponse
275
+ suggestions = []
276
+ for category_id, confidence, method in results:
277
+ category_name = classifier.get_category_name(category_id)
278
+ suggestions.append(
279
+ CategorySuggestion(
280
+ category_id=category_id,
281
+ category_name=category_name,
282
+ confidence=confidence,
283
+ method=method
284
+ )
285
+ )
286
+
287
+ processing_time_ms = int((time.time() - start_time) * 1000)
288
+
289
+ logger.info(
290
+ f"Classification réussie: {len(suggestions)} suggestions, "
291
+ f"top={suggestions[0].category_name if suggestions else 'N/A'}, "
292
+ f"temps={processing_time_ms}ms"
293
+ )
294
+
295
+ return ClassifyDocumentResponse(
296
+ suggestions=suggestions,
297
+ processing_time_ms=processing_time_ms
298
+ )
299
+
300
+ except ValueError as e:
301
+ logger.warning(f"Requête invalide: {e}")
302
+ raise HTTPException(
303
+ status_code=status.HTTP_400_BAD_REQUEST,
304
+ detail=str(e)
305
+ )
306
+
307
+ except DocumentClassificationError as e:
308
+ logger.error(f"Erreur classification: {e}")
309
+ raise HTTPException(
310
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
311
+ detail=f"Erreur de classification: {str(e)}"
312
+ )
313
+
314
+ except Exception as e:
315
+ logger.error(f"Erreur inattendue: {e}", exc_info=True)
316
+ raise HTTPException(
317
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
318
+ detail="Erreur interne du service de classification"
319
+ )
320
+
321
+
322
+ @router.get(
323
+ "/health",
324
+ response_model=HealthResponse,
325
+ status_code=status.HTTP_200_OK,
326
+ summary="Vérifier la santé du service",
327
+ description="Vérifie l'état de santé du service de classification et les modèles chargés."
328
+ )
329
+ async def health_check(
330
+ classifier: DocumentClassifier = Depends(get_document_classifier)
331
+ ) -> HealthResponse:
332
+ """
333
+ Vérifie la santé du service de classification.
334
+
335
+ Args:
336
+ classifier: Instance du classifier (injectée)
337
+
338
+ Returns:
339
+ État du service et des modèles
340
+ """
341
+ try:
342
+ health_status = classifier.health_check()
343
+
344
+ logger.debug(f"Health check: {health_status}")
345
+
346
+ return HealthResponse(**health_status)
347
+
348
+ except Exception as e:
349
+ logger.error(f"Erreur health check: {e}", exc_info=True)
350
+ raise HTTPException(
351
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
352
+ detail="Impossible de vérifier la santé du service"
353
+ )
354
+
355
+
356
+ @router.get(
357
+ "/categories",
358
+ response_model=CategoriesResponse,
359
+ status_code=status.HTTP_200_OK,
360
+ summary="Lister les catégories",
361
+ description="Retourne la liste des 12 catégories juridiques disponibles."
362
+ )
363
+ async def get_categories(
364
+ classifier: DocumentClassifier = Depends(get_document_classifier)
365
+ ) -> CategoriesResponse:
366
+ """
367
+ Retourne toutes les catégories juridiques disponibles.
368
+
369
+ Args:
370
+ classifier: Instance du classifier (injectée)
371
+
372
+ Returns:
373
+ Liste des catégories avec IDs et noms
374
+ """
375
+ try:
376
+ all_categories = classifier.get_all_categories()
377
+
378
+ categories = [
379
+ Category(id=cat_id, name=name)
380
+ for cat_id, name in sorted(all_categories.items())
381
+ ]
382
+
383
+ logger.debug(f"Retour de {len(categories)} catégories")
384
+
385
+ return CategoriesResponse(categories=categories)
386
+
387
+ except Exception as e:
388
+ logger.error(f"Erreur récupération catégories: {e}", exc_info=True)
389
+ raise HTTPException(
390
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
391
+ detail="Impossible de récupérer les catégories"
392
+ )
app/api/routes/language.py ADDED
@@ -0,0 +1,284 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API Routes pour détection de langue.
3
+
4
+ Endpoints:
5
+ - POST /api/v1/language/detect - Détecte langue d'un texte
6
+ - GET /api/v1/language/health - Vérifie santé du service
7
+
8
+ Usage:
9
+ curl -X POST http://localhost:8000/api/v1/language/detect \
10
+ -H "Content-Type: application/json" \
11
+ -d '{"text": "Article 1. La présente loi..."}'
12
+ """
13
+
14
+ from typing import Dict, Any
15
+ import logging
16
+
17
+ from fastapi import APIRouter, Depends, HTTPException, status
18
+ from pydantic import BaseModel, Field, validator
19
+
20
+ from app.core.dependencies import get_language_detector
21
+ from app.services.language_detector import LanguageDetector, LanguageDetectionError
22
+
23
+ logger = logging.getLogger(__name__)
24
+
25
+ # Router configuration
26
+ router = APIRouter(
27
+ prefix="/api/v1/language",
28
+ tags=["language"],
29
+ responses={
30
+ 500: {"description": "Erreur interne du service de détection"}
31
+ }
32
+ )
33
+
34
+
35
+ # ==================== MODELS ====================
36
+
37
+ class DetectLanguageRequest(BaseModel):
38
+ """Requête de détection de langue."""
39
+
40
+ text: str = Field(
41
+ ...,
42
+ min_length=50,
43
+ max_length=50000,
44
+ description="Texte à analyser (50-50000 caractères)",
45
+ example="Article 1. La présente loi régit les conditions de création des sociétés commerciales au Cameroun."
46
+ )
47
+
48
+ min_confidence: float = Field(
49
+ default=0.80,
50
+ ge=0.0,
51
+ le=1.0,
52
+ description="Seuil de confiance minimum (0-1)",
53
+ example=0.80
54
+ )
55
+
56
+ @validator('text')
57
+ def text_not_empty(cls, v):
58
+ """Valide que le texte n'est pas vide."""
59
+ if not v or not v.strip():
60
+ raise ValueError("Le texte ne peut pas être vide")
61
+ return v.strip()
62
+
63
+ class Config:
64
+ schema_extra = {
65
+ "example": {
66
+ "text": "Article 1. La présente loi régit les conditions de création des sociétés commerciales au Cameroun. Les dispositions du Code civil s'appliquent en matière de contrats.",
67
+ "min_confidence": 0.80
68
+ }
69
+ }
70
+
71
+
72
+ class DetectLanguageResponse(BaseModel):
73
+ """Réponse de détection de langue."""
74
+
75
+ language: str = Field(
76
+ ...,
77
+ description="Code langue détectée ('fr' ou 'en')",
78
+ example="fr"
79
+ )
80
+
81
+ confidence: float = Field(
82
+ ...,
83
+ ge=0.0,
84
+ le=1.0,
85
+ description="Score de confiance (0-1)",
86
+ example=0.98
87
+ )
88
+
89
+ method_votes: Dict[str, str] = Field(
90
+ ...,
91
+ description="Votes de chaque méthode de détection",
92
+ example={
93
+ "langdetect": "fr",
94
+ "spacy": "fr",
95
+ "fasttext": "fr"
96
+ }
97
+ )
98
+
99
+ consensus: bool = Field(
100
+ ...,
101
+ description="True si au moins 2/3 méthodes d'accord",
102
+ example=True
103
+ )
104
+
105
+ processing_time_ms: int = Field(
106
+ ...,
107
+ ge=0,
108
+ description="Temps de traitement en millisecondes",
109
+ example=450
110
+ )
111
+
112
+ text_length: int = Field(
113
+ ...,
114
+ ge=0,
115
+ description="Longueur du texte analysé",
116
+ example=156
117
+ )
118
+
119
+ class Config:
120
+ schema_extra = {
121
+ "example": {
122
+ "language": "fr",
123
+ "confidence": 0.98,
124
+ "method_votes": {
125
+ "langdetect": "fr",
126
+ "spacy": "fr",
127
+ "fasttext": "fr"
128
+ },
129
+ "consensus": True,
130
+ "processing_time_ms": 450,
131
+ "text_length": 156
132
+ }
133
+ }
134
+
135
+
136
+ class HealthResponse(BaseModel):
137
+ """Réponse du health check."""
138
+
139
+ service: str = Field(..., example="LanguageDetector")
140
+ status: str = Field(..., example="healthy")
141
+ models: Dict[str, str] = Field(
142
+ ...,
143
+ example={
144
+ "spacy_fr": "✅ OK",
145
+ "spacy_en": "✅ OK",
146
+ "fasttext": "✅ OK"
147
+ }
148
+ )
149
+
150
+
151
+ # ==================== ENDPOINTS ====================
152
+
153
+ @router.post(
154
+ "/detect",
155
+ response_model=DetectLanguageResponse,
156
+ status_code=status.HTTP_200_OK,
157
+ summary="Détecte la langue d'un texte",
158
+ description="""
159
+ Détecte automatiquement la langue (français ou anglais) d'un texte juridique.
160
+
161
+ **Méthode:** Triple ensemble (langdetect + spaCy + fastText) avec vote majoritaire
162
+
163
+ **Performance:** <1 seconde pour textes jusqu'à 5000 caractères
164
+
165
+ **Précision:** >99% sur documents juridiques
166
+ """,
167
+ response_description="Langue détectée avec métadonnées de confiance"
168
+ )
169
+ async def detect_language(
170
+ request: DetectLanguageRequest,
171
+ detector: LanguageDetector = Depends(get_language_detector)
172
+ ) -> DetectLanguageResponse:
173
+ """
174
+ Détecte la langue d'un texte.
175
+
176
+ Args:
177
+ request: Requête contenant le texte à analyser
178
+ detector: Service de détection (injecté)
179
+
180
+ Returns:
181
+ Résultat de détection avec langue, confiance et votes
182
+
183
+ Raises:
184
+ HTTPException 400: Si texte invalide (trop court, vide)
185
+ HTTPException 500: Si erreur interne de détection
186
+ """
187
+ assert request is not None, "DetectLanguageRequest must not be None"
188
+ assert isinstance(request.text, str) and len(request.text) >= 50, "Text must be at least 50 characters"
189
+
190
+ try:
191
+ logger.info(f"📥 Requête détection langue (texte: {len(request.text)} chars)")
192
+
193
+ # Appeler le service de détection
194
+ result = detector.detect(
195
+ text=request.text,
196
+ min_confidence=request.min_confidence
197
+ )
198
+
199
+ logger.info(
200
+ f"✅ Détection réussie: {result['language']} "
201
+ f"({result['confidence']:.2%}, {result['processing_time_ms']}ms)"
202
+ )
203
+
204
+ return DetectLanguageResponse(**result)
205
+
206
+ except ValueError as e:
207
+ # Erreur de validation (texte trop court, etc.)
208
+ logger.warning(f"⚠️ Validation error: {e}")
209
+ raise HTTPException(
210
+ status_code=status.HTTP_400_BAD_REQUEST,
211
+ detail=str(e)
212
+ )
213
+
214
+ except LanguageDetectionError as e:
215
+ # Erreur du service de détection
216
+ logger.error(f"❌ Detection error: {e}")
217
+ raise HTTPException(
218
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
219
+ detail=f"Erreur lors de la détection: {str(e)}"
220
+ )
221
+
222
+ except Exception as e:
223
+ # Erreur inattendue
224
+ logger.exception(f"❌ Unexpected error: {e}")
225
+ raise HTTPException(
226
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
227
+ detail="Erreur interne du serveur"
228
+ )
229
+
230
+
231
+ @router.get(
232
+ "/health",
233
+ response_model=HealthResponse,
234
+ status_code=status.HTTP_200_OK,
235
+ summary="Vérifie la santé du service",
236
+ description="""
237
+ Vérifie que tous les modèles NLP sont chargés et fonctionnels.
238
+
239
+ **Modèles vérifiés:**
240
+ - spaCy français (fr_core_news_sm)
241
+ - spaCy anglais (en_core_web_sm)
242
+ - fastText (lid.176.bin)
243
+ """,
244
+ response_description="État de santé de chaque composant"
245
+ )
246
+ async def health_check(
247
+ detector: LanguageDetector = Depends(get_language_detector)
248
+ ) -> HealthResponse:
249
+ """
250
+ Vérifie l'état de santé du service de détection.
251
+
252
+ Args:
253
+ detector: Service de détection (injecté)
254
+
255
+ Returns:
256
+ État de santé avec status de chaque modèle
257
+
258
+ Raises:
259
+ HTTPException 503: Si un ou plusieurs modèles sont défaillants
260
+ """
261
+ try:
262
+ health_status = detector.health_check()
263
+
264
+ # Si status != "healthy", retourner 503 Service Unavailable
265
+ if health_status["status"] != "healthy":
266
+ logger.warning(f"⚠️ Service degradé: {health_status}")
267
+ raise HTTPException(
268
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
269
+ detail=health_status
270
+ )
271
+
272
+ logger.info("✅ Health check OK")
273
+ return HealthResponse(**health_status)
274
+
275
+ except HTTPException:
276
+ # Re-raise HTTP exceptions
277
+ raise
278
+
279
+ except Exception as e:
280
+ logger.exception(f"❌ Health check error: {e}")
281
+ raise HTTPException(
282
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
283
+ detail=f"Erreur lors du health check: {str(e)}"
284
+ )
app/api/routes/laws.py ADDED
@@ -0,0 +1,810 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API routes for Laws management.
3
+
4
+ Endpoints:
5
+ - GET /api/v1/laws - List laws with filters
6
+ - GET /api/v1/laws/{id} - Get law detail with articles
7
+ - POST /api/v1/admin/laws - Create law (admin only)
8
+ - PUT /api/v1/admin/laws/{id} - Update law (admin only)
9
+ - DELETE /api/v1/admin/laws/{id} - Delete law (admin only)
10
+
11
+ Author: JuriX Development Team
12
+ Date: 2026-01-11
13
+ """
14
+
15
+ import logging
16
+ import time
17
+ from typing import List, Optional
18
+
19
+ from fastapi import APIRouter, Depends, HTTPException, Query, status
20
+ from fastapi.responses import FileResponse
21
+ from pydantic import BaseModel
22
+ from sqlalchemy import select
23
+ from sqlalchemy.ext.asyncio import AsyncSession
24
+ from sqlalchemy.orm import selectinload
25
+
26
+ from app.core.database import get_db
27
+ from app.models.law import Category, Law
28
+ from app.schemas.law import (
29
+ LawCreate,
30
+ LawResponse,
31
+ LawUpdate,
32
+ )
33
+ from app.services.search_service import invalidate_search_cache
34
+ from app.tasks.process_law import delete_from_meilisearch
35
+
36
+
37
+ class LawIngestRequest(BaseModel):
38
+ file_id: str
39
+ title: Optional[str] = None
40
+ original_filename: Optional[str] = None
41
+ reference: Optional[str] = None # Optional custom reference
42
+ category_id: Optional[int] = None # Optional category ID
43
+
44
+
45
+ logger = logging.getLogger(__name__)
46
+
47
+ router = APIRouter(prefix="/api/v1", tags=["Laws"])
48
+
49
+
50
+ # ==================== DEPENDENCIES ====================
51
+
52
+
53
+ # TODO: Implement authentication
54
+ # For now, this is a placeholder
55
+ async def get_current_admin_user():
56
+ """
57
+ Dependency for admin authentication.
58
+
59
+ TODO: Implement actual authentication with JWT tokens.
60
+ For now, returns a mock admin user.
61
+ """
62
+ # In production, verify JWT token and check admin role
63
+ return {"id": 1, "role": "admin"}
64
+
65
+
66
+ # ==================== PUBLIC ENDPOINTS ====================
67
+
68
+
69
+ @router.get("/laws", response_model=List[LawResponse])
70
+ async def get_laws(
71
+ language: Optional[str] = Query(None, description="Filter by language (fr or en)"),
72
+ category_id: Optional[int] = Query(None, description="Filter by category ID"),
73
+ law_status: str = Query(
74
+ "published", description="Filter by status (published, draft, or archived)"
75
+ ),
76
+ skip: int = Query(0, ge=0, description="Number of records to skip"),
77
+ limit: int = Query(100, ge=1, le=10000, description="Maximum number of records to return"),
78
+ db: AsyncSession = Depends(get_db),
79
+ ):
80
+ """
81
+ Get list of laws with optional filters.
82
+
83
+ **Filters:**
84
+ - `language`: Filter by language code (fr or en)
85
+ - `category_id`: Filter by category ID
86
+ - `law_status`: Filter by status (active or archived)
87
+
88
+ **Pagination:**
89
+ - `skip`: Number of records to skip (default: 0)
90
+ - `limit`: Maximum records to return (default: 50, max: 100)
91
+
92
+ **Example:**
93
+ ```
94
+ GET /api/v1/laws?language=fr&category_id=1&skip=0&limit=10
95
+ ```
96
+
97
+ Returns:
98
+ List of laws matching the filters
99
+ """
100
+ logger.info(
101
+ f"📋 GET /laws - language={language}, category_id={category_id}, "
102
+ f"status={law_status}, skip={skip}, limit={limit}"
103
+ )
104
+
105
+ try:
106
+ # Build query
107
+ query = select(Law).options(selectinload(Law.articles), selectinload(Law.category))
108
+
109
+ # Apply filters
110
+ if language:
111
+ query = query.where(Law.language == language)
112
+
113
+ if category_id:
114
+ # Filter by category ID directly
115
+ query = query.where(Law.category_id == category_id)
116
+
117
+ if law_status:
118
+ query = query.where(Law.status == law_status)
119
+
120
+ # Apply pagination
121
+ query = query.offset(skip).limit(limit)
122
+
123
+ # Execute query
124
+ result = await db.execute(query)
125
+ laws = result.scalars().all()
126
+
127
+ logger.info(f"✅ Found {len(laws)} laws")
128
+ return laws
129
+
130
+ except Exception as e:
131
+ logger.error(f"❌ Error fetching laws: {e}", exc_info=True)
132
+ raise HTTPException(
133
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Error fetching laws"
134
+ )
135
+
136
+
137
+ @router.get("/laws/{law_id}", response_model=LawResponse)
138
+ async def get_law(
139
+ law_id: int,
140
+ db: AsyncSession = Depends(get_db),
141
+ ):
142
+ """
143
+ Get law detail by ID with articles.
144
+
145
+ **Includes:**
146
+ - Law metadata
147
+ - All articles (ordered)
148
+ - Categories
149
+ - Auto-detection results (language, category suggestions)
150
+
151
+ Args:
152
+ law_id: Law ID
153
+
154
+ Returns:
155
+ Law detail with articles
156
+
157
+ Raises:
158
+ 404: Law not found
159
+ """
160
+ assert isinstance(law_id, int) and law_id > 0, "law_id must be a positive integer"
161
+
162
+ logger.info(f"📄 GET /laws/{law_id}")
163
+
164
+ try:
165
+ # Query law with relationships
166
+ query = (
167
+ select(Law)
168
+ .options(selectinload(Law.articles), selectinload(Law.category))
169
+ .where(Law.id == law_id)
170
+ )
171
+
172
+ result = await db.execute(query)
173
+ law = result.scalar_one_or_none()
174
+
175
+ if not law:
176
+ logger.warning(f"⚠️ Law {law_id} not found")
177
+ raise HTTPException(
178
+ status_code=status.HTTP_404_NOT_FOUND, detail=f"Law with ID {law_id} not found"
179
+ )
180
+
181
+ logger.info(f"✅ Law {law_id} found: {law.title}")
182
+ return law
183
+
184
+ except HTTPException:
185
+ raise
186
+ except Exception as e:
187
+ logger.error(f"❌ Error fetching law {law_id}: {e}", exc_info=True)
188
+ raise HTTPException(
189
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Error fetching law"
190
+ )
191
+
192
+
193
+ @router.get("/laws/{law_id}/download")
194
+ async def download_law_file(
195
+ law_id: int,
196
+ db: AsyncSession = Depends(get_db),
197
+ ):
198
+ """Download the original uploaded file for a law."""
199
+ query = select(Law).where(Law.id == law_id)
200
+ result = await db.execute(query)
201
+ law = result.scalar_one_or_none()
202
+
203
+ if not law:
204
+ raise HTTPException(status_code=404, detail="Law not found")
205
+
206
+ if not law.file_id:
207
+ raise HTTPException(status_code=404, detail="No source file found for this law")
208
+
209
+ from app.services.file_upload_service import get_upload_service
210
+ upload_service = get_upload_service()
211
+
212
+ # Try to find file with extension
213
+ file_path = None
214
+ # Use stored filename or construct one
215
+ filename = law.original_filename or f"{law.reference}.pdf"
216
+
217
+ # Check for PDF or DOCX using file_id
218
+ for ext in [".pdf", ".docx"]:
219
+ p = upload_service.storage_path / f"{law.file_id}{ext}"
220
+ if p.exists():
221
+ file_path = p
222
+ break
223
+
224
+ if not file_path:
225
+ # Fallback: maybe file_id IS the filename (legacy behavior?)
226
+ # Or maybe stored without extension?
227
+ p = upload_service.storage_path / law.file_id
228
+ if p.exists():
229
+ file_path = p
230
+ else:
231
+ raise HTTPException(status_code=404, detail="File not found on server")
232
+
233
+ return FileResponse(
234
+ path=file_path,
235
+ filename=law.original_filename or file_path.name,
236
+ media_type="application/pdf" if file_path.suffix == ".pdf" else "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
237
+ content_disposition_type="inline"
238
+ )
239
+
240
+
241
+ @router.get("/laws/{law_id}/pdf-data")
242
+ async def get_law_pdf_data(
243
+ law_id: int,
244
+ db: AsyncSession = Depends(get_db),
245
+ ):
246
+ """
247
+ Return PDF as Base64-encoded JSON to bypass download manager interception.
248
+ This allows JavaScript to fetch the PDF without IDM/browser extensions intercepting the request.
249
+ """
250
+ import base64
251
+
252
+ query = select(Law).where(Law.id == law_id)
253
+ result = await db.execute(query)
254
+ law = result.scalar_one_or_none()
255
+
256
+ if not law:
257
+ raise HTTPException(status_code=404, detail="Law not found")
258
+
259
+ if not law.file_id:
260
+ raise HTTPException(status_code=404, detail="No source file found for this law")
261
+
262
+ from app.services.file_upload_service import get_upload_service
263
+ upload_service = get_upload_service()
264
+
265
+ # Find the file
266
+ file_path = None
267
+ for ext in [".pdf", ".docx"]:
268
+ p = upload_service.storage_path / f"{law.file_id}{ext}"
269
+ if p.exists():
270
+ file_path = p
271
+ break
272
+
273
+ if not file_path:
274
+ p = upload_service.storage_path / law.file_id
275
+ if p.exists():
276
+ file_path = p
277
+ else:
278
+ raise HTTPException(status_code=404, detail="File not found on server")
279
+
280
+ # Read file and encode to Base64
281
+ with open(file_path, "rb") as f:
282
+ file_bytes = f.read()
283
+
284
+ base64_data = base64.b64encode(file_bytes).decode("utf-8")
285
+
286
+ return {
287
+ "filename": law.original_filename or file_path.name,
288
+ "content_type": "application/pdf" if file_path.suffix == ".pdf" else "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
289
+ "data": base64_data
290
+ }
291
+
292
+
293
+ @router.post("/laws/{law_id}/pdf-stream")
294
+ async def get_law_pdf_stream(
295
+ law_id: int,
296
+ db: AsyncSession = Depends(get_db),
297
+ ):
298
+ """
299
+ Stream PDF as binary data for efficient loading of large files.
300
+
301
+ Uses POST method to bypass download managers (IDM) which typically
302
+ only intercept GET requests. Returns PDF as binary with special headers.
303
+
304
+ This is more efficient than base64 encoding for large files
305
+ (saves ~33% bandwidth and avoids JavaScript decode overhead).
306
+ """
307
+ from fastapi.responses import Response
308
+
309
+ query = select(Law).where(Law.id == law_id)
310
+ result = await db.execute(query)
311
+ law = result.scalar_one_or_none()
312
+
313
+ if not law:
314
+ raise HTTPException(status_code=404, detail="Law not found")
315
+
316
+ if not law.file_id:
317
+ raise HTTPException(status_code=404, detail="No source file found for this law")
318
+
319
+ from app.services.file_upload_service import get_upload_service
320
+ upload_service = get_upload_service()
321
+
322
+ # Find the file
323
+ file_path = None
324
+ for ext in [".pdf", ".docx"]:
325
+ p = upload_service.storage_path / f"{law.file_id}{ext}"
326
+ if p.exists():
327
+ file_path = p
328
+ break
329
+
330
+ if not file_path:
331
+ p = upload_service.storage_path / law.file_id
332
+ if p.exists():
333
+ file_path = p
334
+ else:
335
+ raise HTTPException(status_code=404, detail="File not found on server")
336
+
337
+ # Read file content
338
+ with open(file_path, "rb") as f:
339
+ file_bytes = f.read()
340
+
341
+ # Return as binary stream with headers that prevent IDM interception
342
+ # Using POST method + octet-stream prevents IDM from intercepting
343
+ return Response(
344
+ content=file_bytes,
345
+ media_type="application/octet-stream", # Not application/pdf - hides from IDM
346
+ headers={
347
+ "Content-Disposition": "inline",
348
+ "X-Content-Type-Options": "nosniff",
349
+ "X-PDF-Content": "true", # Custom header to identify as PDF
350
+ "Cache-Control": "private, max-age=3600",
351
+ }
352
+ )
353
+
354
+
355
+ @router.get("/laws/{law_id}/pdf-info")
356
+ async def get_law_pdf_info(
357
+ law_id: int,
358
+ db: AsyncSession = Depends(get_db),
359
+ ):
360
+ """
361
+ Get PDF information including page count.
362
+ Used by the frontend to know how many pages to request.
363
+ """
364
+ from pypdf import PdfReader
365
+
366
+ query = select(Law).where(Law.id == law_id)
367
+ result = await db.execute(query)
368
+ law = result.scalar_one_or_none()
369
+
370
+ if not law:
371
+ raise HTTPException(status_code=404, detail="Law not found")
372
+
373
+ if not law.file_id:
374
+ raise HTTPException(status_code=404, detail="No source file found for this law")
375
+
376
+ from app.services.file_upload_service import get_upload_service
377
+ upload_service = get_upload_service()
378
+
379
+ # Find the file
380
+ file_path = None
381
+ for ext in [".pdf", ".docx"]:
382
+ p = upload_service.storage_path / f"{law.file_id}{ext}"
383
+ if p.exists():
384
+ file_path = p
385
+ break
386
+
387
+ if not file_path:
388
+ p = upload_service.storage_path / law.file_id
389
+ if p.exists():
390
+ file_path = p
391
+ else:
392
+ raise HTTPException(status_code=404, detail="File not found on server")
393
+
394
+ # Get page count
395
+ try:
396
+ reader = PdfReader(str(file_path))
397
+ page_count = len(reader.pages)
398
+ except Exception as e:
399
+ raise HTTPException(status_code=500, detail=f"Error reading PDF: {str(e)}")
400
+
401
+ return {
402
+ "law_id": law_id,
403
+ "filename": law.original_filename or file_path.name,
404
+ "page_count": page_count
405
+ }
406
+
407
+
408
+ @router.get("/laws/{law_id}/page/{page_num}")
409
+ async def get_law_pdf_page_image(
410
+ law_id: int,
411
+ page_num: int,
412
+ dpi: int = Query(default=120, ge=72, le=200, description="DPI for rendering (72-200)"),
413
+ db: AsyncSession = Depends(get_db),
414
+ ):
415
+ """
416
+ Render a specific PDF page as a JPEG image.
417
+
418
+ Uses Poppler (pdf2image) for reliable rendering of all image formats
419
+ including JPEG2000 which pdf.js cannot handle.
420
+
421
+ Args:
422
+ law_id: ID of the law
423
+ page_num: Page number (1-indexed)
424
+ dpi: Resolution for rendering (default 120, max 200 for performance)
425
+
426
+ Returns:
427
+ JPEG image of the specified page
428
+ """
429
+ from io import BytesIO
430
+ from fastapi.responses import Response
431
+
432
+ query = select(Law).where(Law.id == law_id)
433
+ result = await db.execute(query)
434
+ law = result.scalar_one_or_none()
435
+
436
+ if not law:
437
+ raise HTTPException(status_code=404, detail="Law not found")
438
+
439
+ if not law.file_id:
440
+ raise HTTPException(status_code=404, detail="No source file found for this law")
441
+
442
+ from app.services.file_upload_service import get_upload_service
443
+ upload_service = get_upload_service()
444
+
445
+ # Find the file
446
+ file_path = None
447
+ for ext in [".pdf", ".docx"]:
448
+ p = upload_service.storage_path / f"{law.file_id}{ext}"
449
+ if p.exists():
450
+ file_path = p
451
+ break
452
+
453
+ if not file_path:
454
+ p = upload_service.storage_path / law.file_id
455
+ if p.exists():
456
+ file_path = p
457
+ else:
458
+ raise HTTPException(status_code=404, detail="File not found on server")
459
+
460
+ # Convert page to image using Poppler
461
+ try:
462
+ from pdf2image import convert_from_path
463
+
464
+ # Convert only the specific page (1-indexed)
465
+ images = convert_from_path(
466
+ str(file_path),
467
+ first_page=page_num,
468
+ last_page=page_num,
469
+ dpi=dpi,
470
+ fmt="jpeg",
471
+ )
472
+
473
+ if not images:
474
+ raise HTTPException(status_code=404, detail=f"Page {page_num} not found")
475
+
476
+ # Convert to JPEG bytes
477
+ img_buffer = BytesIO()
478
+ images[0].save(img_buffer, format="JPEG", quality=85)
479
+ img_bytes = img_buffer.getvalue()
480
+
481
+ return Response(
482
+ content=img_bytes,
483
+ media_type="image/jpeg",
484
+ headers={
485
+ "Cache-Control": "public, max-age=86400", # Cache for 24 hours
486
+ "X-Page-Number": str(page_num),
487
+ }
488
+ )
489
+
490
+ except Exception as e:
491
+ logger.error(f"Error rendering page {page_num} for law {law_id}: {e}")
492
+ raise HTTPException(status_code=500, detail=f"Error rendering page: {str(e)}")
493
+
494
+
495
+ # ==================== INGESTION ENDPOINTS ====================
496
+
497
+
498
+ @router.post("/admin/laws/ingest", response_model=LawResponse, status_code=status.HTTP_202_ACCEPTED)
499
+ async def ingest_law(
500
+ request: LawIngestRequest,
501
+ db: AsyncSession = Depends(get_db),
502
+ current_user: dict = Depends(get_current_admin_user),
503
+ ):
504
+ """
505
+ Ingest a new law from an uploaded file.
506
+
507
+ 1. Creates a Law record (status=processing)
508
+ 2. Triggers Celery task to process the file
509
+
510
+ Args:
511
+ request: Ingest request (file_id, title)
512
+
513
+ Returns:
514
+ Created Law object (pending)
515
+ """
516
+ assert request is not None, "LawIngestRequest must not be None"
517
+ assert isinstance(request.file_id, str) and len(request.file_id) > 0, "file_id must be a non-empty string"
518
+
519
+ logger.info(f"📥 POST /admin/laws/ingest - File: {request.file_id}")
520
+
521
+ try:
522
+ # Validate file_id
523
+ if not request.file_id or len(request.file_id) < 8:
524
+ raise HTTPException(
525
+ status_code=status.HTTP_400_BAD_REQUEST,
526
+ detail="Invalid file_id: must be at least 8 characters",
527
+ )
528
+
529
+ # Check if law with this file_id already exists (idempotency)
530
+ ref_prefix = f"PENDING-{request.file_id[:8]}"
531
+
532
+ # Check for existing pending law to avoid duplicates
533
+ query = select(Law).where(Law.reference == ref_prefix)
534
+ result = await db.execute(query)
535
+ existing_law = result.scalar_one_or_none()
536
+
537
+ if existing_law and existing_law.status == "processing":
538
+ logger.info(f"ℹ️ Law already exists for file {request.file_id}: ID={existing_law.id}")
539
+ return existing_law
540
+
541
+ # If existing law failed, create a new one with timestamp
542
+ if existing_law:
543
+ ref_prefix = f"{ref_prefix}-{int(time.time())}"
544
+
545
+ # Use custom reference if provided, otherwise use PENDING prefix
546
+ law_reference = request.reference if request.reference else ref_prefix
547
+
548
+ # Check if reference already exists (collision check)
549
+ existing_ref_query = select(Law).where(Law.reference == law_reference)
550
+ existing_ref_result = await db.execute(existing_ref_query)
551
+ existing_ref_law = existing_ref_result.scalar_one_or_none()
552
+
553
+ if existing_ref_law:
554
+ logger.info(f"ℹ️ Law with reference '{law_reference}' already exists: ID={existing_ref_law.id}. Returning existing law.")
555
+
556
+ # If it was stuck or previous attempt failed, we might want to trigger processing again
557
+ # For now, just return it so the frontend sees it's there
558
+ if existing_ref_law.status == "processing" or existing_ref_law.content == "Document en cours de traitement par le système.":
559
+ # Potentially restart failed processing here if needed
560
+ pass
561
+
562
+ return existing_ref_law
563
+
564
+ # Create initial Law record
565
+ new_law = Law(
566
+ reference=law_reference,
567
+ title=request.title or "Document en cours de traitement",
568
+ type="autre", # Changed from "unknown" to valid type
569
+ content="Document en cours de traitement par le système.", # Min 10 chars required
570
+ status="published", # Published so it appears in public list
571
+ category_id=request.category_id, # Category selected by admin
572
+ file_id=request.file_id,
573
+ original_filename=request.original_filename,
574
+ )
575
+
576
+ db.add(new_law)
577
+ await db.commit()
578
+ await db.refresh(new_law)
579
+
580
+ # Process document synchronously (Windows-compatible)
581
+ # Celery on Windows has billiard issues, so we use direct synchronous processing
582
+ logger.info(f"🔄 Processing document synchronously for Law ID={new_law.id}")
583
+
584
+ try:
585
+ import asyncio
586
+
587
+ from app.tasks.process_law import process_law_sync
588
+
589
+ # Run sync version in background thread to avoid blocking
590
+ result = await asyncio.to_thread(process_law_sync, new_law.id, request.file_id)
591
+ logger.info(f"✅ Synchronous processing completed: {result}")
592
+
593
+ # Invalidate search cache to include new law in results
594
+ invalidate_search_cache()
595
+ except Exception as sync_error:
596
+ logger.error(f"❌ Synchronous processing failed: {sync_error}", exc_info=True)
597
+ logger.info(f"ℹ️ Law ID={new_law.id} created but processing failed")
598
+
599
+ return new_law
600
+
601
+ except HTTPException:
602
+ # Re-raise HTTPException as-is
603
+ raise
604
+ except Exception as e:
605
+ await db.rollback()
606
+ error_msg = f"Error starting ingestion: {type(e).__name__}: {str(e)}"
607
+ logger.error(f"❌ {error_msg}", exc_info=True)
608
+ raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=error_msg)
609
+
610
+
611
+ # ==================== ADMIN ENDPOINTS ====================
612
+
613
+
614
+ @router.post("/admin/laws", response_model=LawResponse, status_code=status.HTTP_201_CREATED)
615
+ async def create_law(
616
+ law: LawCreate,
617
+ db: AsyncSession = Depends(get_db),
618
+ current_user: dict = Depends(get_current_admin_user),
619
+ ):
620
+ """
621
+ Create a new law (admin only).
622
+
623
+ **Auto-Detection (v2.1):**
624
+ - If `language` not provided, auto-detected from content
625
+ - Category suggestions provided based on content
626
+
627
+ **Required Fields:**
628
+ - reference: Unique law reference
629
+ - title: Law title
630
+ - type: Law type (loi, décret, ordonnance, etc.)
631
+ - content: Full text content
632
+
633
+ Args:
634
+ law: Law creation data
635
+
636
+ Returns:
637
+ Created law with auto-detection results
638
+
639
+ Raises:
640
+ 400: Validation error
641
+ 401: Unauthorized
642
+ 409: Law reference already exists
643
+ """
644
+ assert law is not None, "LawCreate must not be None"
645
+ assert isinstance(law.reference, str) and len(law.reference) > 0, "Law reference must be a non-empty string"
646
+
647
+ logger.info(f"➕ POST /admin/laws - Creating law: {law.title}")
648
+
649
+ try:
650
+ # Check if reference already exists
651
+ existing_query = select(Law).where(Law.reference == law.reference)
652
+ existing_result = await db.execute(existing_query)
653
+ existing_law = existing_result.scalar_one_or_none()
654
+
655
+ if existing_law:
656
+ logger.warning(f"⚠️ Law reference {law.reference} already exists")
657
+ raise HTTPException(
658
+ status_code=status.HTTP_409_CONFLICT,
659
+ detail=f"Law with reference '{law.reference}' already exists",
660
+ )
661
+
662
+ # Create law instance
663
+ new_law = Law(**law.model_dump())
664
+
665
+ # TODO: Integrate auto-detection services
666
+ # if not new_law.language:
667
+ # language_service = LanguageDetector()
668
+ # detection = language_service.detect(new_law.content)
669
+ # new_law.detected_language = detection["language"]
670
+ # new_law.language_confidence = detection["confidence"]
671
+
672
+ # Add to database
673
+ db.add(new_law)
674
+ await db.commit()
675
+ await db.refresh(new_law)
676
+
677
+ logger.info(f"✅ Law created: ID={new_law.id}, reference={new_law.reference}")
678
+ return new_law
679
+
680
+ except HTTPException:
681
+ raise
682
+ except Exception as e:
683
+ await db.rollback()
684
+ logger.error(f"❌ Error creating law: {e}", exc_info=True)
685
+ raise HTTPException(
686
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Error creating law"
687
+ )
688
+
689
+
690
+ @router.put("/admin/laws/{law_id}", response_model=LawResponse)
691
+ async def update_law(
692
+ law_id: int,
693
+ law_update: LawUpdate,
694
+ db: AsyncSession = Depends(get_db),
695
+ current_user: dict = Depends(get_current_admin_user),
696
+ ):
697
+ """
698
+ Update an existing law (admin only).
699
+
700
+ **Partial Updates:**
701
+ - Only provided fields are updated
702
+ - Omitted fields remain unchanged
703
+
704
+ Args:
705
+ law_id: Law ID to update
706
+ law_update: Fields to update
707
+
708
+ Returns:
709
+ Updated law
710
+
711
+ Raises:
712
+ 404: Law not found
713
+ 401: Unauthorized
714
+ """
715
+ assert isinstance(law_id, int) and law_id > 0, "law_id must be a positive integer"
716
+ assert law_update is not None, "LawUpdate must not be None"
717
+
718
+ logger.info(f"✏️ PUT /admin/laws/{law_id}")
719
+
720
+ try:
721
+ # Fetch existing law
722
+ query = select(Law).where(Law.id == law_id)
723
+ result = await db.execute(query)
724
+ existing_law = result.scalar_one_or_none()
725
+
726
+ if not existing_law:
727
+ logger.warning(f"⚠️ Law {law_id} not found")
728
+ raise HTTPException(
729
+ status_code=status.HTTP_404_NOT_FOUND, detail=f"Law with ID {law_id} not found"
730
+ )
731
+
732
+ # Update fields
733
+ update_data = law_update.model_dump(exclude_unset=True)
734
+ for field, value in update_data.items():
735
+ setattr(existing_law, field, value)
736
+
737
+ await db.commit()
738
+ await db.refresh(existing_law)
739
+
740
+ logger.info(f"✅ Law {law_id} updated")
741
+ return existing_law
742
+
743
+ except HTTPException:
744
+ raise
745
+ except Exception as e:
746
+ await db.rollback()
747
+ logger.error(f"❌ Error updating law {law_id}: {e}", exc_info=True)
748
+ raise HTTPException(
749
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Error updating law"
750
+ )
751
+
752
+
753
+ @router.delete("/admin/laws/{law_id}", status_code=status.HTTP_204_NO_CONTENT)
754
+ async def delete_law(
755
+ law_id: int,
756
+ db: AsyncSession = Depends(get_db),
757
+ current_user: dict = Depends(get_current_admin_user),
758
+ ):
759
+ """
760
+ Delete a law (admin only).
761
+
762
+ **Cascade Delete:**
763
+ - Deletes law and all associated articles
764
+ - Removes from search index
765
+
766
+ Args:
767
+ law_id: Law ID to delete
768
+
769
+ Returns:
770
+ 204 No Content on success
771
+
772
+ Raises:
773
+ 404: Law not found
774
+ 401: Unauthorized
775
+ """
776
+ logger.info(f"🗑️ DELETE /admin/laws/{law_id}")
777
+
778
+ try:
779
+ # Fetch law
780
+ query = select(Law).where(Law.id == law_id)
781
+ result = await db.execute(query)
782
+ law = result.scalar_one_or_none()
783
+
784
+ if not law:
785
+ logger.warning(f"⚠️ Law {law_id} not found")
786
+ raise HTTPException(
787
+ status_code=status.HTTP_404_NOT_FOUND, detail=f"Law with ID {law_id} not found"
788
+ )
789
+
790
+ # Delete law (cascade deletes articles)
791
+ await db.delete(law)
792
+ await db.commit()
793
+
794
+ # Remove from Meilisearch index
795
+ delete_from_meilisearch(law_id)
796
+
797
+ # Invalidate search cache to prevent stale results
798
+ invalidate_search_cache()
799
+
800
+ logger.info(f"✅ Law {law_id} deleted")
801
+ return None
802
+
803
+ except HTTPException:
804
+ raise
805
+ except Exception as e:
806
+ await db.rollback()
807
+ logger.error(f"❌ Error deleting law {law_id}: {e}", exc_info=True)
808
+ raise HTTPException(
809
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Error deleting law"
810
+ )
app/api/routes/ocr.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API endpoints for OCR operations.
3
+
4
+ Provides REST endpoints for:
5
+ - PDF type detection (POST /api/v1/ocr/detect)
6
+ - OCR processing (POST /api/v1/ocr/process)
7
+ - Health check (GET /api/v1/ocr/health)
8
+
9
+ Author: JuriX Development Team
10
+ Date: 2026-01-11
11
+ """
12
+
13
+ import logging
14
+ from pathlib import Path
15
+
16
+ from fastapi import APIRouter, HTTPException, status
17
+ from fastapi.responses import JSONResponse
18
+
19
+ from app.schemas.ocr import (
20
+ OCRRequest,
21
+ OCRResult,
22
+ OCRServiceHealth,
23
+ PDFTypeDetectionRequest,
24
+ PDFTypeDetectionResult,
25
+ )
26
+ from app.services.ocr_service import OCRError, OCRService
27
+
28
+ logger = logging.getLogger(__name__)
29
+
30
+ # Create router
31
+ router = APIRouter(prefix="/api/v1/ocr", tags=["OCR"])
32
+
33
+ # Initialize service (singleton pattern)
34
+ _ocr_service: OCRService = None
35
+
36
+
37
+ def get_ocr_service() -> OCRService:
38
+ """
39
+ Get or create OCRService instance.
40
+
41
+ Returns:
42
+ OCRService instance
43
+ """
44
+ global _ocr_service
45
+ if _ocr_service is None:
46
+ _ocr_service = OCRService(
47
+ default_language="fra+eng",
48
+ default_dpi=300,
49
+ )
50
+ return _ocr_service
51
+
52
+
53
+ @router.post(
54
+ "/detect",
55
+ response_model=PDFTypeDetectionResult,
56
+ summary="Detect PDF type",
57
+ description="""
58
+ Detect if a PDF is native (text-based), scanned (image-based), or hybrid.
59
+
60
+ **Quick check** to determine if OCR processing is needed.
61
+
62
+ **Returns:**
63
+ - PDF type classification
64
+ - Text coverage percentage
65
+ - OCR recommendation
66
+ """,
67
+ )
68
+ async def detect_pdf_type(request: PDFTypeDetectionRequest) -> PDFTypeDetectionResult:
69
+ """
70
+ Detect PDF type without processing.
71
+
72
+ Args:
73
+ request: Detection request with PDF path
74
+
75
+ Returns:
76
+ PDFTypeDetectionResult with classification
77
+
78
+ Raises:
79
+ 400: Invalid PDF path
80
+ 404: PDF file not found
81
+ 500: Detection error
82
+ """
83
+ assert request is not None, "PDFTypeDetectionRequest must not be None"
84
+ assert isinstance(request.pdf_path, str) and len(request.pdf_path) > 0, "pdf_path must be a non-empty string"
85
+
86
+ logger.info(f"🔍 PDF type detection request: {request.pdf_path}")
87
+
88
+ pdf_path = Path(request.pdf_path)
89
+
90
+ # Validate path
91
+ if not pdf_path.exists():
92
+ raise HTTPException(
93
+ status_code=status.HTTP_404_NOT_FOUND,
94
+ detail=f"PDF file not found: {request.pdf_path}",
95
+ )
96
+
97
+ try:
98
+ service = get_ocr_service()
99
+ result = await service.detect_pdf_type(pdf_path)
100
+
101
+ logger.info(f"✅ Detection complete: {result.pdf_type.value}")
102
+ return result
103
+
104
+ except Exception as e:
105
+ logger.error(f"❌ Detection error: {e}", exc_info=True)
106
+ raise HTTPException(
107
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
108
+ detail=f"PDF type detection failed: {str(e)}",
109
+ )
110
+
111
+
112
+ @router.post(
113
+ "/process",
114
+ response_model=OCRResult,
115
+ summary="Process PDF with OCR",
116
+ description="""
117
+ Process a PDF document with OCR if needed.
118
+
119
+ **Workflow:**
120
+ 1. Auto-detect PDF type
121
+ 2. Extract text (native or OCR)
122
+ 3. Clean and post-process text
123
+
124
+ **Performance:** 5-30s depending on scan quality and page count.
125
+
126
+ **Languages:** French (fra), English (eng), or both (fra+eng)
127
+ """,
128
+ )
129
+ async def process_pdf(request: OCRRequest) -> OCRResult:
130
+ """
131
+ Process PDF with OCR.
132
+
133
+ Args:
134
+ request: OCR request with PDF path and options
135
+
136
+ Returns:
137
+ OCRResult with extracted text
138
+
139
+ Raises:
140
+ 400: Invalid request
141
+ 404: PDF file not found
142
+ 500: Processing error
143
+ """
144
+ assert request is not None, "OCRRequest must not be None"
145
+ assert isinstance(request.pdf_path, str) and len(request.pdf_path) > 0, "pdf_path must be a non-empty string"
146
+
147
+ logger.info(
148
+ f"📄 OCR processing request: {request.pdf_path} "
149
+ f"(lang: {request.language}, dpi: {request.dpi})"
150
+ )
151
+
152
+ pdf_path = Path(request.pdf_path)
153
+
154
+ # Validate path
155
+ if not pdf_path.exists():
156
+ raise HTTPException(
157
+ status_code=status.HTTP_404_NOT_FOUND,
158
+ detail=f"PDF file not found: {request.pdf_path}",
159
+ )
160
+
161
+ try:
162
+ service = get_ocr_service()
163
+ result = await service.process_pdf(
164
+ pdf_path=pdf_path,
165
+ language=request.language,
166
+ dpi=request.dpi,
167
+ timeout_seconds=request.timeout_seconds,
168
+ )
169
+
170
+ logger.info(
171
+ f"✅ OCR complete: {result.text_length} chars "
172
+ f"({result.processing_time_ms}ms)"
173
+ )
174
+ return result
175
+
176
+ except OCRError as e:
177
+ logger.warning(f"⚠️ OCR error: {e}")
178
+ raise HTTPException(
179
+ status_code=status.HTTP_400_BAD_REQUEST,
180
+ detail=str(e),
181
+ )
182
+ except Exception as e:
183
+ logger.error(f"❌ Processing error: {e}", exc_info=True)
184
+ raise HTTPException(
185
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
186
+ detail=f"OCR processing failed: {str(e)}",
187
+ )
188
+
189
+
190
+ @router.get(
191
+ "/health",
192
+ response_model=OCRServiceHealth,
193
+ summary="Service health check",
194
+ description="Check the health status of the OCR service including Tesseract availability.",
195
+ )
196
+ async def health_check() -> OCRServiceHealth:
197
+ """
198
+ Check service health.
199
+
200
+ Returns:
201
+ Health status including Tesseract and Poppler availability
202
+ """
203
+ service = get_ocr_service()
204
+ health = service.health_check()
205
+
206
+ return OCRServiceHealth(**health)
app/api/routes/personas.py ADDED
@@ -0,0 +1,708 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API Routes for Persona Management and Analytics (Service 9).
3
+
4
+ Endpoints:
5
+ - GET /api/v1/personas - List all personas
6
+ - GET /api/v1/personas/{persona} - Get persona info
7
+ - GET /api/v1/personas/health - Health check
8
+ - GET /api/v1/personas/{persona}/stats - Get stats for persona
9
+ - GET /api/v1/personas/stats/all - Get stats for all personas
10
+ - GET /api/v1/personas/stats/usage - Get usage breakdown
11
+ - GET /api/v1/personas/{persona}/engagement - Get engagement metrics
12
+ - GET /api/v1/personas/{persona}/questions - Get popular questions
13
+ - GET /api/v1/personas/compare/{metric} - Compare personas
14
+ - GET /api/v1/personas/{persona}/trends/{metric} - Get trend data
15
+ - POST /api/v1/personas/feedback - Add message feedback
16
+ - GET /api/v1/personas/feedback/{message_id} - Get feedback
17
+ - GET /api/v1/personas/feedback/stats - Get feedback statistics
18
+
19
+ Author: JuriX Team
20
+ Version: 2.1.0
21
+ """
22
+
23
+ import logging
24
+ from typing import List, Dict, Optional, Any
25
+ from datetime import date
26
+ from fastapi import APIRouter, Depends, HTTPException, status, Query, Path
27
+ from sqlalchemy.ext.asyncio import AsyncSession
28
+
29
+ from app.core.database import get_db
30
+ from app.services.persona_service import (
31
+ PersonaService,
32
+ InvalidPersonaError,
33
+ MessageNotFoundError,
34
+ FeedbackAlreadyExistsError,
35
+ PersonaServiceError
36
+ )
37
+ from app.schemas.persona import (
38
+ PersonaInfo,
39
+ PersonaStatsResponse,
40
+ MessageFeedbackCreate,
41
+ MessageFeedbackResponse,
42
+ FeedbackStats,
43
+ EngagementMetricsResponse,
44
+ PopularQuestionsResponse,
45
+ PopularQuestion,
46
+ PersonaComparisonResponse,
47
+ TrendsResponse,
48
+ TrendPoint,
49
+ UsageBreakdownResponse,
50
+ HealthCheckResponse,
51
+ ErrorResponse
52
+ )
53
+
54
+ # Configure logger
55
+ logger = logging.getLogger(__name__)
56
+
57
+ # Create router
58
+ router = APIRouter(
59
+ prefix="/api/v1/personas",
60
+ tags=["personas"],
61
+ responses={
62
+ 400: {"description": "Bad Request - Invalid persona or validation error"},
63
+ 404: {"description": "Not Found - Message or resource doesn't exist"},
64
+ 409: {"description": "Conflict - Feedback already exists"},
65
+ 500: {"description": "Internal Server Error"}
66
+ }
67
+ )
68
+
69
+
70
+ # ============================================================================
71
+ # PERSONA INFORMATION ENDPOINTS
72
+ # ============================================================================
73
+
74
+ @router.get(
75
+ "",
76
+ response_model=List[PersonaInfo],
77
+ summary="List all available personas",
78
+ description="Get information about all 4 supported personas with metadata"
79
+ )
80
+ async def list_personas(
81
+ db: AsyncSession = Depends(get_db)
82
+ ) -> List[PersonaInfo]:
83
+ """
84
+ List all available personas.
85
+
86
+ Returns metadata for all 4 personas:
87
+ - citoyen: Simplified responses for citizens
88
+ - avocat: Technical legal analysis for lawyers
89
+ - entrepreneur: Business-focused compliance advice
90
+ - étudiant: Pedagogical explanations for students
91
+
92
+ **Returns:**
93
+ - List of persona info with name, display name, description, icon, tone, example questions
94
+ """
95
+ try:
96
+ service = PersonaService(db)
97
+ personas = await service.list_personas()
98
+ logger.info(f"📋 Listed {len(personas)} personas")
99
+ return personas
100
+ except Exception as e:
101
+ logger.error(f"❌ Error listing personas: {e}")
102
+ raise HTTPException(
103
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
104
+ detail={"error": "InternalServerError", "message": str(e)}
105
+ )
106
+
107
+
108
+ @router.get(
109
+ "/{persona}",
110
+ response_model=PersonaInfo,
111
+ summary="Get info for specific persona",
112
+ responses={
113
+ 404: {"model": ErrorResponse, "description": "Persona not found"}
114
+ }
115
+ )
116
+ async def get_persona_info(
117
+ persona: str = Path(..., description="Persona name (citoyen|avocat|entrepreneur|étudiant)"),
118
+ db: AsyncSession = Depends(get_db)
119
+ ) -> PersonaInfo:
120
+ """
121
+ Get information about a specific persona.
122
+
123
+ **Parameters:**
124
+ - **persona**: Persona name (citoyen, avocat, entrepreneur, étudiant)
125
+
126
+ **Returns:**
127
+ - Persona metadata including description, tone, and example questions
128
+
129
+ **Raises:**
130
+ - 400: Invalid persona name
131
+ """
132
+ assert isinstance(persona, str) and len(persona) > 0, "Persona must be a non-empty string"
133
+
134
+ try:
135
+ service = PersonaService(db)
136
+ info = await service.get_persona_info(persona)
137
+ logger.info(f"📋 Retrieved info for persona: {persona}")
138
+ return info
139
+ except InvalidPersonaError as e:
140
+ logger.warning(f"❌ Invalid persona: {persona}")
141
+ raise HTTPException(
142
+ status_code=status.HTTP_400_BAD_REQUEST,
143
+ detail={
144
+ "error": "InvalidPersonaError",
145
+ "message": str(e),
146
+ "details": {"provided": persona, "valid": PersonaService.VALID_PERSONAS}
147
+ }
148
+ )
149
+ except Exception as e:
150
+ logger.error(f"❌ Error getting persona info: {e}")
151
+ raise HTTPException(
152
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
153
+ detail={"error": "InternalServerError", "message": str(e)}
154
+ )
155
+
156
+
157
+ @router.get(
158
+ "/health",
159
+ response_model=HealthCheckResponse,
160
+ summary="Service health check"
161
+ )
162
+ def health_check(
163
+ db: AsyncSession = Depends(get_db)
164
+ ) -> HealthCheckResponse:
165
+ """
166
+ Check PersonaService health status.
167
+
168
+ **Returns:**
169
+ - Service status, persona count, and timestamp
170
+ """
171
+ try:
172
+ service = PersonaService(db)
173
+ health = service.health_check()
174
+ return health
175
+ except Exception as e:
176
+ logger.error(f"❌ Health check failed: {e}")
177
+ raise HTTPException(
178
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
179
+ detail={"error": "InternalServerError", "message": str(e)}
180
+ )
181
+
182
+
183
+ # ============================================================================
184
+ # ANALYTICS - STATISTICS ENDPOINTS
185
+ # ============================================================================
186
+
187
+ @router.get(
188
+ "/{persona}/stats",
189
+ response_model=PersonaStatsResponse,
190
+ summary="Get statistics for a persona",
191
+ description="Retrieve usage, performance, engagement, and quality metrics for a specific persona"
192
+ )
193
+ async def get_persona_stats(
194
+ persona: str = Path(..., description="Persona name"),
195
+ start_date: Optional[str] = Query(None, description="Start date (YYYY-MM-DD), defaults to 30 days ago"),
196
+ end_date: Optional[str] = Query(None, description="End date (YYYY-MM-DD), defaults to today"),
197
+ db: AsyncSession = Depends(get_db)
198
+ ) -> PersonaStatsResponse:
199
+ """
200
+ Get statistics for a specific persona over a date range.
201
+
202
+ Queries aggregated data from persona_stats table.
203
+
204
+ **Parameters:**
205
+ - **persona**: Persona name
206
+ - **start_date**: Start date (ISO format), defaults to 30 days ago
207
+ - **end_date**: End date (ISO format), defaults to today
208
+
209
+ **Returns:**
210
+ - Usage metrics (questions, conversations, sessions)
211
+ - Performance metrics (confidence, retrieval/generation time)
212
+ - Engagement metrics (messages per conversation, session duration)
213
+ - Quality metrics (helpful/unhelpful counts, satisfaction rate)
214
+
215
+ **Raises:**
216
+ - 400: Invalid persona or date format
217
+ """
218
+ assert isinstance(persona, str) and len(persona) > 0, "Persona must be a non-empty string"
219
+ assert start_date is None or isinstance(start_date, str), "Start date must be a string or None"
220
+
221
+ try:
222
+ # Parse dates
223
+ start = date.fromisoformat(start_date) if start_date else None
224
+ end = date.fromisoformat(end_date) if end_date else None
225
+
226
+ service = PersonaService(db)
227
+ stats = await service.get_persona_stats(persona, start, end)
228
+ logger.info(f"📊 Retrieved stats for {persona}")
229
+ return stats
230
+ except InvalidPersonaError as e:
231
+ raise HTTPException(
232
+ status_code=status.HTTP_400_BAD_REQUEST,
233
+ detail={"error": "InvalidPersonaError", "message": str(e)}
234
+ )
235
+ except ValueError as e:
236
+ raise HTTPException(
237
+ status_code=status.HTTP_400_BAD_REQUEST,
238
+ detail={"error": "ValidationError", "message": f"Invalid date format: {e}"}
239
+ )
240
+ except Exception as e:
241
+ logger.error(f"❌ Error getting persona stats: {e}")
242
+ raise HTTPException(
243
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
244
+ detail={"error": "InternalServerError", "message": str(e)}
245
+ )
246
+
247
+
248
+ @router.get(
249
+ "/stats/all",
250
+ response_model=List[PersonaStatsResponse],
251
+ summary="Get statistics for all personas"
252
+ )
253
+ async def get_all_persona_stats(
254
+ start_date: Optional[str] = Query(None, description="Start date (YYYY-MM-DD)"),
255
+ end_date: Optional[str] = Query(None, description="End date (YYYY-MM-DD)"),
256
+ db: AsyncSession = Depends(get_db)
257
+ ) -> List[PersonaStatsResponse]:
258
+ """
259
+ Get statistics for all 4 personas.
260
+
261
+ **Parameters:**
262
+ - **start_date**: Optional start date (ISO format)
263
+ - **end_date**: Optional end date (ISO format)
264
+
265
+ **Returns:**
266
+ - List of stats for each persona
267
+
268
+ **Raises:**
269
+ - 400: Invalid date format
270
+ """
271
+ try:
272
+ start = date.fromisoformat(start_date) if start_date else None
273
+ end = date.fromisoformat(end_date) if end_date else None
274
+
275
+ service = PersonaService(db)
276
+ all_stats = await service.get_all_persona_stats(start, end)
277
+ logger.info(f"📊 Retrieved stats for all personas")
278
+ return all_stats
279
+ except ValueError as e:
280
+ raise HTTPException(
281
+ status_code=status.HTTP_400_BAD_REQUEST,
282
+ detail={"error": "ValidationError", "message": f"Invalid date format: {e}"}
283
+ )
284
+ except Exception as e:
285
+ logger.error(f"❌ Error getting all persona stats: {e}")
286
+ raise HTTPException(
287
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
288
+ detail={"error": "InternalServerError", "message": str(e)}
289
+ )
290
+
291
+
292
+ @router.get(
293
+ "/stats/usage",
294
+ response_model=UsageBreakdownResponse,
295
+ summary="Get persona usage breakdown",
296
+ description="Get percentage breakdown of persona usage over last 30 days"
297
+ )
298
+ async def get_usage_breakdown(
299
+ db: AsyncSession = Depends(get_db)
300
+ ) -> UsageBreakdownResponse:
301
+ """
302
+ Get percentage breakdown of persona usage.
303
+
304
+ Analyzes last 30 days of conversations.
305
+
306
+ **Returns:**
307
+ - Total conversations across all personas
308
+ - Usage percentage for each persona
309
+
310
+ """
311
+ try:
312
+ service = PersonaService(db)
313
+ breakdown = await service.get_persona_usage_breakdown()
314
+
315
+ # Calculate total from percentages (approximate)
316
+ total = sum(breakdown.values())
317
+
318
+ response = {
319
+ "total_conversations": int(total),
320
+ "percentages": breakdown
321
+ }
322
+
323
+ logger.info(f"📊 Usage breakdown retrieved")
324
+ return response
325
+ except Exception as e:
326
+ logger.error(f"❌ Error getting usage breakdown: {e}")
327
+ raise HTTPException(
328
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
329
+ detail={"error": "InternalServerError", "message": str(e)}
330
+ )
331
+
332
+
333
+ # ============================================================================
334
+ # ANALYTICS - ENGAGEMENT ENDPOINTS
335
+ # ============================================================================
336
+
337
+ @router.get(
338
+ "/{persona}/engagement",
339
+ response_model=EngagementMetricsResponse,
340
+ summary="Get engagement metrics for persona"
341
+ )
342
+ async def get_engagement_metrics(
343
+ persona: str = Path(..., description="Persona name"),
344
+ days: int = Query(30, ge=1, le=365, description="Number of days to analyze (1-365)"),
345
+ db: AsyncSession = Depends(get_db)
346
+ ) -> EngagementMetricsResponse:
347
+ """
348
+ Get engagement metrics for a persona over N days.
349
+
350
+ **Parameters:**
351
+ - **persona**: Persona name
352
+ - **days**: Number of days to analyze (default 30, max 365)
353
+
354
+ **Returns:**
355
+ - Total conversations and messages
356
+ - Average messages per conversation
357
+ - Average session duration
358
+ - Active days
359
+ - Conversations per active day
360
+
361
+ **Raises:**
362
+ - 400: Invalid persona
363
+ """
364
+ assert isinstance(persona, str) and len(persona) > 0, "Persona must be a non-empty string"
365
+ assert isinstance(days, int) and days > 0, "Days must be a positive integer"
366
+
367
+ try:
368
+ service = PersonaService(db)
369
+ metrics = await service.get_engagement_metrics(persona, days)
370
+ logger.info(f"📊 Engagement metrics for {persona} over {days} days")
371
+ return metrics
372
+ except InvalidPersonaError as e:
373
+ raise HTTPException(
374
+ status_code=status.HTTP_400_BAD_REQUEST,
375
+ detail={"error": "InvalidPersonaError", "message": str(e)}
376
+ )
377
+ except Exception as e:
378
+ logger.error(f"❌ Error getting engagement metrics: {e}")
379
+ raise HTTPException(
380
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
381
+ detail={"error": "InternalServerError", "message": str(e)}
382
+ )
383
+
384
+
385
+ @router.get(
386
+ "/{persona}/questions",
387
+ response_model=PopularQuestionsResponse,
388
+ summary="Get popular questions for persona"
389
+ )
390
+ async def get_popular_questions(
391
+ persona: str = Path(..., description="Persona name"),
392
+ limit: int = Query(10, ge=1, le=50, description="Max number of questions (1-50)"),
393
+ db: AsyncSession = Depends(get_db)
394
+ ) -> PopularQuestionsResponse:
395
+ """
396
+ Get most frequently asked questions for a persona.
397
+
398
+ Analyzes last 90 days of questions.
399
+
400
+ **Parameters:**
401
+ - **persona**: Persona name
402
+ - **limit**: Max number of questions to return (default 10, max 50)
403
+
404
+ **Returns:**
405
+ - List of popular questions with frequency counts
406
+
407
+ **Raises:**
408
+ - 400: Invalid persona
409
+ """
410
+ assert isinstance(persona, str) and len(persona) > 0, "Persona must be a non-empty string"
411
+ assert isinstance(limit, int) and limit > 0, "Limit must be a positive integer"
412
+
413
+ try:
414
+ service = PersonaService(db)
415
+ questions = await service.get_popular_questions(persona, limit)
416
+
417
+ response = {
418
+ "persona": persona,
419
+ "questions": questions,
420
+ "total_count": len(questions)
421
+ }
422
+
423
+ logger.info(f"📊 Popular questions for {persona}: {len(questions)} found")
424
+ return response
425
+ except InvalidPersonaError as e:
426
+ raise HTTPException(
427
+ status_code=status.HTTP_400_BAD_REQUEST,
428
+ detail={"error": "InvalidPersonaError", "message": str(e)}
429
+ )
430
+ except Exception as e:
431
+ logger.error(f"❌ Error getting popular questions: {e}")
432
+ raise HTTPException(
433
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
434
+ detail={"error": "InternalServerError", "message": str(e)}
435
+ )
436
+
437
+
438
+ # ============================================================================
439
+ # ANALYTICS - COMPARISON & TRENDS ENDPOINTS
440
+ # ============================================================================
441
+
442
+ @router.get(
443
+ "/compare/{metric}",
444
+ response_model=PersonaComparisonResponse,
445
+ summary="Compare personas by metric"
446
+ )
447
+ async def compare_personas(
448
+ metric: str = Path(..., description="Metric to compare (usage|confidence|satisfaction)"),
449
+ days: int = Query(30, ge=1, le=365, description="Number of days to analyze"),
450
+ db: AsyncSession = Depends(get_db)
451
+ ) -> PersonaComparisonResponse:
452
+ """
453
+ Compare all personas across a specific metric.
454
+
455
+ **Parameters:**
456
+ - **metric**: Metric to compare (usage, confidence, satisfaction)
457
+ - **days**: Number of days to analyze (default 30)
458
+
459
+ **Returns:**
460
+ - Comparison values for each persona
461
+ - Date range analyzed
462
+
463
+ **Raises:**
464
+ - 400: Invalid metric
465
+ """
466
+ try:
467
+ service = PersonaService(db)
468
+ comparison = await service.compare_personas(metric, days)
469
+ logger.info(f"📊 Compared personas by {metric} over {days} days")
470
+ return comparison
471
+ except ValueError as e:
472
+ raise HTTPException(
473
+ status_code=status.HTTP_400_BAD_REQUEST,
474
+ detail={"error": "ValidationError", "message": str(e)}
475
+ )
476
+ except Exception as e:
477
+ logger.error(f"❌ Error comparing personas: {e}")
478
+ raise HTTPException(
479
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
480
+ detail={"error": "InternalServerError", "message": str(e)}
481
+ )
482
+
483
+
484
+ @router.get(
485
+ "/{persona}/trends/{metric}",
486
+ response_model=TrendsResponse,
487
+ summary="Get trend data for persona"
488
+ )
489
+ async def get_trends(
490
+ persona: str = Path(..., description="Persona name"),
491
+ metric: str = Path(..., description="Metric to track (questions|confidence|satisfaction)"),
492
+ days: int = Query(30, ge=1, le=365, description="Number of days to analyze"),
493
+ db: AsyncSession = Depends(get_db)
494
+ ) -> TrendsResponse:
495
+ """
496
+ Get time-series trend data for a persona metric.
497
+
498
+ **Parameters:**
499
+ - **persona**: Persona name
500
+ - **metric**: Metric to track (questions, confidence, satisfaction)
501
+ - **days**: Number of days to analyze (default 30)
502
+
503
+ **Returns:**
504
+ - List of data points with date and value
505
+ - Metadata about persona, metric, and time range
506
+
507
+ **Raises:**
508
+ - 400: Invalid persona or metric
509
+ """
510
+ try:
511
+ service = PersonaService(db)
512
+ trends = await service.get_trends(persona, metric, days)
513
+
514
+ response = {
515
+ "persona": persona,
516
+ "metric": metric,
517
+ "days": days,
518
+ "data_points": trends
519
+ }
520
+
521
+ logger.info(f"📊 Trends for {persona} ({metric}) over {days} days: {len(trends)} points")
522
+ return response
523
+ except InvalidPersonaError as e:
524
+ raise HTTPException(
525
+ status_code=status.HTTP_400_BAD_REQUEST,
526
+ detail={"error": "InvalidPersonaError", "message": str(e)}
527
+ )
528
+ except ValueError as e:
529
+ raise HTTPException(
530
+ status_code=status.HTTP_400_BAD_REQUEST,
531
+ detail={"error": "ValidationError", "message": str(e)}
532
+ )
533
+ except Exception as e:
534
+ logger.error(f"❌ Error getting trends: {e}")
535
+ raise HTTPException(
536
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
537
+ detail={"error": "InternalServerError", "message": str(e)}
538
+ )
539
+
540
+
541
+ # ============================================================================
542
+ # FEEDBACK ENDPOINTS
543
+ # ============================================================================
544
+
545
+ @router.post(
546
+ "/feedback",
547
+ response_model=MessageFeedbackResponse,
548
+ status_code=status.HTTP_201_CREATED,
549
+ summary="Add message feedback",
550
+ responses={
551
+ 404: {"model": ErrorResponse, "description": "Message not found"},
552
+ 409: {"model": ErrorResponse, "description": "Feedback already exists"}
553
+ }
554
+ )
555
+ async def add_message_feedback(
556
+ feedback_data: MessageFeedbackCreate,
557
+ db: AsyncSession = Depends(get_db)
558
+ ) -> MessageFeedbackResponse:
559
+ """
560
+ Record user feedback on a message.
561
+
562
+ Users can rate messages as helpful/unhelpful (👍/👎) with optional 1-5 star rating.
563
+
564
+ **Parameters:**
565
+ - **message_id**: ID of message to rate
566
+ - **helpful**: Whether message was helpful (boolean)
567
+ - **rating**: Optional 1-5 star rating (integer)
568
+ - **comment**: Optional text comment (max 500 chars)
569
+
570
+ **Returns:**
571
+ - Created feedback with ID and timestamp
572
+
573
+ **Raises:**
574
+ - 404: Message not found
575
+ - 409: Feedback already exists for this message
576
+ - 400: Invalid rating (must be 1-5)
577
+ """
578
+ try:
579
+ service = PersonaService(db)
580
+ feedback = await service.add_message_feedback(
581
+ message_id=feedback_data.message_id,
582
+ helpful=feedback_data.helpful,
583
+ rating=feedback_data.rating,
584
+ comment=feedback_data.comment
585
+ )
586
+ logger.info(f"✅ Added feedback for message {feedback_data.message_id}")
587
+ return feedback
588
+ except MessageNotFoundError as e:
589
+ raise HTTPException(
590
+ status_code=status.HTTP_404_NOT_FOUND,
591
+ detail={"error": "MessageNotFoundError", "message": str(e)}
592
+ )
593
+ except FeedbackAlreadyExistsError as e:
594
+ raise HTTPException(
595
+ status_code=status.HTTP_409_CONFLICT,
596
+ detail={"error": "FeedbackAlreadyExistsError", "message": str(e)}
597
+ )
598
+ except ValueError as e:
599
+ raise HTTPException(
600
+ status_code=status.HTTP_400_BAD_REQUEST,
601
+ detail={"error": "ValidationError", "message": str(e)}
602
+ )
603
+ except Exception as e:
604
+ logger.error(f"❌ Error adding feedback: {e}")
605
+ raise HTTPException(
606
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
607
+ detail={"error": "InternalServerError", "message": str(e)}
608
+ )
609
+
610
+
611
+ @router.get(
612
+ "/feedback/{message_id}",
613
+ response_model=Optional[MessageFeedbackResponse],
614
+ summary="Get feedback for message",
615
+ responses={
616
+ 200: {"description": "Feedback found"},
617
+ 404: {"description": "No feedback exists for this message"}
618
+ }
619
+ )
620
+ async def get_message_feedback(
621
+ message_id: int = Path(..., description="Message ID", gt=0),
622
+ db: AsyncSession = Depends(get_db)
623
+ ) -> Optional[MessageFeedbackResponse]:
624
+ """
625
+ Get feedback for a specific message.
626
+
627
+ **Parameters:**
628
+ - **message_id**: ID of message
629
+
630
+ **Returns:**
631
+ - Feedback data if exists, null otherwise
632
+ """
633
+ try:
634
+ service = PersonaService(db)
635
+ feedback = await service.get_message_feedback(message_id)
636
+
637
+ if not feedback:
638
+ raise HTTPException(
639
+ status_code=status.HTTP_404_NOT_FOUND,
640
+ detail={"error": "NotFound", "message": f"No feedback found for message {message_id}"}
641
+ )
642
+
643
+ logger.info(f"📋 Retrieved feedback for message {message_id}")
644
+ return feedback
645
+ except HTTPException:
646
+ raise
647
+ except Exception as e:
648
+ logger.error(f"❌ Error getting feedback: {e}")
649
+ raise HTTPException(
650
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
651
+ detail={"error": "InternalServerError", "message": str(e)}
652
+ )
653
+
654
+
655
+ @router.get(
656
+ "/feedback/stats",
657
+ response_model=FeedbackStats,
658
+ summary="Get feedback statistics"
659
+ )
660
+ async def get_feedback_stats(
661
+ persona: Optional[str] = Query(None, description="Filter by persona"),
662
+ start_date: Optional[str] = Query(None, description="Start date (YYYY-MM-DD)"),
663
+ end_date: Optional[str] = Query(None, description="End date (YYYY-MM-DD)"),
664
+ db: AsyncSession = Depends(get_db)
665
+ ) -> FeedbackStats:
666
+ """
667
+ Get aggregated feedback statistics.
668
+
669
+ **Parameters:**
670
+ - **persona**: Optional persona filter
671
+ - **start_date**: Optional start date (ISO format)
672
+ - **end_date**: Optional end date (ISO format)
673
+
674
+ **Returns:**
675
+ - Total feedback count
676
+ - Helpful/unhelpful counts
677
+ - Satisfaction rate
678
+ - Average rating
679
+ - Breakdown by persona (if not filtered)
680
+
681
+ **Raises:**
682
+ - 400: Invalid persona or date format
683
+ """
684
+ try:
685
+ # Parse dates
686
+ start = date.fromisoformat(start_date) if start_date else None
687
+ end = date.fromisoformat(end_date) if end_date else None
688
+
689
+ service = PersonaService(db)
690
+ stats = await service.get_feedback_stats(persona, start, end)
691
+ logger.info(f"📊 Feedback stats retrieved")
692
+ return stats
693
+ except InvalidPersonaError as e:
694
+ raise HTTPException(
695
+ status_code=status.HTTP_400_BAD_REQUEST,
696
+ detail={"error": "InvalidPersonaError", "message": str(e)}
697
+ )
698
+ except ValueError as e:
699
+ raise HTTPException(
700
+ status_code=status.HTTP_400_BAD_REQUEST,
701
+ detail={"error": "ValidationError", "message": f"Invalid date format: {e}"}
702
+ )
703
+ except Exception as e:
704
+ logger.error(f"❌ Error getting feedback stats: {e}")
705
+ raise HTTPException(
706
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
707
+ detail={"error": "InternalServerError", "message": str(e)}
708
+ )
app/api/routes/rag.py ADDED
@@ -0,0 +1,353 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API routes for RAG chatbot service.
3
+
4
+ Provides endpoints for:
5
+ - ask: Standard RAG question answering
6
+ - ask/stream: Streaming RAG with SSE
7
+ - conversations: Conversation history management
8
+ - health: Service health check
9
+ """
10
+
11
+ import json
12
+ import logging
13
+
14
+ from fastapi import APIRouter, Depends, HTTPException, status
15
+ from fastapi.responses import StreamingResponse
16
+ from sqlalchemy import desc, select
17
+ from sqlalchemy.ext.asyncio import AsyncSession
18
+ from sqlalchemy.orm import joinedload
19
+
20
+ from app.core.database import get_db
21
+ from app.models.conversation import Conversation, Message
22
+ from app.schemas.rag import (
23
+ ConversationResponse,
24
+ MessageResponse,
25
+ RAGRequest,
26
+ RAGResponse,
27
+ )
28
+ from app.services.rag_service import RAGService, RAGServiceError
29
+
30
+ logger = logging.getLogger(__name__)
31
+
32
+ router = APIRouter()
33
+
34
+
35
+ def get_rag_service(db: AsyncSession = Depends(get_db)) -> RAGService:
36
+ """Dependency injection for RAGService."""
37
+ return RAGService(db)
38
+
39
+
40
+ @router.post("/ask", response_model=RAGResponse, status_code=status.HTTP_200_OK)
41
+ async def ask(
42
+ request: RAGRequest, rag_service: RAGService = Depends(get_rag_service)
43
+ ) -> RAGResponse:
44
+ """
45
+ Ask a legal question and get RAG-powered answer.
46
+
47
+ **Pipeline:**
48
+ 1. Retrieve top 5 relevant legal documents (<200ms)
49
+ 2. Load conversation history (last 5 messages)
50
+ 3. Generate persona-adapted answer with Mistral 7B (2-5s)
51
+ 4. Extract and validate source citations
52
+ 5. Calculate confidence score
53
+ 6. Save interaction to database
54
+
55
+ **Performance:** <5s total (specification requirement)
56
+
57
+ **Example Request:**
58
+ ```json
59
+ {
60
+ "question": "Quelle est la responsabilité des dirigeants de société?",
61
+ "persona": "avocat",
62
+ "language": "fr",
63
+ "session_id": "abc123",
64
+ "stream": false
65
+ }
66
+ ```
67
+
68
+ **Example Response:**
69
+ ```json
70
+ {
71
+ "answer": "Selon l'article 161 du Code OHADA...",
72
+ "confidence": 0.85,
73
+ "sources": [
74
+ {
75
+ "law_id": 156,
76
+ "law_reference": "LOI-2024-001",
77
+ "law_title": "Code OHADA",
78
+ "article_number": "161",
79
+ "excerpt": "Les dirigeants sont responsables...",
80
+ "relevance_score": 0.92
81
+ }
82
+ ],
83
+ "session_id": "abc123",
84
+ "retrieval_time_ms": 180,
85
+ "generation_time_ms": 2400,
86
+ "total_time_ms": 2600,
87
+ "persona": "avocat"
88
+ }
89
+ ```
90
+ """
91
+ assert request is not None, "RAGRequest must not be None"
92
+ assert isinstance(request.question, str) and len(request.question) > 0, "Question must be a non-empty string"
93
+
94
+ try:
95
+ logger.info(f"📥 Ask request: persona={request.persona}")
96
+
97
+ response = await rag_service.ask(request)
98
+
99
+ logger.info(f"📤 Ask response: {response.total_time_ms}ms")
100
+ return response
101
+
102
+ except RAGServiceError as e:
103
+ logger.error(f"❌ RAG error: {e}")
104
+ raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
105
+ except Exception as e:
106
+ logger.error(f"❌ Unexpected error: {e}", exc_info=True)
107
+ raise HTTPException(
108
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Erreur interne du serveur"
109
+ )
110
+
111
+
112
+ @router.post("/ask/stream", status_code=status.HTTP_200_OK)
113
+ async def ask_stream(request: RAGRequest, rag_service: RAGService = Depends(get_rag_service)):
114
+ """
115
+ Ask question with streaming response (SSE).
116
+
117
+ **Benefits:**
118
+ - First token appears in <500ms (faster perceived response)
119
+ - User sees answer being generated in real-time
120
+ - Better UX for longer answers
121
+
122
+ **Response Format:** Server-Sent Events (SSE)
123
+
124
+ Each event is JSON:
125
+ ```json
126
+ {"chunk": "text fragment", "done": false}
127
+ {"chunk": "", "done": true, "sources": [...], "confidence": 0.85}
128
+ ```
129
+
130
+ **Example Usage (JavaScript):**
131
+ ```javascript
132
+ const eventSource = new EventSource('/api/v1/rag/ask/stream');
133
+ eventSource.onmessage = (event) => {
134
+ const data = JSON.parse(event.data);
135
+ if (data.done) {
136
+ // Show sources and confidence
137
+ } else {
138
+ // Append chunk to answer
139
+ }
140
+ };
141
+ ```
142
+ """
143
+ try:
144
+ # Force streaming mode
145
+ request.stream = True
146
+
147
+ async def event_generator():
148
+ try:
149
+ async for chunk_json in rag_service.ask_stream(request):
150
+ yield f"data: {chunk_json}\n\n"
151
+ except Exception as e:
152
+ logger.error(f"❌ Stream error: {e}")
153
+ error_json = json.dumps({"error": str(e), "done": True})
154
+ yield f"data: {error_json}\n\n"
155
+
156
+ return StreamingResponse(
157
+ event_generator(),
158
+ media_type="text/event-stream",
159
+ headers={
160
+ "Cache-Control": "no-cache",
161
+ "Connection": "keep-alive",
162
+ "X-Accel-Buffering": "no", # Disable nginx buffering
163
+ },
164
+ )
165
+
166
+ except Exception as e:
167
+ logger.error(f"❌ Streaming setup error: {e}")
168
+ raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
169
+
170
+
171
+ @router.get(
172
+ "/conversations/{session_id}",
173
+ response_model=ConversationResponse,
174
+ status_code=status.HTTP_200_OK,
175
+ )
176
+ async def get_conversation(
177
+ session_id: str, db: AsyncSession = Depends(get_db)
178
+ ) -> ConversationResponse:
179
+ """
180
+ Get conversation history by session ID.
181
+
182
+ Returns all messages in chronological order with sources and metadata.
183
+
184
+ **Example Response:**
185
+ ```json
186
+ {
187
+ "session_id": "abc123",
188
+ "persona": "citoyen",
189
+ "language": "fr",
190
+ "created_at": "2026-01-10T10:00:00",
191
+ "updated_at": "2026-01-10T10:05:00",
192
+ "messages": [
193
+ {
194
+ "id": 1,
195
+ "role": "user",
196
+ "content": "Comment créer une entreprise?",
197
+ "sources": null,
198
+ "confidence": null,
199
+ "created_at": "2026-01-10T10:00:00"
200
+ },
201
+ {
202
+ "id": 2,
203
+ "role": "assistant",
204
+ "content": "Pour créer une entreprise...",
205
+ "sources": [...],
206
+ "confidence": 0.85,
207
+ "created_at": "2026-01-10T10:00:05"
208
+ }
209
+ ]
210
+ }
211
+ ```
212
+ """
213
+ assert isinstance(session_id, str) and len(session_id) > 0, "session_id must be a non-empty string"
214
+
215
+ try:
216
+ stmt = (
217
+ select(Conversation)
218
+ .where(Conversation.session_id == session_id)
219
+ .options(joinedload(Conversation.messages))
220
+ )
221
+ result = await db.execute(stmt)
222
+ conversation = result.scalar_one_or_none()
223
+
224
+ if not conversation:
225
+ raise HTTPException(
226
+ status_code=status.HTTP_404_NOT_FOUND, detail=f"Conversation {session_id} not found"
227
+ )
228
+
229
+ # Get messages in chronological order
230
+ msg_stmt = (
231
+ select(Message)
232
+ .where(Message.conversation_id == conversation.id)
233
+ .order_by(Message.created_at)
234
+ )
235
+ msg_result = await db.execute(msg_stmt)
236
+ messages = msg_result.scalars().all()
237
+
238
+ return ConversationResponse(
239
+ session_id=conversation.session_id,
240
+ persona=conversation.persona,
241
+ language=conversation.language,
242
+ created_at=conversation.created_at,
243
+ updated_at=conversation.updated_at,
244
+ messages=[MessageResponse.model_validate(m) for m in messages],
245
+ )
246
+
247
+ except HTTPException:
248
+ raise
249
+ except Exception as e:
250
+ logger.error(f"❌ Error fetching conversation: {e}")
251
+ raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
252
+
253
+
254
+ @router.delete("/conversations/{session_id}", status_code=status.HTTP_204_NO_CONTENT)
255
+ async def delete_conversation(session_id: str, db: AsyncSession = Depends(get_db)):
256
+ """
257
+ Delete conversation and all associated messages.
258
+
259
+ Useful for:
260
+ - User wants to start fresh
261
+ - Privacy/GDPR compliance
262
+ - Clear conversation context
263
+
264
+ Returns 204 No Content on success.
265
+ """
266
+ assert isinstance(session_id, str) and len(session_id) > 0, "session_id must be a non-empty string"
267
+
268
+ try:
269
+ stmt = select(Conversation).where(Conversation.session_id == session_id)
270
+ result = await db.execute(stmt)
271
+ conversation = result.scalar_one_or_none()
272
+
273
+ if not conversation:
274
+ raise HTTPException(
275
+ status_code=status.HTTP_404_NOT_FOUND, detail=f"Conversation {session_id} not found"
276
+ )
277
+
278
+ await db.delete(conversation)
279
+ await db.commit()
280
+
281
+ logger.info(f"🗑️ Deleted conversation: {session_id}")
282
+
283
+ except HTTPException:
284
+ raise
285
+ except Exception as e:
286
+ logger.error(f"❌ Error deleting conversation: {e}")
287
+ await db.rollback()
288
+ raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
289
+
290
+
291
+ @router.get("/health", status_code=status.HTTP_200_OK)
292
+ async def health_check(rag_service: RAGService = Depends(get_rag_service)) -> dict:
293
+ """
294
+ Check health of RAG system components.
295
+
296
+ Tests:
297
+ - LLM service availability (Gemini API)
298
+ - Database connectivity
299
+ - SearchService availability
300
+
301
+ **Example Response:**
302
+ ```json
303
+ {
304
+ "status": "healthy",
305
+ "llm": "healthy",
306
+ "database": "connected",
307
+ "search_service": "healthy"
308
+ }
309
+ ```
310
+ """
311
+ health_status = {
312
+ "status": "healthy",
313
+ "llm": "not_configured",
314
+ "database": "unknown",
315
+ "search_service": "unknown",
316
+ }
317
+
318
+ # Test LLM (Gemini - TODO: implement)
319
+ if rag_service.llm is not None:
320
+ try:
321
+ llm_health = await rag_service.llm.health_check()
322
+ health_status["llm"] = llm_health.get("status", "unknown")
323
+ if llm_health.get("status") != "healthy":
324
+ health_status["status"] = "degraded"
325
+ except Exception as e:
326
+ health_status["llm"] = f"error: {str(e)}"
327
+ health_status["status"] = "unhealthy"
328
+ else:
329
+ health_status["llm"] = "not_configured"
330
+ health_status["status"] = "degraded"
331
+
332
+ # Test database
333
+ try:
334
+ await rag_service.db.execute(select(1))
335
+ health_status["database"] = "connected"
336
+ except Exception as e:
337
+ health_status["database"] = f"error: {str(e)}"
338
+ health_status["status"] = "unhealthy"
339
+
340
+ # Test SearchService
341
+ try:
342
+ # Simple test query
343
+ from app.schemas.search import SearchRequest
344
+
345
+ test_response = await rag_service.search_service.search(
346
+ SearchRequest(query="test", mode="text", limit=1)
347
+ )
348
+ health_status["search_service"] = "healthy"
349
+ except Exception as e:
350
+ health_status["search_service"] = f"error: {str(e)}"
351
+ health_status["status"] = "degraded"
352
+
353
+ return health_status
app/api/routes/search.py ADDED
@@ -0,0 +1,668 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Routes API pour la recherche hybride.
3
+
4
+ Endpoints:
5
+ - POST /api/v1/search - Recherche principale (text/semantic/hybrid)
6
+ - POST /api/v1/search/reindex - Réindexation complète (admin)
7
+ - GET /api/v1/search/stats - Statistiques recherche (admin)
8
+
9
+ Author: JuriX Team
10
+ Version: 1.0.0
11
+ """
12
+
13
+ import logging
14
+ import time
15
+ from typing import Optional
16
+
17
+ from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, status
18
+ from sqlalchemy.ext.asyncio import AsyncSession
19
+
20
+ from app.core.database import get_db
21
+ from app.schemas.search import (
22
+ ReindexResponse,
23
+ SearchRequest,
24
+ SearchResponse,
25
+ SearchStats,
26
+ )
27
+ from app.services.search_service import SearchService, SearchServiceError
28
+
29
+ logger = logging.getLogger(__name__)
30
+
31
+ router = APIRouter()
32
+
33
+
34
+ # ==================== DEPENDENCIES ====================
35
+
36
+
37
+ def get_search_service(db: AsyncSession = Depends(get_db)) -> SearchService:
38
+ """
39
+ Dependency injection pour SearchService.
40
+
41
+ Args:
42
+ db: Session database async
43
+
44
+ Returns:
45
+ Instance SearchService
46
+ """
47
+ return SearchService(db, use_cache=True)
48
+
49
+
50
+ # ==================== ENDPOINTS ====================
51
+
52
+
53
+ @router.post("/", response_model=SearchResponse, status_code=status.HTTP_200_OK)
54
+ async def search(
55
+ request: SearchRequest, search_service: SearchService = Depends(get_search_service)
56
+ ) -> SearchResponse:
57
+ """
58
+ Point d'entrée principal pour la recherche.
59
+
60
+ Effectue une recherche selon le mode spécifié:
61
+ - **text**: Recherche textuelle full-text (Meilisearch, <50ms)
62
+ - **semantic**: Recherche sémantique par similarité (pgvector, <200ms)
63
+ - **hybrid**: Combinaison optimale via RRF fusion (40/60, <200ms)
64
+
65
+ **Filtres disponibles**:
66
+ - language: Code langue (fr/en)
67
+ - category_ids: Liste IDs catégories
68
+ - types: Types de lois
69
+ - status: Statut publication
70
+ - year_from/year_to: Plage années
71
+
72
+ **Pagination**:
73
+ - limit: Nombre résultats (1-50, défaut: 15)
74
+ - offset: Offset pagination (défaut: 0)
75
+
76
+ **Performance**:
77
+ - Text: <50ms
78
+ - Semantic: <200ms
79
+ - Hybrid: <200ms (spécification)
80
+
81
+ Args:
82
+ request: SearchRequest avec query, mode, filters, pagination
83
+ search_service: Service injection
84
+
85
+ Returns:
86
+ SearchResponse avec résultats et métadonnées
87
+
88
+ Raises:
89
+ HTTPException 400: Si requête invalide
90
+ HTTPException 500: Si recherche échoue
91
+
92
+ Example:
93
+ ```json
94
+ POST /api/v1/search
95
+ {
96
+ "query": "responsabilité dirigeants société",
97
+ "mode": "hybrid",
98
+ "filters": {
99
+ "language": "fr",
100
+ "category_ids": [1, 3]
101
+ },
102
+ "limit": 15,
103
+ "offset": 0
104
+ }
105
+ ```
106
+
107
+ Response:
108
+ ```json
109
+ {
110
+ "query": "responsabilité dirigeants société",
111
+ "mode": "hybrid",
112
+ "results": [
113
+ {
114
+ "law_id": 156,
115
+ "reference": "LOI-2024-001",
116
+ "title": "Code des sociétés commerciales",
117
+ "relevance_score": 0.95,
118
+ "highlights": {
119
+ "title": "Code des <mark>sociétés</mark> commerciales",
120
+ "content": "...la <mark>responsabilité</mark> des <mark>dirigeants</mark>..."
121
+ }
122
+ }
123
+ ],
124
+ "total": 42,
125
+ "search_time_ms": 187,
126
+ "filters_applied": {"language": "fr", "category_ids": [1, 3]}
127
+ }
128
+ ```
129
+ """
130
+ assert request is not None, "SearchRequest must not be None"
131
+ assert isinstance(request.query, str) and len(request.query) > 0, "Query must be a non-empty string"
132
+ assert request.mode in ("text", "semantic", "hybrid"), f"Invalid search mode: {request.mode}"
133
+
134
+ try:
135
+ logger.info(f'📥 Search request: mode={request.mode}, query="{request.query[:50]}"')
136
+
137
+ # Exécution recherche
138
+ response = await search_service.search(request)
139
+
140
+ logger.info(f"📤 Search response: {response.total} results in {response.search_time_ms}ms")
141
+
142
+ return response
143
+
144
+ except ValueError as e:
145
+ # Validation errors (query vide, mode invalide, etc.)
146
+ logger.warning(f"⚠️ Invalid search request: {e}")
147
+ raise HTTPException(
148
+ status_code=status.HTTP_400_BAD_REQUEST, detail=f"Requête invalide: {str(e)}"
149
+ ) from e
150
+
151
+ except SearchServiceError as e:
152
+ # Erreurs service (Meilisearch down, pgvector error, etc.)
153
+ logger.error(f"❌ Search service error: {e}")
154
+ raise HTTPException(
155
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
156
+ detail=f"Erreur lors de la recherche: {str(e)}",
157
+ ) from e
158
+
159
+ except Exception as e:
160
+ # Erreurs inattendues
161
+ logger.error(f"❌ Unexpected error during search: {e}", exc_info=True)
162
+ raise HTTPException(
163
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Erreur interne du serveur"
164
+ ) from e
165
+
166
+
167
+ @router.get("/suggest", status_code=status.HTTP_200_OK)
168
+ async def suggest(
169
+ q: str,
170
+ limit: int = 5,
171
+ search_service: SearchService = Depends(get_search_service)
172
+ ) -> dict:
173
+ """
174
+ Autocomplétion rapide pour suggestions de recherche.
175
+
176
+ Utilise uniquement Meilisearch (mode text) pour des réponses ultra-rapides (<50ms).
177
+ Retourne titres et références de lois correspondant à la requête.
178
+
179
+ Args:
180
+ q: Query de recherche (min 2 caractères)
181
+ limit: Nombre de suggestions (défaut: 5, max: 10)
182
+
183
+ Returns:
184
+ Liste de suggestions avec titre, référence et ID
185
+
186
+ Example:
187
+ GET /api/v1/search/suggest?q=const&limit=5
188
+
189
+ Response:
190
+ {
191
+ "suggestions": [
192
+ {"id": 1, "title": "Constitution du Cameroun", "reference": "CONST-1996"},
193
+ {"id": 42, "title": "Loi constitutionnelle", "reference": "LOI-2008-001"}
194
+ ],
195
+ "query": "const",
196
+ "search_time_ms": 12
197
+ }
198
+ """
199
+ assert isinstance(q, str), "Query must be a string"
200
+ assert isinstance(limit, int) and limit > 0, "Limit must be a positive integer"
201
+
202
+ if len(q) < 2:
203
+ return {"suggestions": [], "query": q, "search_time_ms": 0}
204
+
205
+ limit = min(limit, 10) # Max 10 suggestions
206
+
207
+ try:
208
+ start_time = time.time()
209
+
210
+ # Recherche Meilisearch directe (ultra-rapide)
211
+ index = search_service.meilisearch_client.index(SearchService.MEILISEARCH_INDEX)
212
+
213
+ results = index.search(
214
+ q,
215
+ {
216
+ "limit": limit,
217
+ "attributesToRetrieve": ["id", "title", "reference"],
218
+ "attributesToHighlight": ["title"],
219
+ "highlightPreTag": "<mark>",
220
+ "highlightPostTag": "</mark>"
221
+ }
222
+ )
223
+
224
+ search_time_ms = int((time.time() - start_time) * 1000)
225
+
226
+ suggestions = [
227
+ {
228
+ "id": hit.get("id"),
229
+ "title": hit.get("_formatted", {}).get("title", hit.get("title", "")),
230
+ "reference": hit.get("reference", "")
231
+ }
232
+ for hit in results.get("hits", [])
233
+ ]
234
+
235
+ logger.debug(f"📋 Suggest: {len(suggestions)} results for '{q}' in {search_time_ms}ms")
236
+
237
+ return {
238
+ "suggestions": suggestions,
239
+ "query": q,
240
+ "search_time_ms": search_time_ms
241
+ }
242
+
243
+ except Exception as e:
244
+ logger.warning(f"⚠️ Suggest error: {e}")
245
+ return {"suggestions": [], "query": q, "search_time_ms": 0, "error": str(e)}
246
+
247
+
248
+ def _parse_article_reference(query: str) -> tuple:
249
+ """
250
+ Parse article number and document hint from a query string.
251
+
252
+ Supports French (article, art.) and English (section) patterns.
253
+ Normalizes 'premier', '1er', 'first' etc. to '1'.
254
+
255
+ Args:
256
+ query: Lowercased query string
257
+
258
+ Returns:
259
+ (article_num: str | None, doc_hint: str | None)
260
+ """
261
+ import re
262
+
263
+ patterns = [
264
+ # "article 5 de la constitution"
265
+ r"article\s+(premier|1er|1ère|\d+)\s+(?:de\s+)?(?:la\s+|le\s+|l[''']|du\s+|des\s+)?(.+)",
266
+ # "art. 12 de la loi"
267
+ r"art\.?\s*(\d+)\s+(?:de\s+)?(?:la\s+|le\s+|l[''']|du\s+)?(.+)",
268
+ # English: "section 5"
269
+ r"section\s+(\d+|one|first)\s+(?:of\s+)?(?:the\s+)?(.+)",
270
+ ]
271
+
272
+ for pattern in patterns:
273
+ match = re.search(pattern, query, re.IGNORECASE)
274
+ if match:
275
+ article_num = match.group(1).strip()
276
+ doc_hint = match.group(2).strip() if match.group(2) else ""
277
+
278
+ # Normalize
279
+ if article_num.lower() in ("premier", "1er", "1ère", "first", "one"):
280
+ article_num = "1"
281
+ return article_num, doc_hint
282
+
283
+ return None, None
284
+
285
+
286
+ def _estimate_page_number(article) -> int:
287
+ """
288
+ Estimate the PDF page number where an article appears.
289
+
290
+ Uses stored page_number if available; otherwise estimates from
291
+ the article number (roughly 2 articles per page).
292
+
293
+ Args:
294
+ article: Article ORM object with .page_number and .number
295
+
296
+ Returns:
297
+ Estimated page number (>= 2)
298
+ """
299
+ if article.page_number is not None:
300
+ return article.page_number
301
+
302
+ try:
303
+ art_num = int(article.number.replace("er", "").replace("ère", "").strip())
304
+ return max(2, 1 + (art_num // 2))
305
+ except ValueError:
306
+ return 2 # Default to page 2
307
+
308
+
309
+ @router.get("/article", status_code=status.HTTP_200_OK)
310
+ async def find_article(
311
+ q: str,
312
+ db: AsyncSession = Depends(get_db)
313
+ ) -> dict:
314
+ """
315
+ Recherche rapide d'article pour navigation directe (<2s).
316
+
317
+ Détecte les références d'articles dans la query et retourne:
318
+ - law_id: ID du document contenant l'article
319
+ - article_num: Numéro de l'article trouvé
320
+ - direct_url: URL pour navigation directe
321
+
322
+ Performance cible: <500ms
323
+
324
+ Args:
325
+ q: Query contenant une référence d'article (ex: "article 5 de la constitution")
326
+
327
+ Returns:
328
+ Résultat avec law_id et article_num pour navigation directe
329
+ """
330
+ from sqlalchemy import select, or_
331
+ from app.models.law import Law, Article
332
+
333
+ assert isinstance(q, str) and len(q) > 0, "Query must be a non-empty string"
334
+
335
+ start_time = time.time()
336
+
337
+ # Parse article reference from query
338
+ article_num, doc_hint = _parse_article_reference(q.lower().strip())
339
+
340
+ if not article_num:
341
+ return {
342
+ "found": False,
343
+ "error": "Aucune référence d'article détectée",
344
+ "query": q,
345
+ "search_time_ms": int((time.time() - start_time) * 1000)
346
+ }
347
+
348
+ try:
349
+ # Search for the law by title hint
350
+ law_query = select(Law).where(Law.status == "published")
351
+
352
+ if doc_hint:
353
+ law_query = law_query.where(
354
+ or_(
355
+ Law.title.ilike(f"%{doc_hint}%"),
356
+ Law.reference.ilike(f"%{doc_hint}%")
357
+ )
358
+ )
359
+
360
+ result = await db.execute(law_query.limit(5))
361
+ laws = result.scalars().all()
362
+
363
+ # Find article in these laws
364
+ for law in laws:
365
+ article_query = select(Article).where(
366
+ Article.law_id == law.id,
367
+ Article.number == article_num
368
+ ).limit(1)
369
+
370
+ article_result = await db.execute(article_query)
371
+ article = article_result.scalar_one_or_none()
372
+
373
+ if article:
374
+ search_time_ms = int((time.time() - start_time) * 1000)
375
+ logger.info(f"🎯 Found article {article.number} in law {law.id} in {search_time_ms}ms")
376
+
377
+ page_number = _estimate_page_number(article)
378
+
379
+ return {
380
+ "found": True,
381
+ "law_id": law.id,
382
+ "law_title": law.title,
383
+ "law_reference": law.reference,
384
+ "article_num": article.number,
385
+ "article_id": article.id,
386
+ "article_order": article.order,
387
+ "estimated_page": page_number,
388
+ "direct_url": f"/laws/{law.id}?article={article.number}&page={page_number}",
389
+ "query": q,
390
+ "search_time_ms": search_time_ms
391
+ }
392
+
393
+ # Article not found
394
+ search_time_ms = int((time.time() - start_time) * 1000)
395
+ return {
396
+ "found": False,
397
+ "error": f"Article {article_num} non trouvé dans '{doc_hint or 'tous les documents'}'",
398
+ "query": q,
399
+ "search_time_ms": search_time_ms
400
+ }
401
+
402
+ except Exception as e:
403
+ logger.error(f"❌ Article search error: {e}")
404
+ return {
405
+ "found": False,
406
+ "error": str(e),
407
+ "query": q,
408
+ "search_time_ms": int((time.time() - start_time) * 1000)
409
+ }
410
+
411
+
412
+
413
+ @router.post(
414
+ "/reindex",
415
+ response_model=ReindexResponse,
416
+ status_code=status.HTTP_200_OK,
417
+ # TODO: Add admin authentication dependency
418
+ # dependencies=[Depends(require_admin)]
419
+ )
420
+ async def reindex_all(
421
+ background_tasks: BackgroundTasks, search_service: SearchService = Depends(get_search_service)
422
+ ) -> ReindexResponse:
423
+ """
424
+ Réindexe toutes les lois publiées dans Meilisearch (admin uniquement).
425
+
426
+ **Opération longue** (~5s pour 100 lois):
427
+ - Récupère toutes les lois publiées depuis DB
428
+ - Supprime ancien index Meilisearch
429
+ - Recrée index avec configuration optimale
430
+ - Indexe documents en batch (1000 par batch)
431
+
432
+ **Configuration index**:
433
+ - Searchable: title, reference, content
434
+ - Filterable: id, category_id, type, language, status, year
435
+ - Sortable: publication_year, created_at
436
+ - Typo tolerance: 1-2 typos selon longueur
437
+ - Ranking: words > typo > proximity > attribute > sort > exactness
438
+
439
+ **Quand utiliser**:
440
+ - Après changements massifs de contenu
441
+ - Après mise à jour configuration Meilisearch
442
+ - Résolution corruption index
443
+ - Tests/développement
444
+
445
+ **⚠️ Attention**:
446
+ - Recherche indisponible pendant réindexation
447
+ - Opération CPU/IO intensive
448
+ - Invalidation cache nécessaire
449
+
450
+ Args:
451
+ background_tasks: FastAPI background tasks (future async support)
452
+ search_service: Service injection
453
+
454
+ Returns:
455
+ ReindexResponse avec statistiques (total, indexed, failed, duration)
456
+
457
+ Raises:
458
+ HTTPException 500: Si réindexation échoue
459
+
460
+ Example:
461
+ ```
462
+ POST /api/v1/search/reindex
463
+ Authorization: Bearer <admin_token>
464
+ ```
465
+
466
+ Response:
467
+ ```json
468
+ {
469
+ "status": "success",
470
+ "total_laws": 156,
471
+ "indexed_count": 156,
472
+ "failed_count": 0,
473
+ "duration_seconds": 4
474
+ }
475
+ ```
476
+ """
477
+ try:
478
+ logger.info("🔄 Starting full reindex (admin operation)...")
479
+
480
+ # Exécution réindexation (blocking pour l'instant)
481
+ # TODO: Implémenter via background_tasks pour async
482
+ response = await search_service.reindex_all_laws()
483
+
484
+ logger.info(
485
+ f"✅ Reindex complete: {response.indexed_count}/{response.total_laws} "
486
+ f"in {response.duration_seconds}s"
487
+ )
488
+
489
+ return response
490
+
491
+ except SearchServiceError as e:
492
+ logger.error(f"❌ Reindex failed: {e}")
493
+ raise HTTPException(
494
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
495
+ detail=f"Échec réindexation: {str(e)}",
496
+ ) from e
497
+
498
+ except Exception as e:
499
+ logger.error(f"❌ Unexpected error during reindex: {e}", exc_info=True)
500
+ raise HTTPException(
501
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Erreur interne du serveur"
502
+ ) from e
503
+
504
+
505
+ @router.get(
506
+ "/stats",
507
+ response_model=SearchStats,
508
+ status_code=status.HTTP_200_OK,
509
+ # TODO: Add admin authentication dependency
510
+ # dependencies=[Depends(require_admin)]
511
+ )
512
+ async def get_search_stats(
513
+ search_service: SearchService = Depends(get_search_service),
514
+ ) -> SearchStats:
515
+ """
516
+ Récupère les statistiques de recherche (admin uniquement).
517
+
518
+ **Métriques fournies**:
519
+ - Nombre total de documents indexés
520
+ - Répartition par langue (fr/en)
521
+ - Répartition par catégorie
522
+ - Répartition par statut
523
+ - État de santé index Meilisearch
524
+ - État cache Redis
525
+
526
+ **Cas d'usage**:
527
+ - Monitoring santé système recherche
528
+ - Analytics utilisation
529
+ - Debugging problèmes indexation
530
+ - Validation après réindexation
531
+
532
+ Args:
533
+ search_service: Service injection
534
+
535
+ Returns:
536
+ SearchStats avec métriques système
537
+
538
+ Raises:
539
+ HTTPException 500: Si récupération stats échoue
540
+
541
+ Example:
542
+ ```
543
+ GET /api/v1/search/stats
544
+ Authorization: Bearer <admin_token>
545
+ ```
546
+
547
+ Response:
548
+ ```json
549
+ {
550
+ "total_documents": 156,
551
+ "by_language": {"fr": 142, "en": 14},
552
+ "by_category": {"Droit Civil": 45, "Droit Pénal": 38, ...},
553
+ "by_status": {"published": 156, "draft": 0},
554
+ "index_health": "healthy",
555
+ "cache_status": "connected"
556
+ }
557
+ ```
558
+ """
559
+ try:
560
+ logger.info("📊 Fetching search stats (admin operation)...")
561
+
562
+ # TODO: Implémenter récupération stats depuis Meilisearch + DB
563
+ # Pour l'instant retourne mock data
564
+
565
+ # Récupération stats Meilisearch
566
+ index = search_service.meilisearch_client.index(SearchService.MEILISEARCH_INDEX)
567
+
568
+ try:
569
+ index_stats = index.get_stats()
570
+ total_docs = index_stats.get("numberOfDocuments", 0)
571
+ except Exception:
572
+ total_docs = 0
573
+
574
+ # Mock stats (TODO: Vraies stats depuis DB)
575
+ stats = SearchStats(
576
+ total_documents=total_docs,
577
+ by_language={"fr": 0, "en": 0}, # TODO: Query DB
578
+ by_category={}, # TODO: Query DB
579
+ by_status={"published": total_docs},
580
+ index_health="healthy" if total_docs > 0 else "empty",
581
+ cache_status=("connected" if search_service.redis_client else "disabled"),
582
+ )
583
+
584
+ logger.info(f"✅ Stats retrieved: {total_docs} documents indexed")
585
+
586
+ return stats
587
+
588
+ except Exception as e:
589
+ logger.error(f"❌ Failed to get stats: {e}", exc_info=True)
590
+ raise HTTPException(
591
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
592
+ detail="Erreur lors de la récupération des statistiques",
593
+ ) from e
594
+
595
+
596
+ # ==================== HEALTH CHECK ====================
597
+
598
+
599
+ @router.get("/health", status_code=status.HTTP_200_OK)
600
+ async def health_check(search_service: SearchService = Depends(get_search_service)) -> dict:
601
+ """
602
+ Vérifie l'état de santé du service de recherche.
603
+
604
+ Teste:
605
+ - Connexion Meilisearch
606
+ - Existence index
607
+ - Connexion Redis (si cache activé)
608
+ - Disponibilité EmbeddingService
609
+
610
+ Returns:
611
+ Statut de santé avec détails composants
612
+
613
+ Example:
614
+ ```
615
+ GET /api/v1/search/health
616
+ ```
617
+
618
+ Response:
619
+ ```json
620
+ {
621
+ "status": "healthy",
622
+ "meilisearch": "connected",
623
+ "redis": "connected",
624
+ "embedding_service": "ready"
625
+ }
626
+ ```
627
+ """
628
+ health_status = {
629
+ "status": "healthy",
630
+ "meilisearch": "unknown",
631
+ "redis": "unknown",
632
+ "embedding_service": "unknown",
633
+ }
634
+
635
+ # Test Meilisearch
636
+ try:
637
+ search_service.meilisearch_client.health()
638
+ health_status["meilisearch"] = "connected"
639
+ except Exception as e:
640
+ health_status["meilisearch"] = f"error: {str(e)}"
641
+ health_status["status"] = "degraded"
642
+
643
+ # Test Redis
644
+ if search_service.redis_client:
645
+ try:
646
+ search_service.redis_client.ping()
647
+ health_status["redis"] = "connected"
648
+ except Exception as e:
649
+ health_status["redis"] = f"error: {str(e)}"
650
+ health_status["status"] = "degraded"
651
+ else:
652
+ health_status["redis"] = "disabled"
653
+
654
+ # Test EmbeddingService
655
+ if search_service.embedding_service is not None:
656
+ try:
657
+ emb_health = search_service.embedding_service.health_check()
658
+ health_status["embedding_service"] = emb_health["status"]
659
+ if emb_health["status"] != "healthy":
660
+ health_status["status"] = "degraded"
661
+ except Exception as e:
662
+ health_status["embedding_service"] = f"error: {str(e)}"
663
+ health_status["status"] = "degraded"
664
+ else:
665
+ health_status["embedding_service"] = "unavailable (text search only)"
666
+ health_status["status"] = "degraded"
667
+
668
+ return health_status
app/api/routes/upload.py ADDED
@@ -0,0 +1,248 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ API endpoints for file upload operations.
3
+
4
+ Provides REST endpoints for:
5
+ - File upload (POST /api/v1/upload)
6
+ - Upload status (GET /api/v1/upload/{file_id})
7
+ - File deletion (DELETE /api/v1/upload/{file_id})
8
+ - Health check (GET /api/v1/upload/health)
9
+
10
+ Author: JuriX Development Team
11
+ Date: 2026-01-11
12
+ """
13
+
14
+ import logging
15
+ from pathlib import Path
16
+ from typing import Dict
17
+
18
+ from fastapi import APIRouter, File, HTTPException, UploadFile, status
19
+ from fastapi.responses import JSONResponse
20
+
21
+ from app.schemas.file_upload import FileUploadResult, UploadServiceHealth
22
+ from app.services.file_upload_service import FileUploadError, FileUploadService
23
+
24
+ logger = logging.getLogger(__name__)
25
+
26
+ # Create router
27
+ router = APIRouter(prefix="/api/v1/upload", tags=["File Upload"])
28
+
29
+ # Initialize service (singleton pattern)
30
+ # In production, this should be dependency-injected
31
+ _upload_service: FileUploadService = None
32
+
33
+
34
+ def get_upload_service() -> FileUploadService:
35
+ """
36
+ Get or create FileUploadService instance.
37
+
38
+ Returns:
39
+ FileUploadService instance
40
+ """
41
+ global _upload_service
42
+ if _upload_service is None:
43
+ # Ensure storage directory exists
44
+ storage_path = Path("./data/uploads")
45
+ storage_path.mkdir(parents=True, exist_ok=True)
46
+
47
+ # TODO: Load from environment variables
48
+ _upload_service = FileUploadService(
49
+ storage_path="./data/uploads",
50
+ max_size_mb=250,
51
+ allowed_formats=("pdf", "docx"),
52
+ clamav_enabled=False, # Mock by default
53
+ cleanup_hours=24,
54
+ )
55
+ return _upload_service
56
+
57
+
58
+ @router.post(
59
+ "",
60
+ response_model=FileUploadResult,
61
+ status_code=status.HTTP_201_CREATED,
62
+ summary="Upload a file",
63
+ description="""
64
+ Upload a PDF or DOCX file for processing.
65
+
66
+ **Validations:**
67
+ - Maximum file size: 50 MB
68
+ - Allowed formats: PDF, DOCX
69
+ - File structure validation
70
+ - Antivirus scan
71
+
72
+ **Returns:**
73
+ - File ID for tracking
74
+ - Validation results
75
+ - Extracted metadata
76
+ - Scan results
77
+ """,
78
+ )
79
+ async def upload_file(
80
+ file: UploadFile = File(..., description="File to upload (PDF or DOCX, max 50 MB)"),
81
+ ) -> FileUploadResult:
82
+ """
83
+ Upload a file with validation and scanning.
84
+
85
+ Args:
86
+ file: Uploaded file
87
+
88
+ Returns:
89
+ FileUploadResult with complete upload information
90
+
91
+ Raises:
92
+ 400: Invalid file format or validation failed
93
+ 413: File too large
94
+ 500: Internal server error
95
+ """
96
+ assert file is not None, "UploadFile must not be None"
97
+ assert file.filename is not None and len(file.filename) > 0, "Filename must not be empty"
98
+
99
+ logger.info(f"📤 Upload request: {file.filename} ({file.content_type})")
100
+
101
+ try:
102
+ service = get_upload_service()
103
+ result = await service.upload_file(file)
104
+
105
+ logger.info(f"✅ Upload successful: {result.file_id}")
106
+ return result
107
+
108
+ except FileUploadError as e:
109
+ logger.warning(f"⚠️ Upload validation failed: {e}")
110
+ raise HTTPException(
111
+ status_code=status.HTTP_400_BAD_REQUEST,
112
+ detail=str(e),
113
+ )
114
+ except Exception as e:
115
+ logger.error(f"❌ Upload error: {e}", exc_info=True)
116
+ raise HTTPException(
117
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
118
+ detail="Internal server error during file upload",
119
+ )
120
+
121
+
122
+ @router.get(
123
+ "/{file_id}",
124
+ response_model=Dict,
125
+ summary="Get upload status",
126
+ description="Retrieve information about an uploaded file by its ID.",
127
+ )
128
+ async def get_upload_status(file_id: str) -> Dict:
129
+ """
130
+ Get status and metadata of an uploaded file.
131
+
132
+ Args:
133
+ file_id: File identifier
134
+
135
+ Returns:
136
+ File information
137
+
138
+ Raises:
139
+ 404: File not found
140
+ """
141
+ assert isinstance(file_id, str) and len(file_id) > 0, "file_id must be a non-empty string"
142
+
143
+ service = get_upload_service()
144
+
145
+ # Check if file exists
146
+ file_path = service.storage_path / f"{file_id}.pdf"
147
+ if not file_path.exists():
148
+ file_path = service.storage_path / f"{file_id}.docx"
149
+
150
+ if not file_path.exists():
151
+ raise HTTPException(
152
+ status_code=status.HTTP_404_NOT_FOUND,
153
+ detail=f"File not found: {file_id}",
154
+ )
155
+
156
+ # Return basic file info
157
+ return {
158
+ "file_id": file_id,
159
+ "exists": True,
160
+ "file_size": file_path.stat().st_size,
161
+ "storage_path": str(file_path),
162
+ }
163
+
164
+
165
+ @router.delete(
166
+ "/{file_id}",
167
+ response_model=Dict,
168
+ summary="Delete uploaded file",
169
+ description="Delete an uploaded file from temporary storage.",
170
+ )
171
+ async def delete_upload(file_id: str) -> Dict:
172
+ """
173
+ Delete an uploaded file.
174
+
175
+ Args:
176
+ file_id: File identifier
177
+
178
+ Returns:
179
+ Success confirmation
180
+
181
+ Raises:
182
+ 404: File not found
183
+ """
184
+ assert isinstance(file_id, str) and len(file_id) > 0, "file_id must be a non-empty string"
185
+
186
+ service = get_upload_service()
187
+
188
+ # Try to find and delete file
189
+ deleted = False
190
+ for ext in [".pdf", ".docx"]:
191
+ file_path = service.storage_path / f"{file_id}{ext}"
192
+ if file_path.exists():
193
+ file_path.unlink()
194
+ deleted = True
195
+ logger.info(f"🗑️ Deleted file: {file_id}{ext}")
196
+ break
197
+
198
+ if not deleted:
199
+ raise HTTPException(
200
+ status_code=status.HTTP_404_NOT_FOUND,
201
+ detail=f"File not found: {file_id}",
202
+ )
203
+
204
+ return {"success": True, "file_id": file_id, "message": "File deleted successfully"}
205
+
206
+
207
+ @router.get(
208
+ "/health",
209
+ response_model=UploadServiceHealth,
210
+ summary="Service health check",
211
+ description="Check the health status of the file upload service.",
212
+ )
213
+ async def health_check() -> UploadServiceHealth:
214
+ """
215
+ Check service health.
216
+
217
+ Returns:
218
+ Health status including storage and scanner information
219
+ """
220
+ service = get_upload_service()
221
+ health = service.health_check()
222
+
223
+ return UploadServiceHealth(**health)
224
+
225
+
226
+ @router.post(
227
+ "/cleanup",
228
+ response_model=Dict,
229
+ summary="Cleanup old files",
230
+ description="Remove files older than specified hours (default: 24h).",
231
+ )
232
+ async def cleanup_old_files(max_age_hours: int = 24) -> Dict:
233
+ """
234
+ Cleanup old uploaded files.
235
+
236
+ Args:
237
+ max_age_hours: Maximum age in hours (default: 24)
238
+
239
+ Returns:
240
+ Cleanup statistics
241
+ """
242
+ assert isinstance(max_age_hours, int) and max_age_hours > 0, "max_age_hours must be a positive integer"
243
+
244
+ service = get_upload_service()
245
+ stats = await service.cleanup_old_files(max_age_hours)
246
+
247
+ logger.info(f"🧹 Cleanup completed: {stats['deleted_count']} files deleted")
248
+ return stats
app/core/__init__.py ADDED
File without changes
app/core/auth.py ADDED
@@ -0,0 +1,188 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Authentication utilities for JuriX.
3
+
4
+ Provides JWT token generation, password hashing, and user authentication.
5
+
6
+ Author: JuriX Team
7
+ Date: 2026-01-12
8
+ """
9
+
10
+ from datetime import datetime, timedelta
11
+ from typing import Optional
12
+
13
+ from fastapi import Depends, HTTPException, status
14
+ from fastapi.security import OAuth2PasswordBearer
15
+ from jose import JWTError, jwt
16
+ from passlib.context import CryptContext
17
+ from sqlalchemy import select
18
+ from sqlalchemy.ext.asyncio import AsyncSession
19
+
20
+ from app.core.config import settings
21
+ from app.core.database import get_db
22
+ from app.models.user import User
23
+
24
+ # Password hashing
25
+ pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
26
+
27
+ # OAuth2 scheme
28
+ oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
29
+
30
+ # JWT settings
31
+ SECRET_KEY = (
32
+ settings.SECRET_KEY
33
+ if hasattr(settings, "SECRET_KEY")
34
+ else "dev-secret-key-change-in-production"
35
+ )
36
+ ALGORITHM = "HS256"
37
+ ACCESS_TOKEN_EXPIRE_MINUTES = 60 * 24 * 7 # 7 days
38
+
39
+
40
+ def hash_password(password: str) -> str:
41
+ """
42
+ Hash a password using bcrypt.
43
+
44
+ Args:
45
+ password: Plain text password
46
+
47
+ Returns:
48
+ Hashed password
49
+ """
50
+ return pwd_context.hash(password)
51
+
52
+
53
+ def verify_password(plain_password: str, hashed_password: str) -> bool:
54
+ """
55
+ Verify a password against its hash.
56
+
57
+ Args:
58
+ plain_password: Plain text password to verify
59
+ hashed_password: Bcrypt hash to verify against
60
+
61
+ Returns:
62
+ True if password matches, False otherwise
63
+ """
64
+ return pwd_context.verify(plain_password, hashed_password)
65
+
66
+
67
+ def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
68
+ """
69
+ Create a JWT access token.
70
+
71
+ Args:
72
+ data: Data to encode in token (typically {"sub": user_email})
73
+ expires_delta: Optional expiration time delta
74
+
75
+ Returns:
76
+ Encoded JWT token
77
+ """
78
+ to_encode = data.copy()
79
+ if expires_delta:
80
+ expire = datetime.utcnow() + expires_delta
81
+ else:
82
+ expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
83
+
84
+ to_encode.update({"exp": expire})
85
+ encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
86
+ return encoded_jwt
87
+
88
+
89
+ async def get_current_user(
90
+ token: str = Depends(oauth2_scheme), db: AsyncSession = Depends(get_db)
91
+ ) -> User:
92
+ """
93
+ Get current authenticated user from JWT token.
94
+
95
+ Args:
96
+ token: JWT token from Authorization header
97
+ db: Database session
98
+
99
+ Returns:
100
+ Authenticated User object
101
+
102
+ Raises:
103
+ HTTPException: If token is invalid or user not found
104
+ """
105
+ credentials_exception = HTTPException(
106
+ status_code=status.HTTP_401_UNAUTHORIZED,
107
+ detail="Could not validate credentials",
108
+ headers={"WWW-Authenticate": "Bearer"},
109
+ )
110
+
111
+ try:
112
+ payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
113
+ email: str = payload.get("sub")
114
+ if email is None:
115
+ raise credentials_exception
116
+ except JWTError:
117
+ raise credentials_exception
118
+
119
+ # Get user from database
120
+ query = select(User).where(User.email == email)
121
+ result = await db.execute(query)
122
+ user = result.scalar_one_or_none()
123
+
124
+ if user is None:
125
+ raise credentials_exception
126
+
127
+ if not user.is_active:
128
+ raise HTTPException(
129
+ status_code=status.HTTP_403_FORBIDDEN, detail="User account is inactive"
130
+ )
131
+
132
+ return user
133
+
134
+
135
+ async def get_current_active_user(current_user: User = Depends(get_current_user)) -> User:
136
+ """
137
+ Get current active user.
138
+
139
+ Args:
140
+ current_user: Current user from token
141
+
142
+ Returns:
143
+ Active user
144
+
145
+ Raises:
146
+ HTTPException: If user is inactive
147
+ """
148
+ if not current_user.is_active:
149
+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Inactive user")
150
+ return current_user
151
+
152
+
153
+ async def get_current_admin_user(current_user: User = Depends(get_current_user)) -> User:
154
+ """
155
+ Get current user with admin role.
156
+
157
+ Args:
158
+ current_user: Current user from token
159
+
160
+ Returns:
161
+ Admin user
162
+
163
+ Raises:
164
+ HTTPException: If user doesn't have admin role
165
+ """
166
+ if not current_user.is_admin():
167
+ raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin access required")
168
+ return current_user
169
+
170
+
171
+ async def get_current_superadmin_user(current_user: User = Depends(get_current_user)) -> User:
172
+ """
173
+ Get current user with superadmin role.
174
+
175
+ Args:
176
+ current_user: Current user from token
177
+
178
+ Returns:
179
+ Superadmin user
180
+
181
+ Raises:
182
+ HTTPException: If user doesn't have superadmin role
183
+ """
184
+ if not current_user.is_superadmin():
185
+ raise HTTPException(
186
+ status_code=status.HTTP_403_FORBIDDEN, detail="Superadmin access required"
187
+ )
188
+ return current_user
app/core/celery_app.py ADDED
@@ -0,0 +1,50 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Celery application configuration for JuriX.
3
+
4
+ Configures Celery with Redis broker for asynchronous task processing.
5
+
6
+ Usage:
7
+ # Start worker
8
+ celery -A app.core.celery_app worker --loglevel=info
9
+
10
+ # Monitor tasks
11
+ celery -A app.core.celery_app flower
12
+
13
+ Author: JuriX Development Team
14
+ Date: 2026-01-11
15
+ """
16
+
17
+ import logging
18
+ import os
19
+
20
+ from celery import Celery
21
+
22
+ from app.core.config import settings
23
+
24
+ os.environ.setdefault("FORKED_BY_MULTIPROCESSING", "1")
25
+
26
+ logger = logging.getLogger(__name__)
27
+
28
+ # Create Celery app with Redis broker
29
+ celery_app = Celery(
30
+ "jurix",
31
+ broker=settings.REDIS_URL,
32
+ backend=settings.REDIS_URL,
33
+ )
34
+
35
+ # Celery configuration
36
+ celery_app.conf.update(
37
+ task_serializer="json",
38
+ accept_content=["json"],
39
+ result_serializer="json",
40
+ timezone="UTC",
41
+ enable_utc=True,
42
+ task_track_started=True,
43
+ task_time_limit=3600, # 1 hour max
44
+ task_soft_time_limit=3000, # 50 minutes soft limit
45
+ worker_prefetch_multiplier=1, # One task at a time
46
+ worker_max_tasks_per_child=1000, # Restart worker after 1000 tasks
47
+ include=["app.tasks.process_law"], # Explicitly include task modules
48
+ )
49
+
50
+ logger.info("✅ Celery app configured")
app/core/config.py ADDED
@@ -0,0 +1,70 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Configuration application - Toutes les variables d'environnement."""
2
+
3
+ from pydantic_settings import BaseSettings
4
+ from typing import Optional
5
+
6
+
7
+ class Settings(BaseSettings):
8
+ """Settings de l'application."""
9
+
10
+ # App
11
+ APP_NAME: str = "JuriX API"
12
+ VERSION: str = "2.1.0"
13
+ DEBUG: bool = True
14
+ ENVIRONMENT: str = "development"
15
+
16
+ # Database
17
+ DATABASE_URL: str = "postgresql+asyncpg://jurix:jurix_dev_password_change_in_prod@localhost:5432/jurix_db"
18
+
19
+ # Redis
20
+ REDIS_URL: str = "redis://:redis_dev_password_change_in_prod@localhost:6379/0"
21
+
22
+ # Meilisearch
23
+ MEILISEARCH_URL: str = "http://localhost:7700"
24
+ MEILISEARCH_KEY: str = "meilisearch_master_key_dev_change_in_prod"
25
+
26
+ # Gemini API (LLM for RAG)
27
+ GEMINI_API_KEY: str = ""
28
+ GEMINI_MODEL: str = "gemini-3-flash"
29
+ GEMINI_EMBEDDING_MODEL: str = "models/gemini-embedding-001" # native 3072-dim embeddings
30
+
31
+ # LlamaParse (PDF extraction)
32
+ LLAMA_CLOUD_API_KEY: str = ""
33
+
34
+ # CORS — comma-separated list of extra allowed origins for production
35
+ # Example: https://jurix.vercel.app,https://www.jurix.cm
36
+ ALLOWED_ORIGINS: str = ""
37
+
38
+ # Security
39
+ SECRET_KEY: str = "dev_secret_key_change_in_production_with_openssl_rand_hex_32"
40
+ ALGORITHM: str = "HS256"
41
+ ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
42
+
43
+ # Qodo (Tests)
44
+ QODO_API_KEY: Optional[str] = None
45
+
46
+ # Zerostep (Tests E2E)
47
+ ZEROSTEP_API_KEY: Optional[str] = None
48
+
49
+ # CORS
50
+ CORS_ORIGINS: list[str] = [
51
+ "http://localhost:5173",
52
+ "http://127.0.0.1:5173",
53
+ "http://localhost:8000",
54
+ "http://127.0.0.1:8000",
55
+ "*" # Keep wildcard for flexibility if needed, but explicit ones usually take precedence
56
+ ]
57
+
58
+ # Upload limits
59
+ MAX_UPLOAD_SIZE: int = 1073741824 # 1GB in bytes for batch upload
60
+
61
+ # OCR
62
+ TESSERACT_PATH: str = r"C:\Program Files\Tesseract-OCR\tesseract.exe"
63
+
64
+ class Config:
65
+ env_file = ".env"
66
+ case_sensitive = True
67
+ extra = "ignore" # Ignore extra fields from .env
68
+
69
+
70
+ settings = Settings()
app/core/database.py ADDED
@@ -0,0 +1,160 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Gestion des sessions de base de données asynchrones.
3
+
4
+ Ce module configure SQLAlchemy 2.0 avec sessions asynchrones pour PostgreSQL.
5
+ Utilise le pattern AsyncSession pour toutes les opérations DB.
6
+
7
+ Usage dans routes FastAPI:
8
+ @router.get("/laws")
9
+ async def list_laws(db: AsyncSession = Depends(get_db)):
10
+ service = LawService(db)
11
+ return await service.list_laws()
12
+
13
+ Author: JuriX Team
14
+ """
15
+
16
+ import logging
17
+ from typing import AsyncGenerator
18
+
19
+ from sqlalchemy.ext.asyncio import (
20
+ AsyncSession,
21
+ create_async_engine,
22
+ async_sessionmaker,
23
+ )
24
+ from sqlalchemy.orm import DeclarativeBase
25
+
26
+ from app.core.config import settings
27
+
28
+ logger = logging.getLogger(__name__)
29
+
30
+
31
+ # Base class for all SQLAlchemy models
32
+ class Base(DeclarativeBase):
33
+ """Base class pour tous les modèles SQLAlchemy."""
34
+ pass
35
+
36
+
37
+ # Create async engine
38
+ engine = create_async_engine(
39
+ settings.DATABASE_URL,
40
+ echo=settings.DEBUG if hasattr(settings, 'DEBUG') else False, # Log SQL queries in debug mode
41
+ pool_size=20, # Connection pool size
42
+ max_overflow=10, # Additional connections beyond pool_size
43
+ pool_pre_ping=True, # Verify connections before using
44
+ pool_recycle=3600, # Recycle connections after 1 hour
45
+ )
46
+
47
+ # Create async session factory
48
+ AsyncSessionLocal = async_sessionmaker(
49
+ engine,
50
+ class_=AsyncSession,
51
+ expire_on_commit=False, # Don't expire objects after commit
52
+ autoflush=False, # Manual flush control
53
+ autocommit=False, # Manual commit control
54
+ )
55
+
56
+
57
+ async def get_db() -> AsyncGenerator[AsyncSession, None]:
58
+ """
59
+ Dependency pour obtenir une session DB asynchrone.
60
+
61
+ Crée une nouvelle session pour chaque requête et garantit
62
+ sa fermeture propre même en cas d'erreur.
63
+
64
+ Yields:
65
+ AsyncSession: Session de base de données asynchrone
66
+
67
+ Example:
68
+ >>> @router.get("/laws")
69
+ >>> async def list_laws(db: AsyncSession = Depends(get_db)):
70
+ ... service = LawService(db)
71
+ ... return await service.list_laws()
72
+ """
73
+ async with AsyncSessionLocal() as session:
74
+ try:
75
+ logger.debug("📦 Nouvelle session DB créée")
76
+ yield session
77
+ except Exception as e:
78
+ logger.error(f"❌ Erreur session DB: {e}")
79
+ await session.rollback()
80
+ raise
81
+ finally:
82
+ await session.close()
83
+ logger.debug("🗑️ Session DB fermée")
84
+
85
+
86
+ async def init_db() -> None:
87
+ """
88
+ Initialise les tables de la base de données.
89
+
90
+ Crée toutes les tables définies dans les modèles SQLAlchemy
91
+ si elles n'existent pas déjà.
92
+
93
+ Note:
94
+ En production, utiliser Alembic pour les migrations.
95
+ Cette fonction est principalement pour les tests.
96
+
97
+ Example:
98
+ >>> # Dans les tests
99
+ >>> await init_db()
100
+ """
101
+ async with engine.begin() as conn:
102
+ logger.info("🚀 Initialisation des tables de la base de données...")
103
+ await conn.run_sync(Base.metadata.create_all)
104
+ logger.info("✅ Tables créées avec succès")
105
+
106
+
107
+ async def drop_db() -> None:
108
+ """
109
+ Supprime toutes les tables de la base de données.
110
+
111
+ ⚠️ ATTENTION: Cette fonction est destructive!
112
+ Utilisée uniquement pour les tests.
113
+
114
+ Example:
115
+ >>> # Nettoyage après tests
116
+ >>> await drop_db()
117
+ """
118
+ async with engine.begin() as conn:
119
+ logger.warning("⚠️ Suppression de toutes les tables...")
120
+ await conn.run_sync(Base.metadata.drop_all)
121
+ logger.info("✅ Tables supprimées")
122
+
123
+
124
+ async def close_db() -> None:
125
+ """
126
+ Ferme le moteur de base de données.
127
+
128
+ Ferme toutes les connexions actives et libère les ressources.
129
+ Doit être appelé lors de l'arrêt de l'application.
130
+
131
+ Example:
132
+ >>> # Dans le shutdown event de FastAPI
133
+ >>> @app.on_event("shutdown")
134
+ >>> async def shutdown():
135
+ ... await close_db()
136
+ """
137
+ await engine.dispose()
138
+ logger.info("✅ Moteur de base de données fermé")
139
+
140
+
141
+ async def health_check_db() -> bool:
142
+ """
143
+ Vérifie la santé de la connexion à la base de données.
144
+
145
+ Returns:
146
+ bool: True si la connexion fonctionne, False sinon
147
+
148
+ Example:
149
+ >>> is_healthy = await health_check_db()
150
+ >>> if not is_healthy:
151
+ ... logger.error("DB connection failed")
152
+ """
153
+ try:
154
+ async with AsyncSessionLocal() as session:
155
+ await session.execute("SELECT 1")
156
+ logger.debug("✅ DB health check OK")
157
+ return True
158
+ except Exception as e:
159
+ logger.error(f"❌ DB health check failed: {e}")
160
+ return False
app/core/dependencies.py ADDED
@@ -0,0 +1,151 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Dependency injection pour FastAPI.
3
+
4
+ Ce module fournit des factory functions pour les services partagés.
5
+ Utilise le pattern singleton avec @lru_cache pour efficacité mémoire.
6
+
7
+ Usage dans routes:
8
+ @router.post("/detect")
9
+ async def detect_language(
10
+ detector: LanguageDetector = Depends(get_language_detector)
11
+ ):
12
+ result = detector.detect(text)
13
+ """
14
+
15
+ import logging
16
+ from functools import lru_cache
17
+
18
+ from app.services.document_classifier import DocumentClassifier
19
+ from app.services.embedding_service import EmbeddingService
20
+ from app.services.language_detector import LanguageDetector
21
+ from app.services.search_service import SearchService
22
+
23
+ logger = logging.getLogger(__name__)
24
+
25
+
26
+ @lru_cache()
27
+ def get_language_detector() -> LanguageDetector:
28
+ """
29
+ Factory pour LanguageDetector (singleton).
30
+
31
+ Utilise @lru_cache pour créer une seule instance partagée
32
+ entre toutes les requêtes. Évite le rechargement des modèles
33
+ NLP (~200MB) à chaque requête.
34
+
35
+ Returns:
36
+ Instance singleton de LanguageDetector
37
+
38
+ Raises:
39
+ LanguageDetectionError: Si les modèles ne peuvent pas être chargés
40
+
41
+ Example:
42
+ >>> from fastapi import Depends
43
+ >>> detector = Depends(get_language_detector)
44
+ """
45
+ logger.info("📦 Création du singleton LanguageDetector")
46
+ return LanguageDetector()
47
+
48
+
49
+ def clear_detector_cache():
50
+ """
51
+ Efface le cache du detector (force rechargement).
52
+
53
+ Utile pour:
54
+ - Tests (isolation entre tests)
55
+ - Mise à jour des modèles
56
+ - Debugging
57
+
58
+ Example:
59
+ >>> clear_detector_cache()
60
+ >>> detector = get_language_detector() # Nouvelle instance
61
+ """
62
+ get_language_detector.cache_clear()
63
+ logger.info("🗑️ Cache LanguageDetector effacé")
64
+
65
+
66
+ @lru_cache()
67
+ def get_document_classifier() -> DocumentClassifier:
68
+ """
69
+ Factory pour DocumentClassifier (singleton).
70
+
71
+ Utilise @lru_cache pour créer une seule instance partagée
72
+ entre toutes les requêtes. Évite le rechargement des modèles
73
+ ML à chaque requête (Phase 3).
74
+
75
+ Returns:
76
+ Instance singleton de DocumentClassifier
77
+
78
+ Example:
79
+ >>> from fastapi import Depends
80
+ >>> classifier = Depends(get_document_classifier)
81
+ """
82
+ logger.info("📦 Création du singleton DocumentClassifier")
83
+ return DocumentClassifier()
84
+
85
+
86
+ def clear_classifier_cache():
87
+ """
88
+ Efface le cache du classifier (force rechargement).
89
+
90
+ Utile pour:
91
+ - Tests (isolation entre tests)
92
+ - Mise à jour des modèles ML
93
+ - Debugging
94
+
95
+ Example:
96
+ >>> clear_classifier_cache()
97
+ >>> classifier = get_document_classifier() # Nouvelle instance
98
+ """
99
+ get_document_classifier.cache_clear()
100
+ logger.info("🗑️ Cache DocumentClassifier effacé")
101
+
102
+
103
+ @lru_cache()
104
+ def get_embedding_service() -> EmbeddingService:
105
+ """
106
+ Factory pour EmbeddingService (singleton).
107
+
108
+ Utilise @lru_cache pour créer une seule instance partagée
109
+ entre toutes les requêtes. Évite le rechargement du modèle
110
+ sentence-transformers (~120MB) à chaque requête.
111
+
112
+ Returns:
113
+ Instance singleton de EmbeddingService
114
+
115
+ Raises:
116
+ EmbeddingServiceError: Si le modèle ne peut pas être chargé
117
+
118
+ Example:
119
+ >>> from fastapi import Depends
120
+ >>> service = Depends(get_embedding_service)
121
+ """
122
+ logger.info("📦 Création du singleton EmbeddingService")
123
+ return EmbeddingService()
124
+
125
+
126
+ def clear_embedding_service_cache():
127
+ """
128
+ Efface le cache du service d'embeddings (force rechargement).
129
+
130
+ Utile pour:
131
+ - Tests (isolation entre tests)
132
+ - Mise à jour des modèles
133
+ - Debugging
134
+
135
+ Example:
136
+ >>> clear_embedding_service_cache()
137
+ >>> service = get_embedding_service() # Nouvelle instance
138
+ """
139
+ get_embedding_service.cache_clear()
140
+ logger.info("🗑️ Cache EmbeddingService effacé")
141
+
142
+
143
+ # Exports for dependency injection
144
+ __all__ = [
145
+ "get_language_detector",
146
+ "get_document_classifier",
147
+ "get_embedding_service",
148
+ "clear_detector_cache",
149
+ "clear_classifier_cache",
150
+ "clear_embedding_service_cache",
151
+ ]
app/main.py ADDED
@@ -0,0 +1,77 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Point d'entrée FastAPI."""
2
+
3
+ from fastapi import FastAPI
4
+ from fastapi.middleware.cors import CORSMiddleware
5
+ from app.core.config import settings
6
+ from app.api.routes import language, classifier, articles, search, rag, categories, personas, upload, ocr, laws, analytics, admin, batch_upload
7
+
8
+ app = FastAPI(
9
+ title=settings.APP_NAME,
10
+ version=settings.VERSION,
11
+ debug=settings.DEBUG
12
+ )
13
+
14
+ # CORS — allow localhost in dev, Vercel domain in prod
15
+ # Set ALLOWED_ORIGINS in your env for production (comma-separated)
16
+ _extra_origins = [o.strip() for o in settings.ALLOWED_ORIGINS.split(",") if o.strip()]
17
+ _cors_origins = [
18
+ "http://localhost:5173",
19
+ "http://localhost:4173",
20
+ "http://127.0.0.1:5173",
21
+ ] + _extra_origins
22
+
23
+ app.add_middleware(
24
+ CORSMiddleware,
25
+ allow_origins=_cors_origins,
26
+ allow_credentials=True,
27
+ allow_methods=["*"],
28
+ allow_headers=["*"],
29
+ )
30
+
31
+
32
+ @app.get("/")
33
+ async def root():
34
+ """Root endpoint."""
35
+ return {
36
+ "message": "JuriX API v2.1",
37
+ "status": "running",
38
+ "version": settings.VERSION
39
+ }
40
+
41
+
42
+ @app.get("/health")
43
+ async def health():
44
+ """Health check endpoint."""
45
+ return {"status": "healthy"}
46
+
47
+
48
+ # Include routers
49
+ app.include_router(language.router)
50
+ app.include_router(classifier.router)
51
+ app.include_router(articles.router)
52
+ app.include_router(
53
+ search.router,
54
+ prefix="/api/v1/search",
55
+ tags=["search"]
56
+ )
57
+ app.include_router(
58
+ rag.router,
59
+ prefix="/api/v1/rag",
60
+ tags=["rag", "chatbot"]
61
+ )
62
+ app.include_router(
63
+ categories.router,
64
+ tags=["categories"]
65
+ )
66
+ app.include_router(
67
+ personas.router,
68
+ tags=["personas"]
69
+ )
70
+ app.include_router(upload.router)
71
+ app.include_router(ocr.router)
72
+ app.include_router(laws.router)
73
+ app.include_router(analytics.router)
74
+ app.include_router(admin.router)
75
+ app.include_router(batch_upload.router) # Batch upload with WebSocket
76
+ # Trigger reload
77
+
app/models/__init__.py ADDED
@@ -0,0 +1,30 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Database models for JuriX application.
3
+
4
+ Exports all SQLAlchemy models for easy import.
5
+ """
6
+
7
+ from app.models.conversation import (
8
+ Conversation,
9
+ Message,
10
+ MessageFeedback,
11
+ PersonaInteraction,
12
+ PersonaStat,
13
+ )
14
+ from app.models.law import Article, Category, Law
15
+ from app.models.user import User
16
+
17
+ __all__ = [
18
+ # Law models
19
+ "Law",
20
+ "Article",
21
+ "Category",
22
+ # Conversation models
23
+ "Conversation",
24
+ "Message",
25
+ "PersonaStat",
26
+ "MessageFeedback",
27
+ "PersonaInteraction",
28
+ # User models
29
+ "User",
30
+ ]
app/models/conversation.py ADDED
@@ -0,0 +1,224 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Database models for RAG conversation tracking.
3
+
4
+ Stores conversation sessions and individual messages with sources and metadata.
5
+ """
6
+
7
+ from datetime import date, datetime
8
+
9
+ from sqlalchemy import (
10
+ JSON,
11
+ Boolean,
12
+ CheckConstraint,
13
+ Column,
14
+ Date,
15
+ DateTime,
16
+ Float,
17
+ ForeignKey,
18
+ Index,
19
+ Integer,
20
+ String,
21
+ Text,
22
+ UniqueConstraint,
23
+ )
24
+ from sqlalchemy.orm import relationship
25
+
26
+ from app.core.database import Base
27
+
28
+
29
+ class Conversation(Base):
30
+ """
31
+ Conversation session tracking for RAG chatbot.
32
+
33
+ Each conversation represents a session with a specific persona and language.
34
+ Conversations can span multiple questions and maintain context.
35
+ """
36
+
37
+ __tablename__ = "conversations"
38
+
39
+ id = Column(Integer, primary_key=True, index=True)
40
+ session_id = Column(String(100), unique=True, index=True, nullable=False)
41
+ user_id = Column(
42
+ Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
43
+ )
44
+ persona = Column(String(50), nullable=False) # citoyen/avocat/entrepreneur/étudiant
45
+ language = Column(String(2), nullable=False, default="fr") # fr/en
46
+ created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
47
+ updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
48
+
49
+ # Relationships
50
+ user = relationship("User", back_populates="conversations", lazy="selectin")
51
+ messages = relationship(
52
+ "Message",
53
+ back_populates="conversation",
54
+ cascade="all, delete-orphan",
55
+ order_by="Message.created_at",
56
+ )
57
+
58
+ def __repr__(self):
59
+ return f"<Conversation(id={self.id}, session_id={self.session_id}, persona={self.persona})>"
60
+
61
+
62
+ class Message(Base):
63
+ """
64
+ Individual messages in conversation (user questions and assistant responses).
65
+
66
+ Stores message content, role, sources, confidence, and performance metrics.
67
+ """
68
+
69
+ __tablename__ = "messages"
70
+
71
+ id = Column(Integer, primary_key=True, index=True)
72
+ conversation_id = Column(
73
+ Integer, ForeignKey("conversations.id", ondelete="CASCADE"), nullable=False, index=True
74
+ )
75
+ role = Column(String(20), nullable=False) # "user" or "assistant"
76
+ content = Column(Text, nullable=False)
77
+ sources = Column(JSON, nullable=True) # [{"law_id": 1, "article_number": "5", ...}]
78
+ confidence = Column(Float, nullable=True) # 0.0-1.0 for assistant messages
79
+ retrieval_time_ms = Column(Integer, nullable=True)
80
+ generation_time_ms = Column(Integer, nullable=True)
81
+ created_at = Column(DateTime, nullable=False, default=datetime.utcnow, index=True)
82
+
83
+ # Relationships
84
+ conversation = relationship("Conversation", back_populates="messages")
85
+
86
+ def __repr__(self):
87
+ return f"<Message(id={self.id}, role={self.role}, conversation_id={self.conversation_id})>"
88
+
89
+
90
+ # Create indexes for performance
91
+ Index("idx_conversations_session_id", Conversation.session_id)
92
+ Index("idx_messages_conversation_id", Message.conversation_id)
93
+ Index("idx_messages_created_at", Message.created_at.desc())
94
+
95
+
96
+ class PersonaStat(Base):
97
+ """
98
+ Aggregated daily statistics per persona.
99
+
100
+ Generated by Celery task daily at midnight UTC.
101
+ Provides pre-aggregated metrics for fast analytics queries.
102
+ """
103
+
104
+ __tablename__ = "persona_stats"
105
+
106
+ id = Column(Integer, primary_key=True, index=True)
107
+ persona = Column(String(50), nullable=False) # citoyen|avocat|entrepreneur|étudiant
108
+ date = Column(Date, nullable=False)
109
+
110
+ # Usage Metrics
111
+ total_questions = Column(Integer, nullable=False, default=0)
112
+ total_conversations = Column(Integer, nullable=False, default=0)
113
+ unique_sessions = Column(Integer, nullable=False, default=0)
114
+
115
+ # Performance Metrics
116
+ avg_confidence = Column(Float, nullable=False, default=0.0)
117
+ avg_retrieval_time_ms = Column(Integer, nullable=False, default=0)
118
+ avg_generation_time_ms = Column(Integer, nullable=False, default=0)
119
+ avg_total_time_ms = Column(Integer, nullable=False, default=0)
120
+
121
+ # Engagement Metrics
122
+ avg_messages_per_conversation = Column(Float, nullable=False, default=0.0)
123
+ avg_session_duration_seconds = Column(Integer, nullable=False, default=0)
124
+
125
+ # Quality Metrics
126
+ helpful_count = Column(Integer, nullable=False, default=0)
127
+ unhelpful_count = Column(Integer, nullable=False, default=0)
128
+ satisfaction_rate = Column(Float, nullable=False, default=0.0)
129
+
130
+ # Metadata
131
+ created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
132
+ updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
133
+
134
+ __table_args__ = (UniqueConstraint("persona", "date", name="uq_persona_date"),)
135
+
136
+ def __repr__(self):
137
+ return f"<PersonaStat(persona={self.persona}, date={self.date}, questions={self.total_questions})>"
138
+
139
+
140
+ class MessageFeedback(Base):
141
+ """
142
+ User ratings and feedback on assistant messages.
143
+
144
+ Allows users to rate messages with ����/👎 and optional rating (1-5).
145
+ One feedback per message (unique constraint).
146
+ """
147
+
148
+ __tablename__ = "message_feedback"
149
+
150
+ id = Column(Integer, primary_key=True, index=True)
151
+ message_id = Column(
152
+ Integer, ForeignKey("messages.id", ondelete="CASCADE"), nullable=False, unique=True
153
+ )
154
+ helpful = Column(Boolean, nullable=False)
155
+ rating = Column(Integer, nullable=True) # 1-5 scale
156
+ comment = Column(Text, nullable=True)
157
+ created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
158
+
159
+ # Relationships
160
+ message = relationship("Message", backref="feedback")
161
+
162
+ __table_args__ = (CheckConstraint("rating >= 1 AND rating <= 5", name="ck_rating_range"),)
163
+
164
+ def __repr__(self):
165
+ return f"<MessageFeedback(message_id={self.message_id}, helpful={self.helpful})>"
166
+
167
+
168
+ class PersonaInteraction(Base):
169
+ """
170
+ Per-session analytics for persona usage.
171
+
172
+ Tracks question/answer counts, confidence, response times, and persona switches
173
+ within a conversation session.
174
+ """
175
+
176
+ __tablename__ = "persona_interactions"
177
+
178
+ id = Column(Integer, primary_key=True, index=True)
179
+ conversation_id = Column(
180
+ Integer, ForeignKey("conversations.id", ondelete="CASCADE"), nullable=False, index=True
181
+ )
182
+ persona = Column(String(50), nullable=False)
183
+ language = Column(String(2), nullable=False)
184
+
185
+ # Interaction Counts
186
+ question_count = Column(Integer, nullable=False, default=0)
187
+ answer_count = Column(Integer, nullable=False, default=0)
188
+
189
+ # Performance
190
+ avg_confidence = Column(Float, nullable=False, default=0.0)
191
+ total_response_time_ms = Column(Integer, nullable=False, default=0)
192
+
193
+ # Persona Behavior
194
+ personas_used = Column(JSON, nullable=True) # Array of all personas used
195
+ persona_switches = Column(Integer, nullable=False, default=0)
196
+
197
+ # Metadata
198
+ created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
199
+ updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
200
+
201
+ # Relationships
202
+ conversation = relationship("Conversation", backref="persona_interactions")
203
+
204
+ def __repr__(self):
205
+ return (
206
+ f"<PersonaInteraction(conversation_id={self.conversation_id}, persona={self.persona})>"
207
+ )
208
+
209
+
210
+ # Create indexes for analytics tables
211
+ Index("idx_persona_stats_persona_date", PersonaStat.persona, PersonaStat.date.desc())
212
+ Index("idx_persona_stats_date", PersonaStat.date.desc())
213
+ Index(
214
+ "idx_message_feedback_message_id_helpful", MessageFeedback.message_id, MessageFeedback.helpful
215
+ )
216
+ Index("idx_message_feedback_created_at", MessageFeedback.created_at.desc())
217
+ Index("idx_message_feedback_helpful", MessageFeedback.helpful)
218
+ Index(
219
+ "idx_persona_interactions_persona_created",
220
+ PersonaInteraction.persona,
221
+ PersonaInteraction.created_at.desc(),
222
+ )
223
+ Index("idx_persona_interactions_conversation_id", PersonaInteraction.conversation_id)
224
+ Index("idx_persona_interactions_created_at", PersonaInteraction.created_at.desc())
app/models/law.py ADDED
@@ -0,0 +1,245 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Modèles SQLAlchemy pour les lois, articles et catégories.
3
+
4
+ Ce module définit les modèles de base de données pour le système JuriX:
5
+ - Law: Documents juridiques (lois, décrets, ordonnances)
6
+ - Article: Articles individuels d'une loi
7
+ - Category: Catégories juridiques (12 catégories camerounaises)
8
+
9
+ Features v2.1:
10
+ - Détection automatique de langue (language, language_confidence)
11
+ - Suggestions de catégories (suggested_categories, category_confidence)
12
+ - Support pgvector pour embeddings sémantiques
13
+
14
+ Author: JuriX Team
15
+ """
16
+
17
+ from datetime import datetime, date
18
+ from typing import List, Optional
19
+
20
+ from sqlalchemy import (
21
+ Column,
22
+ Integer,
23
+ String,
24
+ Text,
25
+ Float,
26
+ Date,
27
+ DateTime,
28
+ ForeignKey,
29
+ Index,
30
+ JSON,
31
+ )
32
+ from sqlalchemy.dialects.postgresql import ARRAY
33
+ from sqlalchemy.orm import relationship
34
+ from sqlalchemy.sql import func
35
+ from pgvector.sqlalchemy import Vector
36
+
37
+ from app.core.database import Base
38
+
39
+
40
+ # Type adapter for suggested_categories - uses ARRAY for PostgreSQL, JSON for others
41
+ def get_array_type():
42
+ """Get appropriate array type based on database dialect."""
43
+ import os
44
+ db_url = os.getenv("DATABASE_URL", "")
45
+ if "postgresql" in db_url or "asyncpg" in db_url:
46
+ return ARRAY(Integer)
47
+ else:
48
+ # Use JSON for SQLite and other databases
49
+ return JSON
50
+
51
+
52
+ class Category(Base):
53
+ """
54
+ Modèle pour les catégories juridiques.
55
+
56
+ Représente les 12 catégories de droit camerounais:
57
+ 1. Droit Constitutionnel
58
+ 2. Droit Civil
59
+ 3. Droit Pénal
60
+ 4. Droit Commercial OHADA
61
+ 5. Droit du Travail
62
+ 6. Droit Fiscal
63
+ 7. Droit Administratif
64
+ 8. Droit Foncier
65
+ 9. Droit de la Famille
66
+ 10. Droit de l'Environnement
67
+ 11. Droit International
68
+ 12. Droit des Affaires
69
+
70
+ Attributes:
71
+ id: Identifiant unique
72
+ name: Nom de la catégorie
73
+ description: Description détaillée
74
+ created_at: Date de création
75
+ laws: Relation vers les lois de cette catégorie
76
+ """
77
+
78
+ __tablename__ = "categories"
79
+
80
+ # Primary key
81
+ id = Column(Integer, primary_key=True, index=True)
82
+
83
+ # Fields
84
+ name = Column(String(100), nullable=False)
85
+ description = Column(Text, nullable=True)
86
+ icon = Column(String(10), nullable=True) # Emoji icon for category
87
+ display_order = Column(Integer, nullable=False, default=0) # Order for display
88
+
89
+ # Metadata
90
+ created_at = Column(DateTime, server_default=func.now(), nullable=False)
91
+
92
+ # Relationships
93
+ laws = relationship("Law", back_populates="category", lazy="selectin")
94
+
95
+ def __repr__(self) -> str:
96
+ return f"<Category(id={self.id}, name='{self.name}')>"
97
+
98
+
99
+ class Law(Base):
100
+ """
101
+ Modèle pour les documents juridiques (lois).
102
+
103
+ Représente un document juridique complet (loi, décret, ordonnance, arrêté)
104
+ avec ses métadonnées, sa catégorisation et ses articles.
105
+
106
+ Features v2.1:
107
+ - Détection automatique de langue
108
+ - Suggestions de catégories automatiques
109
+ - Scores de confiance pour détection/classification
110
+
111
+ Attributes:
112
+ id: Identifiant unique
113
+ reference: Référence officielle (ex: "LOI-2024-001")
114
+ title: Titre de la loi
115
+ type: Type de document (loi, décret, ordonnance, arrêté)
116
+ content: Contenu complet de la loi
117
+ language: Langue détectée ou définie (fr, en)
118
+ language_confidence: Score de confiance de détection (0.0-1.0)
119
+ detected_language: Langue auto-détectée
120
+ suggested_categories: IDs des catégories suggérées (top 3)
121
+ category_confidence: Score de confiance catégorie principale
122
+ category_id: Catégorie assignée
123
+ status: Statut (draft, published, archived)
124
+ publication_date: Date de publication officielle
125
+ created_at: Date de création dans le système
126
+ updated_at: Date de dernière mise à jour
127
+ category: Relation vers la catégorie
128
+ articles: Relation vers les articles
129
+ """
130
+
131
+ __tablename__ = "laws"
132
+
133
+ # Primary key
134
+ id = Column(Integer, primary_key=True, index=True)
135
+
136
+ # Core fields
137
+ reference = Column(String(500), nullable=False, unique=True, index=True)
138
+ title = Column(String(500), nullable=False)
139
+ type = Column(String(50), nullable=False) # loi, décret, ordonnance, arrêté
140
+ content = Column(Text, nullable=False)
141
+
142
+ # v2.1 Auto-detection fields
143
+ language = Column(String(2), nullable=True, index=True) # fr, en
144
+ language_confidence = Column(Float, nullable=True)
145
+ detected_language = Column(String(2), nullable=True)
146
+ suggested_categories = Column(JSON, nullable=True) # List[int] stored as JSON for compatibility
147
+ category_confidence = Column(Float, nullable=True)
148
+
149
+ # File tracking
150
+ file_id = Column(String(100), nullable=True, index=True) # UUID of uploaded file
151
+ original_filename = Column(String(500), nullable=True) # Original filename
152
+
153
+ # Relationships
154
+ category_id = Column(Integer, ForeignKey("categories.id"), nullable=True, index=True)
155
+ category = relationship("Category", back_populates="laws", lazy="selectin")
156
+ articles = relationship(
157
+ "Article",
158
+ back_populates="law",
159
+ cascade="all, delete-orphan",
160
+ lazy="selectin"
161
+ )
162
+
163
+
164
+ # Status & metadata
165
+ status = Column(String(20), nullable=False, server_default="draft", index=True) # draft, published, archived, pending, processing, refused
166
+ processing_progress = Column(Integer, nullable=True) # 0-100 for batch upload tracking
167
+ processing_error = Column(Text, nullable=True) # Error message if processing failed
168
+ processing_started_at = Column(DateTime, nullable=True) # When processing started
169
+ publication_date = Column(Date, nullable=True)
170
+ created_at = Column(DateTime, server_default=func.now(), nullable=False)
171
+ updated_at = Column(
172
+ DateTime,
173
+ server_default=func.now(),
174
+ onupdate=func.now(),
175
+ nullable=False
176
+ )
177
+
178
+ def __repr__(self) -> str:
179
+ return f"<Law(id={self.id}, reference='{self.reference}', title='{self.title[:50]}...')>"
180
+
181
+ @property
182
+ def article_count(self) -> int:
183
+ """Nombre d'articles dans cette loi."""
184
+ return len(self.articles) if self.articles else 0
185
+
186
+
187
+ class Article(Base):
188
+ """
189
+ Modèle pour les articles individuels d'une loi.
190
+
191
+ Représente un article spécifique d'un document juridique,
192
+ avec son contenu et son embedding vectoriel pour la recherche sémantique.
193
+
194
+ Attributes:
195
+ id: Identifiant unique
196
+ law_id: ID de la loi parent
197
+ number: Numéro de l'article (ex: "1er", "2", "3bis")
198
+ title: Titre optionnel de l'article
199
+ content: Contenu textuel de l'article
200
+ embedding: Vecteur d'embedding (3072 dimensions) pour recherche sémantique
201
+ order: Ordre dans la loi (pour tri)
202
+ created_at: Date de création
203
+ law: Relation vers la loi parent
204
+ """
205
+
206
+ __tablename__ = "articles"
207
+
208
+ # Primary key
209
+ id = Column(Integer, primary_key=True, index=True)
210
+
211
+ # Foreign key
212
+ law_id = Column(
213
+ Integer,
214
+ ForeignKey("laws.id", ondelete="CASCADE"),
215
+ nullable=False,
216
+ index=True
217
+ )
218
+
219
+ # Fields
220
+ number = Column(String(20), nullable=False)
221
+ title = Column(String(200), nullable=True)
222
+ section = Column(String(300), nullable=True) # TITRE/CHAPITRE section header
223
+ content = Column(Text, nullable=False)
224
+
225
+ # pgvector embedding for semantic search (3072-dimensional vector from Gemini)
226
+ embedding = Column(Vector(3072), nullable=True)
227
+
228
+ # Metadata
229
+ order = Column(Integer, nullable=False) # Position in law
230
+ page_number = Column(Integer, nullable=True) # PDF page number (1-indexed) for navigation
231
+ created_at = Column(DateTime, server_default=func.now(), nullable=False)
232
+
233
+ # Relationships
234
+ law = relationship("Law", back_populates="articles")
235
+
236
+ def __repr__(self) -> str:
237
+ return f"<Article(id={self.id}, number='{self.number}', law_id={self.law_id})>"
238
+
239
+
240
+ # Indexes for performance
241
+ Index("idx_laws_language", Law.language)
242
+ Index("idx_laws_category", Law.category_id)
243
+ Index("idx_laws_status", Law.status)
244
+ Index("idx_laws_reference", Law.reference)
245
+ Index("idx_articles_law", Article.law_id)
app/models/user.py ADDED
@@ -0,0 +1,107 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ User model for authentication and authorization.
3
+
4
+ Provides user management with role-based access control (RBAC).
5
+
6
+ Author: JuriX Team
7
+ Date: 2026-01-12
8
+ """
9
+
10
+ from datetime import datetime
11
+ from typing import Optional
12
+
13
+ from sqlalchemy import Boolean, Column, DateTime, Integer, String
14
+ from sqlalchemy.orm import relationship
15
+
16
+ from app.core.database import Base
17
+
18
+
19
+ class User(Base):
20
+ """
21
+ User model for authentication and authorization.
22
+
23
+ Attributes:
24
+ id: Unique user identifier
25
+ email: User email (unique, used for login)
26
+ username: Display username
27
+ hashed_password: Bcrypt hashed password
28
+ full_name: User's full name
29
+ role: User role (user, admin, superadmin)
30
+ is_active: Account active status
31
+ is_verified: Email verification status
32
+ created_at: Account creation timestamp
33
+ updated_at: Last update timestamp
34
+ last_login_at: Last login timestamp
35
+
36
+ Relationships:
37
+ conversations: User's chat conversations
38
+ """
39
+
40
+ __tablename__ = "users"
41
+
42
+ # Primary key
43
+ id = Column(Integer, primary_key=True, index=True)
44
+
45
+ # Authentication
46
+ email = Column(String(255), unique=True, index=True, nullable=False)
47
+ username = Column(String(100), unique=True, index=True, nullable=False)
48
+ hashed_password = Column(String(255), nullable=False)
49
+
50
+ # Profile
51
+ full_name = Column(String(255), nullable=True)
52
+
53
+ # Authorization
54
+ role = Column(
55
+ String(50),
56
+ nullable=False,
57
+ default="user",
58
+ index=True,
59
+ comment="Role: user, admin, superadmin",
60
+ )
61
+
62
+ # Status flags
63
+ is_active = Column(Boolean, default=True, nullable=False)
64
+ is_verified = Column(Boolean, default=False, nullable=False)
65
+
66
+ # Timestamps
67
+ created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
68
+ updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
69
+ last_login_at = Column(DateTime, nullable=True)
70
+
71
+ # Relationships
72
+ conversations = relationship(
73
+ "Conversation", back_populates="user", cascade="all, delete-orphan", lazy="selectin"
74
+ )
75
+
76
+ def __repr__(self) -> str:
77
+ return f"<User(id={self.id}, email='{self.email}', role='{self.role}')>"
78
+
79
+ def has_role(self, required_role: str) -> bool:
80
+ """
81
+ Check if user has required role or higher.
82
+
83
+ Role hierarchy: superadmin > admin > user
84
+
85
+ Args:
86
+ required_role: Required role to check
87
+
88
+ Returns:
89
+ True if user has required role or higher
90
+
91
+ Example:
92
+ >>> user.role = "admin"
93
+ >>> user.has_role("user") # True
94
+ >>> user.has_role("superadmin") # False
95
+ """
96
+ role_hierarchy = {"superadmin": 3, "admin": 2, "user": 1}
97
+ user_level = role_hierarchy.get(self.role, 0)
98
+ required_level = role_hierarchy.get(required_role, 0)
99
+ return user_level >= required_level
100
+
101
+ def is_admin(self) -> bool:
102
+ """Check if user has admin or superadmin role."""
103
+ return self.role in ("admin", "superadmin")
104
+
105
+ def is_superadmin(self) -> bool:
106
+ """Check if user has superadmin role."""
107
+ return self.role == "superadmin"
app/schemas/file_upload.py ADDED
@@ -0,0 +1,238 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Pydantic schemas for file upload operations.
3
+
4
+ Provides request/response models with validation for:
5
+ - File upload results
6
+ - File metadata (PDF, DOCX)
7
+ - Validation results
8
+ - Antivirus scan results
9
+
10
+ Author: JuriX Development Team
11
+ Date: 2026-01-11
12
+ """
13
+
14
+ from datetime import datetime
15
+ from typing import List, Optional
16
+
17
+ from pydantic import BaseModel, Field, field_validator
18
+
19
+
20
+ # ============================================================================
21
+ # File Upload Result Schemas
22
+ # ============================================================================
23
+
24
+
25
+ class FileMetadata(BaseModel):
26
+ """
27
+ Metadata extracted from uploaded files.
28
+
29
+ Fields vary by file type:
30
+ - PDF: title, author, creation_date, page_count
31
+ - DOCX: title, author, creation_date, word_count
32
+ """
33
+
34
+ title: Optional[str] = Field(None, description="Document title")
35
+ author: Optional[str] = Field(None, description="Document author")
36
+ creation_date: Optional[datetime] = Field(None, description="Document creation date")
37
+ page_count: Optional[int] = Field(None, ge=0, description="Number of pages (PDF only)")
38
+ word_count: Optional[int] = Field(None, ge=0, description="Number of words (DOCX only)")
39
+ file_size: int = Field(..., ge=0, description="File size in bytes")
40
+ file_hash: str = Field(..., min_length=64, max_length=64, description="SHA-256 hash")
41
+
42
+ class Config:
43
+ json_schema_extra = {
44
+ "example": {
45
+ "title": "Loi N°2024-015",
46
+ "author": "République du Cameroun",
47
+ "creation_date": "2024-01-15T10:30:00",
48
+ "page_count": 45,
49
+ "file_size": 2048576,
50
+ "file_hash": "a" * 64,
51
+ }
52
+ }
53
+
54
+
55
+ class ValidationResult(BaseModel):
56
+ """
57
+ Result of file validation checks.
58
+
59
+ Validates:
60
+ - File format (PDF, DOCX)
61
+ - File size (max 50 MB)
62
+ - File structure integrity
63
+ - MIME type
64
+ """
65
+
66
+ is_valid: bool = Field(..., description="Whether file passed all validation checks")
67
+ format: Optional[str] = Field(None, description="Detected file format (pdf or docx)")
68
+ mime_type: str = Field(..., description="Detected MIME type")
69
+ errors: List[str] = Field(default_factory=list, description="List of validation errors")
70
+ warnings: List[str] = Field(default_factory=list, description="List of validation warnings")
71
+
72
+ class Config:
73
+ json_schema_extra = {
74
+ "example": {
75
+ "is_valid": True,
76
+ "format": "pdf",
77
+ "mime_type": "application/pdf",
78
+ "errors": [],
79
+ "warnings": [],
80
+ }
81
+ }
82
+
83
+
84
+ class ScanResult(BaseModel):
85
+ """
86
+ Result of antivirus scan.
87
+
88
+ Supports:
89
+ - ClamAV (production)
90
+ - Mock scanner (development)
91
+ """
92
+
93
+ is_clean: bool = Field(..., description="Whether file is clean (no threats detected)")
94
+ scanner: str = Field(..., description="Scanner used (clamav or mock)")
95
+ scan_time_ms: int = Field(..., ge=0, description="Scan duration in milliseconds")
96
+ threat_found: Optional[str] = Field(None, description="Name of threat if detected")
97
+ scanner_version: Optional[str] = Field(None, description="Scanner version")
98
+
99
+ @field_validator("scanner")
100
+ @classmethod
101
+ def validate_scanner(cls, v: str) -> str:
102
+ """Validate scanner type."""
103
+ allowed_scanners = {"clamav", "mock"}
104
+ if v.lower() not in allowed_scanners:
105
+ raise ValueError(f"Scanner must be one of: {', '.join(allowed_scanners)}. Got: {v}")
106
+ return v.lower()
107
+
108
+ class Config:
109
+ json_schema_extra = {
110
+ "example": {
111
+ "is_clean": True,
112
+ "scanner": "mock",
113
+ "scan_time_ms": 150,
114
+ "threat_found": None,
115
+ "scanner_version": "1.0.0",
116
+ }
117
+ }
118
+
119
+
120
+ class FileUploadResult(BaseModel):
121
+ """
122
+ Complete result of file upload operation.
123
+
124
+ Includes:
125
+ - File identification
126
+ - Validation results
127
+ - Scan results
128
+ - Extracted metadata
129
+ - Storage information
130
+ """
131
+
132
+ file_id: str = Field(..., description="Unique file identifier (UUID)")
133
+ filename: str = Field(..., min_length=1, description="Original filename")
134
+ file_size: int = Field(..., ge=0, description="File size in bytes")
135
+ mime_type: str = Field(..., description="Detected MIME type")
136
+ file_hash: str = Field(..., min_length=64, max_length=64, description="SHA-256 hash")
137
+
138
+ # Nested results
139
+ metadata: FileMetadata = Field(..., description="Extracted file metadata")
140
+ validation: ValidationResult = Field(..., description="Validation results")
141
+ scan_result: ScanResult = Field(..., description="Antivirus scan results")
142
+
143
+ # Storage info
144
+ storage_path: str = Field(..., description="Relative path to stored file")
145
+ uploaded_at: datetime = Field(..., description="Upload timestamp")
146
+ expires_at: Optional[datetime] = Field(None, description="Expiration timestamp for temp files")
147
+
148
+ class Config:
149
+ json_schema_extra = {
150
+ "example": {
151
+ "file_id": "550e8400-e29b-41d4-a716-446655440000",
152
+ "filename": "loi_2024_015.pdf",
153
+ "file_size": 2048576,
154
+ "mime_type": "application/pdf",
155
+ "file_hash": "a" * 64,
156
+ "metadata": {
157
+ "title": "Loi N°2024-015",
158
+ "author": "République du Cameroun",
159
+ "page_count": 45,
160
+ "file_size": 2048576,
161
+ "file_hash": "a" * 64,
162
+ },
163
+ "validation": {
164
+ "is_valid": True,
165
+ "format": "pdf",
166
+ "mime_type": "application/pdf",
167
+ "errors": [],
168
+ "warnings": [],
169
+ },
170
+ "scan_result": {
171
+ "is_clean": True,
172
+ "scanner": "mock",
173
+ "scan_time_ms": 150,
174
+ },
175
+ "storage_path": "uploads/550e8400-e29b-41d4-a716-446655440000.pdf",
176
+ "uploaded_at": "2024-01-15T10:30:00",
177
+ "expires_at": "2024-01-16T10:30:00",
178
+ }
179
+ }
180
+
181
+
182
+ # ============================================================================
183
+ # Request Schemas
184
+ # ============================================================================
185
+
186
+
187
+ class FileUploadRequest(BaseModel):
188
+ """
189
+ Request schema for file upload (for documentation).
190
+
191
+ Note: Actual upload uses multipart/form-data, not JSON.
192
+ This schema is for OpenAPI documentation only.
193
+ """
194
+
195
+ file: str = Field(..., description="File to upload (multipart/form-data)")
196
+
197
+ class Config:
198
+ json_schema_extra = {
199
+ "example": {
200
+ "file": "binary file data",
201
+ }
202
+ }
203
+
204
+
205
+ # ============================================================================
206
+ # Health Check Schema
207
+ # ============================================================================
208
+
209
+
210
+ class UploadServiceHealth(BaseModel):
211
+ """Health check response for upload service."""
212
+
213
+ service: str = Field(default="FileUploadService", description="Service name")
214
+ status: str = Field(..., description="Service status (healthy, degraded, unhealthy)")
215
+ storage: dict = Field(..., description="Storage status and statistics")
216
+ scanner: dict = Field(..., description="Antivirus scanner status")
217
+ timestamp: datetime = Field(..., description="Health check timestamp")
218
+
219
+ class Config:
220
+ json_schema_extra = {
221
+ "example": {
222
+ "service": "FileUploadService",
223
+ "status": "healthy",
224
+ "storage": {
225
+ "path": "/app/data/uploads",
226
+ "exists": True,
227
+ "writable": True,
228
+ "total_files": 42,
229
+ "total_size_mb": 128.5,
230
+ },
231
+ "scanner": {
232
+ "type": "mock",
233
+ "available": True,
234
+ "version": "1.0.0",
235
+ },
236
+ "timestamp": "2024-01-15T10:30:00",
237
+ }
238
+ }
app/schemas/law.py ADDED
@@ -0,0 +1,467 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Pydantic schemas for Law CRUD operations.
3
+
4
+ Provides request/response models with validation for:
5
+ - Law creation, update, and response
6
+ - Category operations
7
+ - Article management
8
+ - Filtering and pagination
9
+ - v2.1 features: language filtering, category suggestions, confidence scores
10
+
11
+ Author: JuriX Development Team
12
+ Date: 2026-01-10
13
+ """
14
+
15
+ from datetime import date, datetime
16
+ from typing import List, Optional
17
+
18
+ from pydantic import BaseModel, Field, field_validator
19
+
20
+ # ============================================================================
21
+ # Category Schemas
22
+ # ============================================================================
23
+
24
+
25
+ class CategoryBase(BaseModel):
26
+ """Base schema for Category with shared fields."""
27
+
28
+ name: str = Field(..., min_length=1, max_length=100, description="Category name")
29
+ description: Optional[str] = Field(None, description="Category description")
30
+ icon: Optional[str] = Field(None, max_length=10, description="Emoji icon for category")
31
+
32
+
33
+ class CategoryCreate(CategoryBase):
34
+ """Schema for creating a new category."""
35
+
36
+ pass
37
+
38
+
39
+ class CategoryUpdate(BaseModel):
40
+ """Schema for updating an existing category."""
41
+
42
+ name: Optional[str] = Field(None, min_length=1, max_length=100)
43
+ description: Optional[str] = None
44
+
45
+
46
+ class CategoryResponse(CategoryBase):
47
+ """Schema for category responses."""
48
+
49
+ id: int
50
+ created_at: datetime
51
+ law_count: int = Field(0, description="Number of laws in this category")
52
+
53
+ class Config:
54
+ from_attributes = True # SQLAlchemy 2.0 (orm_mode replacement)
55
+
56
+
57
+ # ============================================================================
58
+ # Article Schemas
59
+ # ============================================================================
60
+
61
+
62
+ class ArticleBase(BaseModel):
63
+ """Base schema for Article with shared fields."""
64
+
65
+ number: str = Field(
66
+ ..., min_length=1, max_length=20, description="Article number (e.g., 'Art. 1', '42')"
67
+ )
68
+ title: Optional[str] = Field(None, max_length=200, description="Article title (optional)")
69
+ content: str = Field(..., min_length=1, description="Article text content")
70
+ order: int = Field(..., ge=1, description="Display order within the law")
71
+
72
+
73
+ class ArticleCreate(ArticleBase):
74
+ """Schema for creating a new article."""
75
+
76
+ pass
77
+
78
+
79
+ class ArticleUpdate(BaseModel):
80
+ """Schema for updating an existing article."""
81
+
82
+ number: Optional[str] = Field(None, min_length=1, max_length=20)
83
+ title: Optional[str] = Field(None, max_length=200)
84
+ content: Optional[str] = Field(None, min_length=1)
85
+ order: Optional[int] = Field(None, ge=1)
86
+
87
+
88
+ class ArticleResponse(ArticleBase):
89
+ """Schema for article responses."""
90
+
91
+ id: int
92
+ law_id: int
93
+ created_at: datetime
94
+ has_embedding: bool = Field(False, description="Whether article has semantic embedding")
95
+
96
+ class Config:
97
+ from_attributes = True
98
+
99
+
100
+ # ============================================================================
101
+ # Law Schemas
102
+ # ============================================================================
103
+
104
+
105
+ class LawBase(BaseModel):
106
+ """Base schema for Law with shared fields."""
107
+
108
+ reference: str = Field(
109
+ ...,
110
+ min_length=1,
111
+ max_length=500,
112
+ description="Unique law reference (e.g., 'LOI-2024-001', 'DECRET-2023-045')",
113
+ )
114
+ title: str = Field(..., min_length=1, max_length=500, description="Law title")
115
+ type: str = Field(..., description="Law type (loi, décret, ordonnance, arrêté, etc.)")
116
+ content: str = Field(..., min_length=10, description="Full text content of the law")
117
+ language: Optional[str] = Field(
118
+ None, description="Language code (fr or en). Auto-detected if not provided."
119
+ )
120
+ category_id: Optional[int] = Field(
121
+ None, ge=1, description="Category ID. Auto-suggested if not provided."
122
+ )
123
+ status: Optional[str] = Field(
124
+ "draft", description="Publication status (draft, published, archived)"
125
+ )
126
+ publication_date: Optional[date] = Field(None, description="Official publication date")
127
+
128
+ @field_validator("type")
129
+ @classmethod
130
+ def validate_type(cls, v: str) -> str:
131
+ """Validate law type against allowed values."""
132
+ allowed_types = {
133
+ "loi",
134
+ "décret",
135
+ "ordonnance",
136
+ "arrêté",
137
+ "circulaire",
138
+ "instruction",
139
+ "décision",
140
+ "autre",
141
+ "acte uniforme", # Added for OHADA acts
142
+ }
143
+ if v.lower() not in allowed_types:
144
+ raise ValueError(f"Type must be one of: {', '.join(allowed_types)}. Got: {v}")
145
+ return v.lower()
146
+
147
+ @field_validator("language")
148
+ @classmethod
149
+ def validate_language(cls, v: Optional[str]) -> Optional[str]:
150
+ """Validate language code."""
151
+ if v is None:
152
+ return v
153
+ if v.lower() not in {"fr", "en"}:
154
+ raise ValueError(f"Language must be 'fr' or 'en'. Got: {v}")
155
+ return v.lower()
156
+
157
+ @field_validator("status")
158
+ @classmethod
159
+ def validate_status(cls, v: Optional[str]) -> str:
160
+ """Validate status against allowed values."""
161
+ if v is None:
162
+ return "draft"
163
+ allowed_statuses = {"draft", "published", "archived"}
164
+ if v.lower() not in allowed_statuses:
165
+ raise ValueError(f"Status must be one of: {', '.join(allowed_statuses)}. Got: {v}")
166
+ return v.lower()
167
+
168
+
169
+ class LawCreate(LawBase):
170
+ """Schema for creating a new law."""
171
+
172
+ pass
173
+
174
+
175
+ class LawUpdate(BaseModel):
176
+ """
177
+ Schema for updating an existing law.
178
+
179
+ All fields are optional to support partial updates.
180
+ If content is updated, language and categories will be re-detected.
181
+ """
182
+
183
+ reference: Optional[str] = Field(None, min_length=1, max_length=500)
184
+ title: Optional[str] = Field(None, min_length=1, max_length=500)
185
+ type: Optional[str] = None
186
+ content: Optional[str] = Field(None, min_length=10)
187
+ language: Optional[str] = None
188
+ category_id: Optional[int] = Field(None, ge=1)
189
+ status: Optional[str] = None
190
+ publication_date: Optional[date] = None
191
+
192
+ @field_validator("type")
193
+ @classmethod
194
+ def validate_type(cls, v: Optional[str]) -> Optional[str]:
195
+ """Validate law type if provided."""
196
+ if v is None:
197
+ return v
198
+ allowed_types = {
199
+ "loi",
200
+ "décret",
201
+ "ordonnance",
202
+ "arrêté",
203
+ "circulaire",
204
+ "instruction",
205
+ "décision",
206
+ "autre",
207
+ }
208
+ if v.lower() not in allowed_types:
209
+ raise ValueError(f"Type must be one of: {', '.join(allowed_types)}. Got: {v}")
210
+ return v.lower()
211
+
212
+ @field_validator("language")
213
+ @classmethod
214
+ def validate_language(cls, v: Optional[str]) -> Optional[str]:
215
+ """Validate language code if provided."""
216
+ if v is None:
217
+ return v
218
+ if v.lower() not in {"fr", "en"}:
219
+ raise ValueError(f"Language must be 'fr' or 'en'. Got: {v}")
220
+ return v.lower()
221
+
222
+ @field_validator("status")
223
+ @classmethod
224
+ def validate_status(cls, v: Optional[str]) -> Optional[str]:
225
+ """Validate status if provided."""
226
+ if v is None:
227
+ return v
228
+ allowed_statuses = {"draft", "published", "archived"}
229
+ if v.lower() not in allowed_statuses:
230
+ raise ValueError(f"Status must be one of: {', '.join(allowed_statuses)}. Got: {v}")
231
+ return v.lower()
232
+
233
+
234
+ class LawResponse(LawBase):
235
+ """
236
+ Schema for law responses with v2.1 auto-detection fields.
237
+
238
+ Includes:
239
+ - Basic law metadata
240
+ - v2.1 language detection (detected_language, language_confidence)
241
+ - v2.1 category suggestions (suggested_categories, category_confidence)
242
+ - Article count
243
+ - Timestamps
244
+ """
245
+
246
+ id: int
247
+
248
+ # v2.1 Auto-detection fields
249
+ detected_language: Optional[str] = Field(None, description="Auto-detected language (fr or en)")
250
+ language_confidence: Optional[float] = Field(
251
+ None, ge=0.0, le=1.0, description="Confidence score for language detection (0.0-1.0)"
252
+ )
253
+ suggested_categories: Optional[List[int]] = Field(
254
+ None, description="Top 3 suggested category IDs from DocumentClassifier"
255
+ )
256
+ category_confidence: Optional[float] = Field(
257
+ None, ge=0.0, le=1.0, description="Confidence score for top category suggestion (0.0-1.0)"
258
+ )
259
+
260
+ # File tracking
261
+ file_id: Optional[str] = Field(None, description="ID of the uploaded file")
262
+ original_filename: Optional[str] = Field(None, description="Original filename of the uploaded file")
263
+
264
+ # Metadata
265
+ article_count: int = Field(0, description="Number of articles in this law")
266
+ created_at: datetime
267
+ updated_at: Optional[datetime] = None
268
+
269
+ # Optional nested category
270
+ category: Optional[CategoryResponse] = None
271
+
272
+ class Config:
273
+ from_attributes = True
274
+
275
+
276
+ class LawDetailResponse(LawResponse):
277
+ """
278
+ Detailed law response including articles.
279
+
280
+ Used for GET /laws/{id}?include_articles=true
281
+ """
282
+
283
+ articles: List[ArticleResponse] = Field(default_factory=list)
284
+
285
+
286
+ # ============================================================================
287
+ # Filtering & Pagination Schemas
288
+ # ============================================================================
289
+
290
+
291
+ class LawFilters(BaseModel):
292
+ """
293
+ Query parameters for filtering and paginating law lists.
294
+
295
+ Supports:
296
+ - Language filtering (v2.1 feature)
297
+ - Category filtering
298
+ - Status filtering
299
+ - Type filtering
300
+ - Date range filtering
301
+ - Pagination
302
+ """
303
+
304
+ # v2.1 Language filtering
305
+ language: Optional[str] = Field(None, description="Filter by language (fr or en)")
306
+
307
+ # Category filtering
308
+ category_id: Optional[int] = Field(None, ge=1, description="Filter by category ID")
309
+
310
+ # Status filtering
311
+ status: Optional[str] = Field(None, description="Filter by status (draft, published, archived)")
312
+
313
+ # Type filtering
314
+ type: Optional[str] = Field(None, description="Filter by law type")
315
+
316
+ # Date range filtering
317
+ year_from: Optional[int] = Field(
318
+ None, ge=1900, le=2100, description="Filter laws published from this year"
319
+ )
320
+ year_to: Optional[int] = Field(
321
+ None, ge=1900, le=2100, description="Filter laws published up to this year"
322
+ )
323
+
324
+ # Pagination
325
+ page: int = Field(1, ge=1, description="Page number (1-indexed)")
326
+ per_page: int = Field(20, ge=1, le=100, description="Items per page (max 100)")
327
+
328
+ # Sorting
329
+ sort_by: Optional[str] = Field(
330
+ "created_at", description="Sort field (created_at, publication_date, title, reference)"
331
+ )
332
+ sort_order: Optional[str] = Field("desc", description="Sort order (asc or desc)")
333
+
334
+ @field_validator("language")
335
+ @classmethod
336
+ def validate_language(cls, v: Optional[str]) -> Optional[str]:
337
+ """Validate language filter."""
338
+ if v is None:
339
+ return v
340
+ if v.lower() not in {"fr", "en"}:
341
+ raise ValueError(f"Language must be 'fr' or 'en'. Got: {v}")
342
+ return v.lower()
343
+
344
+ @field_validator("status")
345
+ @classmethod
346
+ def validate_status(cls, v: Optional[str]) -> Optional[str]:
347
+ """Validate status filter."""
348
+ if v is None:
349
+ return v
350
+ allowed_statuses = {"draft", "published", "archived"}
351
+ if v.lower() not in allowed_statuses:
352
+ raise ValueError(f"Status must be one of: {', '.join(allowed_statuses)}. Got: {v}")
353
+ return v.lower()
354
+
355
+ @field_validator("sort_by")
356
+ @classmethod
357
+ def validate_sort_by(cls, v: Optional[str]) -> str:
358
+ """Validate sort field."""
359
+ if v is None:
360
+ return "created_at"
361
+ allowed_fields = {"created_at", "publication_date", "title", "reference", "updated_at"}
362
+ if v.lower() not in allowed_fields:
363
+ raise ValueError(f"sort_by must be one of: {', '.join(allowed_fields)}. Got: {v}")
364
+ return v.lower()
365
+
366
+ @field_validator("sort_order")
367
+ @classmethod
368
+ def validate_sort_order(cls, v: Optional[str]) -> str:
369
+ """Validate sort order."""
370
+ if v is None:
371
+ return "desc"
372
+ if v.lower() not in {"asc", "desc"}:
373
+ raise ValueError(f"sort_order must be 'asc' or 'desc'. Got: {v}")
374
+ return v.lower()
375
+
376
+ @field_validator("year_to")
377
+ @classmethod
378
+ def validate_year_range(cls, v: Optional[int], info) -> Optional[int]:
379
+ """Ensure year_to >= year_from if both provided."""
380
+ if v is None:
381
+ return v
382
+ year_from = info.data.get("year_from")
383
+ if year_from is not None and v < year_from:
384
+ raise ValueError(f"year_to ({v}) must be >= year_from ({year_from})")
385
+ return v
386
+
387
+
388
+ class LawListResponse(BaseModel):
389
+ """
390
+ Paginated list of laws with metadata.
391
+
392
+ Used for GET /laws with filtering and pagination.
393
+ """
394
+
395
+ items: List[LawResponse] = Field(default_factory=list)
396
+ total: int = Field(0, description="Total number of laws matching filters")
397
+ page: int = Field(1, description="Current page number")
398
+ per_page: int = Field(20, description="Items per page")
399
+ pages: int = Field(0, description="Total number of pages")
400
+
401
+ # Optional filter summary
402
+ filters_applied: Optional[dict] = Field(None, description="Summary of applied filters")
403
+
404
+
405
+ # ============================================================================
406
+ # Search Schemas
407
+ # ============================================================================
408
+
409
+
410
+ class SearchQuery(BaseModel):
411
+ """Schema for search operations."""
412
+
413
+ query: str = Field(..., min_length=1, max_length=500, description="Search query text")
414
+ filters: Optional[LawFilters] = Field(None, description="Additional filters to apply")
415
+
416
+
417
+ class SearchResult(LawResponse):
418
+ """Search result with relevance score."""
419
+
420
+ relevance_score: float = Field(
421
+ 0.0, ge=0.0, le=1.0, description="Search relevance score (0.0-1.0)"
422
+ )
423
+
424
+
425
+ class SearchResponse(BaseModel):
426
+ """Response for search operations."""
427
+
428
+ query: str
429
+ results: List[SearchResult] = Field(default_factory=list)
430
+ total: int = Field(0, description="Total number of results")
431
+ search_time_ms: float = Field(0.0, description="Search execution time in milliseconds")
432
+
433
+
434
+ # ============================================================================
435
+ # Statistics Schemas
436
+ # ============================================================================
437
+
438
+
439
+ class LanguageStats(BaseModel):
440
+ """Statistics on law distribution by language (v2.1 feature)."""
441
+
442
+ french: int = Field(0, description="Number of French laws")
443
+ english: int = Field(0, description="Number of English laws")
444
+ unknown: int = Field(0, description="Number of laws with unknown language")
445
+ total: int = Field(0, description="Total number of laws")
446
+
447
+
448
+ class CategoryStats(BaseModel):
449
+ """Statistics on law distribution by category."""
450
+
451
+ category_id: int
452
+ category_name: str
453
+ law_count: int
454
+ percentage: float = Field(0.0, ge=0.0, le=100.0)
455
+
456
+
457
+ class LawStats(BaseModel):
458
+ """Overall statistics for the law database."""
459
+
460
+ total_laws: int = Field(0)
461
+ total_articles: int = Field(0)
462
+ by_language: LanguageStats
463
+ by_status: dict = Field(default_factory=dict) # {"draft": 10, "published": 50, ...}
464
+ by_type: dict = Field(default_factory=dict) # {"loi": 30, "décret": 20, ...}
465
+ top_categories: List[CategoryStats] = Field(default_factory=list)
466
+ avg_articles_per_law: float = Field(0.0)
467
+ latest_publication: Optional[date] = None
app/schemas/ocr.py ADDED
@@ -0,0 +1,213 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Pydantic schemas for OCR operations.
3
+
4
+ Provides request/response models with validation for:
5
+ - PDF type detection (native, scanned, hybrid)
6
+ - OCR processing results
7
+ - OCR configuration
8
+ - Health check
9
+
10
+ Author: JuriX Development Team
11
+ Date: 2026-01-11
12
+ """
13
+
14
+ from enum import Enum
15
+ from typing import Optional
16
+
17
+ from pydantic import BaseModel, Field, field_validator
18
+
19
+
20
+ # ============================================================================
21
+ # Enums
22
+ # ============================================================================
23
+
24
+
25
+ class PDFType(str, Enum):
26
+ """Type of PDF document."""
27
+
28
+ NATIVE = "native" # Text-based PDF with embedded text
29
+ SCANNED = "scanned" # Image-based PDF requiring OCR
30
+ HYBRID = "hybrid" # Mixed content (text + images)
31
+ UNKNOWN = "unknown" # Unable to determine
32
+
33
+
34
+ # ============================================================================
35
+ # OCR Result Schemas
36
+ # ============================================================================
37
+
38
+
39
+ class OCRResult(BaseModel):
40
+ """
41
+ Result of OCR processing on a PDF.
42
+
43
+ Contains:
44
+ - PDF type classification
45
+ - Extracted text (cleaned)
46
+ - Processing metadata
47
+ - Confidence scores
48
+ """
49
+
50
+ pdf_type: PDFType = Field(..., description="Detected PDF type")
51
+ text: str = Field(..., description="Extracted and cleaned text")
52
+ page_count: int = Field(..., ge=1, description="Number of pages processed")
53
+ processing_time_ms: int = Field(..., ge=0, description="Processing time in milliseconds")
54
+ language: str = Field(..., description="OCR language used (e.g., 'fra+eng')")
55
+ confidence: Optional[float] = Field(
56
+ None, ge=0.0, le=1.0, description="OCR confidence score (0-1)"
57
+ )
58
+ ocr_engine: str = Field(default="tesseract", description="OCR engine used")
59
+ text_length: int = Field(..., ge=0, description="Length of extracted text")
60
+
61
+ class Config:
62
+ json_schema_extra = {
63
+ "example": {
64
+ "pdf_type": "scanned",
65
+ "text": "Article 1. La présente loi régit...",
66
+ "page_count": 45,
67
+ "processing_time_ms": 15000,
68
+ "language": "fra+eng",
69
+ "confidence": 0.92,
70
+ "ocr_engine": "tesseract",
71
+ "text_length": 25000,
72
+ }
73
+ }
74
+
75
+
76
+ class PDFTypeDetectionResult(BaseModel):
77
+ """
78
+ Result of PDF type detection only (no OCR).
79
+
80
+ Quick check to determine if OCR is needed.
81
+ """
82
+
83
+ pdf_type: PDFType = Field(..., description="Detected PDF type")
84
+ has_text: bool = Field(..., description="Whether PDF has embedded text")
85
+ has_images: bool = Field(..., description="Whether PDF contains images")
86
+ page_count: int = Field(..., ge=1, description="Number of pages")
87
+ text_coverage: float = Field(
88
+ ..., ge=0.0, le=1.0, description="Percentage of pages with text (0-1)"
89
+ )
90
+ needs_ocr: bool = Field(..., description="Whether OCR processing is recommended")
91
+
92
+ class Config:
93
+ json_schema_extra = {
94
+ "example": {
95
+ "pdf_type": "scanned",
96
+ "has_text": False,
97
+ "has_images": True,
98
+ "page_count": 45,
99
+ "text_coverage": 0.0,
100
+ "needs_ocr": True,
101
+ }
102
+ }
103
+
104
+
105
+ # ============================================================================
106
+ # Request Schemas
107
+ # ============================================================================
108
+
109
+
110
+ class OCRRequest(BaseModel):
111
+ """
112
+ Request schema for OCR processing.
113
+ """
114
+
115
+ pdf_path: str = Field(..., min_length=1, description="Path to PDF file")
116
+ language: str = Field(
117
+ default="fra+eng",
118
+ description="Tesseract language codes (e.g., 'fra', 'eng', 'fra+eng')",
119
+ )
120
+ dpi: int = Field(
121
+ default=300, ge=72, le=600, description="DPI for PDF to image conversion"
122
+ )
123
+ timeout_seconds: int = Field(
124
+ default=60, ge=5, le=300, description="Maximum processing time per page"
125
+ )
126
+
127
+ @field_validator("language")
128
+ @classmethod
129
+ def validate_language(cls, v: str) -> str:
130
+ """Validate language codes."""
131
+ allowed_languages = {"fra", "eng", "fra+eng", "eng+fra"}
132
+ if v.lower() not in allowed_languages:
133
+ raise ValueError(
134
+ f"Language must be one of: {', '.join(allowed_languages)}. Got: {v}"
135
+ )
136
+ return v.lower()
137
+
138
+ class Config:
139
+ json_schema_extra = {
140
+ "example": {
141
+ "pdf_path": "/path/to/document.pdf",
142
+ "language": "fra+eng",
143
+ "dpi": 300,
144
+ "timeout_seconds": 60,
145
+ }
146
+ }
147
+
148
+
149
+ class PDFTypeDetectionRequest(BaseModel):
150
+ """Request schema for PDF type detection only."""
151
+
152
+ pdf_path: str = Field(..., min_length=1, description="Path to PDF file")
153
+
154
+ class Config:
155
+ json_schema_extra = {"example": {"pdf_path": "/path/to/document.pdf"}}
156
+
157
+
158
+ # ============================================================================
159
+ # Health Check Schema
160
+ # ============================================================================
161
+
162
+
163
+ class OCRServiceHealth(BaseModel):
164
+ """Health check response for OCR service."""
165
+
166
+ service: str = Field(default="OCRService", description="Service name")
167
+ status: str = Field(..., description="Service status (healthy, degraded, unhealthy)")
168
+ tesseract: dict = Field(..., description="Tesseract OCR status")
169
+ poppler: dict = Field(..., description="Poppler (pdf2image) status")
170
+ supported_languages: list = Field(
171
+ default_factory=list, description="Available Tesseract languages"
172
+ )
173
+
174
+ class Config:
175
+ json_schema_extra = {
176
+ "example": {
177
+ "service": "OCRService",
178
+ "status": "healthy",
179
+ "tesseract": {
180
+ "available": True,
181
+ "version": "5.3.0",
182
+ "path": "/usr/bin/tesseract",
183
+ },
184
+ "poppler": {"available": True, "version": "22.12.0"},
185
+ "supported_languages": ["fra", "eng", "osd"],
186
+ }
187
+ }
188
+
189
+
190
+ # ============================================================================
191
+ # Statistics Schema
192
+ # ============================================================================
193
+
194
+
195
+ class OCRStatistics(BaseModel):
196
+ """Statistics for OCR processing."""
197
+
198
+ total_pages_processed: int = Field(0, ge=0)
199
+ total_processing_time_ms: int = Field(0, ge=0)
200
+ average_time_per_page_ms: float = Field(0.0, ge=0.0)
201
+ total_text_extracted: int = Field(0, ge=0, description="Total characters extracted")
202
+ success_rate: float = Field(0.0, ge=0.0, le=1.0, description="Success rate (0-1)")
203
+
204
+ class Config:
205
+ json_schema_extra = {
206
+ "example": {
207
+ "total_pages_processed": 450,
208
+ "total_processing_time_ms": 180000,
209
+ "average_time_per_page_ms": 400,
210
+ "total_text_extracted": 1250000,
211
+ "success_rate": 0.98,
212
+ }
213
+ }
app/schemas/persona.py ADDED
@@ -0,0 +1,428 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Pydantic schemas for PersonaService API.
3
+
4
+ Request/response models for persona management and analytics endpoints.
5
+ """
6
+
7
+ from datetime import date, datetime
8
+ from typing import Dict, List, Optional, Any
9
+ from pydantic import BaseModel, Field, field_validator
10
+
11
+
12
+ # ============================================================================
13
+ # REQUEST SCHEMAS
14
+ # ============================================================================
15
+
16
+ class MessageFeedbackCreate(BaseModel):
17
+ """
18
+ Schema for creating message feedback.
19
+
20
+ Users can rate messages as helpful/unhelpful with optional 1-5 rating.
21
+ """
22
+ message_id: int = Field(..., description="ID of the message to rate", gt=0)
23
+ helpful: bool = Field(..., description="Whether the message was helpful (👍/👎)")
24
+ rating: Optional[int] = Field(None, description="Optional 1-5 star rating", ge=1, le=5)
25
+ comment: Optional[str] = Field(None, description="Optional comment", max_length=500)
26
+
27
+ model_config = {
28
+ "json_schema_extra": {
29
+ "examples": [
30
+ {
31
+ "message_id": 123,
32
+ "helpful": True,
33
+ "rating": 5,
34
+ "comment": "Très claire et utile!"
35
+ }
36
+ ]
37
+ }
38
+ }
39
+
40
+
41
+ # ============================================================================
42
+ # RESPONSE SCHEMAS
43
+ # ============================================================================
44
+
45
+ class PersonaInfo(BaseModel):
46
+ """
47
+ Information about a specific persona.
48
+
49
+ Includes name, display name, description, icon, tone, and example questions.
50
+ """
51
+ name: str = Field(..., description="Persona identifier (citoyen|avocat|entrepreneur|étudiant)")
52
+ display_name: str = Field(..., description="Display name (e.g., 'Citoyen', 'Avocat')")
53
+ description: str = Field(..., description="Description of persona's approach")
54
+ icon: str = Field(..., description="Emoji icon representing persona")
55
+ tone: str = Field(..., description="Communication tone of persona")
56
+ example_questions: List[str] = Field(..., description="Example questions for this persona")
57
+
58
+ model_config = {
59
+ "json_schema_extra": {
60
+ "examples": [
61
+ {
62
+ "name": "citoyen",
63
+ "display_name": "Citoyen",
64
+ "description": "Assistant bienveillant qui aide les citoyens à comprendre leurs droits",
65
+ "icon": "👤",
66
+ "tone": "Empathique et rassurant",
67
+ "example_questions": [
68
+ "Quels sont mes droits en tant que locataire?",
69
+ "Comment porter plainte au commissariat?"
70
+ ]
71
+ }
72
+ ]
73
+ }
74
+ }
75
+
76
+
77
+ class UsageMetrics(BaseModel):
78
+ """Usage statistics metrics."""
79
+ total_questions: int = Field(..., description="Total number of questions asked")
80
+ total_conversations: int = Field(..., description="Total number of conversations")
81
+ unique_sessions: int = Field(..., description="Number of unique session IDs")
82
+
83
+
84
+ class PerformanceMetrics(BaseModel):
85
+ """Performance statistics metrics."""
86
+ avg_confidence: float = Field(..., description="Average confidence score (0.0-1.0)")
87
+ avg_retrieval_time_ms: int = Field(..., description="Average retrieval time in milliseconds")
88
+ avg_generation_time_ms: int = Field(..., description="Average generation time in milliseconds")
89
+ avg_total_time_ms: int = Field(..., description="Average total response time in milliseconds")
90
+
91
+
92
+ class EngagementMetrics(BaseModel):
93
+ """Engagement statistics metrics."""
94
+ avg_messages_per_conversation: float = Field(..., description="Average messages per conversation")
95
+ avg_session_duration_seconds: int = Field(..., description="Average session duration in seconds")
96
+
97
+
98
+ class QualityMetrics(BaseModel):
99
+ """Quality statistics metrics from user feedback."""
100
+ helpful_count: int = Field(..., description="Number of helpful ratings (👍)")
101
+ unhelpful_count: int = Field(..., description="Number of unhelpful ratings (👎)")
102
+ satisfaction_rate: float = Field(..., description="Satisfaction rate (0.0-1.0)")
103
+
104
+
105
+ class DateRange(BaseModel):
106
+ """Date range for statistics."""
107
+ start: str = Field(..., description="Start date (ISO format)")
108
+ end: str = Field(..., description="End date (ISO format)")
109
+
110
+
111
+ class PersonaStatsResponse(BaseModel):
112
+ """
113
+ Comprehensive statistics for a persona over a date range.
114
+
115
+ Aggregated from persona_stats table.
116
+ """
117
+ persona: str = Field(..., description="Persona name")
118
+ date_range: DateRange = Field(..., description="Date range for statistics")
119
+ usage: UsageMetrics = Field(..., description="Usage metrics")
120
+ performance: PerformanceMetrics = Field(..., description="Performance metrics")
121
+ engagement: EngagementMetrics = Field(..., description="Engagement metrics")
122
+ quality: QualityMetrics = Field(..., description="Quality metrics from feedback")
123
+
124
+ model_config = {
125
+ "json_schema_extra": {
126
+ "examples": [
127
+ {
128
+ "persona": "citoyen",
129
+ "date_range": {"start": "2024-01-01", "end": "2024-01-31"},
130
+ "usage": {
131
+ "total_questions": 150,
132
+ "total_conversations": 80,
133
+ "unique_sessions": 75
134
+ },
135
+ "performance": {
136
+ "avg_confidence": 0.85,
137
+ "avg_retrieval_time_ms": 450,
138
+ "avg_generation_time_ms": 1200,
139
+ "avg_total_time_ms": 1650
140
+ },
141
+ "engagement": {
142
+ "avg_messages_per_conversation": 1.88,
143
+ "avg_session_duration_seconds": 180
144
+ },
145
+ "quality": {
146
+ "helpful_count": 45,
147
+ "unhelpful_count": 5,
148
+ "satisfaction_rate": 0.9
149
+ }
150
+ }
151
+ ]
152
+ }
153
+ }
154
+
155
+
156
+ class MessageFeedbackResponse(BaseModel):
157
+ """Response schema for message feedback."""
158
+ id: int = Field(..., description="Feedback ID")
159
+ message_id: int = Field(..., description="Message ID")
160
+ helpful: bool = Field(..., description="Whether message was helpful")
161
+ rating: Optional[int] = Field(None, description="Optional 1-5 rating")
162
+ comment: Optional[str] = Field(None, description="Optional comment")
163
+ created_at: str = Field(..., description="Creation timestamp (ISO format)")
164
+
165
+ model_config = {
166
+ "json_schema_extra": {
167
+ "examples": [
168
+ {
169
+ "id": 1,
170
+ "message_id": 123,
171
+ "helpful": True,
172
+ "rating": 5,
173
+ "comment": "Très utile!",
174
+ "created_at": "2024-01-15T10:30:00"
175
+ }
176
+ ]
177
+ }
178
+ }
179
+
180
+
181
+ class PersonaFeedbackBreakdown(BaseModel):
182
+ """Feedback breakdown for a single persona."""
183
+ total: int = Field(..., description="Total feedback count")
184
+ helpful: int = Field(..., description="Helpful count")
185
+ unhelpful: int = Field(..., description="Unhelpful count")
186
+
187
+
188
+ class FeedbackStats(BaseModel):
189
+ """
190
+ Aggregated feedback statistics.
191
+
192
+ Can be filtered by persona and date range.
193
+ """
194
+ total_feedback: int = Field(..., description="Total number of feedback entries")
195
+ helpful_count: int = Field(..., description="Number of helpful ratings")
196
+ unhelpful_count: int = Field(..., description="Number of unhelpful ratings")
197
+ satisfaction_rate: float = Field(..., description="Satisfaction rate (0.0-1.0)")
198
+ avg_rating: Optional[float] = Field(None, description="Average star rating (1-5)")
199
+ by_persona: Dict[str, PersonaFeedbackBreakdown] = Field(
200
+ default_factory=dict,
201
+ description="Breakdown by persona (empty if filtered by persona)"
202
+ )
203
+
204
+ model_config = {
205
+ "json_schema_extra": {
206
+ "examples": [
207
+ {
208
+ "total_feedback": 100,
209
+ "helpful_count": 85,
210
+ "unhelpful_count": 15,
211
+ "satisfaction_rate": 0.85,
212
+ "avg_rating": 4.2,
213
+ "by_persona": {
214
+ "citoyen": {"total": 50, "helpful": 45, "unhelpful": 5},
215
+ "avocat": {"total": 30, "helpful": 25, "unhelpful": 5},
216
+ "entrepreneur": {"total": 15, "helpful": 12, "unhelpful": 3},
217
+ "étudiant": {"total": 5, "helpful": 3, "unhelpful": 2}
218
+ }
219
+ }
220
+ ]
221
+ }
222
+ }
223
+
224
+
225
+ class DetailedEngagementMetrics(BaseModel):
226
+ """Detailed engagement metrics for a persona."""
227
+ total_conversations: int = Field(..., description="Total conversations in period")
228
+ total_messages: int = Field(..., description="Total messages exchanged")
229
+ avg_messages_per_conversation: float = Field(..., description="Average messages per conversation")
230
+ avg_session_duration_seconds: int = Field(..., description="Average session duration")
231
+ active_days: int = Field(..., description="Number of days with activity")
232
+ conversations_per_active_day: float = Field(..., description="Average conversations per active day")
233
+
234
+
235
+ class EngagementMetricsResponse(BaseModel):
236
+ """
237
+ Response schema for engagement metrics endpoint.
238
+ """
239
+ persona: str = Field(..., description="Persona name")
240
+ days: int = Field(..., description="Number of days analyzed")
241
+ metrics: DetailedEngagementMetrics = Field(..., description="Engagement metrics")
242
+
243
+ model_config = {
244
+ "json_schema_extra": {
245
+ "examples": [
246
+ {
247
+ "persona": "citoyen",
248
+ "days": 30,
249
+ "metrics": {
250
+ "total_conversations": 120,
251
+ "total_messages": 240,
252
+ "avg_messages_per_conversation": 2.0,
253
+ "avg_session_duration_seconds": 180,
254
+ "active_days": 25,
255
+ "conversations_per_active_day": 4.8
256
+ }
257
+ }
258
+ ]
259
+ }
260
+ }
261
+
262
+
263
+ class PopularQuestion(BaseModel):
264
+ """A popular question with its frequency count."""
265
+ question: str = Field(..., description="Question text")
266
+ count: int = Field(..., description="Number of times asked")
267
+
268
+
269
+ class PopularQuestionsResponse(BaseModel):
270
+ """Response schema for popular questions endpoint."""
271
+ persona: str = Field(..., description="Persona name")
272
+ questions: List[PopularQuestion] = Field(..., description="List of popular questions")
273
+ total_count: int = Field(..., description="Total number of questions found")
274
+
275
+ model_config = {
276
+ "json_schema_extra": {
277
+ "examples": [
278
+ {
279
+ "persona": "citoyen",
280
+ "questions": [
281
+ {"question": "Quels sont mes droits en tant que locataire?", "count": 15},
282
+ {"question": "Comment porter plainte?", "count": 12}
283
+ ],
284
+ "total_count": 2
285
+ }
286
+ ]
287
+ }
288
+ }
289
+
290
+
291
+ class PersonaValue(BaseModel):
292
+ """Value and display name for a persona in comparison."""
293
+ value: float = Field(..., description="Metric value")
294
+ display_name: str = Field(..., description="Display name of persona")
295
+
296
+
297
+ class PersonaComparisonResponse(BaseModel):
298
+ """
299
+ Response schema for persona comparison endpoint.
300
+ """
301
+ metric: str = Field(..., description="Metric being compared (usage|confidence|satisfaction)")
302
+ days: int = Field(..., description="Number of days analyzed")
303
+ date_range: DateRange = Field(..., description="Date range for comparison")
304
+ personas: Dict[str, PersonaValue] = Field(..., description="Comparison values per persona")
305
+
306
+ model_config = {
307
+ "json_schema_extra": {
308
+ "examples": [
309
+ {
310
+ "metric": "usage",
311
+ "days": 30,
312
+ "date_range": {"start": "2024-01-01", "end": "2024-01-31"},
313
+ "personas": {
314
+ "citoyen": {"value": 150, "display_name": "Citoyen"},
315
+ "avocat": {"value": 80, "display_name": "Avocat"},
316
+ "entrepreneur": {"value": 45, "display_name": "Entrepreneur"},
317
+ "étudiant": {"value": 25, "display_name": "Étudiant"}
318
+ }
319
+ }
320
+ ]
321
+ }
322
+ }
323
+
324
+
325
+ class TrendPoint(BaseModel):
326
+ """A single point in a trend time series."""
327
+ date: str = Field(..., description="Date (ISO format)")
328
+ value: float = Field(..., description="Metric value for this date")
329
+
330
+
331
+ class TrendsResponse(BaseModel):
332
+ """Response schema for trends endpoint."""
333
+ persona: str = Field(..., description="Persona name")
334
+ metric: str = Field(..., description="Metric tracked (questions|confidence|satisfaction)")
335
+ days: int = Field(..., description="Number of days analyzed")
336
+ data_points: List[TrendPoint] = Field(..., description="Time series data points")
337
+
338
+ model_config = {
339
+ "json_schema_extra": {
340
+ "examples": [
341
+ {
342
+ "persona": "citoyen",
343
+ "metric": "questions",
344
+ "days": 7,
345
+ "data_points": [
346
+ {"date": "2024-01-01", "value": 5},
347
+ {"date": "2024-01-02", "value": 8},
348
+ {"date": "2024-01-03", "value": 12}
349
+ ]
350
+ }
351
+ ]
352
+ }
353
+ }
354
+
355
+
356
+ class UsageBreakdownResponse(BaseModel):
357
+ """Response schema for persona usage breakdown."""
358
+ total_conversations: int = Field(..., description="Total conversations across all personas")
359
+ percentages: Dict[str, float] = Field(..., description="Usage percentage per persona")
360
+
361
+ model_config = {
362
+ "json_schema_extra": {
363
+ "examples": [
364
+ {
365
+ "total_conversations": 300,
366
+ "percentages": {
367
+ "citoyen": 50.0,
368
+ "avocat": 26.67,
369
+ "entrepreneur": 15.0,
370
+ "étudiant": 8.33
371
+ }
372
+ }
373
+ ]
374
+ }
375
+ }
376
+
377
+
378
+ class HealthCheckResponse(BaseModel):
379
+ """Response schema for health check endpoint."""
380
+ service: str = Field(..., description="Service name")
381
+ status: str = Field(..., description="Service status")
382
+ personas_count: int = Field(..., description="Number of supported personas")
383
+ personas: List[str] = Field(..., description="List of persona names")
384
+ timestamp: str = Field(..., description="Timestamp (ISO format)")
385
+
386
+ model_config = {
387
+ "json_schema_extra": {
388
+ "examples": [
389
+ {
390
+ "service": "PersonaService",
391
+ "status": "healthy",
392
+ "personas_count": 4,
393
+ "personas": ["citoyen", "avocat", "entrepreneur", "étudiant"],
394
+ "timestamp": "2024-01-15T10:30:00"
395
+ }
396
+ ]
397
+ }
398
+ }
399
+
400
+
401
+ # ============================================================================
402
+ # ERROR RESPONSE SCHEMAS
403
+ # ============================================================================
404
+
405
+ class ErrorDetail(BaseModel):
406
+ """Detailed error information."""
407
+ error: str = Field(..., description="Error type")
408
+ message: str = Field(..., description="Human-readable error message")
409
+ details: Optional[Dict[str, Any]] = Field(None, description="Additional error details")
410
+
411
+
412
+ class ErrorResponse(BaseModel):
413
+ """Standard error response schema."""
414
+ detail: ErrorDetail = Field(..., description="Error details")
415
+
416
+ model_config = {
417
+ "json_schema_extra": {
418
+ "examples": [
419
+ {
420
+ "detail": {
421
+ "error": "InvalidPersonaError",
422
+ "message": "Invalid persona 'unknown'. Must be one of: citoyen, avocat, entrepreneur, étudiant",
423
+ "details": {"provided": "unknown", "valid": ["citoyen", "avocat", "entrepreneur", "étudiant"]}
424
+ }
425
+ }
426
+ ]
427
+ }
428
+ }