kj-depviz 0.1.0
A visualizer for Python packages using UV dependencies.
Requires Python: >=3.9

# 📦 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:

```bash
pip install kj-depviz

```

> **Note:** `kj-depviz` requires the **[uv](https://github.com/astral-sh/uv)** tool to be installed on your system to perform resolutions and simulations.
> ```bash
> 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`.

```bash
cd my-awesome-python-project

```

### 2. Run the Visualizer

Execute the analysis command:

```bash
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.