Medusa Extend · IA
Créer un draft order à la voix dans Medusa
Un commercial dicte une commande sur son téléphone. L’assistant retrouve l’entreprise et les variantes des produits, vérifie les quantités et le stock, puis demande confirmation avant de créer un brouillon de commande dans Medusa.
Prenons Linwood Clothing, un grossiste qui vend des chemises et des vestes à des boutiques indépendantes. Son application Medusa contient déjà ses clients professionnels, chacun avec un contact acheteur et des adresses, et indique quel commercial suit chaque entreprise. Nous concevons un assistant de commande pour les commerciaux de Linwood.
Entre deux visites, Alex, l'un des commerciaux, envoie un message vocal à l'assistant. Supposons que le service de transcription le restitue ainsi :
« Bon, pour So and So à Bristol, six Harbor Shirt bleu marine en M et trois en L. »
La transcription se trompe sur deux noms. Alex parlait de Sew & Sew, une boutique : en anglais, « sew » et « so » se prononcent de la même façon, et le service a écrit l'expression courante « so and so », l'équivalent de « Untel ». Alex parlait aussi de la Harbour Shirt, un produit du catalogue : « Harbor » et « Harbour » sont deux graphies du même mot, américaine et britannique, et le service a choisi la première. Même avec les bons noms, la phrase désigne les choses comme on le fait à l'oral, alors que Medusa attend des enregistrements : l'identifiant d'une entreprise et ceux des deux variantes de chemise voulues par Alex.
L'objectif est de créer un draft order, un brouillon de commande dans Medusa.
Le service de transcription transforme l'audio en texte et ne connaît ni les clients ni le catalogue de Linwood. Un modèle de langage lit ce texte, appelle des outils sur le serveur pour chercher et vérifier les données de Linwood, et rédige les questions qu'Alex lit ; le modèle et ces outils forment ensemble l'assistant. Un workflow Medusa crée le brouillon de commande seulement après qu'Alex a confirmé un récapitulatif.
Ce que le modèle tire de la transcription
Une fois la transcription reçue, le modèle de langage la lit. Il n'a encore appelé aucun outil de recherche. Il range la demande dans une structure fixe : quelle entreprise, quelles lignes, et pour chaque ligne le produit, les options et la quantité. Pour la phrase d'Alex, il produit :
- entreprise : « So and So », lieu « Bristol » ;
- ligne 1 : produit « Harbor Shirt », couleur « bleu marine », taille « M », quantité 6 chemises ;
- ligne 2 : produit « Harbor Shirt », couleur « bleu marine », taille « L », quantité 3 chemises. Alex a seulement dit « trois en L » : le produit et la couleur sont marqués comme repris de la ligne 1.
Le serveur enregistre ce résultat comme la fiche de préparation du message d'Alex : un enregistrement de l'extension, distinct du brouillon de commande Medusa. Chaque valeur garde les mots dont elle vient et porte une marque : dite dans la transcription, ou reprise d'une autre ligne. Les champs d'identifiant sont vides. « So and So » est du texte, pas l'enregistrement d'une entreprise. « M » est une lettre de la transcription, pas encore une taille dont on sait que la Harbour Shirt existe.
Chaque quantité garde son unité. « Six chemises » est enregistré comme six chemises ; « deux packs » serait enregistré comme deux packs, sans conversion.
Le modèle a pour consigne de ne pas combler les manques. Si Alex avait dit « quelques chemises bleu marine en M », la quantité serait notée manquante, pas fixée à un. Si la transcription donnait deux quantités pour la même ligne sans dire laquelle remplace l'autre, le modèle demanderait à Alex de répéter ce passage. Les champs d'identifiant restent vides pendant cette extraction. Plus tard, le modèle ne pourra prendre un identifiant que dans un résultat d'outil, et le serveur y veille : il refuse tout identifiant que ses propres outils n'ont pas renvoyé dans cette conversation.
Certaines erreurs de transcription ne laissent aucune trace. Si Alex dit « cinq » et que la transcription écrit « cent », la phrase reste normale, et rien ne signale l'erreur au modèle. C'est l'une des raisons pour lesquelles Alex relit un récapitulatif avant toute création.
La fiche de préparation contient maintenant un nom d'entreprise et deux lignes de produits, toujours avec les mots d'Alex. L'assistant doit retrouver l'entreprise et les références du catalogue qui correspondent, en commençant par l'entreprise.
Retrouver l'entreprise derrière « So and So »
Le modèle ne reçoit jamais la liste complète des entreprises de Linwood. Elle peut compter des milliers de noms, la plupart non suivis par Alex, et une copie placée dans un prompt peut devenir fausse dès qu'une boutique ferme son compte. Le serveur donne plutôt au modèle un outil de recherche : le modèle l'appelle avec quelques mots, et l'outil renvoie une poignée d'entreprises pour lesquelles Alex a le droit de commander.
L'outil s'appuie sur le Search Module de Medusa. L'extension déclare un index des entreprises : le nom et la ville servent à la recherche, le statut et le commercial attitré servent de filtres. La même définition liste les événements qui mettent l'index à jour quand une entreprise change, et le code de l'extension doit émettre ces événements. L'outil interroge l'index avec query.search, qui prend du texte libre, des filtres et un nombre maximal de résultats. Le serveur ajoute deux filtres à chaque appel, entreprises actives seulement et entreprises suivies par Alex seulement, et le modèle ne peut pas les modifier. Comme un index peut être en retard sur les données, l'outil relit aussi chaque entreprise trouvée dans les données de l'application avant de la renvoyer.
Deux sortes d'écart peuvent séparer la transcription d'un nom enregistré chez Linwood. La première est orthographique : un accent manquant, une lettre inversée, « Harbor » pour « Harbour ». L'outil active la tolérance aux fautes de frappe pour ces cas. Avec le fournisseur PostgreSQL, la recherche compare les mots par séquences de trois lettres et ignore les accents, si bien qu'un nom écrit un peu différemment peut encore correspondre. La seconde est un autre mot qui se prononce pareil : à l'écrit, « so » et « sew » n'ont en commun que leur première lettre. La tolérance aux fautes compare des lettres, pas des sons ; rien ne garantit donc qu'une recherche sur « so and so » trouve Sew & Sew.
Augmenter le nombre de résultats ne fait pas apparaître une correspondance absente. La limite coupe une liste déjà filtrée et classée ; si Sew & Sew n'y figure pas, une liste plus longue ne la contiendra pas davantage. C'est la requête elle-même qui doit changer.
Le modèle lance donc plusieurs recherches courtes, chacune fondée sur une hypothèse différente :
- les mots tels que transcrits, « so and so » ;
- une ou deux graphies que le modèle juge compatibles avec le même son, comme « Sew and Sew » ;
- le lieu seul : les entreprises suivies par Alex à Bristol. Il n'y a alors pas de texte à classer, donc l'outil les lit directement dans les données de l'application, filtrées sur la ville.
La ville n'est pas ajoutée comme filtre aux deux premières recherches. C'est un indice, et un indice peut lui aussi être mal entendu : si la transcription s'était trompée de ville, ce filtre aurait écarté la bonne boutique.
Le serveur borne l'effort : quelques recherches par mention, quelques résultats par recherche. Il fusionne les listes, retire les doublons et garde au plus dix candidats, une limite choisie pour cet exemple, chacun étiqueté avec la recherche qui l'a trouvé. Ici, la première recherche ne renvoie rien. La deuxième renvoie deux entreprises : Sew & Sew à Bristol, et Sew & Sew à Cardiff, une autre boutique du même nom. La troisième renvoie de nouveau Sew & Sew à Bristol, plus deux autres boutiques de Bristol, Kite & Kin et Marlow Menswear. Le serveur transmet ces quatre entreprises distinctes au modèle ; Alex ne verra que celles qui demandent une confirmation.
Le modèle compare ensuite chaque candidat à la transcription. Les deux Sew & Sew correspondent au nom demandé par la deuxième recherche, et un score de recherche ne fait que classer la proximité du texte : il ne dit pas au modèle quelle boutique Alex visait. C'est la ville qui les départage : la transcription dit Bristol, une seule des deux est à Bristol, et c'est aussi pour cela que la troisième recherche l'a renvoyée. Kite & Kin et Marlow Menswear n'ont en commun avec la transcription que la ville. Sew & Sew à Bristol est le candidat le mieux étayé, mais son lien avec « so and so » repose sur une ressemblance sonore que le modèle a supposée. Le modèle ne choisit donc pas l'entreprise seul. Il demandera à Alex de confirmer Sew & Sew à Bristol, en citant la boutique de Cardiff comme autre possibilité.
Si la transcription n'avait donné aucune ville et qu'aucune recherche n'avait renvoyé de candidat convaincant, le modèle ne prendrait pas le plus proche. Il demanderait à Alex la ville, la rue ou l'orthographe du nom, puis lancerait une nouvelle recherche bornée avec la réponse.
L'entreprise n'est pas encore confirmée, mais le modèle ne s'arrête pas là. Il passe aux deux lignes, pour que toutes ses questions parviennent à Alex dans un seul message.
Du nom du produit au stock disponible
Les produits passent par le même type d'outil de recherche, adossé à un second index que le serveur limite aux produits publiés dans le canal de vente de l'application B2B de Linwood. « Harbor Shirt » ne diffère de « Harbour Shirt » que par l'orthographe, et dans cet exemple la recherche renvoie trois produits : la Harbour Shirt, la Harbour Jacket et l'Oxford Shirt. Le modèle garde la Harbour Shirt, la seule qui correspond aux deux mots de la transcription. Si deux produits avaient correspondu aussi bien, il aurait posé la question à Alex.
Connaître le produit ne donne pas encore une ligne que Medusa peut accepter. Le serveur fait trois vérifications sur chaque ligne.
La première porte sur la variante : la combinaison d'options qui sera réellement commandée. Dans Medusa, un produit se vend à travers ses variantes. La Harbour Shirt existe en trois couleurs, Navy (bleu marine), White (blanc) et Olive (vert olive), et en quatre tailles, Small, Medium, Large et X-Large (S, M, L et XL) ; chaque paire couleur-taille est une variante distincte, avec son propre identifiant. Le catalogue garde ces libellés anglais. Le serveur lit ces options dans le catalogue, pas dans l'index de recherche, et y rapporte les mots de la fiche de préparation : « bleu marine » et « M » donnent la variante Navy / Medium, « bleu marine » et « L » la variante Navy / Large. Si Alex avait dit « XXL », une taille qui n'existe pas pour cette chemise, l'assistant ne la remplacerait pas par X-Large : il poserait la question à Alex en listant les tailles proposées. Une ligne sans couleur donnerait aussi lieu à une question.
La deuxième porte sur la quantité : un nombre entier positif, dans l'unité que vend le catalogue. Linwood vend cette chemise à l'unité ; si Alex dicte des packs ou des cartons, l'assistant demande combien de chemises cela représente. Une quantité manquante ou contradictoire n'est jamais complétée : le modèle pose la question. Si Alex dicte « six en M » puis « deux de plus en M », le serveur vérifie les deux lignes ensemble, car c'est leur total que le stock doit couvrir. Si une seconde mention peut être une correction plutôt qu'un ajout, le modèle demande de quoi il s'agit avant d'additionner quoi que ce soit.
La troisième porte sur le stock disponible : combien d'unités de cette variante Linwood peut vendre dans ce canal de vente. Medusa ne garde pas ce nombre dans un seul champ. Le stock d'une variante est réparti entre des emplacements de stock, comme des entrepôts, et un canal de vente n'est servi que par certains d'entre eux. À chaque emplacement, la quantité disponible est le stock présent moins ce qui est déjà réservé. La disponibilité d'une variante dans un canal additionne ces quantités sur les emplacements liés à ce canal. Le stock d'un entrepôt qui ne sert pas le canal B2B ne compte pas, et une livraison annoncée n'est disponible qu'à son arrivée. L'outil de disponibilité du serveur s'appuie sur l'utilitaire de Medusa pour ce calcul. Cet utilitaire gère aussi les variantes composées d'articles d'inventaire : un pack de trois peut être configuré pour consommer trois unités du même article d'inventaire que la variante à l'unité, et l'utilitaire compte alors combien de packs ce stock permet de fournir. L'outil signale aussi les variantes dont le stock n'est pas suivi : Medusa les considère comme toujours commandables, et le calcul peut renvoyer zéro pour elles sans qu'elles soient épuisées.
Plus de trois Navy / Large sont disponibles dans le canal B2B. Pour Navy / Medium, l'outil en renvoie quatre, et Alex en a demandé six.
Dans cet exemple, Linwood n'autorise pas la vente au-delà du stock (backorders) : l'assistant ne peut donc pas accepter six chemises quand quatre sont disponibles. Il ne ramène pas de lui-même la quantité à quatre, ne passe pas la ligne en chemises blanches et ne promet pas de date de réassort qu'il ne connaît pas. Il signale le manque à Alex et lui demande s'il faut passer la quantité à quatre ou retirer la ligne. Il peut aussi suggérer la même chemise en White / Medium si l'outil de disponibilité en montre assez, mais seulement comme une suggestion qu'Alex doit accepter. Medusa permet d'autoriser les backorders variante par variante ; un grossiste qui le souhaite configurerait cette règle sur le serveur, et le modèle ne pourrait toujours pas l'activer sur une variante ou une ligne.
Vérifier le stock ne le réserve pas. Quatre chemises disponibles maintenant peuvent n'être plus que deux dans une heure ; le serveur relit donc la disponibilité juste avant de créer le brouillon de commande.
Choisir l'étape suivante : chercher encore, demander ou proposer
Après ces vérifications, la ligne 2, trois Harbour Shirt Navy / Large, a un identifiant de variante et une vérification de stock à jour. Deux points restent ouverts : l'entreprise et la quantité de Navy / Medium. Le modèle choisit maintenant entre relancer une recherche, poser une question à Alex et montrer un récapitulatif à confirmer, dans les limites fixées par le serveur.
Avant qu'Alex confirme un récapitulatif, le modèle peut appeler les outils de recherche et de lecture, et demander au serveur de mettre à jour la fiche de préparation. Il n'a aucun outil qui crée un brouillon de commande. Le serveur vérifie chaque mise à jour proposée avant de l'enregistrer : un identifiant n'est accepté que si l'un de ses outils l'a renvoyé, le nombre de recherches par mention est plafonné, Alex doit avoir le droit de commander pour l'entreprise, la variante doit exister, la quantité doit être un nombre entier positif de chemises, et la règle sans backorder s'applique. Seul un récapitulatif confirmé ouvre au serveur le chemin vers la création du brouillon de commande, comme le décrit la dernière partie.
Le modèle part de ce que montre la fiche de préparation :
| Situation | Ce que fait l'assistant ensuite |
|---|---|
| Une recherche a renvoyé un seul candidat étayé par les indices, sans passer par une graphie supposée | Il enregistre ce candidat et poursuit la vérification de la commande sans questionner Alex. |
| Pas encore de candidat convaincant, et d'autres recherches sont permises | Il relance une recherche sur une autre hypothèse, comme une autre graphie ou la ville seule. |
| Aucun candidat après les recherches permises | Il demande à Alex la ville, la rue ou l'orthographe du nom, ou une référence ou une description du produit, puis relance une recherche avec la réponse. |
| Plusieurs candidats plausibles, ou un seul trouvé grâce à une graphie supposée | Il demande à Alex de confirmer le candidat trouvé grâce à une graphie supposée, ou montre deux ou trois candidats plausibles et demande lequel est le bon. |
| Une option ou une quantité manque | Il pose une question sur ce champ seulement. |
| Une valeur n'existe pas dans le catalogue, ou deux valeurs se contredisent | Il liste les valeurs qui existent, ou demande à Alex de répéter ce passage, sans choisir lui-même. |
| Le stock est insuffisant | Il indique le manque et demande à Alex de réduire la quantité, de retirer la ligne ou d'accepter une autre option dont le stock a été vérifié. |
| Tous les champs sont réglés | Il montre un récapitulatif qu'Alex doit confirmer. |
La commande d'Alex relève de deux de ces lignes : une entreprise à confirmer et un stock insuffisant. L'assistant garde les champs déjà réglés et regroupe les points ouverts dans un seul message. Tant qu'une réponse manque, aucun brouillon de commande n'existe. Alex lit :
« Je n'ai trouvé aucune boutique "So and So" parmi vos clients. Vouliez-vous dire Sew & Sew à Bristol, ou Sew & Sew à Cardiff ? Par ailleurs, seules quatre Harbour Shirt Navy / Medium sont disponibles, et vous en avez demandé six. Je passe la quantité à quatre, ou je retire cette ligne ? »
Appliquer la réponse d'Alex sans tout reprendre
Alex répond après la visite suivante : « Sew & Sew, Bristol. Quatre, ça va. »
Le modèle rattache chaque partie de la réponse au champ qu'elle concerne, « Sew & Sew, Bristol » à l'entreprise et « quatre » à la quantité de Navy / Medium, et demande ces deux mises à jour au serveur. Le serveur les vérifie et ne modifie que ces deux champs. Le champ entreprise contient désormais l'identifiant de Sew & Sew à Bristol, que l'outil de recherche avait renvoyé. La quantité de la ligne 1 passe de six à quatre, avec la réponse d'Alex enregistrée comme source. La ligne 2 ne fait pas l'objet d'une nouvelle recherche.
Repartir de la transcription exposerait à de nouvelles erreurs : le modèle pourrait lire « so and so » autrement cette fois, ou défaire une variante que le serveur avait déjà vérifiée. Tenir toutes les vérifications précédentes pour encore valables serait l'erreur inverse : la vérification de stock de la ligne 1 comparait quatre chemises disponibles à six demandées, et cette comparaison ne décrit plus la ligne. Le serveur enregistre donc de quels champs dépend chaque vérification ; quand un champ change, il refait les vérifications qui en dépendent, et seulement celles-là. Ici, la quantité de la ligne 1 a changé, donc le serveur relance sa vérification de stock : quatre demandées, quatre disponibles.
D'autres réponses déclencheraient d'autres vérifications. Si Alex avait répondu « six en blanc », le serveur aurait passé la ligne 1 en White / Medium, gardé six et vérifié le stock de cette variante. Si Alex avait choisi la boutique de Cardiff, le serveur aurait vérifié qu'Alex peut commander pour cette entreprise et relu son contact acheteur, ses adresses et ses conditions tarifaires, ainsi que toute vérification qui en dépend, car deux entreprises du même canal de vente peuvent avoir des prix différents. Les deux boutiques achètent par ce canal ; les vérifications de catalogue et de stock resteraient donc valables.
Une fois tous les champs réglés, le serveur construit un récapitulatif de la fiche de préparation et lui attribue un numéro de version. Tout changement ultérieur produit une nouvelle version, et une confirmation ne vaut que pour la version à laquelle elle répond. Un « oui » à la version 1 ne couvre pas une version 2 où une quantité a changé.
Alex lit la version 1 : Sew & Sew, Bristol ; 4 × Harbour Shirt, Navy / Medium ; 3 × Harbour Shirt, Navy / Large. Alex répond « oui », et le serveur enregistre ce oui avec le numéro de version.
Du « oui » au brouillon de commande
Le « oui » arrive sur une route d'API de l'extension, qui vérifie que le message vient du compte d'Alex et confie la suite à un workflow. Le workflow commence par des contrôles sans modèle ni recherche, uniquement des relectures fraîches des données. La confirmation répond-elle à la dernière version du récapitulatif ? Sew & Sew à Bristol est-elle toujours active, et toujours suivie par Alex ? Les deux variantes existent-elles encore, et sont-elles toujours vendues dans le canal ? Le stock disponible couvre-t-il encore quatre et trois chemises ? Si un contrôle échoue, par exemple parce que deux Navy / Medium ont été vendues entre-temps, le workflow ne crée aucun brouillon de commande. La confirmation tombe, et Alex reçoit une nouvelle question sur ce seul point.
Le brouillon de commande lui-même passe par le parcours natif de Medusa. La route Admin qui crée les draft orders appelle createOrderWorkflow avec le statut draft, et le workflow de l'extension fait de même. Ce qu'Alex n'a pas dicté vient de l'enregistrement de Sew & Sew dans l'application : sa région, son canal de vente, son contact acheteur et ses adresses. Les prix ne passent jamais par le modèle : createOrderWorkflow les calcule à partir des prix Medusa pour cet acheteur et cette région, et son hook setPricingContext permet à l'application d'ajouter les conditions tarifaires de l'entreprise.
createOrderWorkflow vérifie aussi que les variantes dont le stock est suivi en ont assez, et échoue sinon, sauf si le backorder est autorisé sur la variante ou sur la ligne. Cette proposition n'autorise ni l'un ni l'autre : si le stock baisse entre le dernier contrôle et la création, le workflow s'arrête et l'assistant revient à la question du stock. Le workflow ne réserve pas de stock : le brouillon de commande ne met pas de côté les quatre Navy / Medium.
Une exigence reste à implémenter et à tester dans l'extension : un « oui » doit créer un seul brouillon de commande. La confirmation pourrait arriver deux fois, ou le serveur pourrait s'arrêter juste après avoir créé le brouillon. Le mécanisme proposé donne à chaque confirmation une clé de création. Avant de créer le brouillon, le serveur s'attribue cette clé d'une façon qui ne peut réussir que pour un seul processus, puis il l'enregistre avec le brouillon de commande. Si la même confirmation est traitée à nouveau, le serveur renvoie ce brouillon au lieu d'en créer un autre. Le lien entre la clé et le brouillon doit survivre à un plantage et rester facile à retrouver.
Dans ce scénario, le workflow réussit. Medusa contient un brouillon de commande de plus, pour Sew & Sew à Bristol, avec deux lignes et des prix calculés par Medusa, et Alex reçoit un message qui le lui indique.