Initial commit: Production-ready Predictive Maintenance API

Author: Volodymyr Samoilov

.coveragerc

@@ -0,0 +1,2 @@
+[run]
+omit = src/visualization/*

.dockerignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.ipynb_checkpoints/
+.venv/
+venv/
+.env
+.DS_Store
+logs/
+.git/
+.gitignore
+.github/
+.pytest_cache/
+.coverage
+htmlcov/

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main", "master" ]
+  pull_request:
+    branches: [ "main", "master" ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run tests
+        run: |
+          pytest -v --cov=src --cov=api --cov-report=term-missing
+
+  docker-build:
+    runs-on: ubuntu-latest
+    needs: tests
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: |
+          docker build -t pm-api:ci .

.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+
+# Jupyter / notebooks
+.ipynb_checkpoints/
+*.ipynb
+
+# Pytest / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Logs
+logs/
+*.log
+
+# Environment / secrets
+.env
+.env.*
+*.env
+
+# OS / Editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Docker
+docker-compose.override.yml
+
+# Temporary files
+tmp/
+.cache/
+
+# IDE
+.vscode/
+.idea/

Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.9.6-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volodymyr Samoilov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,104 @@
+# =========================
+# Predictive Maintenance API
+# =========================
+
+IMAGE_NAME ?= pm-api
+CONTAINER_NAME ?= pm-api
+PORT ?= 8000
+
+API_URL ?= http://127.0.0.1:$(PORT)
+
+
+help:
+	@echo "Available commands:"
+	@echo "  make build                Build Docker image ($(IMAGE_NAME))"
+	@echo "  make run                  Run container on port $(PORT)"
+	@echo "  make run-d                Run container in background (detached)"
+	@echo "  make stop                 Stop & remove container ($(CONTAINER_NAME))"
+	@echo "  make rebuild              Stop + build + run"
+	@echo "  make clean                Remove image + prune build cache"
+	@echo "  make health               Call GET /health"
+	@echo "  make predict              Call POST /predict (single record)"
+	@echo "  make explain              Call POST /explain (top contributors)"
+	@echo "  make explain-plot          Call POST /explain/plot -> saves shap.png"
+	@echo "  make test                 Run all tests (local)"
+	@echo "  make test-cov             Run tests with coverage"
+	@echo "  make test-unit            Run unit tests only"
+	@echo "  make test-integration     Run integration tests only"
+	@echo "  make test-docker          Run tests inside Docker"
+	@echo ""
+	@echo "Vars:"
+	@echo "  IMAGE_NAME=pm-api PORT=8000 CONTAINER_NAME=pm-api"
+
+# Build Docker image
+build:
+	docker build -t $(IMAGE_NAME) .
+
+# Run container (foreground)
+run: stop
+	docker run --rm \
+		--name $(CONTAINER_NAME) \
+		-p $(PORT):8000 \
+		$(IMAGE_NAME)
+
+# Run container (detached)
+run-d: stop
+	docker run -d \
+		--name $(CONTAINER_NAME) \
+		-p $(PORT):8000 \
+		$(IMAGE_NAME)
+	@echo "Running: $(CONTAINER_NAME) on $(API_URL)"
+
+
+
+# Stop & remove container by name (safe if not running)
+stop:
+	@docker rm -f $(CONTAINER_NAME) >/dev/null 2>&1 || true
+	@echo "Container $(CONTAINER_NAME) stopped/removed (if existed)."
+
+# Rebuild (stop + build + run-d)
+rebuild: stop build run-d
+
+# Healthcheck
+health:
+	curl -s $(API_URL)/health | python3 -m json.tool
+
+# Test /predict
+predict:
+	curl -s -X POST $(API_URL)/predict \
+		-H "Content-Type: application/json" \
+		-d '{"Air temperature [K]":300,"Process temperature [K]":310,"Rotational speed [rpm]":1500,"Torque [Nm]":40,"Tool wear [min]":100,"Type":"M"}' \
+	| python3 -m json.tool
+
+# Test /explain
+explain:
+	curl -s -X POST "$(API_URL)/explain?top_k=8" \
+		-H "Content-Type: application/json" \
+		-d '{"Air temperature [K]":300,"Process temperature [K]":310,"Rotational speed [rpm]":1500,"Torque [Nm]":40,"Tool wear [min]":100,"Type":"M"}' \
+	| python3 -m json.tool
+
+# Test /explain/plot (saves PNG)
+explain-plot:
+	curl -s -X POST $(API_URL)/explain/plot \
+		-H "Content-Type: application/json" \
+		-d '{"Air temperature [K]":300,"Process temperature [K]":310,"Rotational speed [rpm]":1500,"Torque [Nm]":40,"Tool wear [min]":100,"Type":"M"}' \
+	-o shap.png
+	@echo "Saved SHAP plot to ./shap.png"
+
+
+# Clean image + build cache 
+clean: stop
+	@docker image rm -f $(IMAGE_NAME) >/dev/null 2>&1 || true
+	@docker builder prune -f >/dev/null 2>&1 || true
+	@echo "🧹 Cleanup done."
+
+# Run tests inside Docker container
+test-docker: build
+	docker run --rm \
+		$(IMAGE_NAME) \
+		pytest -v
+
+test-docker-cov: build
+	docker run --rm \
+		$(IMAGE_NAME) \
+		pytest -v --cov=src --cov=api --cov-report=term-missing