full-stack-ai-agent-template AGENTS.md

AGENTS.md

Guidance for AI coding agents (Codex, Copilot, Cursor, Zed, OpenCode) working with this repository.

Project Overview

Full-Stack AI Agent Template — CLI tool that generates production-ready FastAPI + Next.js projects with AI agents (5 frameworks), RAG (4 vector stores), and 20+ enterprise integrations.

Commands

uv sync                    # Install dependencies
uv run pytest              # Run tests
uv run ruff check . --fix  # Lint
uv run ruff format .       # Format
uv run ty check            # Type check

CLI

fastapi-fullstack                                  # Interactive wizard (default)
fastapi-fullstack create my_app --database postgresql
fastapi-fullstack create my_app --rag --task-queue celery
fastapi-fullstack templates                        # List all options

Generated project CLI includes sync source commands:

uv run <project_slug> cmd rag-sources              # List configured sources
uv run <project_slug> cmd rag-source-add           # Add a new source
uv run <project_slug> cmd rag-source-sync          # Trigger sync for a source

Architecture

Module	Purpose
fastapi_gen/cli.py	Click CLI: new, create, templates
fastapi_gen/config.py	Pydantic models, enums, validation, cookiecutter context
fastapi_gen/prompts.py	Interactive prompts (Questionary)
fastapi_gen/generator.py	Cookiecutter invocation

Template (template/)

template/
├── cookiecutter.json            # ~120 variables
├── hooks/post_gen_project.py    # Cleanup & formatting
└── {{cookiecutter.project_slug}}/
    ├── backend/app/             # FastAPI (agents, rag, services, repos)
    └── frontend/                # Next.js 15 (optional)

Jinja2 conditionals: {%- if cookiecutter.enable_rag %}...{%- endif %}

Key Features

• 5 AI Frameworks: PydanticAI, PydanticDeep, LangChain, LangGraph, DeepAgents
• 4 LLM Providers: OpenAI, Anthropic, Google Gemini, OpenRouter
• RAG: 4 vector stores (Milvus, Qdrant, ChromaDB, pgvector), 4 embedding providers, reranking, image description
• Document Sources: Local files (CLI), API upload, Google Drive (service account), S3/MinIO
• Sync Sources: Configurable connectors (Google Drive, S3) with scheduled sync
• PDF Parsers: PyMuPDF, LiteParse, LlamaParse (runtime selection via env var)
• Observability: Logfire (PydanticAI), LangSmith (LangChain/LangGraph/DeepAgents)