fastapi-struct 0.4.0

Scaffold production-ready FastAPI architectures — AI/ML microservices, enterprise web APIs, or both combined.

---

FastAPI Documentation: https://fastapi.tiangolo.com
PyPI Package: https://pypi.org/project/fastapi-struct/

---

🗂️ Three Templates, One Tool

Template	Flag	Best For
ml (default)	-t ml	AI/ML microservices — LLM chat, RAG, inference
basic	-t basic	Traditional enterprise web APIs — CRUD, users, items
all	-t all	Full-stack: AI/ML + traditional web API combined

---

⚡ 60-Second Easy Setup Process

Step 1 — Install & Scaffold

pip install fastapi-struct

Pick your architecture:

# Default: AI & ML microservice
fastapi-struct my_project

# Traditional enterprise web API
fastapi-struct my_project -t basic

# Everything combined (AI + Web API)
fastapi-struct my_project -t all

# Scaffold into the current directory
fastapi-struct .

# List all templates
fastapi-struct --list-templates

---

Step 2 — Activate Environment & Install Dependencies

Windows (PowerShell):

cd my_project
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Windows (Command Prompt):

cd my_project
python -m venv .venv
call .venv\Scripts\activate.bat
pip install -r requirements.txt

macOS / Linux:

cd my_project
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

---

Step 3 — Configure & Run

cp .env.example .env   # edit with your API keys / settings
python -m uvicorn app.main:app --reload

Open http://127.0.0.1:8000/docs → interactive Swagger UI, ready to use.

---

🤖 Template: ml — AI & ML Microservice (default)

Lean, production-grade AI/ML service. No CRUD noise.

my_project/
├── app/
│   ├── main.py                    # Lifespan model loader (GPU/CPU)
│   ├── api/v1/routes/
│   │   ├── health.py              # GET  /health — GPU & readiness probe
│   │   ├── chat.py                # POST /chat, /chat/stream — LLM streaming
│   │   ├── rag.py                 # POST /rag/query — vector retrieval + LLM
│   │   └── predict.py             # POST /predict — ML inference
│   ├── ai/
│   │   ├── llm.py                 # Async token streaming client
│   │   ├── prompt.py              # System prompt templates
│   │   └── rag.py                 # VectorRetriever (Pinecone/Qdrant/ChromaDB ready)
│   ├── ml/
│   │   ├── model.py               # MLModel wrapper (PyTorch/ONNX/HuggingFace)
│   │   └── pipeline.py            # Pre/post-processing pipeline
│   ├── schemas/                   # chat.py · rag.py · predict.py
│   ├── services/
│   │   ├── ai_service.py          # GenAI orchestration (chat + RAG)
│   │   └── inference.py           # ML inference + latency tracking
│   └── core/config.py             # LLM_MODEL, DEVICE, OPENAI_API_KEY, etc.
└── tests/
    ├── test_chat.py               # Chat & RAG integration tests
    └── test_predict.py            # Health & predict integration tests

Capabilities:

Feature	Route
GenAI Chat	POST /api/v1/chat/
Token Streaming (SSE)	POST /api/v1/chat/stream
RAG Vector Search	POST /api/v1/rag/query
ML Inference	POST /api/v1/predict/
GPU Health Probe	GET /api/v1/health

---

🏗️ Template: basic — Enterprise Web API

Clean layered architecture for traditional REST APIs. Relational-DB ready.

my_project/
├── app/
│   ├── main.py
│   ├── api/v1/routes/
│   │   ├── users.py               # GET/POST /users — user CRUD
│   │   └── items.py               # GET/POST /items — item CRUD
│   ├── core/
│   │   ├── config.py              # PROJECT_NAME, SECRET_KEY, DEBUG
│   │   ├── database.py            # SQLAlchemy/SQLModel engine (plug-in ready)
│   │   └── security.py            # Password hashing helpers
│   ├── models/                    # ORM models (item.py, user.py)
│   ├── schemas/                   # Pydantic schemas (item.py, user.py)
│   ├── services/                  # Business logic (item_service.py, user_service.py)
│   └── repositories/              # DB query layer (item_repository.py, user_repository.py)
└── tests/
    ├── test_items.py
    └── test_users.py

Capabilities:

Feature	Route
User CRUD	GET/POST /api/v1/users/
Item CRUD	GET/POST /api/v1/items/
Health check	GET /health

---

🔀 Template: all — Full-Stack AI + Web API

Everything in one project. AI/ML inference and traditional REST CRUD, security, repositories — unified under one FastAPI app.

my_project/
├── app/
│   ├── main.py                    # Lifespan model loader + full app init
│   ├── api/v1/routes/
│   │   ├── health.py              # GET  /health — GPU & readiness probe
│   │   ├── chat.py                # POST /chat, /chat/stream — LLM streaming
│   │   ├── rag.py                 # POST /rag/query — RAG + vector search
│   │   ├── predict.py             # POST /predict — ML inference
│   │   ├── users.py               # GET/POST /users — user CRUD
│   │   └── items.py               # GET/POST /items — item CRUD
│   ├── ai/                        # GenAI engine (llm.py, prompt.py, rag.py)
│   ├── ml/                        # ML engine (model.py, pipeline.py)
│   ├── schemas/                   # chat.py, rag.py, predict.py, user.py, item.py
│   ├── services/                  # ai_service.py, inference.py, user_service.py, item_service.py
│   ├── repositories/              # user_repository.py, item_repository.py
│   ├── models/                    # user.py, item.py (ORM-ready)
│   └── core/
│       ├── config.py              # All settings — LLM, ML, Auth, DB
│       ├── database.py            # DB engine (SQLAlchemy/SQLModel ready)
│       └── security.py            # Password hashing
└── tests/
    ├── test_ai.py                 # 4 AI/ML integration tests
    └── test_web.py                # 4 Web API integration tests

All Capabilities Combined:

Feature	Route
GenAI Chat	POST /api/v1/chat/
Token Streaming	POST /api/v1/chat/stream
RAG Vector Search	POST /api/v1/rag/query
ML Inference	POST /api/v1/predict/
GPU Health Probe	GET /api/v1/health
User CRUD	GET/POST /api/v1/users/
Item CRUD	GET/POST /api/v1/items/

---

🎯 Feature Highlights (All Templates)

• 🤖 GenAI Token Streaming — Real-time StreamingResponse (SSE) for LLM chat completions
• 📚 RAG & Vector Search — Plug in Pinecone, Qdrant, ChromaDB, or pgvector
• 🧠 Lifespan Model Caching — PyTorch/ONNX/HuggingFace weights loaded once at startup
• 🩺 GPU & Readiness Probes — /health reports cpu/cuda device status
• 🧹 Zero __pycache__ Clutter — Byte-compiled files automatically excluded
• 🧪 Preconfigured Pytest Suite — Integration tests included for every template

---

🧪 Run Tests

pytest

Tests are in tests/ and run against the live FastAPI app via TestClient.

---

📦 Installation

pip install fastapi-struct

Both entry points work identically:

fastapi-struct my_project        # recommended
create-fastapi-app my_project    # alias

---

🔑 Environment Configuration

Copy .env.example → .env and fill in your values:

# Common
PROJECT_NAME="My Service"
DEBUG=true
SECRET_KEY="your_secret_key_here"         # basic / all only

# AI / GenAI (ml / all templates)
OPENAI_API_KEY="sk-..."
LLM_MODEL="gpt-4o-mini"
EMBEDDING_MODEL="text-embedding-3-small"

# ML Inference (ml / all templates)
ML_MODEL_NAME="classifier-v1"
ML_MODEL_PATH="models/weights.bin"
DEVICE="cpu"   # or "cuda"

---

📋 Requirements

• Python 3.10+
• FastAPI 0.115+
• Pydantic v2