diff --git a/docs/en/docs/project-generation-ai.md b/docs/en/docs/project-generation-ai.md new file mode 100644 index 000000000..1d0c11a1e --- /dev/null +++ b/docs/en/docs/project-generation-ai.md @@ -0,0 +1,254 @@ +# Full Stack FastAPI + Next.js Template for AI/LLM Applications + +A production-ready project generator specifically designed for AI and LLM applications. It provides everything you need to build professional AI-powered products with 20+ enterprise integrations. + +This template is ideal for building AI chatbots, ML applications, enterprise SaaS, or any project that needs type-safe AI agents with real-time streaming responses. + +GitHub Repository: Full Stack FastAPI + Next.js LLM Template + +## Why This Template + +Building AI/LLM applications requires more than just an API wrapper. You need: + +- **Type-safe AI agents** with tool/function calling +- **Real-time streaming** responses via WebSocket +- **Conversation persistence** and history management +- **Production infrastructure** - auth, rate limiting, observability +- **Enterprise integrations** - background tasks, webhooks, admin panels + +This template gives you all of that out of the box, with **20+ configurable integrations** so you can focus on building your AI product, not boilerplate. + +### Perfect For + +- ๐Ÿค– **AI Chatbots & Assistants** - PydanticAI or LangChain agents with streaming responses +- ๐Ÿ“Š **ML Applications** - Background task processing with Celery/Taskiq +- ๐Ÿข **Enterprise SaaS** - Full auth, admin panel, webhooks, and more +- ๐Ÿš€ **Startups** - Ship fast with production-ready infrastructure + +### AI-Agent Friendly + +Generated projects include **CLAUDE.md** and **AGENTS.md** files optimized for AI coding assistants (Claude Code, Codex, Copilot, Cursor, Zed). Following progressive disclosure best practices - concise project overview with pointers to detailed docs when needed. + +## Technology Stack and Features + +- **AI/LLM First** + - ๐Ÿค– **PydanticAI** or **LangChain** with **LangGraph** - Choose your preferred AI framework. + - ๐ŸŒŠ **WebSocket Streaming** - Real-time responses with full event access. + - ๐Ÿ’ฌ **Conversation Persistence** - Save chat history to database. + - ๐Ÿ”ง **Custom Tools** - Easily extend agent capabilities. + - ๐Ÿ”Œ **Multi-provider Support** - OpenAI, Anthropic, OpenRouter. + - ๐Ÿ“Š **Observability** - Logfire for PydanticAI, LangSmith for LangChain. +- โšก **FastAPI** for the Python backend API. + - ๐Ÿ” **Pydantic v2** for data validation and settings management. + - ๐Ÿงฐ **SQLModel** or **SQLAlchemy** for Python SQL database interactions (ORM). + - ๐Ÿ’พ **Multiple Databases** - PostgreSQL (async), MongoDB (async), SQLite. + - ๐Ÿ”‘ **Authentication** - JWT + Refresh tokens, API Keys, OAuth2 (Google). + - โฑ๏ธ **Background Tasks** - Celery, Taskiq, or ARQ. + - ๐Ÿ› ๏ธ **Django-style CLI** - Custom management commands with auto-discovery. +- ๐Ÿš€ **Next.js 15** for the frontend. + - ๐Ÿ’ป **React 19** + **TypeScript** + **Tailwind CSS v4**. + - ๐Ÿ’ญ **AI Chat Interface** - WebSocket streaming, tool call visualization. + - ๐Ÿ” **Authentication** - HTTP-only cookies, auto-refresh. + - ๐Ÿ—„๏ธ **Zustand** for state management. + - ๐Ÿงช **Playwright** for End-to-End testing. + - ๐ŸŒ™ **Dark Mode** + **i18n** (optional). +- ๐Ÿข **Enterprise Integrations** + - ๐Ÿ“ฆ **Caching & State** - Redis, fastapi-cache2. + - ๐Ÿ›ก๏ธ **Security** - Rate limiting, CORS, CSRF protection. + - ๐Ÿ“ˆ **Observability** - Logfire, LangSmith, Sentry, Prometheus. + - ๐Ÿ–ฅ๏ธ **Admin** - SQLAdmin panel with auth. + - ๐Ÿ“ก **Events** - Webhooks, WebSockets. + - ๐Ÿณ **DevOps** - Docker, GitHub Actions, GitLab CI, Kubernetes. + +## Quick Start + +### Installation + +```bash +# pip +pip install fastapi-fullstack + +# uv (recommended) +uv tool install fastapi-fullstack + +# pipx +pipx install fastapi-fullstack +``` + +### Create Your Project + +```bash +# Interactive wizard (recommended) +fastapi-fullstack new + +# Quick mode with options +fastapi-fullstack create my_ai_app \ + --database postgresql \ + --auth jwt \ + --frontend nextjs + +# Use presets for common setups +fastapi-fullstack create my_ai_app --preset production # Full production setup +fastapi-fullstack create my_ai_app --preset ai-agent # AI agent with streaming + +# Minimal project (no extras) +fastapi-fullstack create my_ai_app --minimal +``` + +### Start Development + +```bash +cd my_ai_app +make install # Install dependencies +make docker-db # Start PostgreSQL +make db-migrate # Create migration +make db-upgrade # Apply migrations +make create-admin # Create admin user +make run # Start backend + +# In another terminal +cd frontend +bun install +bun dev +``` + +Access points: + +- API: http://localhost:8000 +- API Docs: http://localhost:8000/docs +- Admin Panel: http://localhost:8000/admin +- Frontend: http://localhost:3000 + +### Quick Start with Docker + +```bash +make docker-up # Start backend + database +make docker-frontend # Start frontend +``` + +## Architecture + +The backend follows a clean **Repository + Service** pattern: + +| Layer | Responsibility | +|-------|---------------| +| **Routes** | HTTP handling, validation, auth | +| **Services** | Business logic, orchestration | +| **Repositories** | Data access, queries | + +## AI Agent + +Choose between **PydanticAI** or **LangChain** when generating your project: + +```bash +# PydanticAI with OpenAI (default) +fastapi-fullstack create my_app --ai-agent --ai-framework pydantic_ai + +# PydanticAI with Anthropic +fastapi-fullstack create my_app --ai-agent --ai-framework pydantic_ai --llm-provider anthropic + +# LangChain with OpenAI +fastapi-fullstack create my_app --ai-agent --ai-framework langchain +``` + +### Supported LLM Providers + +| Framework | OpenAI | Anthropic | OpenRouter | +|-----------|:------:|:---------:|:----------:| +| **PydanticAI** | โœ“ | โœ“ | โœ“ | +| **LangChain** | โœ“ | โœ“ | - | + +### PydanticAI Example + +Type-safe agents with full dependency injection: + +```python +from pydantic_ai import Agent, RunContext +from dataclasses import dataclass + +@dataclass +class Deps: + user_id: str | None = None + db: AsyncSession | None = None + +agent = Agent[Deps, str]( + model="openai:gpt-4o-mini", + system_prompt="You are a helpful assistant.", +) + +@agent.tool +async def search_database(ctx: RunContext[Deps], query: str) -> list[dict]: + """Search the database for relevant information.""" + # Access user context and database via ctx.deps + ... +``` + +### LangChain with LangGraph Example + +Flexible agents with LangGraph: + +```python +from langchain.tools import tool +from langgraph.prebuilt import create_react_agent + +@tool +def search_database(query: str) -> list[dict]: + """Search the database for relevant information.""" + ... + +agent = create_react_agent( + model=ChatOpenAI(model="gpt-4o-mini"), + tools=[search_database], + prompt="You are a helpful assistant.", +) +``` + +## Django-style CLI + +Each generated project includes a CLI with built-in commands: + +```bash +# Server +my_app server run --reload +my_app server routes + +# Database (Alembic wrapper) +my_app db init +my_app db migrate -m "Add users" +my_app db upgrade + +# Users +my_app user create --email admin@example.com --superuser +my_app user list +``` + +Custom commands are **automatically discovered** from `app/commands/`. + +## Configuration Options + +| Option | Values | Description | +|--------|--------|-------------| +| **Database** | `postgresql`, `mongodb`, `sqlite`, `none` | Async by default | +| **ORM** | `sqlalchemy`, `sqlmodel` | SQLModel for simplified syntax | +| **Auth** | `jwt`, `api_key`, `both`, `none` | JWT includes user management | +| **OAuth** | `none`, `google` | Social login | +| **AI Framework** | `pydantic_ai`, `langchain` | Choose your AI agent framework | +| **LLM Provider** | `openai`, `anthropic`, `openrouter` | OpenRouter only with PydanticAI | +| **Background Tasks** | `none`, `celery`, `taskiq`, `arq` | Distributed queues | +| **Frontend** | `none`, `nextjs` | Next.js 15 + React 19 | + +### Presets + +| Preset | Description | +|--------|-------------| +| `--preset production` | Full production setup with Redis, Sentry, Kubernetes, Prometheus | +| `--preset ai-agent` | AI agent with WebSocket streaming and conversation persistence | +| `--minimal` | Minimal project with no extras | + +## Documentation + +For detailed documentation, see the GitHub repository. + +--- + +Created by Vstorm. diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 66094c81e..5477eae6b 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -246,6 +246,7 @@ nav: - help-fastapi.md - contributing.md - project-generation.md + - project-generation-ai.md - external-links.md - newsletter.md - management-tasks.md