Project Motivation & Problem Statement
Python dependency conflicts are one of the most frustrating and time-consuming issues developers face. Error messages from pip are often cryptic, providing version numbers and constraint violations without explaining why the conflict exists or how to resolve it. ResolveLens addresses this pain point by combining automated dependency conflict detection with AI-powered natural language explanations, transforming confusing error messages into clear, actionable guidance that helps developers resolve issues quickly and understand the underlying causes.
Technical Approach
1. Dependency Parsing Engine
- Built a custom dependency parser (
dependency_parser.py) that reads requirements files and extracts package names, version specifiers, and constraint operators.
- Resolved the full dependency tree by recursively analyzing transitive dependencies-packages required by your direct dependencies.
- Handled complex version specifiers including ranges (
>=1.0,<2.0), exact pins (==1.5.3), and compatibility releases (~=1.4).
2. Conflict Detection System
- Implemented a conflict detector (
conflict_detector.py) that compares version requirements across the entire dependency tree to identify incompatible constraints.
- Detected multiple conflict types: direct version conflicts, transitive dependency clashes, Python version incompatibilities, and circular dependency chains.
- Generated structured conflict reports with the specific packages, versions, and constraints involved in each conflict.
3. AI-Powered Explanation Engine
- Developed an explanation engine (
explanation_engine.py) that feeds structured conflict data to an LLM to generate human-readable explanations.
- Explanations are organized into three sections: What the conflict is, Why it happens (technical root cause), and How to Fix it (specific actionable steps).
- Prompt engineering ensures explanations are tailored to the developer's specific conflict rather than generic advice.
- Included context about common resolution patterns: pinning versions, using virtual environments, finding alternative packages, or upgrading/downgrading.
4. Interactive UI with Streamlit
- Built a Streamlit-based web interface (
app.py) allowing users to paste their requirements file or upload it directly.
- Real-time conflict analysis with immediate visual feedback on detected issues.
- Collapsible explanation cards for each conflict, making it easy to navigate complex dependency situations.
- Copy-to-clipboard functionality for suggested resolution commands.
Results
- Successfully detects and explains common Python dependency conflicts that typically confuse developers.
- AI-generated explanations significantly reduce debugging time compared to manually interpreting pip error messages.
- Streamlit interface provides an accessible, no-installation-needed tool for local development use.
- Modular architecture allows easy extension to support additional package managers (conda, poetry) in the future.
Limitations
- Dependency resolution relies on locally available package metadata; some edge cases with private repositories or custom indexes may not be handled.
- LLM explanations, while generally accurate, may occasionally suggest resolutions that don't account for project-specific constraints.
- The tool currently focuses on pip-based workflows; conda and poetry support is planned but not yet implemented.
Skills and Technologies Demonstrated
- Python dependency management and resolution algorithms
- LLM integration for automated technical documentation
- Streamlit web application development
- Software architecture with modular, testable components
- Developer tooling and DX (Developer Experience) design
- Prompt engineering for technical explanation generation