kj-depviz 0.1.0

A visualizer for Python packages using UV dependencies.

📦 KJ-DepViz: The Interactive Dependency Visualizer & AI Conflict Solver

Stop staring at pip freeze. Start visualizing your project.

kj-depviz is a next-generation tool that turns your requirements.txt, pyproject.toml, or uv.lock files into an interactive, explorable graph. But it doesn't just show you dependencies—it helps you fix them.

Powered by Google Gemini and the blazing-fast uv package manager, kj-depviz lets you simulate dependency changes and detect conflicts before they break your environment.

---

✨ Key Features

• 🎨 Interactive Graph Visualization: See exactly how your packages connect. Differentiate between Root projects, Direct dependencies, and Transitive (deep) dependencies instantly.
• 🚀 Powered by uv: Uses the ultra-fast uv resolver to parse lock files and convert standard requirements instantly.
• 🧠 AI Conflict Analyst: Connect your Google Gemini API Key to get an elite DevOps engineer in your browser. It analyzes dependency errors and explains why a package is failing in plain English.
• 🧪 The Playground (Simulation Mode): Want to upgrade pandas or add tensorflow but afraid of breaking everything? Run a simulation in the UI. We create a temporary sandbox, try the install, and report the results without touching your actual project.
• 🔦 Deep Inspection: Click any node to see who uses it, what version is installed, and its dependency path.
• 📸 Export Ready: One-click export your dependency graph to high-quality PNG for documentation or presentations.

---

🛠️ Installation

Install kj-depviz from PyPI using pip:

pip install kj-depviz

Note: kj-depviz requires the uv tool to be installed on your system to perform resolutions and simulations.

pip install uv

---

🚀 How to Use

1. Navigate to your Project

Open your terminal and go to any Python project folder that contains a requirements.txt, pyproject.toml, or uv.lock.

cd my-awesome-python-project

2. Run the Visualizer

Execute the analysis command:

kj-depviz analysis

3. Explore

The tool will start a local server and tell you where to look (usually http://127.0.0.1:8000). Open that link in your browser!

---

🎮 The Dashboard Features

🕸️ The Graph View

• 🟡 Yellow Nodes: Your Root Project.
• 🟠 Orange Nodes: Direct Dependencies (things you installed explicitly).
• 🔵 Blue Nodes: Transitive Dependencies (things your packages rely on).
• Interactions: Drag nodes, zoom in/out, and double-click a node to copy its ID.

🤖 AI Conflict Analyst (The "Magic" Button)

Click the ✨ AI Analyst button in the bottom menu to open the AI Drawer.

1. Connect Gemini: Paste your Google Gemini API Key (stored locally in your browser).
2. Select a Mode:

• Modify: specific what happens if you upgrade a package (e.g., change numpy to 2.0.0).
• Add: See if adding a new package (e.g., scipy) will cause conflicts.
• Python Version: Check if your project is compatible with a newer Python version (e.g., 3.12).

3. Run Simulation: kj-depviz will spin up a sandbox, attempt the change using uv, and if it fails, Gemini will analyze the error logs and tell you exactly how to fix it.

⚙️ Settings & Customization

• Toggle Theme: Switch between Dark 🌙 and Light ☀️ modes.
• Layouts: Rotate the graph (Top-Down or Left-Right).
• Search: Instantly find any package in massive dependency trees.

---

📦 Supported Formats

kj-depviz automatically detects:

1. uv.lock & pyproject.toml (Best experience)
2. requirements.txt (Will be automatically converted to a temporary uv format for visualization)

---

👨‍💻 Author

Karan Jain (KJ)

• A passionate developer bridging the gap between complex dependency trees and developer experience.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.