ModelGate 🚀

Containerized machine learning inference API with zero boilerplate.

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: Endpoints, request payloads, and example curl commands.
• ⚙️ Usage & Configuration: Environment variables, Schema validation, Model URL loading, and SDK implementation.
• 🏗️ Architecture & Design: System flow, Mermaid diagrams, and error shielding concepts.
• 🧪 Testing Standards: Pytest strategies, coverage, and CI checks.
• 🧹 Code Quality: 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.

# Install dependencies
pip install -e .[dev]

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

Test the endpoint:

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.

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:

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:

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