{"id":30190836,"url":"https://github.com/mac2bua/ml-deployment-fastapi-uv","last_synced_at":"2025-09-10T19:42:00.958Z","repository":{"id":309439500,"uuid":"1036089293","full_name":"mac2bua/ml-deployment-fastapi-uv","owner":"mac2bua","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-11T22:22:02.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-11T23:33:50.110Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mac2bua.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-11T14:40:39.000Z","updated_at":"2025-08-11T22:22:05.000Z","dependencies_parsed_at":"2025-08-11T23:44:06.814Z","dependency_job_id":null,"html_url":"https://github.com/mac2bua/ml-deployment-fastapi-uv","commit_stats":null,"previous_names":["mac2bua/ml-deployment-fastapi-uv"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mac2bua/ml-deployment-fastapi-uv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac2bua%2Fml-deployment-fastapi-uv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac2bua%2Fml-deployment-fastapi-uv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac2bua%2Fml-deployment-fastapi-uv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac2bua%2Fml-deployment-fastapi-uv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mac2bua","download_url":"https://codeload.github.com/mac2bua/ml-deployment-fastapi-uv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac2bua%2Fml-deployment-fastapi-uv/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270127392,"owners_count":24531793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-12T20:09:13.127Z","updated_at":"2025-08-12T20:09:17.510Z","avatar_url":"https://github.com/mac2bua.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ML Churn Prediction API Demo\n\nThis repository demonstrates how to deploy a machine learning model as a web API endpoint for churn prediction, using a modern Python stack:\n\n- **FastAPI** for building the API\n- **Pydantic** for data validation and error handling\n- **UV** for dependency management and reproducible builds\n- **Docker** for containerization with optimized multi-stage builds\n- **Fly.io** for cloud deployment with CI/CD\n\nThe project is inspired by and follows the [mlzoomcamp-flask-uv workshop](https://github.com/alexeygrigorev/workshops/tree/main/mlzoomcamp-flask-uv) by [Alexey Grigorev](https://github.com/alexeygrigorev) from [DataTalks.Club](https://datatalks.club/). Many thanks to Alexey and the DataTalks.Club community for their excellent educational resources!\n\n## Features\n\n- **Churn prediction**: Exposes a `/predict` endpoint that accepts customer data and returns the probability of churn.\n- **Modern Python stack**: Uses FastAPI and Pydantic for robust, type-safe APIs with proper error handling.\n- **Reproducible builds**: Uses [UV](https://github.com/astral-sh/uv) for fast, reliable dependency management.\n- **Optimized Docker**: Multi-stage Docker build with proper layer caching and security best practices.\n- **Cloud deployment**: Ready for deployment on Fly.io with automated CI/CD via GitHub Actions.\n- **Production-ready**: Includes proper error handling, dependency locking, and containerization.\n\n## Getting Started\n\n### Prerequisites\n\n- [Docker](https://www.docker.com/) installed\n- (Optional) [UV](https://github.com/astral-sh/uv) for local development\n- (Optional) [Fly CLI](https://fly.io/docs/flyctl/) for cloud deployment\n\n### Local Development\n\n#### Option 1: Using Docker (Recommended)\n\n1. **Build the Docker image:**\n   ```sh\n   docker build -t churn-api .\n   ```\n\n2. **Run the container:**\n   ```sh\n   docker run -p 9696:9696 churn-api\n   ```\n\n#### Option 2: Using UV (for development)\n\n1. **Install dependencies:**\n   ```sh\n   uv sync\n   ```\n\n2. **Run the application:**\n   ```sh\n   uv run uvicorn predict:app --host 0.0.0.0 --port 9696\n   ```\n\n### Testing the API\n\nOnce the service is running, test the `/predict` endpoint by sending a POST request with customer data:\n\n```sh\ncurl -X POST \"http://localhost:9696/predict\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"gender\": \"male\",\n    \"seniorcitizen\": 0,\n    \"partner\": \"no\",\n    \"dependents\": \"yes\",\n    \"phoneservice\": \"no\",\n    \"multiplelines\": \"no_phone_service\",\n    \"internetservice\": \"dsl\",\n    \"onlinesecurity\": \"no\",\n    \"onlinebackup\": \"yes\",\n    \"deviceprotection\": \"no\",\n    \"techsupport\": \"no\",\n    \"streamingtv\": \"no\",\n    \"streamingmovies\": \"no\",\n    \"contract\": \"month-to-month\",\n    \"paperlessbilling\": \"yes\",\n    \"paymentmethod\": \"electronic_check\",\n    \"tenure\": 6,\n    \"monthlycharges\": 29.85,\n    \"totalcharges\": 129.85\n  }'\n```\n\nYou should receive a response like:\n```json\n{\n  \"churn_probability\": 0.54,\n  \"churn\": true\n}\n```\n\n### Cloud Deployment\n\nThe project includes configuration for deployment on [Fly.io](https://fly.io/) with automated CI/CD:\n\n1. **Set up Fly.io** (one-time setup):\n   ```sh\n   fly auth signup  # or fly auth login if you have an account\n   fly apps create  # creates a new app\n   ```\n\n2. **Deploy manually**:\n   ```sh\n   fly deploy\n   ```\n\n3. **Automated deployment**: \n   The GitHub Actions workflow in `.github/workflows/fly-deploy.yml` automatically deploys the app when you push to the `main` branch. You'll need to set the `FLY_API_TOKEN` secret in your GitHub repository settings.\n\n## Architecture\n\n- **Application code**: `predict.py` contains the FastAPI application with Pydantic models for request/response validation\n- **Model**: `model.bin` contains the trained scikit-learn model\n- **Dependencies**: `pyproject.toml` and `uv.lock` define and lock dependencies for reproducibility\n- **Containerization**: `Dockerfile` uses UV for efficient dependency installation and includes proper error handling\n- **Deployment**: `fly.toml` configures the Fly.io deployment with appropriate resource allocation\n\n## Credits\n\n- Workshop: [mlzoomcamp-flask-uv](https://github.com/alexeygrigorev/workshops/tree/main/mlzoomcamp-flask-uv)\n- Author: [Alexey Grigorev](https://github.com/alexeygrigorev)\n- Community: [DataTalks.Club](https://datatalks.club/)\n\n---\n\nThis project is for educational and demonstration purposes only. It is not intended for production use. Please review the code and adapt it to your needs if you plan to use it in a real application.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmac2bua%2Fml-deployment-fastapi-uv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmac2bua%2Fml-deployment-fastapi-uv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmac2bua%2Fml-deployment-fastapi-uv/lists"}