Metadata-Version: 2.4
Name: gitputra
Version: 0.3.2
Summary: Gitputra is an AI-powered CLI tool designed to analyze, chat with, and visualize local or remote repositories using RAG-based pipelines, automated technical audits, and interactive 3D architectural maps. Run 'gitputra info' to see all commands and features.
Author-email: Adityava Gangopadhyay <adityava49cse@gmail.com>
License: MIT
Project-URL: Homepage, https://pypi.org/project/gitputra/
Project-URL: LinkedIn, https://www.linkedin.com/in/adityava-gangopadhyay
Keywords: cli,ai,github,code-analysis,developer-tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click<9.0,>=8.1
Requires-Dist: python-dotenv<2.0,>=1.0
Requires-Dist: gitpython<4.0,>=3.1
Requires-Dist: chromadb>=1.0
Requires-Dist: reportlab<5.0,>=4.0
Requires-Dist: google-generativeai>=0.5
Requires-Dist: pyvis<1.0,>=0.3
Requires-Dist: openai<2.0,>=1.0
Requires-Dist: pdfplumber<1.0,>=0.9
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: tree-sitter-c>=0.24.2
Requires-Dist: tree-sitter-cpp>=0.23.4
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-rust>=0.24.2
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: rich<14.0,>=13.0
Requires-Dist: rank-bm25>=0.2

# 🔍 GitPutra

<p align="center">
  <img src="https://i.ibb.co/s9VWC1qL/image.png" alt="GitPutra Logo" width="200"/>
</p>

<p align="center">
  <img src="https://img.shields.io/pypi/v/gitputra?color=blue&label=PyPI&logo=pypi&logoColor=white" alt="PyPI Version">
  <img src="https://img.shields.io/pypi/pyversions/gitputra?color=blue&logo=python&logoColor=white" alt="Python Versions">
  <img src="https://static.pepy.tech/badge/gitputra" alt="Downloads">
  <img src="https://img.shields.io/pypi/l/gitputra?color=yellow" alt="License">
  <img src="https://img.shields.io/badge/AI-Gemini%20%7C%20OpenAI%20%7C%20Ollama-blueviolet?logo=openai&logoColor=white" alt="AI Providers">
</p>

<p align="center">
  <b>◈ Analyze ◈ Visualize ◈ Synthesize ◈</b><br><br>
  Clone any repo, generate a structured analysis report, visualize architecture,<br>
  export codebase context for any AI tool, and chat with your codebase — all from the terminal.<br><br>
  <i>Turn any repository or local codebase into AI memory.</i>
</p>

---

## ✨ Features

**🔍 See Beyond the Code** — Turn any repository into a fully mapped system — architecture, patterns, flaws, and opportunities laid bare.

**🧠 Export the Brain of Your Project** — Switched AI tools? Export the full project context — function inventory, module dependency graph, and function-level call graph — into a single Markdown file, ready to paste into any AI chat.

**💬 Talk to Your Codebase** — Ask anything. Get answers grounded in context, not guesses, powered by RAG and semantic search.

**💾 Chat Sessions** — Save and resume conversations. Your chat history persists across sessions so you can pick up exactly where you left off.

**🌌 3D Code Galaxy** — Explore your repo as an interactive 3D architecture map in the browser. Each file is a node; call relationships are edges.

**🔀 AI-Powered Diff** — Compare any two branches or commits and get an AI-written summary of what changed and why it matters.

**🌿 Git Timeline** — Visualize the branch history of any local or remote repo right in the terminal.

**🤖 Choose Your Intelligence** — Switch effortlessly between Google Gemini, OpenAI, or a locally running Ollama model — no cloud required.

**📊 Rich Diagrams** — Interactive HTML call graphs (full, cross-module, module-level) powered by pyvis, plus Mermaid diagrams in multiple types — all saved to `output/`.

**☢️ Nuclear Reset** — One command to rule them all. Wipe your vector database, all session history, and file hashes to start from a clean slate.

**💾 Robust Session Management** — Save, list, show, and resume conversations. Resume a session and GitPutra will intelligently re-index only the files that changed while you were away.

**📄 Multilingual PDF Reports** — Export analysis as a styled PDF in ~110 languages.

**🌐 Offline Context Export** — No API key required. The functionality graph, call map, and file tree are built entirely offline using Tree-sitter AST parsing.

**🗂️ Smart Indexing** — Skips re-embedding if a repo is already indexed. Run `clear-db` to reset.

**📁 50+ File Types** — From Python to Rust, configs to notebooks — your entire stack, decoded.

---

## 📦 Installation

```bash
pip install gitputra
```

Requires **Python 3.10+**

---

## 🗺️ Commands at a Glance

```bash
gitputra info
```
| Command | Description |
|---|---|
| `info` | Show all commands, AI providers, languages, and extensions |
| `analyze` | Clone & analyze a repo, generate report + diagrams |
| `chat` | RAG-powered interactive chat with a codebase |
| `export-context` | Export portable `.md` context file (offline by default) |
| `visualize` | Generate an interactive 3D Code Galaxy |
| `diff` | Compare two branches/commits with optional AI summary |
| `show-graph` | Render git branch timeline in the terminal |
| `session` | Manage sessions: `--list`, `resume`, `--show`, or `--delete` |
| `clear-db` | Wipe the local ChromaDB index |
| `nuke` | ☢️ Wipe everything: DB, Sessions, and Hashes |

---

## 🚀 Usage

### `analyze` — Analyze a Repository

Clones (or reads) a repo, embeds it, runs an AI analysis, and saves a PDF report + interactive diagrams.

```bash
# Remote repo
gitputra analyze https://github.com/user/repo --ai gemini --key YOUR_API_KEY

# Local codebase
gitputra analyze ./my-project --ai gemini

# Analyze without AI (diagrams only, no report)
gitputra analyze https://github.com/user/repo

# Specific branch, different language, skip PDF
gitputra analyze https://github.com/user/repo --branch dev --ai openai --lang Bangla --no-pdf

# Custom output directory
gitputra analyze ./my-project --ai gemini --output-dir ./results

# With a local Ollama model
gitputra analyze ./my-project --ai ollama --ollama-model llama3
```

**Outputs saved to `./output/` (or `--output-dir`):**
- `report.pdf` — Full AI analysis report
- `diagram_full.html` — Interactive full call graph
- `diagram_crossmodule.html` — Cross-module call graph
- `diagram_modules.html` — Module dependency graph
- `mermaid_<type>.txt` — Mermaid diagram source (graph, flowchart, architecture, sequence, class)

---

### `chat` — Chat with a Repository

Interactive RAG chat grounded in your codebase. Reuses existing index if `analyze` was already run.

```bash
# Remote repo
gitputra chat https://github.com/user/repo --ai gemini --key YOUR_API_KEY

# Local codebase
gitputra chat ./my-project --ai gemini

# Specific branch
gitputra chat https://github.com/user/repo --branch feature/my-branch --ai gemini

# Save session on exit
gitputra chat ./my-project --ai gemini --save-session mysession

# Resume a saved session
gitputra chat ./my-project --ai gemini --load-session mysession

# With a local Ollama model
gitputra chat ./my-project --ai ollama --ollama-model mistral
```

```
💬 Chat mode [repo] — ask anything about the codebase. Type 'exit' to quit.

>>  What does main.py do?
>>  How is authentication handled?
>>  exit
```

**In-chat commands:**

| Command | Action |
|---|---|
| `exit` / `quit` / `q` | Exit chat (prompts to save session) |
| `!switch` | Reload `API_KEY` from `.env` (quota reset, history preserved) |
| `!save` | Snapshot the session immediately without exiting |

---

### `export-context` — Export Codebase Context

Exports your entire codebase as a single Markdown file to paste into any AI tool (ChatGPT, Gemini, Claude…) without re-explaining the project. **Fully offline by default.**

The export includes:
- **File tree** of the project
- **Tech stack detection** (languages, infra, package files)
- **Function inventory** — all functions extracted per module
- **Module dependency graph** — Mermaid + plain-text fallback
- **Function-level call graph** — cross-module calls + full call map
- **Per-file summaries** — AI-generated (with `--use-ai`) or function-list stats (offline)
- **Source snapshot** — truncated source for each file

```bash
# Current directory, fully offline
gitputra export-context

# Specific local path
gitputra export-context ./my-project

# With AI summaries
gitputra export-context ./my-project --use-ai --ai gemini --key YOUR_API_KEY

# With a local Ollama model
gitputra export-context ./my-project --use-ai --ai ollama --ollama-model llama3

# Remote repo (auto-detected from URL)
gitputra export-context https://github.com/user/repo --remote --ai gemini

# Remote repo, specific branch, with AI summaries
gitputra export-context https://github.com/user/repo --remote --branch dev --use-ai --ai gemini

# Path with spaces — wrap in quotes
gitputra export-context "C:\Users\you\My Project"
```

Output saved to `./output/context_<project_name>_<timestamp>.md`

**How to use:**
1. Open the `.md` file
2. Paste it into any AI chat
3. Say: *"Here is my codebase context. Read it and help me continue."*

---

### `visualize` — 3D Code Galaxy

Generates an interactive 3D visualization of your repo's architecture, explorable in the browser.

```bash
# Remote repo
gitputra visualize https://github.com/user/repo

# Local codebase
gitputra visualize ./my-project

# Easter egg: visualize GitPutra's own RAG pipeline
gitputra visualize --self-map

# Custom output directory
gitputra visualize ./my-project --output-dir ./results
```

---

### `diff` — Compare Branches or Commits

Shows changed files between any two refs, with an optional AI-written summary saved as PDF.

```bash
# Last commit vs its parent (local repo)
gitputra diff .

# Compare branches with AI summary
gitputra diff https://github.com/user/repo --base main --head dev --ai gemini --key YOUR_API_KEY

# Local repo, specific commits
gitputra diff ./my-project --base abc1234 --head def5678 --ai openai

# Skip PDF output
gitputra diff . --base main --head dev --ai gemini --no-pdf

# With a local Ollama model
gitputra diff ./my-project --base main --head dev --ai ollama --ollama-model phi3:mini
```

---

### `show-graph` — Git Branch Timeline

Renders the git commit/branch graph in the terminal.

```bash
# Current directory
gitputra show-graph

# Local repo
gitputra show-graph ./my-project

# Remote repo (clones first)
gitputra show-graph https://github.com/user/repo

# Limit commits shown per branch
gitputra show-graph ./my-project --max-commits 50
```

---

### 💾 Session Management
Manage your navigation logs with the new session suite:

```bash
# List all sessions with repo paths and turn counts
gitputra session --list

# Show the chat history of a specific session
gitputra session mysession --show

# Resume a session (auto-detects local codebase and syncs changes)
gitputra session mysession resume

# Delete a specific session 
gitputra session --delete mysession

#Use --all for a clean sweep
gitputra session --delete --all
```
---

### Other Commands

```bash
# Wipe the local ChromaDB index (forces full re-index on next run)
gitputra clear-db

# Check version
gitputra --version

# Show all info
gitputra info

#delete the DB & chats to start from start
gitputra nuke
```

---

## 🤖 AI Providers

| Flag | Provider | Text Model | Embedding Model |
|---|---|---|---|
| `--ai gemini` | Google Gemini | gemini-2.5-flash | gemini-embedding-001 |
| `--ai openai` | OpenAI | gpt-4o-mini | text-embedding-3-large |
| `--ai ollama` | Ollama (local) | `--ollama-model user_selected` *(default phi3:mini)* | nomic-embed-text |

### Setting Up Your API Key

**Option 1 — `.env` file (recommended):**
```env
API_KEY=your_api_key_here
```

**Option 2 — Secure interactive prompt:**
If no key is provided, GitPutra will prompt you at runtime — keeping your key out of shell history.

**Option 3 — CLI flag:**
```bash
gitputra analyze https://github.com/user/repo --key YOUR_API_KEY
```
> Avoid Option 3 in shared environments — CLI flags appear in shell history.

---

### 🦙 Using Ollama (Local, No API Key Required)

Ollama lets you run models entirely on your own machine — no internet, no API key, no cost.

**1. Install Ollama:** [ollama.com](https://ollama.com)

**2. Pull a model:**
```bash
ollama pull llama3
ollama pull mistral
ollama pull phi3:mini     # default if --ollama-model is omitted
ollama pull codellama
```

**3. Run GitPutra with Ollama:**
```bash
gitputra chat ./my-project --ai ollama --ollama-model llama3
gitputra analyze ./my-project --ai ollama --ollama-model mistral
```

> **Note:** Embeddings always use `nomic-embed-text` regardless of the `--ollama-model` you pass — only the chat/analysis model is overridden. Make sure `nomic-embed-text` is pulled: `ollama pull nomic-embed-text`.

> **Fallback:** If Ollama is unreachable (server not running), GitPutra will automatically fall back to Gemini using the `API_KEY` from your `.env`.

---

## 🧬 Call Graph Extraction (Tree-sitter AST)

The functionality graph and context export use a shared `call_extractor` module powered by **Tree-sitter** for precise AST-based extraction.

| Method | Languages |
|---|---|
| Tree-sitter (AST) | Python, JavaScript, TypeScript, JSX, TSX, C, C++ (`.cc`, `.cxx`), Go, Rust, Java |
| Regex fallback | Ruby, PHP, Swift, Kotlin, Scala, Lua, C#, Groovy, Perl, Shell/Bash |

> For Python, the stdlib `ast` module is used for maximum accuracy, with Tree-sitter as fallback on syntax errors.

---

## 🌍 Supported Languages (PDF Output)

GitPutra can generate PDF reports in ~110 languages across 3 scripts:

**Latin Script (~100 languages)**
English, French, Spanish, Portuguese, Italian, German, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Slovak, Hungarian, Romanian, Croatian, Serbian (Latin), Slovenian, Albanian, Lithuanian, Latvian, Estonian, Turkish, Azerbaijani, Uzbek, Kazakh (Latin), Turkmen, Indonesian, Malay, Filipino, Swahili, Zulu, Xhosa, Afrikaans, Yoruba, Igbo, Hausa, Somali, Kinyarwanda, Welsh, Irish, Basque, Catalan, Galician, Maltese, Icelandic, Faroese, Vietnamese, Hawaiian, Maori, Tok Pisin, Tswana, Shona, Sesotho, and more.

**Bangla Script:** Bangla, Assamese

**Devanagari Script:** Hindi, Marathi, Nepali, Sanskrit, Maithili, Konkani, Bodo, Dogri

```bash
gitputra analyze https://github.com/user/repo --ai gemini --lang Bangla
```

> AI response language depends on the chosen model's capability.

---

## 📁 Supported File Extensions (50+ types)

| Category | Extensions |
|---|---|
| Python | `.py`, `.ipynb` |
| C/C++ | `.c`, `.h`, `.cpp` |
| Web | `.js`, `.ts`, `.jsx`, `.tsx`, `.html`, `.css`, `.vue` |
| JVM | `.java`, `.kt`, `.kts`, `.scala`, `.groovy`, `.clj`, `.cljs` |
| Systems | `.go`, `.rs`, `.swift`, `.dart` |
| Scripting | `.sh`, `.bat`, `.ps1`, `.pl`, `.lua`, `.r`, `.m`, `.rb`, `.php`, `.coffee`, `.elm` |
| Config | `.json`, `.yaml`, `.yml`, `.xml`, `.toml`, `.ini`, `.cfg`, `.conf`, `.gradle`, `.makefile` |
| Docs | `.md`, `.txt`, `.log`, `.sql`, `.pdf` |
| Special | `Dockerfile`, `Makefile` |

---

## 👨‍💻 Author

**Adityava Gangopadhyay**

- 📧 Email: adityava49cse@gmail.com
- 🔗 LinkedIn: [adityava-gangopadhyay](https://www.linkedin.com/in/adityava-gangopadhyay)
- 📦 PyPI: [pypi.org/project/gitputra](https://pypi.org/project/gitputra/)

Feel free to reach out for any suggestions or issues!

---

*AI is ARTIFICIALLY Intelligent — YOU are NATURALLY WISE. Use the tool, but keep track of the correctness of the results it produces.*

**THANK YOU**

## 📄 License

MIT License — free to use, modify, and distribute.
