Metadata-Version: 2.4
Name: fastapi-struct
Version: 0.4.0
Summary: CLI tool to generate standard, production-ready FastAPI architectures for AI, GenAI & ML services.
License-Expression: MIT
Keywords: fastapi,ai,machine-learning,genai,llm,rag,inference,project-structure,boilerplate,scaffold,cli
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: FastAPI
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
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>Scaffold production-ready FastAPI architectures — AI/ML microservices, enterprise web APIs, or both combined.</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/)

---

## 🗂️ 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

```bash
pip install fastapi-struct
```

Pick your architecture:

```bash
# 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):
```powershell
cd my_project
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

#### Windows (Command Prompt):
```cmd
cd my_project
python -m venv .venv
call .venv\Scripts\activate.bat
pip install -r requirements.txt
```

#### macOS / Linux:
```bash
cd my_project
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

---

### Step 3 — Configure & Run

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

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

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

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

```bash
pytest
```

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

---

## 📦 Installation

```bash
pip install fastapi-struct
```

Both entry points work identically:

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

---

## 🔑 Environment Configuration

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

```env
# 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
