MaintainIQ

AI-Powered Predictive Maintenance & Industrial Operations Intelligence Platform

Which machines are likely to fail, when, why, what will it cost, and what should we do about it?

MaintainIQ is an end-to-end industrial analytics platform built for a fictional multi-plant manufacturer, Nova Manufacturing Group (4 plants, 300 machines across 6 machine types). It takes raw sensor, production, and maintenance data through a full pipeline — ingestion → data quality → warehouse → feature engineering → statistics → anomaly detection → failure prediction → RUL → explainability → risk scoring → business impact → maintenance decision engine → GenAI analyst → API → Power BI — and ends with an AI-powered decision-support tool a plant manager could actually use.

This is a portfolio project. The dataset is synthetic but built from a physically-motivated simulation (a hidden "wear" state drives sensor drift, maintenance resets, and failure hazard — see docs/data_generation.md), and every number in this README, the app, and the docs comes from actually running the pipeline in this repository — nothing is invented. Where a result is weak or a model underperforms, that's reported too (see the Model Card and docs/ml_methodology.md for two examples).

---

What's actually in here

Layer	What it does	Where
Data generation	Synthetic industrial dataset with correlated wear/sensor/failure dynamics	src/data_generation/
Data quality	21-rule validation engine with a generated report	src/validation/
Database	PostgreSQL DDL (tested against a live Postgres 16 instance) + SQLite default	database/, src/ingestion/
SQL analytics	27 business queries (CTEs, window functions, rolling aggregates)	sql/analytics/
Feature engineering	Leakage-safe daily feature table (rolling drift signals)	src/feature_engineering/
EDA / statistics	Real hypothesis tests, confidence intervals, SPC control limits	src/statistics/
Anomaly detection	Rolling z-score/IQR + Isolation Forest	src/anomaly_detection/
Failure prediction	Logistic Regression / Random Forest / XGBoost, time-aware split	src/models/
RUL estimation	Remaining Useful Life regression (with an honest negative finding)	src/forecasting/
Explainability	SHAP — global + per-machine	src/explainability/
Risk engine	0-100 health score + root cause narratives	src/risk_engine/
Business impact	Failure risk → ₹ financial exposure	src/risk_engine/business_impact.py
Decision engine	Rule-based priority queue	src/recommendations/
Optimizer	Knapsack-based capacity-constrained scheduling	src/optimization/
GenAI analyst	Grounded Q&A, local fallback + optional real LLM	src/llm/
API	FastAPI, 10 endpoints	src/api/
App	Streamlit, 6 pages	app/
Tests	56 pytest tests, all passing	tests/
Power BI	Star-schema exports + DAX + Power Query + page spec	dashboard/

Quickstart (Windows 11, PowerShell)

# 1. Extract the zip, then from the MaintainIQ folder:
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt --break-system-packages

# 2. Copy environment config
copy .env.example .env

# 3. Run the full pipeline (generates data, validates, loads DB, engineers
#    features, trains models, computes risk/business outputs) — about 5-8 minutes.
python scripts\run_pipeline.py

# 4. Launch the app
streamlit run app\Home.py
# in a second terminal, optionally:
uvicorn src.api.main:app --port 8000

See docs/deployment.md for the full Windows setup guide, PostgreSQL instructions, and common issues. scripts/*.ps1 wrap each stage individually if you'd rather run them one at a time.

What's real vs. what's a documented simplification

• Data is synthetic — generated by src/data_generation/, not observed from a real factory. The generation logic and calibration process are fully documented in docs/data_generation.md.
• PostgreSQL is genuinely supported and was tested — the schema in database/schema/postgres_schema.sql was applied to a real PostgreSQL 16 instance, and the full 1.24M-row dataset was loaded through it with foreign keys enforced. SQLite is the zero-setup local default (DB_ENGINE=sqlite in .env).
• Every SQL query in sql/analytics/business_queries.sql was executed against live PostgreSQL and returns real results — see docs/sql_analytics.md for sample output.
• ML metrics are unmassaged. The failure classifier gets ROC-AUC ~0.66 — a real, moderate lift over chance, not a suspiciously perfect number. The RUL regressor is reported as not beating a naive baseline, with an explanation of why. See docs/model_card.md.
• No live .pbix file is included — Power BI Desktop can't be authored programmatically in this environment. Instead: clean CSV exports, the DAX measures, Power Query steps, and an exact page-by-page import guide are provided (docs/powerbi.md), so recreating the dashboard is copy-paste work, not guesswork.
• The GenAI analyst runs with zero API cost by default (LLM_PROVIDER unset in .env) using a deterministic template that reads the same structured context a real LLM call would get. Set LLM_PROVIDER/LLM_API_KEY to route through Anthropic or OpenAI instead.

Project layout

MaintainIQ/
├── config/                 # settings.py — single source of truth for paths, seeds, costs
├── data/                   # raw / processed / synthetic (regenerated by the pipeline)
├── database/schema/        # PostgreSQL DDL (star schema, constraints, indexes, views)
├── sql/analytics/          # 27 business SQL queries
├── src/
│   ├── data_generation/    # simulator (domain.py, simulate.py, engine.py)
│   ├── validation/         # data quality engine
│   ├── ingestion/          # warehouse loader (SQLite/Postgres via SQLAlchemy)
│   ├── feature_engineering/
│   ├── statistics/         # EDA + hypothesis tests
│   ├── anomaly_detection/
│   ├── models/             # failure prediction
│   ├── forecasting/        # RUL
│   ├── explainability/     # SHAP
│   ├── risk_engine/        # health score, root cause, business impact
│   ├── recommendations/    # decision engine
│   ├── optimization/       # knapsack scheduler
│   ├── llm/                # GenAI analyst
│   └── api/                # FastAPI
├── app/                    # Streamlit (Home.py + pages/)
├── dashboard/               # Power BI exports, DAX, Power Query
├── tests/                  # pytest (56 tests)
├── scripts/                # PowerShell + Python orchestration
└── docs/                   # architecture, methodology, business logic, interview prep, etc.

Documentation index

• docs/architecture.md — system design, data flow
• docs/data_dictionary.md — every table and column
• docs/data_generation.md — how the synthetic data is built & calibrated
• docs/sql_analytics.md — the 27 queries with sample output
• docs/eda_findings.md — statistical findings (Finding → Evidence → Meaning)
• docs/ml_methodology.md — leakage discipline, validation strategy, tradeoffs
• docs/model_card.md — failure model + RUL model cards
• docs/anomaly_detection.md — method choice and rationale
• docs/explainability.md — SHAP setup and the bug I found and fixed
• docs/business_logic.md — cost assumptions, decision rules, correlation vs. causation
• docs/api.md — endpoint reference
• docs/powerbi.md — dashboard recreation guide
• docs/genai.md — analyst architecture, grounding, hallucination prevention
• docs/deployment.md — Windows/PostgreSQL/Docker setup, troubleshooting
• docs/interview_questions.md — 35+ Q&A for presenting this project
• docs/resume_bullets.md, docs/linkedin_post.md, docs/portfolio_content.md

License

MIT — see LICENSE. The data is synthetic; there is no real company, machine, or person behind any record in this dataset.