Construire une analyse de rêves boostée à l'IA avec Mistral AI dans mon API Rails

Publié le : 29 avril 2026

Pastel est un projet que j'ai construit seul — une API où les utilisateurs consignent leurs expériences de sommeil : rêves, cauchemars, rêves lucides, et les schémas émotionnels qui vont avec. Récemment, j'ai décidé d'aller plus loin. Et si l'appli pouvait analyser ces rêves à ta place ? Et si elle pouvait lire la description, l'humeur, les tags, et te dire quelque chose de vraiment parlant sur ce que ton rêve essaie peut-être de te dire ?

Alors je l'ai construit. Avec Mistral AI, des background jobs, et beaucoup de code défensif. Voici comment je m'y suis pris.

Ce que je voulais

Le flow que j'avais en tête était simple : un utilisateur enregistre une entrée de sommeil avec un titre, une description, un type de sommeil (lucide, cauchemar, récurrent), des tags, son humeur du moment et l'intensité de l'expérience. À partir de tout ce contexte, je voulais renvoyer une interprétation structurée et pertinente — et dans sa langue, pas seulement en anglais.

Le plus dur, ce n'était pas l'appel à l'API. Le plus dur, c'était de rendre le tout fiable, testable et prêt pour la production.

L'architecture que j'ai retenue

POST /api/v1/sleeps/:id/analyse
│
▼
┌──────────────────────┐
│ SleepsController │ ← I validate status, enqueue the job
│ #analyse │
└──────────────────────┘
│
▼ (enqueue)
┌──────────────────────┐
│ SleepAnalyseJob │ ← Background job via Solid Queue
│ perform() │
└──────────────────────┘
│
▼ (call)
┌──────────────────────┐
│ SleepAnalysisService │ ← I call Mistral, parse the response
│ call() │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ Mistral AI API │ ← magistral-small-2509 model
│ /chat/completions │
└──────────────────────┘

C'est un pattern asynchrone classique en Rails. Le controller valide et met en file, le background job orchestre, et un service object encapsule la logique métier. Je te détaille chaque couche.

Premier problème : comment suivre le cycle de vie de l'analyse ?

L'analyse d'un rêve n'est pas instantanée. Il me fallait un moyen de savoir où en était chaque requête dans son cycle de vie. J'aurais pu me contenter d'un booléen — analysé ou non — mais ça me semblait fragile. Et si l'API part en timeout ? Et si le job crashe ? Et si l'utilisateur spamme l'endpoint ?

J'ai donc ajouté un vrai enum à trois états au modèle Sleep :

ANALYSIS_STATUS = {
  not_started: 'not_started',
  in_progress: 'in_progress',
  done: 'done'
}.freeze

enum :analysis_status, ANALYSIS_STATUS, default: 'not_started'

Et deux méthodes de transition d'état explicites, pour que rien n'arrive par accident :

def mark_as_analysis_not_started
  update(analysis_status: :not_started)
end

def mark_as_analysis_done(analysis)
  update(analysis: analysis, analysis_status: :done)
end

J'ai aussi chiffré le champ analysis avec les autres données sensibles (title, description, current_mood). Les résultats d'une analyse de rêve sont profondément personnels — ils méritent la même protection que le rêve d'origine :

encrypts :title, :description, :current_mood, :analysis

Consulte la documentation Rails sur Active Record Encryption pour en savoir plus sur cette fonctionnalité.

Enfin, un scope pour mon dashboard afin de suivre combien de rêves ont été analysés :

scope :ai_analyzed, -> { where.not(analysis: nil).where(analysis_status: :done) }

Le controller : l'idempotence, mon obsession

Quand j'ai écrit l'action #analyse, la première question que je me suis posée, c'est : qu'est-ce qui se passe si quelqu'un l'appelle deux fois ? Ou si une appli mobile relance la requête à cause d'une connexion lente ?

def analyse
  if @sleep.analysis_status == 'done' ||
     @sleep.analysis_status == 'in_progress' ||
     @sleep.analysis.present?
    return render json: {
      message: 'Sleep analysis already in progress or done',
      code: 'analysis_already_in_progress_or_done'
    }, status: :ok
  end

  locale = params[:locale] || I18n.default_locale
  SleepAnalyseJob.perform_later(@sleep.id, locale)

  @sleep.analysis_status = :in_progress
  if @sleep.save
    render json: SleepSerializer.render(@sleep, view: :update_and_show)
  else
    render json: { message: 'Failed to start sleep analysis', code: 'analysis_start_failed' },
           status: :unprocessable_content
  end
end

Trois décisions dont je suis fier ici :

  1. De l'idempotence partout. Je vérifie l'enum de statut ET la présence d'une analyse existante. L'endpoint peut être appelé cent fois — seul le premier appel fait quelque chose.
  2. Transmission de la locale. La locale part de la requête, passe par le job, puis par le service, et arrive directement dans le prompt Mistral. L'IA répond dans la langue de l'utilisateur.
  3. Mise à jour optimiste du statut. Je passe immédiatement le statut à in_progress. Si une deuxième requête arrive pendant que le job tourne, elle est rejetée proprement.

Solid Queue pour le traitement en arrière-plan

J'ai intégré Solid Queue — le backend Active Job intégré à Rails — pour gérer l'analyse des rêves de manière asynchrone. Faire un appel synchrone à une API d'IA pendant une requête de controller ? C'est une expérience utilisateur catastrophique.

class SleepAnalyseJob < ApplicationJob
  queue_as :sleep_analysis

  def perform(sleep_id, locale)
    sleep = Sleep.find_by(id: sleep_id)
    return if sleep.blank?
    return if sleep.analysis_status == 'done' || sleep.analysis.present?

    SleepAnalysisService.call(sleep, locale)
  rescue StandardError => e
    Rails.logger.error("Error analyzing sleep with ID: #{sleep_id} - #{e.message}")
    sleep.presence&.mark_as_analysis_not_started
    raise
  end
end

Trois couches de défense dans ce job :

  1. find_by au lieu de find. Si le sommeil a été supprimé entre le controller et l'exécution du job, je récupère nil au lieu d'un crash.
  2. Double vérification de l'idempotence. Les race conditions, ça existe. Le controller a passé le statut à in_progress, mais je vérifie à nouveau avant d'appeler le service.
  3. Récupération en douceur. Si quelque chose explose — API indisponible, problème réseau, peu importe — je remets le statut à not_started pour que l'utilisateur puisse réessayer. Puis je relance l'exception pour que le framework de jobs gère sa logique de retry.

Je l'ai aussi placé dans une queue dédiée :sleep_analysis. Si mon appli grandit et que j'ai d'autres traitements en arrière-plan, je peux contrôler la concurrence et la priorité queue par queue. Jette un œil à la documentation de Solid Queue pour les détails de configuration.

Le service : ma conversation avec Mistral

C'est la partie qui m'enthousiasmait le plus — et celle qui me rendait le plus nerveux. J'ai décidé d'utiliser Net::HTTP de la stdlib Ruby plutôt que d'ajouter une gem de plus. Pour une seule intégration d'API, je ne voulais pas du poids d'une dépendance comme Faraday ou HTTParty.

class SleepAnalysisService < ApplicationService
  def initialize(sleep, locale)
    super()
    @mistral_api_key = ENV.fetch('MISTRAL_API_KEY', nil)
    @mistral_api_url = 'https://api.mistral.ai/v1/chat/completions'
    @sleep = sleep
    @locale = locale
  end

  def call
    response = send_request_to_mistral
    result = parse_response(response) if response.present?
    update_sleep_with_analysis(result) if result.present?
  end

Un point d'entrée simple : envoyer, parser, persister. Chaque étape vérifie la précédente.

Pourquoi Mistral, et quel modèle

J'ai choisi le modèle magistral-small-2509 de Mistral. Il est rapide, économique et produit des réponses de qualité pour les tâches créatives et interprétatives. Le payload suit leur API de chat completions :

def build_payload
  {
    model: 'magistral-small-2509',
    response_format: { type: 'text' },
    messages: [
      { role: 'system', content: system_prompt },
      { role: 'user', content: user_prompt }
    ]
  }.to_json
end

Découvre la documentation complète de l'API Mistral pour les endpoints, l'authentification et plus encore.

Le plus dur : le prompt engineering

Je vais être honnête — j'ai réécrit le prompt système au moins cinq fois. La première version donnait des réponses trop génériques. La deuxième était trop clinique. Il fallait trouver un équilibre : pertinent sans être mystique, personnel sans être présomptueux.

Voici ce à quoi je suis arrivé :

def system_prompt
  <<~PROMPT
    You are an expert dream analyst combining psychology, symbolism, and emotional intelligence.
    Your role is to provide structured, insightful dream interpretations that feel personal and meaningful.

    When analyzing a dream, you must:
    - Identify the core narrative and dominant themes
    - Decode symbols and archetypes present in the dream
    - Connect the emotional tone (mood + intensity) to the dream's meaning
    - Consider the sleep type (lucid, nightmare, recurring, etc.) as interpretive context
    - Use the tags as thematic anchors to deepen the analysis
    - Reference the timing ("when") only if it adds contextual relevance

    Structure your response EXACTLY (adapt title to the language
    corresponding to this locale: #{locale}) as follows:

    ##### 🌙 Global interpretation
    A 3-4 sentence synthesis of the dream's overall meaning.

    ##### 🎭 Theme and meaning
    Identify 2-3 key symbols or themes and explain their psychological significance.

    ##### 💭 Emotional dimension
    Analyze how the mood and intensity level shape the dream's message.

    ##### 🔮 Points to consider
    2-3 open-ended questions or reflections.

    Keep the tone warm, insightful, and grounded.
    Respond in the language corresponding to this locale: #{locale}.
  PROMPT
end

Ce que j'en ai retenu :

Le prompt utilisateur est plus simple — je rassemble juste toutes les données du sommeil dans une requête cohérente :

def user_prompt
  <<~PROMPT
    Please analyze this dream and provide a structured interpretation:

    **Title:** #{sleep.title}
    **Type:** #{sleep.sleep_type}
    **When:** #{sleep.happened}

    **Description:**
    #{sleep.description}

    **Tags:** #{sleep.tags.pluck(:name).join(', ')}
    **Emotional state (current mood):** #{sleep.current_mood}
    **Dream intensity:** #{sleep.intensity}

    Use all of the above attributes in your analysis. The tags, mood,
    and intensity are especially important.
  PROMPT
end

Je fais en sorte de transmettre chaque attribut — le titre, le type, le moment où c'est arrivé, la description complète, les tags, l'humeur et l'intensité. Je précise explicitement que les tags, l'humeur et l'intensité sont importants, parce que l'IA a tendance à se concentrer uniquement sur la description et à ignorer les métadonnées.

La requête HTTP

Rien de sophistiqué ici — juste Net::HTTP avec une gestion d'erreurs correcte :

def send_request_to_mistral
  uri = URI(mistral_api_url)
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri.path, {
    'Content-Type' => 'application/json',
    'Authorization' => "Bearer #{mistral_api_key}"
  })
  request.body = build_payload
  response = http.request(request)

  if response.is_a?(Net::HTTPSuccess)
    response.body
  else
    Rails.logger.error "Failed to get response from Mistral API: #{response.code}"
    sleep.mark_as_analysis_not_started
    nil
  end
rescue StandardError => e
  Rails.logger.error "Error while sending request to Mistral API: #{e.message}"
  sleep.mark_as_analysis_not_started
  nil
end

Consulte la documentation Ruby de Net::HTTP pour en savoir plus sur les requêtes HTTP en Ruby.

Si quoi que ce soit se passe mal — erreur HTTP, panne réseau, peu importe — je le logue, je réinitialise le statut et je renvoie nil. L'appelant gère ce nil proprement.

Parser la réponse

def parse_response(raw_response)
  response = JSON.parse(raw_response)
  return response['choices'].first['message']['content'][1]['text'] if response.present?
  nil
end

Je vais être honnête — ce parsing est fragile. Le chemin vers le contenu texte dépend de la structure de réponse de Mistral. S'ils changent leur API, ça casse. Dans un système en production à grande échelle, j'utiliserais dig ou un validateur de schéma de réponse. Pour l'instant, ça fonctionne, et je sais exactement où regarder si ça casse.

Les tests : parce que je ne veux pas de mauvaise surprise sur la facture d'API

Tester des intégrations d'IA, c'est délicat. Je ne veux pas appeler la vraie API Mistral à chaque lancement des tests — ça coûte de l'argent, c'est lent et c'est instable. Mais j'ai besoin d'être sûr que mon code gère correctement de vraies réponses.

VCR à la rescousse

J'ai mis en place VCR pour enregistrer de vraies réponses d'API et les rejouer de façon déterministe :

# spec/support/vcr.rb
VCR.configure do |config|
  config.cassette_library_dir = 'spec/fixtures/vcr_cassettes'
  config.hook_into :webmock
  config.configure_rspec_metadata!
  config.filter_sensitive_data('<MISTRAL_API_KEY>') { ENV['MISTRAL_API_KEY'] }
end

Cette ligne filter_sensitive_data est cruciale — elle remplace ma vraie clé d'API dans les fichiers de cassette pour que je ne la commite jamais par erreur. Couplé à WebMock, VCR intercepte toutes les requêtes HTTP pendant les tests.

Ensuite, dans la spec de mon service :

describe SleepAnalysisService do
  let(:sleep) { create(:sleep, :with_tags) }
  let(:locale) { 'en' }

  describe '#call' do
    it 'analyzes the sleep and persists the result' do
      VCR.use_cassette('sleep_analysis_service/success') do
        service = described_class.call(sleep, locale)

        expect(sleep.reload.analysis).to be_present
        expect(sleep.analysis_status).to eq('done')
      end
    end
  end
end

La première fois que je lance ce test, VCR appelle la vraie API Mistral et enregistre la réponse. Toutes les fois suivantes, il rejoue la cassette. Rapide, déterministe, gratuit.

Tester le job

La spec du job vérifie l'idempotence et la récupération après erreur :

describe SleepAnalyseJob do
  let(:sleep) { create(:sleep) }

  it 'enqueues the job' do
    expect {
      described_class.perform_later(sleep.id, 'en')
    }.to have_enqueued_job.on_queue('sleep_analysis')
  end

  it 'does not analyze if already done' do
    sleep.mark_as_analysis_done('existing analysis')
    expect(SleepAnalysisService).not_to receive(:call)
    described_class.perform_now(sleep.id, 'en')
  end
end

Tester l'endpoint

Et au niveau des requêtes, je vérifie que le garde-fou d'idempotence fonctionne vraiment :

describe 'POST /api/v1/sleeps/:id/analyse' do
  context 'when analysis is already done' do
    before { sleep.mark_as_analysis_done('analysis text') }

    it 'returns ok with appropriate message' do
      post analyse_api_v1_sleep_path(sleep)
      expect(response).to have_http_status(:ok)
      expect(json_response['code']).to eq('analysis_already_in_progress_or_done')
    end
  end
end

Ce que j'ai appris en chemin

Le prompt engineering est itératif

Je ne le répéterai jamais assez. Le prompt système a connu au moins cinq révisions. Chacune était meilleure, mais il a fallu que je lise vraiment les réponses de l'IA et que je repère les schémas : trop vague, trop clinique, tags ignorés, mauvaise langue. C'est seulement en itérant sur de vraies réponses que j'ai obtenu quelque chose qui sonnait juste.

Les machines à états te protègent de toi-même

L'enum à trois états, combiné aux doubles vérifications au niveau du controller et du job — ça m'a évité des bugs que je ne savais même pas que j'allais avoir. Race conditions, retries, requêtes en double — tout est géré proprement parce que j'ai réfléchi aux cas d'échec dès le départ.

VCR vaut le temps de mise en place

Enregistrer les réponses d'API une fois et les rejouer à l'infini, c'est un super-pouvoir. Ma suite de tests tourne vite, je ne m'inquiète jamais des rate limits de l'API, et je ne brûle pas de crédits à chaque run de CI.

Toujours réinitialiser en cas d'échec

Au début du développement, j'avais un bug où un appel d'API échoué laissait le statut bloqué sur in_progress. L'utilisateur ne pouvait pas réessayer. L'analyse était orpheline. C'est là que j'ai ajouté les appels à mark_as_analysis_not_started dans chaque chemin d'erreur. Le code défensif, ce n'est pas de la paranoïa — c'est de l'expérience.

Moins il y a de dépendances, mieux c'est

J'aurais pu ajouter Faraday, HTTParty ou un SDK Mistral dédié. À la place, j'ai utilisé Net::HTTP et ça marche très bien. Le code est un peu plus verbeux, mais j'ai une gem de moins à maintenir et une dépendance de moins à auditer.

Pour conclure

Construire cette fonctionnalité a été un super exercice : envelopper quelque chose d'intrinsèquement imprévisible — un appel à une API d'IA — dans une infrastructure prévisible et bien testée. L'intégration de Mistral elle-même représente peut-être 30 % du travail. Les 70 % restants, c'est le suivi des statuts, les background jobs, la récupération après erreur, l'idempotence et les tests.

C'est de ça que je suis le plus fier : pas d'avoir appelé une API d'IA, mais d'avoir construit autour un système assez résilient pour tourner en production sans que j'aie à le surveiller en permanence.

Si tu construis quelque chose de similaire, mon conseil : passe plus de temps sur la plomberie que sur le prompt. Un bon prompt avec une mauvaise gestion d'erreurs échouera en silence. Un prompt moyen avec une excellente gestion d'erreurs échouera au moins proprement — et tu auras les logs pour corriger le prompt plus tard.

Tu peux consulter l'implémentation complète dans la Pull Request sur GitHub.