Full Stack AI Agent Template

<h1 align="center">Full-Stack AI Agent Template</h1> <p align="center"> <i>Production-ready FastAPI + Next.js project generator with AI agents, RAG, and 20+ enterprise integrations.</i> </p> <p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-features">Features</a> • <a href="#-demo">Demo</a> • <a href="https://vstorm-co.github.io/full-stack-ai-agent-template/">Documentation</a> • <a href="https://oss.vstorm.co/projects/full-stack-ai-agent-template/configurator/">Configurator</a> • <a href="https://pypi.org/project/fastapi-fullstack/">PyPI</a> </p> <p align="center"> <a href="https://pypi.org/project/fastapi-fullstack/"><img src="https://img.shields.io/pypi/v/fastapi-fullstack?color=green&logo=pypi&logoColor=white" alt="PyPI"></a> <a href="https://pepy.tech/projects/fastapi-fullstack"><img src="https://static.pepy.tech/badge/fastapi-fullstack/month" alt="PyPI Downloads"></a> <a href="https://github.com/vstorm-co/full-stack-ai-agent-template/stargazers"><img src="https://img.shields.io/github/stars/vstorm-co/full-stack-ai-agent-template?style=flat&logo=github&color=yellow" alt="GitHub Stars"></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11+-blue?logo=python&logoColor=white" alt="Python 3.11+"></a> <a href="https://github.com/vstorm-co/full-stack-ai-agent-template/blob/main/LICENSE"><img src="https://img.shields.io/github/license/vstorm-co/full-stack-ai-agent-template?color=blue" alt="License"></a> <img src="https://img.shields.io/badge/coverage-100%25-brightgreen" alt="Coverage"> <a href="https://github.com/vstorm-co/full-stack-ai-agent-template/actions/workflows/ci.yml"><img src="https://github.com/vstorm-co/full-stack-ai-agent-template/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/vstorm-co/full-stack-ai-agent-template/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/security-policy-blueviolet?logo=shieldsdotio&logoColor=white" alt="Security Policy"></a> <a href="https://www.bestpractices.dev/projects/12539"><img src="https://www.bestpractices.dev/projects/12539/badge" alt="OpenSSF Best Practices"></a> <a href="https://github.com/pydantic/pydantic-ai"><img src="https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic&logoColor=white" alt="Pydantic AI"></a> <a href="https://x.com/Kacper95682155"><img src="https://img.shields.io/badge/X-000000?logo=x&logoColor=white" alt="X"></a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/vstorm-co/full-stack-ai-agent-template/main/assets/new3/chat_demo_with_tasks.gif" alt="AI chat with live plan & task checklist" width="100%"> </p> <p align="center"> <b>🤖 5 AI Agent Frameworks</b> <i>(PydanticAI, PydanticDeep, LangChain, LangGraph, DeepAgents)</i> <br> <b>📄 RAG Pipeline</b> <i>(Milvus, Qdrant, pgvector, ChromaDB)</i> <br> <b>⚡ FastAPI + Next.js 15</b> <i>(WebSocket streaming, real-time chat UI)</i> <br> <b>🔗 Conversation Sharing</b> <i>(direct sharing, public links, admin browser)</i> <br> <b>🔒 Enterprise-Ready</b> <i>(JWT, OAuth, admin panel, Celery, Docker, K8s)</i> </p> <details> <summary><b>Table of Contents</b></summary>

• Quick Start
• Demo
• Screenshots
• Why This Template
• Features
• Architecture
• AI Agent
• RAG
• Observability
• Django-style CLI
• Generated Project Structure
• Configuration Options
• Comparison
• FAQ
• Documentation
• Contributing

</details>

---

Vstorm OSS Ecosystem

This template is part of a broader open-source ecosystem for production AI agents:

| Project | Description | | |---------|-------------|---| | pydantic-deepagents | The modular agent runtime for Python. Claude Code-style CLI with Docker sandbox, browser automation, multi-agent teams, and /improve. | | | pydantic-ai-shields | Drop-in guardrails for Pydantic AI agents. 5 infra + 5 content shields. | | | pydantic-ai-subagents | Declarative multi-agent orchestration with token tracking. | | | summarization-pydantic-ai | Smart context compression for long-running agents. | | | pydantic-ai-backend | Sandboxed execution for AI agents. Docker + Daytona. | |

Want the runtime behind this template's AI agents? pydantic-deepagents powers the deepagents framework option — install it standalone with curl -fsSL .../install.sh | bash.

Browse all projects at oss.vstorm.co

---

🚀 Quick Start

[!TIP] Prefer a visual configurator? Use the Web Configurator to configure your project in the browser and download a ZIP — no CLI installation needed.

Installation

# pip
pip install fastapi-fullstack

# uv (recommended)
uv tool install fastapi-fullstack

# pipx
pipx install fastapi-fullstack

From zero to a running app

Three steps. The wizard scaffolds the project, make bootstrap brings up the whole backend, and the frontend runs with a single command:

# 1. Generate your project — just answer the wizard's prompts
fastapi-fullstack

# 2. Backend + PostgreSQL up, migrations applied, default admin seeded
cd my_ai_app
make bootstrap

# 3. Frontend (in a second terminal)
cd frontend && bun install && bun dev

What make bootstrap does (= make dev + make seed): builds the backend Docker image, starts the stack via docker-compose.dev.yml, waits for PostgreSQL (pg_isready), applies Alembic migrations, and seeds admin@example.com / admin123. It's idempotent — re-run it anytime.

Then access:

| | URL | | |---|---|---| | Backend API | http://localhost:8000 | | | Docs | http://localhost:8000/docs | OpenAPI / Swagger | | Admin | http://localhost:8000/admin | admin@example.com / admin123 (after make seed) | | Frontend | http://localhost:3000 | make dev-frontend (Docker) or cd frontend && bun install && bun dev (local) |

Day-to-day commands

make dev           # bootstrap or restart (no admin re-seed)
make seed          # one-shot admin creation (no-op if admin exists)
make dev-down      # stop everything
make dev-logs      # tail container logs
make dev-rebuild   # force-rebuild backend image (after pyproject.toml changes)
make dev-frontend  # start the Next.js container

After the first make bootstrap, day-to-day you just run make dev (skips admin re-seed). Run make help inside the project for the full list.

<details> <summary><b>Other ways to generate (flags, presets, minimal)</b></summary>

Skip the wizard and pass options directly:

# Non-interactive with explicit options
fastapi-fullstack create my_ai_app --database postgresql --frontend nextjs

# Presets for common scenarios (run `fastapi-fullstack templates` for the full list)
fastapi-fullstack create my_ai_app --preset ai-agent           # AI agent with streaming
fastapi-fullstack create my_ai_app --preset production         # Full production setup
fastapi-fullstack create my_ai_app --preset production-saas    # SaaS: billing, teams, admin

# Bare-bones project (PostgreSQL, no Docker/Redis/CI)
fastapi-fullstack create my_ai_app --minimal

</details>

Keeping your project up to date

Your project doesn't get stranded on the template version you generated from. Pull the latest template improvements into your existing project with a real 3-way merge — your customizations are preserved, conflicts are left for you to resolve in your IDE, and the whole thing lands on a dedicated branch so it's fully reversible:

make upgrade-dry-run     # preview what would change (no changes made)
make upgrade             # apply on a `template-upgrade/v…` branch
# resolve any conflicts in your IDE's 3-way merge editor, then:
make upgrade-finalize    # bump the manifest to the new version

Files only you changed are kept, files only the template changed are updated, and new features/migrations are pulled in. By default an upgrade keeps your existing feature set — to also adopt optional features added since your version, use:

make upgrade-new-features   # prompts Yes/No for each new optional feature

One-off flags (e.g. pinning a target version) go through ARGS, and you can always call the CLI directly instead of make:

make upgrade ARGS=--to=0.3.0
uvx fastapi-fullstack@latest upgrade --with-new-features

See the version-upgrade guide for the full walkthrough (including projects generated befo