Metadata-Version: 2.4
Name: repomind-ai
Version: 0.1.0
Summary: Understand any GitHub repository with AI - analysis plus evidence-based agent chat.
Author: RepoMind
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: streamlit>=1.36
Requires-Dist: google-genai>=1.0
Requires-Dist: openai>=1.40
Requires-Dist: chromadb>=0.5
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30; extra == "server"

# 🧠 RepoMind

**Understand any GitHub repository with AI.**

RepoMind is an AI-powered developer tool that analyzes any public GitHub
repository and lets you have an evidence-based conversation with it. Paste a
repository URL, and RepoMind clones it safely, understands its architecture,
tech stack, APIs, and database, generates a structured report — and then answers
your questions by actually searching and reading the code.

## Features

- **One-click repository analysis** — URL in, structured report out: overview,
  tech stack, file structure, entry points, architecture, data flow, important
  files, dependencies, APIs, database, setup guide, and AI insights.
- **Agent-style chat ("Ask RepoMind")** — not a single LLM call. The agent
  decides which tools to use (`search_repository`, `read_file`,
  `semantic_search`, `find_api_endpoints`, ...) and answers from real evidence,
  citing file paths and functions.
- **Semantic code retrieval** — code is chunked on function/class boundaries,
  embedded (Gemini or any OpenAI-compatible API), and stored in a persistent
  ChromaDB vector store, so large repositories are searched, not dumped into
  the model.
- **Smart filtering** — ignores `.git`, images, binaries, lock files, generated
  files, and oversized files; prioritizes README → configs → entry points →
  core source.
- **Hallucination-resistant** — if the repository has no evidence for a claim,
  RepoMind says so instead of inventing it.
- **Architecture diagram** — a Mermaid diagram generated from the detected
  entry points, API endpoints, and database usage.
- **Disk cache** — analyses are cached per commit SHA; re-opening the same
  repository is instant.
- **Safe by design** — repository code is never executed, installed, or passed
  to a shell; only read and analyzed.

## Architecture

```
Streamlit UI (app.py)
      │
      ▼
RepositoryAnalyzer (orchestrator)
      │  ┌──────────────────────┐
      ├──► github_client        │  URL validation, REST API metadata,
      │   └─────────────────────┘  safe shallow clone
      │  ┌──────────────────────┐
      ├──► analyzers/           │  deterministic: dependencies, entry
      │   └─────────────────────┘  points, API routes, DB code, ranking
      │  ┌──────────────────────┐
      ├──► retrieval/           │  code-aware chunker + ChromaDB store
      │   └─────────────────────┘  (embeddings)
      │  ┌──────────────────────┐
      └──► agents/              │  tool registry + ReAct-style loop
          └─────────────────────┘  (LLM function calling)
```

The **agent loop** works like this: the user question plus a system prompt
("answer only from repository evidence") is sent to the LLM along with the tool
schemas. The model returns a *function call*, the agent executes the real tool
against the local clone / vector store, feeds the result back, and repeats until
the model produces a final answer (capped at 8 iterations). Tools are plain
Python functions — adding a tool means adding one function and one schema entry.

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Desktop UI | Streamlit |
| Web UI | FastAPI + vanilla HTML/CSS/JS (Cobalt design system) |
| CLI | `repomind` console script, wrapped by an npm launcher (`npx repomind-ai`) |
| LLM | Google Gemini (default) **or** any OpenAI-compatible API (OpenAI, NVIDIA) via a pluggable client |
| Embeddings | Gemini embedding model (or `nvidia/nv-embed-v1` via the OpenAI client) |
| Vector store | ChromaDB (persistent, cosine similarity) |
| Repo access | GitHub REST API + shallow `git clone` (depth 1) |
| Config | `python-dotenv` + `.env` |

## Screenshots

_Screenshots to be added — run the app and capture the landing page, the report
tabs, and the chat view._

## Installation

Requires **Python 3.11+** and **Git** on your PATH.

```bash
# 1. Clone or download this repository
git clone https://github.com/your-username/repomind.git
cd repomind

# 2. Create a virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Linux/macOS

pip install -e .

# 3. Configure environment
copy .env.example .env        # Windows
cp .env.example .env          # Linux/macOS
```

## Terminal CLI

RepoMind also runs in your terminal (published as `repomind-ai`; the command is `repomind`):

```bash
# One-time install via uv (installs Python for you if missing)
uv tool install repomind-ai

# Analyze a repository, then chat about it interactively
repomind https://github.com/psf/requests

# Or ask a single question and exit
repomind https://github.com/psf/requests --ask "where is authentication handled?"

# Once published to npm, no-install usage works too:
npx repomind-ai https://github.com/psf/requests
```

On first run the CLI asks for your Gemini or OpenAI key and saves it to
`~/.repomind/config.env`. Override providers/models with `--provider` and
`--model`.

## Website

A self-hostable web app built on FastAPI. It serves the same analyzer through a
job-based API and ships with a dependency-free static frontend.

```bash
# Install server extras and run locally
pip install -e ".[server]"
uvicorn server.main:app --reload
# open http://localhost:8000
```

API surface:

| Endpoint | Purpose |
|---|---|
| `POST /api/analyze` `{url, api_key?}` | Start an analysis job, returns `{job_id}` |
| `GET /api/jobs/{id}` | Poll status + current pipeline stage |
| `GET /api/report/{id}` | Full structured report (JSON) |
| `POST /api/ask` `{job_id, question, api_key?}` | Ask the agent; answers cite files |

**Hybrid key model:** visitors without a key use the server's shared key under
per-IP daily limits (`REPOMIND_DAILY_ANALYZES`, default 5; `REPOMIND_DAILY_QUESTIONS`,
default 40). Pasting your own Gemini/OpenAI key in the UI bypasses the limits;
keys stay in the browser session and are never persisted server-side.

## Deployment

The included `Dockerfile` builds one container that serves the frontend, API,
and worker threads (Python 3.12 slim + git).

**Deploy to Render / Fly.io / Railway:**

1. Push this repository to GitHub.
2. Create a Web Service from the repo — the host detects the Dockerfile
   (Render/Railway) or use `fly launch` (Fly.io).
3. Set environment variables on the host:
   - `GEMINI_API_KEY` (or `OPENAI_API_KEY` + `OPENAI_BASE_URL`) — the shared key
   - `GITHUB_TOKEN` (optional, raises GitHub API limits)
4. Deploy. The cache lives at `/tmp/repomind` inside the container and is
   disposable — a cold cache simply means the next analysis re-clones.

**Continuous delivery:** tagging a release (`git tag v0.1.0 && git push --tags`)
triggers `.github/workflows/publish.yml`, which publishes the Python package to
PyPI (trusted publishing) and the npm launcher to npmjs.com. One-time setup:
add the PyPI trusted publisher for this repo (workflow `publish.yml`,
environment `pypi`) and store an npm automation token as the `NPM_TOKEN`
secret. CI (pytest on Linux/macOS/Windows × Python 3.11/3.12) runs on every
push via `.github/workflows/ci.yml`.

## Environment Variables

| Variable | Required | Default | Purpose |
|----------|----------|---------|---------|
| `LLM_PROVIDER` | No | `gemini` | `gemini` or `openai` (OpenAI/NVIDIA-compatible) |
| `EMBEDDING_PROVIDER` | No | *(= `LLM_PROVIDER`)* | Override the embedding provider separately (e.g. NVIDIA embeddings + Gemini chat) |
| `GEMINI_API_KEY` | For Gemini | — | Free key from [aistudio.google.com](https://aistudio.google.com) |
| `OPENAI_API_KEY` | For OpenAI | — | OpenAI or NVIDIA (`nvapi-...`) key |
| `OPENAI_BASE_URL` | For NVIDIA | `https://api.openai.com/v1` | Set to `https://integrate.api.nvidia.com/v1` for NVIDIA |
| `OPENAI_MODEL` | No | `gpt-4o-mini` | Chat model for the OpenAI client |
| `OPENAI_EMBEDDING_MODEL` | No | `text-embedding-3-small` | Embeddings for the OpenAI client (NVIDIA: `nvidia/nv-embed-v1`) |
| `GITHUB_TOKEN` | No | — | Raises GitHub API rate limits (60/hr → 5000/hr) |
| `REPOMIND_CACHE_DIR` | No | `~/.repomind` | Where clones/reports/vectors persist |
| `REPOMIND_MAX_REPO_MB` | No | `500` | Max repository size |
| `REPOMIND_MAX_FILES` | No | `200` | Max files analyzed per repo |
| `REPOMIND_TOP_K` | No | `8` | Semantic search result count |
| `REPOMIND_DAILY_ANALYZES` | No | `5` | Website: per-IP daily analyses on the shared key |
| `REPOMIND_DAILY_QUESTIONS` | No | `40` | Website: per-IP daily questions on the shared key |

> **Note on free tiers:** Gemini's free tier works reliably for chat but limits
> embedding requests (`gemini-embedding-001`, ~100 requests/min). NVIDIA's free
> tier authenticates and provides embeddings (`nvidia/nv-embed-v1`) but chat
> completions time out. A practical combination: **Gemini for chat + NVIDIA for
> embeddings** — set `EMBEDDING_PROVIDER=openai` with the NVIDIA key/base URL.
> **OpenCode Zen** (`https://opencode.ai/zen/v1`, `sk-...` key) also works as an
> OpenAI-compatible chat provider — e.g. `OPENAI_MODEL=hy3-free` (free models
> are rate-limited per account). The OpenAI client is also fully usable with a
> paid OpenAI key.

## Running Locally

```bash
streamlit run app.py
```

Open the printed URL (default `http://localhost:8501`), paste a public GitHub
repository URL, and click **Analyze Repository**.

## Example Usage

1. Enter `https://github.com/psf/requests`
2. RepoMind clones it, builds the report (~1–3 min depending on repo size), and
   shows the tabs.
3. In **💬 Ask RepoMind**, try:
   - "What does this project do?"
   - "Where is authentication implemented?"
   - "Explain the architecture."
   - "Which database is being used?"
   - "What files should I read first if I'm new to this project?"

Answers cite evidence, e.g.:

> Authentication lives in `requests/auth.py` → `HTTPBasicAuth.__call__()`, which
> sets the `Authorization` header on each request.

If a claim cannot be supported by the repository, you'll see: *"I couldn't find
evidence for this in the repository."*

## Project Structure

```
├── app.py                       # Streamlit UI (desktop/local)
├── pyproject.toml               # packaging; console script `repomind`
├── Dockerfile                   # web deployment container
├── .github/workflows/           # CI (pytest) + publish (PyPI/npm)
├── repomind/
│   ├── config.py                # env vars, limits, paths
│   ├── github/github_client.py  # URL validation, API, safe clone
│   ├── analyzers/
│   │   ├── repository_analyzer.py  # orchestration, tree, ranking, mermaid
│   │   ├── dependency_analyzer.py  # manifests & tech stack
│   │   └── code_analyzer.py        # entry points, API routes, DB code
│   ├── retrieval/
│   │   ├── chunker.py           # code-aware chunking
│   │   └── vector_store.py      # ChromaDB persistence + search
│   ├── agents/repository_agent.py  # tool registry + agent loop + report
│   ├── cli/                     # terminal entry point (rich TUI)
│   ├── llm/gemini_client.py     # Gemini wrapper, retries, embeddings
│   └── utils/helpers.py         # logging, safe subprocess, file guards
├── server/
│   ├── main.py                  # FastAPI: analyze jobs, ask endpoint
│   ├── ratelimit.py             # per-IP daily limits (shared key)
│   └── static/                  # frontend (tokens.css / styles.css / app.js)
├── npm/                         # `npx repomind-ai` launcher (bootstraps uv)
├── tests/                       # pytest suite
└── docs/superpowers/specs/      # design specifications
```

## Testing

```bash
.venv\Scripts\python -m pytest -q
```

## Limitations

- Analyzes **public** repositories only (private repos are refused by design).
- Free-tier Gemini rate limits apply; a Pro model can be set via
  `REPOMIND_CHAT_MODEL`.
- Repos over 500 MB (configurable) are refused before cloning.
- Heuristic detection of API endpoints and database code covers common
  frameworks (FastAPI, Flask, Django, Express, Spring, etc.); exotic
  frameworks may be partially detected.
- Analysis time scales with repository size (bounded by `REPOMIND_MAX_FILES`).

## Future Improvements

- GitHub PR / commit-history analysis
- Code-quality and security-vulnerability scanning
- Repository comparison and developer-onboarding mode
- Automatic documentation generation
- "Explain this code like I'm a beginner" mode
- Deeper architecture visualization (per-module diagrams)

## License

MIT
