🧬 CompactIQ (PyCompat)

An AI-Powered Python Package Compatibility Prediction Engine

CompactIQ (also referred to as PyCompat) is a complete machine learning system designed to predict whether a specific Python package version will successfully install and import on a given system architecture and Python version.

If a package is incompatible, the model predicts the exact Error Type (e.g., no_wheel, abi_mismatch, import_error). It can also rank and recommend the best alternative versions of a package for your system.

---

🪟 Run the demo on Windows

What you need

Requirement	Needed for	Notes
Python 3.10 – 3.13	everything	Install from https://www.python.org/downloads/ and tick "Add python.exe to PATH". Python 3.14+ will not work yet.
Git (optional)	checking a GitHub repo by link	https://git-scm.com/download/win – without it you can still check a folder on your disk
Docker Desktop (optional)	the "verify with real Docker installs" option	Must be running, in Linux containers mode. First run downloads an image (about a minute).
Groq API key (optional)	the "ask an LLM about unknown packages" option	Free at https://console.groq.com. Use your own key.

1. One-time setup

Unzip the folder, open Command Prompt (or PowerShell) inside it, and run:

setup_windows.bat

That creates a virtual environment and installs the dependencies. Manual equivalent:

python -m venv venv
venv\Scripts\activate.bat
pip install -r requirements.txt

2. Option A – Web dashboard

run_dashboard.bat

Wait about 15 seconds until you see Running on http://127.0.0.1:5050, then open http://localhost:5050. Tabs: Predict, Recommend, Analytics, Packages, Deploy Check, plus the chat-style Dependency Assistant.

Try this in Deploy Check (the box is pre-filled): local machine Windows, deploy target AWS EC2, click Check Deploy Compatibility. pywin32 gets flagged as Windows-only and fixed with a platform marker.

Try this in the Dependency Assistant: paste pip install torch==2.8.0 torchvision==0.17.0, or just describe a project, e.g. I am building a web scraper.

3. Option B – Interactive command line

run_cli.bat

It shows your system, then asks for a project. Give it a folder on your disk, or a GitHub repo (needs Git):

Project path or GitHub repo: SibgathKhan777/nomeshops-sample

That repo is a ready-made demo: a stale numpy pin and psycopg2 get fixed, and a typo'd package (reqests) is reported as unfixable instead of being guessed at. It is a dry run first – nothing is written unless you answer y to the apply question (and every changed file gets a .bak backup).

4. Option C – One command, no questions

venv\Scripts\activate.bat
python fix_project_requirements.py C:\path\to\your\project --deploy-target linux_x86_64
python fix_project_requirements.py C:\path\to\your\project --deploy-target linux_x86_64 --apply
python fix_project_requirements.py SibgathKhan777/nomeshops-sample --deploy-target linux_x86_64

Useful flags: --docker-verify (real container installs, for every package), --no-llm (never ask the LLM), --deploy-target linux_aarch64 | win_amd64, --pattern "requirements-dev.txt", --json. It only changes exact package==version pins; ranges like >= are left alone on purpose.

5. Optional – automatic LLM second opinion

There is no button for it. When the ML model is not sure about a package (it has never seen it, or its prediction is close to a coin flip), CompactIQ asks an LLM and shows the answer labelled unverified, and also runs a real Docker install for that package if Docker is available. This only happens if you add a key:

copy .env.example .env
notepad .env

Paste your key after GROQ_API_KEY= and save. Without a key this step is skipped silently. Never share your .env.

6. Optional – standalone REST API (no UI)

venv\Scripts\activate.bat
python api_server.py --port 8080
curl http://localhost:8080/api/health

Troubleshooting

• python is not recognized – reinstall Python with Add to PATH ticked, or use py -3 instead of python.
• PowerShell blocks activate – use Command Prompt, or run the .bat files, which avoid activation.
• Port 5050 already in use – close the other window running the dashboard, or find the process: netstat -ano | findstr 5050.
• pip install fails – check python --version is 3.10–3.13.
• Garbled symbols in the console – harmless; the .bat files already set PYTHONUTF8=1.
• Docker option shows a warning – Docker Desktop is not running, or is in Windows-containers mode; switch to Linux containers.

---

🚀 Features

• Binary Compatibility Model (Random Forest): 97.1% accuracy.
• Error Type Classifier (Gradient Boosting): 98.4% accuracy.
• Flask REST API: Production-ready API server to integrate predictions anywhere.
• Web Dashboard: Premium dark-themed UI with interactive analytics and a compatibility checker.
• Hugging Face Hub: Supports one-click download/upload to huggingface (sibbbuu/pycompat-model).

💻 Quick Start

1. Installation

Install the required dependencies:

pip install -r requirements.txt

Or install the local package directly:

pip install -e .

2. Start the API Server

Run the production REST API to serve predictions (defaults to port 8080):

python api_server.py --port 8080

3. Start the Web Dashboard

Launch the premium interactive dashboard to visualize stats and manually test versions:

python app.py

Visit http://localhost:5050 in your browser.

4. CLI Usage

You can test predictions directly from the terminal without starting a server:

# General predict format:
# python pycompat_model.py predict <model_dir> <package> <version> <python_ver>
python pycompat_model.py predict ./model boto3 1.42.49 3.12

# Get recommendations for the best versions:
python pycompat_model.py recommend ./model alembic 3.9

---

📊 Gantt Chart Generation

If you are planning out the development lifecycle of this project (or a similar AI project) and want to generate a Gantt Chart exactly like the classic Data Science timeline example, you can copy and paste the prompt below into ChatGPT, Claude, or Gemini.

It is engineered to generate a Python script using Matplotlib that beautifully recreates the exact styling, colors, and layout of a professional project timeline.

📋 The Prompt:

Write a Python script using Matplotlib to generate a horizontal Gantt Chart timeline for an AI prediction project. 

It must exactly match this visual style:
1. The background of the plot and the figure should be a light grey color (e.g., '#cfcfcf' or '#d9d9d9').
2. There should be a massive main title at the top saying "GANTT CHART" in a dark blue font (e.g., '#0b4d8c'), with a smaller subtitle below it saying "Project Timeline (Apr - Nov)".
3. Use horizontal bars (`ax.barh`). 
4. The X-axis should represent the months from April to November. The labels should perfectly align with the start of each month (Apr, May, Jun, Jul, Aug, Sep, Oct, Nov).
5. The Y-axis should list the project tasks in descending order from top to bottom.
6. The tasks and their approximate timelines should be:
   - "Research & Planning" (Apr to mid-May)
   - "Data Collection & Integration" (Apr to Jun)
   - "Data Preprocessing" (May to Jun)
   - "Feature Engineering" (May to Jul)
   - "Baseline Model" (Jun to Jul)
   - "Advanced Model Development" (Jun to Aug)
   - "Model Comparison & Evaluation" (Jul to Aug)
   - "Dashboard UI & API Integration" (Aug to Oct)
   - "System Integration" (Sep to Oct)
   - "Performance Optimization" (Sep to Nov)
   - "Testing & Validation" (Oct to Nov)
   - "Documentation & Report" (Oct to Nov)
   - "Final Demo & Closure" (Nov)
7. Give every single task a distinct, solid color (e.g., dark blue, orange, green, red, purple, brown, pink, dark grey, olive, teal).
8. Put a thin black border frame around the main plot area.
9. Ensure there are no gridlines, and keep the font sizes legible (around 9 or 10 for the Y-axis tasks).

Provide the fully working Python code.

Just copy the block above and the AI will generate the Python code required to plot your chart!

---

🌐 API Endpoints

When the API is running, the following REST endpoints are available:

• POST /api/predict — Check compatibility for a specific package version.
• POST /api/predict/batch — Send an array of configurations to test at once.
• POST /api/recommend — Pass a package and Python version to get a ranked list of versions.
• POST /api/validate — Validate (and auto-correct) a whole pip install line: ML prediction + live PyPI verification + joint dependency conflict checking across every package, with a risk score and explanation. See below.
• GET /api/info — Fetch model metrics and accuracy stats.
• GET /api/packages — Browse the list of supported pip packages.

POST /api/validate

Validates every package==version pin in a snippet of pip install code — not just individually, but against each other (do the pinned versions violate each other's declared dependencies?) and against live PyPI (does the version actually exist, does a wheel exist for this platform/Python combo?). Returns a risk score, a plain-language explanation, and a corrected install line.

curl -X POST http://localhost:8080/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "code": "pip install alembic==1.18.4 SQLAlchemy==1.0.0",
    "python_version": "3.12",
    "platform": "darwin_x86_64"
  }'

{
  "original_code": "pip install alembic==1.18.4 SQLAlchemy==1.0.0",
  "corrected_code": "pip install alembic==1.18.4 SQLAlchemy==2.0.42",
  "changed": true,
  "risk_score": 1.0,
  "joint_dependency_conflicts": [
    {
      "from_package": "alembic",
      "depends_on": "SQLAlchemy",
      "required_specifier": ">=1.4.23",
      "pinned_version": "1.0.0",
      "satisfied": false
    }
  ],
  "packages": [ { "package": "alembic", "is_clean": true, "..." : "..." },
                { "package": "SQLAlchemy", "is_clean": false, "explanation": "...", "..." : "..." } ]
}

Set "live": false in the request body to skip the live PyPI calls and get an ML-only response (useful offline).

Standalone modules behind /api/validate

These can also be run directly, without the API server:

• live_verify.py — checks a package/version against PyPI right now (does it exist, is there a wheel for this platform + Python version). Fills the gap where the trained model can only reflect what was true in data.json at training time.

  python live_verify.py boto3 1.42.49 3.12 darwin_x86_64

• dependency_conflicts.py — checks a batch of pinned packages against each other's real PyPI-declared requires_dist, catching cross-package conflicts a single-package classifier can't see.

  python dependency_conflicts.py 3.12 alembic 1.18.4 SQLAlchemy 1.0.0

• eval_temporal_holdout.py — evaluates the model on packages/versions it was never trained on (instead of the random 80/20 split), to measure real-world generalization rather than in-distribution fit.

  python eval_temporal_holdout.py data.json

🤝 Contributing

Contributions are welcome. Please ensure that modifying the dataset (data.json) triggers a successful retraining. By default, app.py actively monitors data.json and automatically retrains the model in the background when changes are detected!