Metadata-Version: 2.4
Name: modelgate_py
Version: 0.3.0
Summary: Deploy-ready machine learning inference API and SDK with zero boilerplate.
Author: ModelGate Contributors
Maintainer-email: Bibek Dhakal <imbibek8366@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Bibek-Dhakal/modelgate
Project-URL: Documentation, https://github.com/Bibek-Dhakal/modelgate/blob/main/README.md
Project-URL: Repository, https://github.com/Bibek-Dhakal/modelgate.git
Project-URL: Issues, https://github.com/Bibek-Dhakal/modelgate/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: joblib>=1.2.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Dynamic: license-file

# ModelGate 🚀

> **Containerized machine learning inference API with zero boilerplate.**

![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-009688.svg)
![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg)
![Ruff](https://img.shields.io/badge/Linter-Ruff-gray.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

A trained model sitting in a Jupyter Notebook proves nothing about production readiness. **ModelGate** bridges the gap
between data science experiments and software engineering by providing a robust, dynamic, and safe microservice for
tabular ML models (Scikit-Learn, Joblib, Pickle).

## ✨ Key Features

- **Dynamic Artifact Loading**: Instantly serve `.joblib` or `.pkl` models by simply providing a local path or a
  **direct HTTP URL**. The API downloads and loads it on startup.
- **Strict, Dynamic Input Validation**: Pass a `schema.json` via environment variables. ModelGate uses `jsonschema` to
  ensure malformed data never reaches your model.
- **Out-of-the-box Ready**: Defaults to downloading and serving a public Scikit-Learn Iris classification model so you
  can test integrations immediately.
- **Error Shielding**: Overridden Exception Handlers strictly prevent Python stack traces from leaking to the client,
  returning standardized, safe JSON `422` and `500` errors.
- **Docker-Native & SDK-Ready**: Fully containerized for microservice use, or importable as a native Python SDK into
  existing codebases.

---

## 📖 Documentation

Dive deeper into the specific subsystems:

- 🌐 **[API Reference](https://github.com/Bibek-Dhakal/modelgate/blob/main/docs/api/README.md)**: Endpoints, request
  payloads, and
  example curl commands.
- ⚙️ **[Usage & Configuration](https://github.com/Bibek-Dhakal/modelgate/blob/main/docs/usage/README.md)**: Environment
  variables,
  Schema validation, Model URL loading, and
  SDK implementation.
- 🏗️ **[Architecture & Design](https://github.com/Bibek-Dhakal/modelgate/blob/main/docs/architecture/README.md)**:
  System flow,
  Mermaid diagrams, and error shielding
  concepts.
- 🧪 **[Testing Standards](https://github.com/Bibek-Dhakal/modelgate/blob/main/docs/testing/README.md)**: Pytest
  strategies,
  coverage, and CI checks.
- 🧹 **[Code Quality](https://github.com/Bibek-Dhakal/modelgate/blob/main/docs/code_quality.md)**: Pre-commit, Ruff
  linting, and
  formatting.

---

## ⚡ Quickstart: Zero to Inference

### 1. Run the Default Model (Local API)

By default, ModelGate automatically downloads a Scikit-Learn Logistic Regression model (Iris dataset) and enforces its
JSON schema.

```bash
# Install dependencies
pip install -e .[dev]

# Start the server
uvicorn modelgate.main:app --reload
```

Test the endpoint:

```bash
curl -X POST "http://localhost:8000/api/v1/predict" \
     -H "Content-Type: application/json" \
     -d '{
           "features": {
             "sepal_length": 5.1,
             "sepal_width": 3.5,
             "petal_length": 1.4,
             "petal_width": 0.2
           }
         }'
```

*Response:* `{"prediction": "setosa", "model_version": "v1.0.0"}`

### 2. Use as a Python SDK

ModelGate isn't just a standalone API—it can be used programmatically in your Python code as a lightweight SDK.

```python
from modelgate import ModelGate

gate = ModelGate()
gate.load_model(
    model_path="https://huggingface.co/DmytroSerbeniuk/my-iris-model/resolve/main/model.joblib",
    model_type="joblib",
    schema="default_schema.json"
)

# Validates input against schema and executes model inference securely
result = gate.predict({
    "sepal_length": 5.1,
    "sepal_width": 3.5,
    "petal_length": 1.4,
    "petal_width": 0.2
})
print(result)  # Output: "setosa"
```

### 3. Run with your own Real Model (Docker)

Have your own `.joblib` model? Let's deploy it.

1. Create an `.env` file pointing to your assets:

```env
MODEL_ARTIFACT_TYPE=joblib
MODEL_ARTIFACT_PATH=https://github.com/your-username/your-repo/raw/main/model.joblib
INPUT_SCHEMA_PATH=my_custom_schema.json
```

2. Build and Run:

```bash
docker build -t modelgate .
docker run -p 8000:8000 --env-file .env modelgate
```

Your Scikit-Learn model is now securely exposed via a REST API!

---

## 🤝 Contributing

We welcome contributions! Please check out
our [Contributing Guidelines](https://github.com/Bibek-Dhakal/blob/main/modelgate/CONTRIBUTING.md) for details on our
strict
Conventional Commits requirement, automated release process, and local setup.

## 📝 License

Distributed under the MIT License. See `LICENSE` for more information.
