fastapi-fullstack : un générateur de projet qui assemble FastAPI, Next.js et une pile RAG

Le problème que la commande fastapi-fullstack prétend résoudre

Monter une application d'agent conversationnel en Python implique aujourd'hui d'assembler plusieurs morceaux qui n'ont rien à voir entre eux : un serveur ASGI, une couche WebSocket pour le streaming des tokens, un schéma de base relationnelle, une base vectorielle pour la recherche, une page de connexion, et un panneau d'administration pour les utilisateurs. Le dépôt part du constat que ces briques sont presque identiques d'un projet à l'autre et les livre sous forme de gabarit paramétrable. Le public visé est l'ingénieur qui connaît Python et TypeScript mais qui ne veut pas passer une semaine sur la plomberie avant d'écrire sa première requête vers un modèle. La page d'accueil du projet parle d'un générateur de projet FastAPI + Next.js avec agents IA, RAG et plus de vingt intégrations. C'est une description de générateur, pas de framework : le résultat est du code que vous possédez, pas une dépendance que vous appelez.

Ce que le générateur écrit sur le disque

L'installation se fait par pip, uv ou pipx, selon les trois commandes listées dans le README. Une fois l'outil présent, la commande fastapi-fullstack sans argument lance un assistant interactif qui pose des questions et produit une arborescence de projet. Le README ne détaille pas chaque invite, mais la section Configuration Options et le configurateur web en ligne laissent entendre que les choix portent au minimum sur le framework d'agent, la base vectorielle et les intégrations. Le nom du paquet sur PyPI, fastapi-fullstack, diffère du nom du dépôt GitHub, ce qui surprend au premier abord : chercher le dépôt par le nom du paquet ne fonctionne pas. Le gabarit couvre cinq frameworks d'agent (PydanticAI, PydanticDeep, LangChain, LangGraph, DeepAgents) et quatre bases vectorielles (Milvus, Qdrant, pgvector, ChromaDB). Le README précise aussi que le framework deepagents s'appuie sur pydantic-deepagents, un projet distinct de la même organisation. Autrement dit, choisir cette option fait entrer dans votre pile un second dépôt maintenu séparément.

make bootstrap : ce que la cible fait réellement

Le README décrit make bootstrap comme un alias de make dev suivi de make seed. La cible construit l'image Docker du backend, démarre la pile via docker-compose.dev.yml, attend PostgreSQL avec pg_isready, applique les migrations Alembic, puis insère un compte administrateur par défaut. Le fichier compose est explicitement nommé docker-compose.dev.yml, ce qui suppose l'existence d'une variante de production que le README ne décrit pas dans les extraits fournis. Le frontend se lance séparément, avec bun install puis bun dev dans le répertoire frontend. Deux détails méritent l'attention. D'abord, la cible seed crée un compte admin avec une adresse du type admin@ex..., tronquée dans le matériel fourni : la valeur exacte et le mot de passe associé ne sont pas confirmés ici. Ensuite, l'outil de gestion de paquets retenu côté frontend est bun, pas npm ni pnpm. Si votre équipe est standardisée sur npm, il faudra adapter la commande et probablement le lockfile, ce que la documentation ne traite pas.

Le streaming, la persistance et le partage de conversations

La démonstration principale du dépôt montre une conversation avec un plan et une liste de tâches qui se mettent à jour en direct. Le mécanisme annoncé est le streaming par WebSocket entre FastAPI et le client Next.js 15. Le README mentionne également le partage de conversations sous trois formes : partage direct, liens publics et navigateur administratif. Ces éléments impliquent une couche de persistance des messages et des sessions, cohérente avec la présence d'Alembic et de PostgreSQL. En revanche, le format exact des événements WebSocket, la stratégie de reprise après déconnexion et la gestion de la concurrence sur une même conversation ne figurent pas dans les extraits disponibles. Pour un projet qui place le streaming au centre de son argumentaire, c'est le point que je vérifierais en premier dans le code généré, avant même de brancher un modèle.

Les choix de pile qui deviennent des contraintes

Un générateur vous fait gagner du temps au démarrage et vous en fait perdre plus tard, proportionnellement au nombre de décisions qu'il a prises à votre place. Ici, la liste est longue : Pydantic pour la validation, Alembic pour les migrations, Celery pour les tâches asynchrones, Docker et des manifestes Kubernetes, JWT et OAuth pour l'authentification. Si votre organisation utilise déjà un autre ordonnanceur que Celery, ou si elle interdit les tâches en arrière-plan hors d'un service managé, vous devrez retirer du code plutôt que l'ajouter. Le cas où l'outil est franchement inadapté est celui d'une application sans agent : une API REST classique avec quelques endpoints n'a rien à faire d'une base vectorielle, d'un pipeline RAG et d'un client WebSocket. Le gabarit ajouterait de la surface de maintenance sans contrepartie. Le second cas défavorable est un projet qui doit rester sur une seule base de données : ajouter Milvus ou Qdrant à côté de PostgreSQL crée un second système à sauvegarder, à superviser et à mettre à niveau.

Ce que le dépôt ne dit pas sur la maintenance

Le rythme de publication est rapide : trois versions en août 2026, dont deux le même jour, et une dernière poussée sur la branche main début septembre 2026. Ce rythme a deux conséquences opposées. Il indique un projet actif, ce qui est rassurant pour la correction de bogues. Il implique aussi que le code généré hier peut diverger du code généré demain, et qu'un projet échafaudé avec la version 0.2.17 ne bénéficiera pas automatiquement des correctifs de la 0.2.19. Le générateur ne crée pas de lien de mise à jour : une fois le projet écrit sur le disque, il n'existe pas de commande documentée pour appliquer un correctif du gabarit à une base existante. C'est le coût réel de ce type d'outil, et il n'est pas chiffré dans le README. Le dépôt est publié sous licence MIT, ce qui autorise la modification et la redistribution du gabarit, y compris dans un produit commercial, à condition de conserver l'avis de licence. Cette lecture ne remplace pas un examen juridique, notamment si vous redistribuez le projet généré.

Comparer avec un générateur généraliste comme cookiecutter

L'alternative la plus directe n'est pas un framework concurrent mais cookiecutter, qui résout le même problème d'échafaudage avec une philosophie différente. cookiecutter applique un gabarit Jinja à une arborescence de fichiers et s'arrête là : il ne connaît ni Docker, ni les migrations, ni le streaming, et il ne fournit aucun assistant intégré. Vous écrivez vous-même les hooks de post-génération. fastapi-fullstack prend le parti inverse : la logique de génération est du code Python embarqué dans le paquet installé, les options sont validées par l'outil, et le résultat est une pile complète et cohérente plutôt qu'un squelette neutre. La différence pratique est le périmètre du débogage. Avec cookiecutter, un problème vient de votre gabarit. Ici, un problème peut venir du gabarit, de l'assistant, du fichier compose ou de la cible Make, et vous devez lire du code que vous n'avez pas écrit pour trancher. En échange, vous n'avez pas à écrire la partie RAG ni la couche d'authentification.

Conclusion éditoriale

Adoptez-le si vous démarrez une application FastAPI + Next.js avec agents et RAG et que vous voulez éviter de recâbler l'authentification, les migrations et le streaming. Évitez-le si votre application n'a pas besoin d'agents, ou si vous refusez d'hériter d'une pile choisie à votre place. Avant de vous engager, lancez fastapi-fullstack sur un projet jetable, inspectez le docker-compose.dev.yml généré et vérifiez quelles dépendances Python et Node le gabarit impose, puis relisez le fichier LICENSE du dépôt pour les conditions exactes de redistribution.

Sources officielles

1. License: MIT
2. Project website
3. README
4. Releases
5. vstorm-co/full-stack-ai-agent-template on GitHub