kj-depviz 0.2.0

The Interactive Dependency Visualizer & AI Conflict Solver

📦 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 uv and your choice of LLM (Google Gemini, OpenAI, or OpenRouter), kj-depviz lets you simulate dependency changes, detect conflicts before they break your environment, and interactively resolve errors.

---

✨ 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 near-instantly.
• 🤖 Multi-LLM Conflict Analyst: Connect your API Key for Gemini, OpenAI, or OpenRouter. The AI acts as an elite DevOps engineer in your browser, analyzing dependency errors and explaining exactly how to fix them.
• 🧪 3-Way Analysis Modes:
  • Static AI Analysis: Fast, theoretical conflict detection.
  • UV Playground (AI): Safely simulate adding/modifying packages in a temporary sandbox. If it breaks, the AI explains the CLI output.
  • Dry Run: Run raw UV simulations and see the exact terminal logs without AI intervention.
• 🧠 Smart CLI Resolver: If your dependencies are completely broken, the new terminal-based Interactive Surgeon steps in. Use AI Deep Diagnosis, pinpoint culprit packages, or relax strict versions right from your terminal via a beautiful TUI.
• 🔦 Deep Inspection: Click any node to see who uses it, what version is installed, and its dependency path.

---

🛠️ Installation

Install kj-depviz from PyPI using pip or uv:

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

If your dependencies are severely broken, the CLI will automatically launch the Smart Resolver TUI to help you fix them before starting the server!

3. Explore

The tool will start a local server. Open the link in your browser (usually http://127.0.0.1:8000).

---

🎮 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, hover for versions, 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 Your LLM: Choose Gemini, OpenAI, or OpenRouter and paste your API Key (safely stored locally in your browser).
2. Select an Action:

• Modify: See what happens if you upgrade/downgrade a package.
• Add: Test if adding a new package will cause math conflicts.
• Python Version: Check if your project survives a Python version bump.

3. Choose your Mode: Static Analysis, Playground Simulation, or Dry Run.
4. Analyze: kj-depviz will run the math or spin up a sandbox, attempt the change, and give you a beautiful markdown report of the results.

⚙️ Settings & Customization

• Toggle Theme: Switch between Dark 🌙 and Light ☀️ modes.
• Layouts: Rotate the graph (Top-Down or Left-Right).
• Search & Refresh: Instantly find packages, or hit refresh to live-reload the graph if you edit your uv.lock in another window.

---

📦 Supported Formats

kj-depviz automatically detects:

1. uv.lock & pyproject.toml (Native Mode - Best Experience)
2. requirements.txt (Automatically converted to a secure, temporary uv sandbox for visualization)

---

👨‍💻 Author

Karan Jain (KJ) A passionate developer and AI-ML Engineer 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.