01 Prérequis
| Élément | Détail |
|---|---|
| Python | Version 3.11 ou supérieure, exécutée depuis le .venv du repo agent |
| Repo | Être dans ../cv-critic-agent, repo autonome migré depuis cv-portfolio |
| Clé API Mistral | Mistral est le provider par défaut. Anthropic reste disponible en fallback. |
| .env.local | Fichier à créer dans cv-critic-agent si absent (voir ci-dessous) |
Créer un fichier .env.local à la racine de cv-critic-agent si ce n'est pas déjà fait :
CV_CRITIC_PROVIDER=mistral CV_CRITIC_MODEL=mistral-medium-latest MISTRAL_API_KEY=...
Le fichier .env.local est dans .gitignore — ne jamais committer les clés API dans le dépôt.
02 Lancer un run
-
1
Se placer dans le repo autonome
Depuis n'importe quel répertoire :
cd /Users/mansour/Documents/projects/cv-critic-agent source .venv/bin/activate
-
2
Lancer un smoke test gratuit
python -m cv_critic_agent --mock
Ce mode utilise le Mock LLM : aucun appel API réel, utile avant un run Mistral.
-
3
Lancer le run réel
Le provider par défaut est Mistral. La version CrewAI native brute reste disponible via
--crewai-native.python -m cv_critic_agent # mode CrewAI Agent/Task/Crew natif brut python -m cv_critic_agent --crewai-native
-
4
Suivre la progression dans le terminal ou l'UI
Les 3 agents s'exécutent en séquence. Le terminal affiche la progression :
▶ Global Critic... [1/3] ▶ Printable CV Critic... [2/3] ▶ Strategy Agent... [3/3] ✓ Run terminé — reports/2026-06-04T19-16-50Z/
-
5
Rapports disponibles immédiatement
Un dossier horodaté est créé dans
cv-critic-agent/reports/etreports/latest/est mis à jour automatiquement.
Interface web locale
Pour visualiser un run en temps réel avec graphe d'agents, panneaux sources et prévisualisation des rapports :
# terminal 1 — API FastAPI python -m cv_critic_agent --serve --port 8000 # terminal 2 — UI Next.js cd ui cp .env.local.example .env.local npm run dev
Tester les endpoints Phase 5 en local
Phase 5 ajoute le flow d'accès public (Sprint 1–4 livrés). Pour activer le gate sur ton API locale, remplir .env.local avec :
# Phase 5 — Access gate (générer les clés) HMAC_KEY=$(python -c "import secrets; print(secrets.token_hex(32))") FERNET_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") # Tokens externes (créer les comptes au préalable) TURNSTILE_SECRET=... TELEGRAM_BOT_TOKEN=... TELEGRAM_OWNER_CHAT_ID=... RESEND_API_KEY=... RESEND_FROM_ADDRESS=agent@cv-critic.saifallah.dev OWNER_EMAIL=mansour.saifallah@gmail.com CV_CRITIC_BASE_URL=http://localhost:8000 CV_CRITIC_UI_URL=http://localhost:3000
Sans ces variables, les endpoints Phase 5 renvoient 503 Service Unavailable et le reste de l'API fonctionne normalement (runs mock ouverts à tous).
Le gate est actif sur POST /api/runs depuis Sprint 5. Pour lancer un real run, il faut soumettre un formulaire d'accès (protégé Turnstile), attendre l'approbation owner (Telegram ou email), puis utiliser le lien /access-granted/[token] reçu par mail. La session est liée à l'IP, dure 24 h et permet 3 runs. Au-delà du cap journalier (MAX_TOKENS_PER_DAY), les real runs dégradent silencieusement vers mock avec degraded: true dans la réponse.
Cron nettoyage TTL : POST /api/cron/cleanup avec header X-Cleanup-Secret: $CV_CRITIC_CLEANUP_SECRET. À planifier une fois par jour (cron Render, GitHub Actions, etc.). Purge les requêtes pending > 7 j, les decidées > 90 j, et rotate les fichiers budget par jour > 90 j.
03 Les 4 rapports générés
Chaque run produit 4 fichiers Markdown dans cv-critic-agent/reports/<timestamp>/ :
Critique globale du portfolio complet — CV, chatbot, fiches techniques. Regard externe, sans filtre.
Critique du CV imprimable — lisibilité A4, clarté en 10 secondes, cohérence titre/preuves, ATS.
Plan d'action priorisé P0/P1/P2 — tensions identifiées, décisions recommandées, prochain incrément.
Résumé exécutif — les 3 points critiques les plus importants du run, à lire en premier.
Pour accéder rapidement au dernier run sans chercher le bon dossier horodaté, aller dans cv-critic-agent/reports/latest/.
04 Interpréter le rapport global
Le rapport global simule un regard externe sur l'ensemble du dispositif. Il peut être dur — c'est voulu. Sa valeur vient précisément de l'absence de filtre.
Structure typique
| Partie | Ce qu'elle évalue |
|---|---|
| Première impression | Ce que perçoit quelqu'un qui découvre le portfolio pour la première fois |
| Points forts | Ce qui convainc vraiment, les preuves qui portent |
| Points faibles | Incohérences, zones d'ombre, signaux qui nuisent à la crédibilité |
| Risques de perception | Comment le profil peut être mal interprété par un recruteur |
Ne pas réagir défensivement à chaque critique. Lire d'abord tout le rapport, puis noter les points qui reviennent dans plusieurs sections — ce sont les vrais signaux, pas les artefacts de variabilité du LLM.
05 Interpréter le rapport CV imprimable
Ce rapport se concentre uniquement sur le CV téléchargeable/imprimable (/cv), vu comme un document A4 par un recruteur pressé. Contrairement au rapport global, il ignore le chatbot et les fiches techniques.
Critères évalués
| Critère | Question posée par l'agent |
|---|---|
| Lisibilité A4 | Le document est-il trop dense ? Bien aéré ? Déborde-t-il d'une page ? |
| Clarté en 10 sec | Le titre et le profil sont-ils immédiatement compréhensibles au premier coup d'œil ? |
| Cohérence titre / preuves | Le titre annonce-t-il ce que les expériences confirment réellement ? |
| Compatibilité ATS | Mots-clés présents, structure parseable, format compatible avec les outils RH |
| Hiérarchie visuelle | Les sections importantes ressortent-elles clairement ? Les missions récentes dominent-elles ? |
L'agent analyse le HTML de /cv tel qu'il serait imprimé. Si la mise en page change dans le code, relancer un run pour mettre à jour le rapport.
06 Exploiter la stratégie P0/P1/P2
Le rapport strategy.md est le plus actionnable. Il synthétise les critiques et les transforme en plan priorisé, enrichi des contraintes de context.md.
Bloquant — à corriger avant toute diffusion
Nuit activement à la crédibilité du portfolio. Ne pas diffuser tant qu'un P0 existe.
Important — prochain incrément
Améliore significativement l'impact. À traiter dès que les P0 sont réglés.
Améliorations — nice-to-have
Raffinements utiles mais non urgents. À faire quand le reste est stable.
Traiter tous les P0 avant de partager le portfolio. Commencer le prochain incrément par les P1 les plus rapides à corriger.
07 Mettre à jour context.md
Le fichier cv-critic-agent/context.md contient les décisions internes que le Strategy Agent doit respecter lors de la formulation des recommandations. Il évolue avec le projet.
Quand mettre à jour
- Après avoir appliqué une recommandation → noter que c'est fait, date incluse
- Après avoir refusé une recommandation avec une bonne raison → documenter pourquoi
- Après un changement de positionnement, un nouveau projet, ou une décision stratégique
Format recommandé
## Décisions validées - [2026-05-14] Ne pas mentionner le service AI/RAG Sense comme réalisé par moi → délégué à une équipe dédiée, mon rôle = cadrage et points de contact API - [2026-05-20] Garder Resell Radar en titre "veille automatisée" (pas "scraper") → posture éthique et légale clairement affichée ## Décisions écartées - [2026-05-30] Suggestion : ajouter une section "Certifications" → pas pertinent pour le positionnement senior actuel, à reconsidérer si AWS SAA obtenu
Les agents Critic ignorent context.md — seul le Strategy Agent le lit. Cela garantit que les critiques restent objectives, non filtrées par les décisions passées.
08 Itérer efficacement
Lire summary.md
3 points critiques. Rien de nouveau = itération précédente réussie.
Appliquer les P0
Modifier data.ts, fiches ou CV selon strategy.md.
Mettre à jour context.md
Documenter ce qui a été appliqué et ce qui a été écarté.
Relancer un run
Comparer le nouveau strategy.md avec le précédent.
Comparer deux runs
Pour visualiser rapidement l'évolution entre deux runs :
diff cv-critic-agent/reports/<run1>/summary.md \
cv-critic-agent/reports/<run2>/summary.md
Les P0 qui disparaissent entre deux runs confirment le progrès. Les P1 qui migrent vers P0 signalent une dégradation — à traiter en priorité.
09 FAQ
MISTRAL_API_KEY est correctement renseigné dans cv-critic-agent/.env.local. Si CV_CRITIC_PROVIDER=anthropic, vérifier plutôt ANTHROPIC_API_KEY.context.md avec la raison et la date. Le prochain run respectera la contrainte — le Strategy Agent lit ce fichier avant de formuler ses recommandations.summary.md via diff est le moyen le plus rapide de le vérifier en un coup d'œil.