repomind-ai 0.1.0__tar.gz

repomind_ai-0.1.0/PKG-INFO

@@ -0,0 +1,313 @@
+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

repomind_ai-0.1.0/README.md

@@ -0,0 +1,291 @@
+# 🧠 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

repomind_ai-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "repomind-ai"
+version = "0.1.0"
+description = "Understand any GitHub repository with AI - analysis plus evidence-based agent chat."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "RepoMind" }]
+requires-python = ">=3.11"
+dependencies = [
+    "streamlit>=1.36",
+    "google-genai>=1.0",
+    "openai>=1.40",
+    "chromadb>=0.5",
+    "python-dotenv>=1.0",
+    "requests>=2.31",
+    "rich>=13.7",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "httpx>=0.27"]
+server = ["fastapi>=0.115", "uvicorn[standard]>=0.30"]
+
+[project.scripts]
+repomind = "repomind.cli.main:main"
+
+[tool.setuptools.packages.find]
+include = ["repomind*"]
+exclude = ["tests*", "docs*", "server*", "npm*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

repomind_ai-0.1.0/repomind/__init__.py

@@ -0,0 +1,3 @@
+"""RepoMind - AI-powered GitHub repository analysis and conversation."""
+
+__version__ = "0.1.0"

repomind_ai-0.1.0/repomind/agents/__init__.py

@@ -0,0 +1 @@
+"""Agent loop and tool registry for answering repository questions."""