README.md

---
title: Python Dependency Compatibility Board
emoji: 🐍
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: mit
---

# 🐍 Python Dependency Compatibility Board

A powerful tool to analyze and resolve Python package dependencies. Check for version conflicts, compatibility issues, and generate clean `requirements.txt` files.

## ✨ Features

- **Multiple Input Methods**: Library list, requirements.txt paste, or file upload
- **Conflict Detection**: Automatically detects version conflicts and compatibility issues
- **🤖 AI-Powered Explanations**: Uses LLM to generate intelligent, natural language explanations for conflicts (with fallback to rule-based)
- **Dependency Resolution**: Uses pip's resolver to find compatible versions
- **Environment Aware**: Configure Python version, device (CPU/GPU), and OS
- **Analysis Modes**: Quick (top-level) or Deep (with transitive dependencies)
- **Resolution Strategies**: Latest compatible, stable/pinned, keep existing, or minimal changes
- **Spell Checking**: Auto-corrects common spelling mistakes in package names
- **Validation Utilities**: Benchmark against the bundled synthetic dataset and generate perturbed requirements for stress testing

## 🚀 How to Use

### Input Your Dependencies

You can provide dependencies in three ways:

1. **Library List**: Enter package names one per line
   ```
   pandas
   torch
   langchain
   fastapi
   ```

2. **Requirements Text**: Paste your existing requirements.txt
   ```
   pandas==2.0.3
   torch>=2.0.0
   langchain==0.1.0
   ```

3. **File Upload**: Upload a requirements.txt file directly

### Configure Environment

- **Python Version**: Select your target Python version (3.8-3.12)
- **Device**: CPU only, NVIDIA GPU (CUDA), Apple Silicon (MPS), or Custom
- **Operating System**: Any, Linux, Windows, or macOS

### Analysis & Resolution

1. Choose **Analysis Mode**:
   - **Quick**: Fast analysis of top-level dependencies
   - **Deep**: Complete dependency tree with transitive dependencies

2. Select **Resolution Strategy**:
   - **latest_compatible**: Resolve to latest compatible versions
   - **stable/pinned**: Prefer stable, pinned versions
   - **keep_existing_pins**: Preserve your existing version pins
   - **minimal_changes**: Make minimal changes to resolve conflicts

3. Click **"Analyze & Resolve Dependencies"**

4. Review the results and download your resolved `requirements.txt`

## 🔍 What It Detects

The tool automatically detects:

- **Duplicate Packages**: Same package specified multiple times with conflicting versions
- **PyTorch Compatibility**: Ensures pytorch-lightning>=2.0 works with torch>=2.0
- **FastAPI/Pydantic**: Checks version compatibility (e.g., fastapi 0.78.x requires pydantic v1)
- **TensorFlow/Keras**: Validates TensorFlow/Keras version pairs
- **Version Conflicts**: Identifies incompatible version specifications

## 🤖 AI Explanations

When enabled, the tool uses LLM reasoning to provide:
- **Clear Explanations**: Natural language descriptions of what the conflict is
- **Why It Happens**: Technical reasons behind the conflict
- **How to Fix**: Actionable solutions with specific version recommendations

The LLM explanations use Hugging Face Inference API (free tier) and automatically fall back to rule-based explanations if the API is unavailable.

## 📋 Example

**Input:**
```
torch==1.8.0
pytorch-lightning==2.2.0
pandas==2.0.3
```

**Output:**
```
⚠️ Compatibility Issues Found:
- pytorch-lightning>=2.0 requires torch>=2.0, but torch<2.0 is specified

Resolved requirements.txt:
torch==2.1.0
pytorch-lightning==2.2.0
pandas==2.0.3
...
```

## 🛠️ Technical Details

- Built with [Gradio](https://gradio.app/)
- Uses `packaging` library for version parsing
- Leverages pip's dependency resolver
- Supports PEP 508 requirement specifications

## 📝 Notes

- Full dependency resolution requires pip >= 22.2
- Deep mode may take longer for large dependency sets
- The tool works best with packages available on PyPI
- Platform-specific dependencies (e.g., CUDA) are detected but resolution may vary
- Run `python validation_tools.py` to benchmark the built-in compatibility checks against synthetic cases.
- Use `python scripts/perturb_requirements.py --help` to generate noisy/invalid requirements for robustness testing.

## 🤝 Contributing

Feel free to test the tool and report any issues! This tool is designed to help developers manage Python dependencies more effectively.

## 📄 License

MIT License - feel free to use and modify as needed.

---

**Made with ❤️ for the Python community**