CV Critic Agent

Objectif produit

CV Critic & Strategy Agent est un workflow interne d'audit du CV et du positionnement professionnel. Objectif volontairement opposé à SAIF-IA : challenger le discours au lieu de vendre.

• Analyser le CV, le portfolio et le chatbot avec un regard critique externe
• Produire une critique globale et une critique spécifique du CV imprimable
• Transformer ces critiques en stratégie d'amélioration priorisée
• Versionner chaque run pour suivre l'évolution du positionnement
• Démontrer une migration technique complète : Node.js manuel → CrewAI script → CrewAI native autonome

Architecture globale

Agents & séparation des rôles

Séparation des sources

Séquences d'un run

Trois modes sont conservés en parallèle. Même contrat de sortie, trois niveaux d'abstraction (SDK direct → script CrewAI → CrewAI native).

Étape 1 — Node.js legacy, orchestration manuelle

npm run critique-cv
  │
  ├─ charge .env.local (ANTHROPIC_API_KEY)
  ├─ prépare reports/<timestamp>/
  │
  ├─ [1] Global Critic — Anthropic SDK direct
  │    lit : data.ts · chatbot-knowledge · system-prompt · tools · /cv · fiches
  │    écrit : global.md via writeFileSync
  │
  ├─ [2] Printable CV Critic — indépendant, sans contexte du [1]
  │    lit : data.ts · /cv · fiches techniques
  │    écrit : printable-cv.md
  │
  ├─ [3] Strategy Agent
  │    lit : global.md + printable-cv.md + context.md (manuellement)
  │    écrit : strategy.md
  │
  └─ summary.md + copie dans reports/latest/

Cette version contrôle explicitement chaque étape : prompts, séquence, passage de contexte, écriture des rapports — orchestration custom sans framework.

Étape 2 — Script Python CrewAI de migration

npm run critique-cv-crew
  │
  ├─ charge .env.local via python-dotenv
  ├─ prépare reports/<timestamp>/
  │
  ├─ Crew.kickoff() — Process.sequential
  │
  ├─ Task 1 : global_critic (External Portfolio Critic)
  │    role/goal/backstory formalisés · LLM via LiteLLM anthropic/claude-haiku-*
  │    context=[] — intentionnellement vide
  │    output_file → global.md (écrit automatiquement par CrewAI)
  │
  ├─ Task 2 : cv_critic (Printable CV & ATS Specialist)
  │    indépendant — context=[] intentionnellement vide
  │    output_file → printable-cv.md
  │
  ├─ Task 3 : strategy_agent (CV Strategy Synthesizer)
  │    context=[task_global, task_cv] → injection automatique des outputs
  │    context.md injecté dans la description de la tâche
  │    output_file → strategy.md
  │
  └─ write_report() + write_summary() → latest/

Étape 3 — CrewAI native autonome

PYTHONPATH=src python -m cv_critic_agent.main
  │
  ├─ charge .env.local / .env
  ├─ sélectionne le provider LLM
  │    par défaut : CV_CRITIC_PROVIDER=mistral
  │
  ├─ CVCriticCrew
  │    ├─ Global Critic
  │    ├─ Printable CV Critic
  │    └─ Strategy Agent
  │
  └─ reports/<timestamp>/ + reports/latest/

La version cible vit dans un repo séparé cv-critic-agent avec un package Python, une CLI, une configuration CrewAI native, des tests et un provider Mistral par défaut.

Durée typique : 60 à 120 secondes (3 appels LLM séquentiels, contexte large).

Migration Node.js → CrewAI

Trois implémentations maintenues côte à côte. La migration explicite les responsabilités : agents, tâches, prompts, sources, providers LLM, rapports et tests.

Pourquoi CrewAI

Les 3 agents (Global Critic → Printable CV Critic → Strategy) correspondent au modèle Agent/Task/Crew : rôles distincts, séquence fixe, un seul agent lit les outputs des autres. L'orchestration manuelle Node.js a été conservée en miroir pour permettre la comparaison directe entre les deux niveaux d'abstraction.

Ce qui ne change pas

• L'architecture métier est identique (3 agents, 2 critics indépendants, 1 stratège)
• L'indépendance des critics est préservée — context=[] intentionnellement vide sur les deux tasks critics
• Les fichiers sources lus sont exactement les mêmes
• Le format de sortie (Markdown, dossiers horodatés, latest/) est identique

Provider LLM paramétrable

CV_CRITIC_PROVIDER=mistral
CV_CRITIC_MODEL=mistral-medium-latest
MISTRAL_API_KEY=...

# fallback de comparaison
CV_CRITIC_PROVIDER=anthropic
CV_CRITIC_MODEL=claude-haiku-4-5-20251001
ANTHROPIC_API_KEY=...

Le provider n'est plus figé dans le code. Le mode mock reste le standard pour les tests, Mistral devient le choix par défaut pour les runs réels à coût réduit.

Étapes techniques de refactoring

Tests automatisés (288 tests, 0 appel API)

• Séparation critics vs strategy : les critics ne lisent pas context.md
• Parité des sorties entre CrewAI native, script CrewAI et Node.js legacy
• Mock LLM sans appel API réel — avec injection custom de responses
• Régression context.md : strategy l'injecte dans les 3 implémentations
• Nettoyage messages Mistral : clean_mistral_messages strip cache_breakpoint
• API FastAPI testée avec Mock LLM : runs, rapports, sources, graph
• Phase 5 S1–S4 : crypto HMAC (signature timing-safe, replay, expiry), PII Fernet (round-trip, tampering), logging filter (mask emails), security middleware (Turnstile, rate limit, headers), notifier Telegram + Resend (network errors, malformed JSON, owner-id check), access-request model (state machine + IP binding + quotas), store (fcntl concurrency, lazy TTL, PII at rest), endpoints Sprint 4 (49 tests : honeypot, captcha, HMAC decide, idempotence, Telegram webhook, admin magic-link, PATCH approve/reject/revoke)
• Phase 5 S5–S7 : real-run gate (verify_session sig + exp + approved + IP-bind + quota), Store.atomic_consume_run (locked read+validate+bind+consume+write), budget/tracker.py (concurrence multi-thread, alertes 80/100 % idempotentes, race buffer Python corrigée par fh.flush() avant LOCK_UN), budget/wiring.py (record_real_run alert dispatcher, fail-soft, factory injectable), cron_router.py (auth hmac.compare_digest, idempotence, dégrade gracefully si stores non configurés), BudgetTracker.cleanup_old_days (rétention configurable, dates lexicographiques UTC)

Gestion du contexte interne

Le fichier context.md contient les décisions internes déjà validées que le Strategy Agent doit respecter.

Exemples de décisions dans context.md

• Ne pas prétendre avoir implémenté le service AI/RAG Sense (délégué à une équipe dédiée)
• Présenter Resell Radar comme veille automatisée d'annonces publiques (pas "scraper")
• Séparer SAIF-IA (vend) et CV Critic Agent (challenge)
• Garder le CV imprimable lisible sans le surcharger

Sorties & versioning

Chaque run génère un dossier horodaté et une copie latest pour accès rapide. Les trois implémentations produisent la même structure.

reports/
  2026-06-04T19-16-50Z/       # run CrewAI native
    global.md                 # critique globale (252 lignes)
    printable-cv.md           # critique CV imprimable (252 lignes)
    strategy.md               # plan d'action P0/P1/P2 (180 lignes)
    summary.md                # résumé exécutif

  2026-05-14T21-52-40Z/       # run Node.js
    global.md
    printable-cv.md
    strategy.md
    summary.md

  latest/                     # dernier run (mis à jour automatiquement)
    global.md
    printable-cv.md
    strategy.md
    summary.md

Plan de déploiement CrewAI native

Phase 1 — CLI locale

• Commande smoke test : PYTHONPATH=src python -m cv_critic_agent.main --mock
• Commande réelle : PYTHONPATH=src python -m cv_critic_agent.main
• Configuration via .env.local : provider, modèle, clé Mistral
• Sortie attendue : reports/latest/*.md

Phase 2 — GitHub Actions CI

• Workflow .github/workflows/ci.yml actif
• Lint Ruff sur src, tests, scripts
• Tests mock sans appel LLM réel
• Contrôle de drift des sources prêt à brancher sur cv-portfolio

Phase 3 — API + UI locale

• FastAPI : POST /api/runs, GET /api/runs/{id}, GET /api/runs/{id}/events, GET /api/runs/{id}/reports/{slug}
• UI Next.js : landing, lancement mock, graphe Live Agent, panneau sources et rapports
• Authentification simple pour les runs réels via CV_CRITIC_API_TOKEN
• CORS configurable avec CV_CRITIC_ALLOWED_ORIGINS

Phase 4 — Déploiement (livré)

• API Python sur Render free tier (région Frankfurt) via Infrastructure-as-Code render.yaml
• URL API : https://cv-critic-agent-api.onrender.com
• UI Next.js sur Vercel avec domaine custom : https://agentic-ai.saifallah.dev (CNAME Cloudflare vers cname.vercel-dns.com)
• Variable UI : NEXT_PUBLIC_API_URL=https://cv-critic-agent-api.onrender.com
• Secrets serveur sur Render dashboard : MISTRAL_API_KEY, CV_CRITIC_API_TOKEN
• CORS restreint : CV_CRITIC_ALLOWED_ORIGINS=https://agentic-ai.saifallah.dev,https://cv-critic-agent.vercel.app
• Runs mock publics gratuits, runs réels protégés par token X-API-Token

Choix Render plutôt que Vercel pour l'API : le backend est statefull (RunManager en RAM, threads, écriture fichiers reports/<timestamp>/, SSE long-lived 60-90s). Le modèle serverless de Vercel Functions imposerait une réécriture vers Redis + queue + Blob storage. Render free tier accepte le design tel quel (1 container always-on, disk attaché, cold start 30s acceptable pour une démo).

Phase 5 — Access gate avec validation humaine

Ouvre les real runs au public derrière un flow d'approbation human-in-the-loop. Plan complet et threat model : docs/PHASE5_ACCESS_GATE.md. 7 sprints, S1–S7 livrés au 9 juin 2026 (288 tests verts + UI 8 routes), reste sync portfolio + smoke prod.

Flow utilisateur cible

1. Demandeur remplit un formulaire (nom, société, email, motif) protégé par Cloudflare Turnstile (siteverify server-side, score < 0.5 rejeté).
2. Owner reçoit la demande sur Telegram (inline buttons Approve / Reject) et par email (liens HMAC signés, accept encodé dans le token pour bloquer le tampering URL).
3. Owner approuve → session token HMAC envoyé par email au demandeur, lié à son email, lié à son IP à la 1ère utilisation, valide 24 h, quota 3 runs.
4. Budget cap quotidien (MAX_TOKENS_PER_DAY=200000) avec alertes Telegram à 80 % et 100 %, dégradation vers mock au-delà.

Threat model

6 adversaires (bot crawler, curieux, concurrent hostile, attaquant ciblé, canal owner compromis, insider futur) × 6 surfaces (formulaire public, décision owner, session requester, OAuth optionnel V2, stockage PII, exécution run). Décisions principales : Cloudflare Turnstile, magic-link admin (pas de token en URL), Fernet pour PII at rest, IP-binding au lieu de cookies cross-origin, rétention 7 j pending / 90 j décidées avec endpoint RGPD DELETE.

Sprints livrés

Conventions code (Phase 5)

• Pas d'env read dans les modules métier — secrets (bot_token, fernet_key, hmac_secret, api_key) passés explicitement, api.py seul lit os.environ au startup.
• Fail-soft sur I/O externe — Telegram / Resend / Turnstile retournent False sur erreur réseau, jamais d'exception au caller.
• Tests unittest negative-first — un test par concern, mock async _RecordingClient qui capture url / json / headers, factory injectée via http_client_factory=.
• PII jamais en clair sur disque ni dans les logs — Fernet at rest pour name / company / email / motive, IP et status restent indexables en clair, filter logging mask les emails.

Limites & suite

Limites actuelles

• Pas d'application automatique des recommandations
• Pas de comparaison automatique entre deux runs
• Pas de scoring stable par grille mathématique
• Dépend d'un LLM externe — les résultats peuvent varier d'un run à l'autre
• Les décisions finales restent humaines

Suite directe

• Phase 5 — smoke test prod (Telegram + Resend + Turnstile en conditions réelles, vérifier que l'alerte 80 % tombe et que le degrade real→mock s'enclenche au cap)
• Fichier action-plan.md cocheable
• Comparateur de runs pour suivre l'évolution entre versions
• Grille de scoring fixe et reproductible