fastapi-struct 0.2.1

CLI tool to generate standard, production-ready FastAPI folder structures in seconds — with dedicated templates for Enterprise Web APIs and AI/ML Inference Services.

---

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

---

⚡ What is fastapi-struct?

fastapi-struct generates clean, modular, and production-tested architectures for FastAPI applications. Rather than spending hours writing repetitive boilerplate, you get an instantly runnable codebase tailored to your exact project type:

1. basic (Default): Layered enterprise web API architecture (Routes → Services → Repositories → Database & Models).
2. ml: Lean, specialized AI/ML inference microservice (Lifespan Model Loader → Inference Pipeline → Predictions & Latency Tracking).

---

📦 Quick Start & CLI Usage

1. Enterprise Web API (Default)

# With uvx (instant, no install needed)
uvx fastapi-struct my_api

# Or with pip:
pip install fastapi-struct
fastapi-struct my_api

2. AI / ML Inference Service (--template ml)

# Generate a dedicated AI/ML service:
fastapi-struct my_ml_service --template ml

# Or shorthand:
fastapi-struct my_ml_service -t ml

3. Scaffold in the Current Directory (.)

fastapi-struct . --template ml

---

📂 Template 1: AI / ML Inference Architecture (-t ml)

Specially designed for AI/ML and GenAI engineers. Removes database CRUD overhead and optimizes for model loading, tensor preprocessing, inference, and latency benchmarking.

my_ml_service/
│
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI app + lifespan model loader (loads weights once at startup)
│   │
│   ├── api/
│   │   ├── __init__.py
│   │   └── v1/                 # API Versioning
│   │       ├── __init__.py
│   │       ├── api.py          # Central router aggregating endpoints
│   │       └── routes/
│   │           ├── __init__.py
│   │           ├── health.py   # /health probe (readiness check + GPU/device info)
│   │           └── predict.py  # /predict endpoint (input validation, inference, latency)
│   │
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py           # MODEL_NAME, MODEL_PATH, DEVICE ("cpu"/"cuda"), API_KEYS
│   │
│   ├── ml/                     # Machine learning logic
│   │   ├── __init__.py
│   │   ├── model.py            # Model wrapper (PyTorch / ONNX / HuggingFace)
│   │   └── pipeline.py         # Tokenizer, preprocessing & postprocessing
│   │
│   ├── schemas/                # Request & Response Pydantic models
│   │   ├── __init__.py
│   │   └── predict.py          # PredictionRequest, PredictionResponse, HealthResponse
│   │
│   └── services/               # Orchestration layer
│       ├── __init__.py
│       └── inference.py        # Validates payload, executes pipeline, measures latency
│
├── tests/                      # Automated test suite
│   ├── __init__.py
│   ├── conftest.py             # TestClient fixtures + mock model
│   └── test_predict.py         # Pytest test cases for /health & /predict
│
├── .gitignore
├── .env                        # Local model configuration
├── .env.example
├── requirements.txt            # Ready for pip install -r requirements.txt
├── pyproject.toml              # Build & pytest configuration
└── README.md

---

📂 Template 2: Layered Enterprise Web Architecture (-t basic)

Designed for full-stack and backend services that require domain-driven separation of concerns.

my_fastapi_project/
│
├── app/
│   ├── __init__.py
│   ├── main.py                 # Application factory & router registration
│   │
│   ├── api/v1/routes/          # HTTP route endpoints (items.py, users.py)
│   ├── core/                   # config.py, database.py, security.py
│   ├── models/                 # Database ORM models (item.py, user.py)
│   ├── schemas/                # Pydantic serialization schemas (item.py, user.py)
│   ├── services/               # Pure business logic layer
│   ├── repositories/           # Database CRUD queries layer
│   └── utils/                  # Utility helpers (email.py)
│
├── tests/                      # conftest.py, test_items.py, test_users.py
├── requirements.txt
├── pyproject.toml
└── README.md

---

🚀 Running Your Generated Project

1. Step into your project directory

cd my_ml_service

2. Create and activate a virtual environment

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Windows CMD:

python -m venv .venv
call .venv\Scripts\activate.bat

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Start the server

python -m uvicorn app.main:app --reload

---

🔍 Interactive API Documentation

Once running, visit:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

---

🧪 Running Automated Tests

Run the included Pytest suite:

python -m pytest

Output:

tests\test_predict.py ..                                                 [100%]
============================== 2 passed in 0.15s ==============================

---

📜 License

This project is licensed under the terms of the MIT License.