fastapi-struct 0.2.0__tar.gz → 0.2.1__tar.gz

fastapi_struct-0.2.1/PKG-INFO

@@ -0,0 +1,231 @@
+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).

fastapi_struct-0.2.1/README.md

@@ -0,0 +1,218 @@
+<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).

{fastapi_struct-0.2.0 → fastapi_struct-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-struct"
-version = "0.2.0"
+version = "0.2.1"
 description = "CLI tool to generate standard, layered enterprise folder structures for FastAPI applications."
 readme = "README.md"
 requires-python = ">=3.10"

fastapi_struct-0.2.1/src/create_fastapi_app/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

{fastapi_struct-0.2.0 → fastapi_struct-0.2.1}/src/create_fastapi_app/cli.py

@@ -7,14 +7,21 @@ from create_fastapi_app.generator import create_project
 
 def main():
     parser = argparse.ArgumentParser(
-        prog="create-fastapi-app",
-        description="Create a new FastAPI project.",
+        prog="fastapi-struct",
+        description="Create a production-ready FastAPI project.",
     )
     parser.add_argument(
         "name",
         nargs="?",
         help="Name of the project to generate (or . for current directory)",
     )
+    parser.add_argument(
+        "-t",
+        "--template",
+        choices=["basic", "ml"],
+        default="basic",
+        help="Architecture template to use: 'basic' (layered enterprise web API) or 'ml' (AI/ML inference service). Default: basic",
+    )
     parser.add_argument(
         "--version",
         action="version",
@@ -28,17 +35,19 @@ def main():
         sys.exit(2)
 
     try:
-        path = create_project(args.name)
+        path = create_project(args.name, template=args.template)
     except (ValueError, FileExistsError, FileNotFoundError) as exc:
         parser.error(str(exc))
 
-    print(f"\nSuccess! Created project at: {path}")
+    template_desc = "AI/ML Inference Service" if args.template == "ml" else "Enterprise Layered Web API"
+    print(f"\nSuccess! Created {template_desc} at: {path}")
     print("\nNext steps:")
     if args.name != ".":
         print(f"  cd {args.name}")
     print("  python -m venv .venv")
-    print(r"  .\.venv\Scripts\Activate.ps1")
-    print('  python -m pip install -e ".[dev]"')
+    print(r"  .\.venv\Scripts\Activate.ps1   # Windows PowerShell")
+    print("  # or: source .venv/bin/activate  # macOS / Linux")
+    print("  pip install -r requirements.txt")
     print("  python -m uvicorn app.main:app --reload")
 
 

{fastapi_struct-0.2.0 → fastapi_struct-0.2.1}/src/create_fastapi_app/generator.py

@@ -3,10 +3,10 @@ import re
 import shutil
 
 PACKAGE_DIR = Path(__file__).parent
-TEMPLATE_DIR = PACKAGE_DIR / "templates" / "basic"
+TEMPLATES_DIR = PACKAGE_DIR / "templates"
 
 
-def create_project(name: str) -> Path:
+def create_project(name: str, template: str = "basic") -> Path:
     if name == ".":
         project_path = Path.cwd()
         project_name = project_path.name
@@ -24,13 +24,15 @@ def create_project(name: str) -> Path:
                 f"Destination directory already exists: {project_path}"
             )
 
-    if not TEMPLATE_DIR.is_dir():
+    selected_template_dir = TEMPLATES_DIR / template
+    if not selected_template_dir.is_dir():
+        available = [p.name for p in TEMPLATES_DIR.iterdir() if p.is_dir()]
         raise FileNotFoundError(
-            f"Template directory not found: {TEMPLATE_DIR}"
+            f"Template '{template}' not found. Available templates: {', '.join(available)}"
         )
 
     # Copy files allowing existing directory (useful when name is '.')
-    shutil.copytree(TEMPLATE_DIR, project_path, dirs_exist_ok=True)
+    shutil.copytree(selected_template_dir, project_path, dirs_exist_ok=True)
 
     config_path = project_path / "pyproject.toml"
     if config_path.exists():
@@ -38,6 +40,9 @@ def create_project(name: str) -> Path:
         config = config.replace(
             'name = "my-api"',
             f'name = "{project_name.lower().replace("_", "-")}"',
+        ).replace(
+            'name = "my-ml-api"',
+            f'name = "{project_name.lower().replace("_", "-")}"',
         )
         config_path.write_text(config, encoding="utf-8")
 

fastapi_struct-0.2.1/src/create_fastapi_app/templates/ml/.env

@@ -0,0 +1,4 @@
+PROJECT_NAME="FastAPI AI Inference Service"
+MODEL_NAME="classifier-v1"
+DEVICE="cpu"
+DEBUG=true

fastapi_struct-0.2.1/src/create_fastapi_app/templates/ml/.env.example

@@ -0,0 +1,4 @@
+PROJECT_NAME="FastAPI AI Inference Service"
+MODEL_NAME="classifier-v1"
+DEVICE="cpu"
+DEBUG=true

fastapi_struct-0.2.1/src/create_fastapi_app/templates/ml/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.env
+.pytest_cache/
+*.py[cod]
+*.pt
+*.onnx
+*.bin
+weights/

fastapi_struct-0.2.1/src/create_fastapi_app/templates/ml/README.md

@@ -0,0 +1,31 @@
+# FastAPI AI/ML Inference Service
+
+High-performance AI/ML inference microservice generated with `fastapi-struct --template ml`.
+
+## Quick Start
+
+### 1. Setup Virtual Environment
+```bash
+python -m venv .venv
+```
+- Windows: `.\.venv\Scripts\Activate.ps1`
+- macOS/Linux: `source .venv/bin/activate`
+
+### 2. Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### 3. Run Inference Server
+```bash
+python -m uvicorn app.main:app --reload
+```
+
+- Swagger UI: http://127.0.0.1:8000/docs
+- Prediction endpoint: `POST /api/v1/predict/`
+- Health/Readiness probe: `GET /api/v1/health`
+
+### 4. Run Tests
+```bash
+python -m pytest
+```

fastapi_struct-0.2.1/src/create_fastapi_app/templates/ml/app/api/v1/api.py

@@ -0,0 +1,6 @@
+from fastapi import APIRouter
+from app.api.v1.routes import health, predict
+
+api_router = APIRouter()
+api_router.include_router(health.router)
+api_router.include_router(predict.router)

fastapi_struct-0.2.1/src/create_fastapi_app/templates/ml/app/api/v1/routes/health.py

@@ -0,0 +1,15 @@
+from fastapi import APIRouter
+from app.core.config import settings
+from app.ml.model import ml_model
+from app.schemas.predict import HealthResponse
+
+router = APIRouter(tags=["Health"])
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check():
+    return {
+        "status": "healthy" if ml_model.is_loaded else "degraded",
+        "model_loaded": ml_model.is_loaded,
+        "device": settings.DEVICE,
+    }

fastapi_struct-0.2.1/src/create_fastapi_app/templates/ml/app/api/v1/routes/predict.py

@@ -0,0 +1,16 @@
+from fastapi import APIRouter, HTTPException, status
+from app.schemas.predict import PredictionRequest, PredictionResponse
+from app.services.inference import inference_service
+
+router = APIRouter(prefix="/predict", tags=["Inference"])
+
+
+@router.post("/", response_model=PredictionResponse, status_code=status.HTTP_200_OK)
+async def predict(payload: PredictionRequest):
+    try:
+        return inference_service.run_prediction(payload)
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Inference error: {str(exc)}",
+        )

fastapi_struct-0.2.1/src/create_fastapi_app/templates/ml/app/core/config.py

@@ -0,0 +1,20 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "FastAPI AI Inference Service"
+    API_V1_STR: str = "/api/v1"
+    DEBUG: bool = True
+    MODEL_NAME: str = "classifier-v1"
+    MODEL_PATH: str = "models/weights.bin"
+    DEVICE: str = "cpu"  # "cpu" or "cuda"
+    MAX_BATCH_SIZE: int = 32
+    API_KEY: str = "secret_ai_key"
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        extra="ignore",
+    )
+
+
+settings = Settings()