Tuteur

Le tuteur est Gaspard dans son rôle d’enseignant. À partir d’une leçon (un titre et son contenu en Markdown), il explique, crée des quiz et des cartes de révision, et corrige les réponses rédigées. Il s’adapte au niveau de l’apprenant et à son pays (formes régionales, numéros d’urgence).

Scope tutor, réservé aux applications serveur (clé secrète). Les tokens du modèle comptent dans le quota mensuel de l’application (usage dans chaque réponse) ; quand il est épuisé, le tuteur répond 429 token_quota_exceeded. Rien n’est conservé : ni la leçon, ni les réponses.

La leçon et l’apprenant #

Toutes les routes reçoivent la leçon, et la plupart l’apprenant :

{
  "locale": "fr",
  "lesson": {
    "course_title": "Biologie végétale",
    "title": "La photosynthèse",
    "objectives": ["Expliquer le rôle de la chlorophylle"],
    "content": "La photosynthèse permet aux plantes de produire du glucose…"
  },
  "learner": {
    "first_name": "Awa",
    "level": "bachelor",
    "program": "Biologie",
    "study_year": 1,
    "country_code": "SN"
  }
}

• locale : fr, de ou en. content : le tuteur garde les 6 000 caractères les plus utiles.
• learner.level : secondary, apprenticeship, bachelor (défaut), master… Tous les champs de l’apprenant sont facultatifs.

Expliquer #

POST /v1/public/tutor/explanations : un dialogue dans la leçon, du plus ancien message au plus récent, le dernier venant de l’apprenant. mode : explain (défaut), socratic (le tuteur guide par des questions) ou exam_prep.

curl -X POST https://hubmix.dealmood-solutions.com/v1/public/tutor/explanations \
  -H "Authorization: Bearer $VC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lesson": {"title": "La photosynthèse", "content": "…"},
    "mode": "explain",
    "messages": [{"role": "user", "content": "Pourquoi les feuilles sont-elles vertes ?"}]
  }'

{
  "text": "Les feuilles contiennent de la **chlorophylle**, qui absorbe surtout le rouge et le bleu…",
  "follow_ups": ["Que se passe-t-il en automne ?"],
  "usage": { "model": "…", "prompt_tokens": 512, "completion_tokens": 141, "duration_ms": 2100 }
}

Quiz #

POST /v1/public/tutor/quizzes : count de 1 à 10 (défaut 5), difficulty (easy, medium, hard), kinds parmi single_choice, multiple_choice, true_false, short_answer.

Chaque question a son prompt, ses choices (vides pour une réponse courte), les correct_choice_ids ou l’expected_answer, et une explanation.

Cartes de révision #

POST /v1/public/tutor/flashcards : count de 1 à 20 (défaut 10). Réponse : {"cards": [{"front", "back"}], "usage"}.

Corriger une réponse #

POST /v1/public/tutor/grades :

{
  "lesson": { "title": "La photosynthèse" },
  "question": { "prompt": "Que rejette la photosynthèse ?", "expected_answer": "De l’oxygène." },
  "answer": "Elle rejette du CO2.",
  "country_code": "FR"
}

Réponse : score (de 0 à 1), verdict (correct, partial, incorrect), feedback (80 mots au plus, bienveillant, qui dit ce qui manque) et usage.

Erreurs : 403 insufficient_scope, 422 invalid_request, 429 token_quota_exceeded, 503 tutor_unavailable (réessayez après Retry-After). Voir Erreurs, limites et quotas.