documentation/API_DOCUMENTATION.md

Interview Simulation API Documentation

Cette documentation détaille l'utilisation de l'API de simulation d'entretiens, motorisée par LangGraph et FastAPI.

Introduction

L'Interview Simulation API permet de mener des simulations d'entretiens d'embauche réalistes. Elle utilise un système d'agents spécialisés (Icebreaker, Auditeur, Enquêteur, Stratège, Projecteur) pour évaluer un candidat par rapport à une offre d'emploi spécifique.

Base URL: http://localhost:7860 (ou URL de déploiement)
Version: 1.0.0

Configuration & Authentification

L'API utilise des variables d'environnement pour la configuration :

• OPENAI_API_KEY: Requis pour les agents LLM.
• LANGTRACE_API_KEY: Pour l'observabilité (Langtrace).
• CORS_ORIGINS: Liste des origines autorisées (défaut: *).

Endpoints

1. Health Check

Vérifie que l'API est opérationnelle.

• URL: /
• Method: GET
• Success Response (200 OK):

  {
    "status": "ok"
  }
  

2. Simulate Interview

Déclenche ou poursuit une simulation d'entretien.

• URL: /simulate-interview/

• Method: POST

• Request Body:

  {
    "user_id": "string",          // ID unique de l'utilisateur
    "job_offer_id": "string",     // ID de l'offre d'emploi
    "cv_document": {              // Données extraites du CV
      "candidat": { ... }         // Voir section "Data Models"
    },
    "job_offer": {                // Détails de l'offre
      "poste": "string",
      "entreprise": "string",
      "mission": "string",
      ...
    },
    "messages": [                 // Historique de la conversation (optionnel)
      {
        "role": "user",
        "content": "Bonjour"
      },
      ...
    ],
    "cheat_metrics": { ... }      // Métriques anti-triche (optionnel)
  }
  

• Success Response (200 OK):

  {
    "response": "Texte généré par l'agent IA",
    "status": "interviewing" | "interview_finished"
  }
  

• Error Responses:

  • 400 Bad Request: Payload incomplet ou données invalides.
  • 500 Internal Server Error: Erreur lors de l'exécution du graph LangGraph.

Data Models (Schemas)

Feedback Output (Output final de l'analyse)

Une fois l'entretien terminé, un rapport complet est généré (via Celery) suivant cette structure :

• CandidatFeedback: Points forts, axes d'amélioration, conseils, score global.
• EntrepriseInsights:
  • Dashboard: Technique, Cognitive, Comportementale (0-100).
  • Decision: RECRUTER, APPROFONDIR ou REJETER.
  • Fraud Detection: Score global d'usage d'IA, mots-clés détectés, alertes (red flags).

Exemples d'Usage

Exemple cURL

curl -X POST http://localhost:7860/simulate-interview/ \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "job_offer_id": "job_456",
    "cv_document": { "candidat": { "first_name": "Jean", "expériences": [] } },
    "job_offer": { "poste": "Développeur Python", "entreprise": "TechCorp" },
    "messages": []
  }'

Exemple Python (Requests)

import requests

url = "http://localhost:7860/simulate-interview/"
payload = {
    "user_id": "user_123",
    "job_offer_id": "job_456",
    "cv_document": { "candidat": { "first_name": "Jean", "expériences": [] } },
    "job_offer": { "poste": "Développeur Python", "entreprise": "TechCorp" },
    "messages": [{"role": "user", "content": "Je suis prêt."}]
}

response = requests.post(url, json=payload)
print(response.json())

Error Handling

Toutes les erreurs renvoient un format JSON standardisé :

{
  "error": "Description de l'erreur"
}