Metadata-Version: 2.4
Name: code-prism
Version: 0.2.1
Summary: Code Prism - MCP server for intelligent codebase exploration with multi-LLM support and dependency analysis
Author-email: Your Name <your.email@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/code-prism
Project-URL: Repository, https://github.com/yourusername/code-prism
Project-URL: Issues, https://github.com/yourusername/code-prism/issues
Keywords: mcp,codebase,analysis,dependencies,ai,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.40.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: litellm>=1.50.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# Prism - AI-Powered Codebase Explorer

![Prism - Refracting code into structured dependencies](prism.jpg)

**Give AI the bird's eye view it's missing.** Prism is an MCP server that helps AI assistants like Claude Code understand codebases from the top down, not the bottom up.

## The Problem: Tunnel Vision

When AI explores code, it sees files in isolation. It reads one file, then another, then another - like looking at a city through a drinking straw. It understands the details but misses how everything connects.

This leads to:
- **Fragmented understanding** - Knows individual components but not the system
- **Missed context** - Doesn't see what calls what, or why something exists
- **Wrong assumptions** - Guesses at architecture instead of seeing it
- **Inefficient exploration** - Reads the wrong files, misses the important ones

## The Solution: Hierarchical Understanding

Prism gives AI a **lens that zooms out**. Before diving into implementation details, it can:

1. **See the big picture** - Understand the system architecture and how components relate
2. **Follow the flow** - Trace how code connects from entry points to implementation
3. **Think hierarchically** - Start with high-level patterns, then drill down
4. **Navigate intelligently** - Know which files matter for answering a specific question

Instead of reading files randomly, AI gets **structural wisdom first, then specifics**.

## Macro → Micro Exploration

Prism enables a natural exploration flow:

**Macro Level (Bird's Eye View)**
- "Show me the overall architecture"
- "What are the main components and how do they interact?"
- "Where does authentication fit in the system?"

**Middle Level (Connections)**
- "What files handle user authentication?"
- "How does data flow from API to database?"
- "Which components depend on this module?"

**Micro Level (Implementation)**
- "Show me the actual login function"
- "What's the specific error handling logic?"
- "Read the complete source for these 3 files"

At each level, Prism tells AI **what to look at next** for deeper understanding.

## Quick Install for Claude Code

### Step 1: Get a Free API Key (30 seconds)

Prism works with **17+ LLM providers**, including several **free options** (no credit card needed):

**Recommended: Groq (Free & Fast)**
- 500K-1M tokens/day free
- 10-100x faster than most providers
- Sign up: https://console.groq.com

```bash
export GROQ_API_KEY="gsk-..."
```

**Other free options:**
- **Cerebras**: https://inference.cerebras.ai (1M tokens/day)
- **SambaNova**: https://community.sambanova.ai (free tier + $5 credits)

**Paid options (higher quality):**
- **Anthropic (Claude)**: https://console.anthropic.com (highest quality)
- **OpenAI (GPT-4o)**: https://platform.openai.com

**See [LLM_SETUP.md](LLM_SETUP.md) for complete guide with all 17+ providers.**

### Step 2: Install Prism

Add this to your Claude Code MCP config (`~/.claude/config.json` or use `/config` command):

```json
{
  "mcpServers": {
    "prism": {
      "command": "uvx",
      "args": ["code-prism"],
      "env": {
        "GROQ_API_KEY": "your-groq-key-here"
      }
    }
  }
}
```

**Or use Claude's built-in command:**
```bash
claude mcp add prism --env GROQ_API_KEY=your-key -- uvx code-prism
```

That's it! Claude Code will automatically:
- Install Prism via `uvx`
- Auto-detect your LLM provider (tries free providers first!)
- Run in your current working directory
- Each project gets its own config in `.zdeps_cache/`

**Note:** Prism auto-detects available providers. Set any of these env vars and it'll work:
- `GROQ_API_KEY`, `CEREBRAS_API_KEY`, `SAMBANOVA_API_KEY` (free)
- `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY` (paid)

## How It Works

Instead of just searching code or reading files, Prism provides:

### 🎯 Structural Understanding
AI can see how your codebase is organized:
- What are the entry points (where execution begins)?
- Which files import this module?
- What does this file depend on?
- How does code flow from user request to response?

### 🧠 AI-Powered Analysis
Ask high-level questions and get architectural answers:
- "How does authentication work in this system?"
- "Where is caching implemented and why?"
- "What's the error handling strategy?"
- "How do these components communicate?"

### 📚 Smart File Recommendations
Instead of guessing which files to read, AI gets guidance:
- See code snippets in context
- Get ranked list of files that answer your question
- Choose to read full source only for what matters

### 🗺️ Multiple Exploration Modes
Different tools for different levels of understanding:
- **Query the structure** - Get the lay of the land
- **Ask questions** - Understand patterns and architecture
- **Read strategically** - Only dive deep where it matters

## Example Workflows

### Understanding a New Codebase
```
You: "I need to understand how authentication works"
Claude uses Prism to:
1. Map out auth-related files and their relationships
2. Explain the high-level authentication flow
3. Identify the 3-4 key files you should read
4. Show you those files with full context
```

### Debugging a Complex Issue
```
You: "Users are getting intermittent 500 errors on checkout"
Claude uses Prism to:
1. Trace the checkout flow from API to database
2. Identify error handling at each layer
3. Find where exceptions might go unhandled
4. Point you to the specific problematic code
```

### Planning a Feature
```
You: "I want to add rate limiting"
Claude uses Prism to:
1. Show where API requests are handled
2. Identify existing middleware patterns
3. Find similar features (like auth) for reference
4. Suggest where rate limiting should be inserted
```

## What Makes Prism Different

**Traditional code search:** Find where "login" appears → read all those files → try to piece together understanding

**Prism approach:** Understand the authentication system architecture → see how components connect → identify the core files → read those strategically

It's the difference between:
- **Bottom-up** (random access, tunnel vision, local understanding)
- **Top-down** (hierarchical, bird's eye view, global understanding)


### LLM Provider Configuration

Prism supports **17+ LLM providers** via LiteLLM. Set any of these environment variables:

**Free Providers (No Credit Card):**
- `GROQ_API_KEY` - Groq (recommended: 500K-1M tokens/day, blazing fast)
- `CEREBRAS_API_KEY` - Cerebras (1M tokens/day, wafer-scale inference)
- `SAMBANOVA_API_KEY` - SambaNova (free tier + $5 credits)

**Paid Providers (Higher Quality):**
- `ANTHROPIC_API_KEY` - Claude (highest quality code understanding)
- `OPENAI_API_KEY` - GPT-4o (solid all-around)
- `GEMINI_API_KEY` - Google Gemini (fast, cost-effective)
- `XAI_API_KEY` - Grok (large context windows)

**Advanced:**
- `PRISM_LLM_PROVIDER` - Manually specify provider (e.g., "groq", "openai")
- `PRISM_PROJECT_ROOT` - Override project root detection

**Auto-Detection:** Prism automatically uses the first available provider, prioritizing free options. No manual configuration needed!

**Complete Guide:** See [LLM_SETUP.md](LLM_SETUP.md) for detailed setup, all providers, cost comparison, and troubleshooting.

### Multi-Project Support

The MCP server is installed **globally** but works with **multiple projects**:

- Each Claude Code session runs in its working directory (e.g., your project folder)
- Prism uses the current working directory as the project root
- Config and cache are stored in `{working_directory}/.zdeps_cache/`
- Multiple agents can run simultaneously, each analyzing their own project
- No conflicts between different projects

**Example**: If you have Claude Code open in `/Users/you/project-a` and `/Users/you/project-b`, each gets:
- Separate config: `/Users/you/project-a/.zdeps_cache/config.json` and `/Users/you/project-b/.zdeps_cache/config.json`
- Separate cache: `/Users/you/project-a/.zdeps_cache/semantic_cache.json` and `/Users/you/project-b/.zdeps_cache/semantic_cache.json`
- One shared MCP server handling both

**Advanced**: You can manually override the project root with `PRISM_PROJECT_ROOT` environment variable if needed, but this is not necessary for Claude Code users.

## Tools Available to AI

Prism exposes these capabilities:

- **`query_codebase`** - Explore any part of the codebase with AI understanding
- **`query_snapshot_batch`** - Ask multiple related questions at different levels
- **`preview_snapshot`** - Check scope before exploring (how many files, tokens, etc.)
- **`get_dependency_info`** - Quick lookup of structural relationships
- **`list_entry_points`** - See where execution begins in your project

## Features

### 🔍 Hierarchical Exploration
Understand systems from top to bottom:
- Start with architecture and patterns
- Drill down through layers
- See connections between components
- Follow execution flows

### 🤖 Intelligent Questioning
Ask conceptual questions, get architectural answers:
- No need to know file names
- Focus on what/how/why, not where
- Get explanations with supporting code
- Understand patterns across the codebase

### ⚡ Exploration Efficiency
Don't read everything, read what matters:
- AI learns which files are important
- Skip boilerplate and focus on logic
- Get recommendations at each level
- Build understanding incrementally

### 📁 Context-Aware File Reading
When you do read files, understand why they matter:
- See how files fit in the bigger picture
- Understand what calls them and what they call
- Know their role in the architecture
- Read with full context, not in isolation

### 🌐 Flexible LLM Support
Works with any LLM provider you choose:
- **Free options**: Groq, Cerebras, SambaNova (no credit card!)
- **Paid options**: Claude, GPT-4o, Gemini, Grok, and 10+ more
- **Auto-detection**: Just set an API key, Prism handles the rest
- **Local support**: Run Ollama for 100% private, offline analysis

## Supported Languages

Currently optimized for Python projects. The structural analysis works for any language, but AI-powered understanding is best with Python.
