Metadata-Version: 2.4
Name: fastapi-struct
Version: 0.2.1
Summary: CLI tool to generate standard, layered enterprise folder structures for FastAPI applications.
License-Expression: MIT
Keywords: fastapi,project-structure,boilerplate,scaffold,cli,template,folder-structure,architecture,repository-pattern,rest-api
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Code Generators
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://pypi.org/project/fastapi-struct/"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" width="320" alt="fastapi-struct"></a>
</p>
<p align="center">
    <em>CLI tool to generate standard, production-ready FastAPI folder structures in seconds — with dedicated templates for Enterprise Web APIs and AI/ML Inference Services.</em>
</p>
<p align="center">
<a href="https://pypi.org/project/fastapi-struct" target="_blank">
    <img src="https://img.shields.io/pypi/v/fastapi-struct.svg?color=%2334D058" alt="Package version">
</a>
<a href="https://pypi.org/project/fastapi-struct" target="_blank">
    <img src="https://img.shields.io/pypi/pyversions/fastapi-struct.svg?color=%2334D058" alt="Supported Python versions">
</a>
<a href="https://github.com/fastapi/fastapi" target="_blank">
    <img src="https://img.shields.io/badge/FastAPI-0.115+-009688.svg?logo=fastapi&logoColor=white" alt="FastAPI">
</a>
<a href="https://github.com/pydantic/pydantic" target="_blank">
    <img src="https://img.shields.io/badge/Pydantic-v2-E92063.svg?logo=pydantic&logoColor=white" alt="Pydantic v2">
</a>
<a href="https://opensource.org/licenses/MIT" target="_blank">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT">
</a>
</p>

---

**FastAPI Documentation:** [https://fastapi.tiangolo.com](https://fastapi.tiangolo.com)  
**PyPI Package:** [https://pypi.org/project/fastapi-struct/](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 &rarr; Services &rarr; Repositories &rarr; Database & Models).
2. **`ml`**: Lean, specialized AI/ML inference microservice (Lifespan Model Loader &rarr; Inference Pipeline &rarr; Predictions & Latency Tracking).

---

## 📦 Quick Start & CLI Usage

### 1. Enterprise Web API (Default)

```bash
# 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`)

```bash
# 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 (`.`)

```bash
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.

```text
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.

```text
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
```bash
cd my_ml_service
```

### 2. Create and activate a virtual environment

**Windows PowerShell:**
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

**Windows CMD:**
```cmd
python -m venv .venv
call .venv\Scripts\activate.bat
```

**macOS / Linux:**
```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3. Install dependencies
```bash
pip install -r requirements.txt
```

### 4. Start the server
```bash
python -m uvicorn app.main:app --reload
```

---

## 🔍 Interactive API Documentation

Once running, visit:

- **Swagger UI**: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
- **ReDoc**: [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)

---

## 🧪 Running Automated Tests

Run the included Pytest suite:

```bash
python -m pytest
```

Output:
```text
tests\test_predict.py ..                                                 [100%]
============================== 2 passed in 0.15s ==============================
```

---

## 📜 License

This project is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT).
