README.md

metadata

title: RepoAnalyzer
emoji: ⚡
colorFrom: yellow
colorTo: purple
sdk: docker
pinned: false
short_description: analyze repo and provide documentation about repo

RepoAnalyzer 🧙‍♂️

AI-powered code documentation and search agent — paste a GitHub URL, get professional docs in seconds.

---

What It Does

RepoAnalyzer takes any public GitHub repository, reads every Python file, and automatically generates clean human-readable documentation using AI. It also lets developers search the codebase in plain English — no more digging through files manually.

Core features:

• Generates documentation for every file in a repo with one click
• Answers natural language questions about the codebase
• Semantic search powered by FAISS vector embeddings
• Download individual file docs or all docs as a ZIP
• Auto-generates README.md and .gitignore for any project

---

Tech Stack

Layer	Technology
Backend	Python 3.10+, FastAPI, Uvicorn
LLM	OpenRouter API (qwen/qwen3-coder:free)
Embeddings	sentence-transformers (all-MiniLM-L6-v2)
Vector Search	FAISS (faiss-cpu)
Code Parsing	Python AST (built-in)
GitHub Access	GitHub REST API v3
Frontend	React 18, Vite, Tailwind CSS
File Handling	JSZip (client-side ZIP generation)

Total cost to run: $0 — all free tier services, no credit card required.

---

Project Structure

RepoAnalyzer/
├── backend/
│   ├── main.py              # FastAPI app, all API endpoints
│   ├── doc_generator.py     # OpenRouter API calls, doc generation logic
│   ├── parser.py            # AST-based Python code parser
│   ├── vector_store.py      # FAISS index creation and semantic search
│   ├── github_client.py     # GitHub API, repo file fetching
│   └── requirements.txt     # Python dependencies
├── frontend/
│   └── src/
│       ├── App.jsx          # Main React component, full UI
│       └── components/      # UI sub-components
├── faiss_indexes/           # Auto-generated, gitignored
├── .env                     # Your API keys, gitignored
├── .env.example             # Template for environment variables
├── .gitignore
└── README.md

---

Prerequisites

Make sure these are installed on your machine before starting:

• Python 3.10+
• Node.js 18+
• Git

---

Installation

1. Clone the repository

git clone https://github.com/yourusername/repoanalyzer.git
cd repoanalyzer

2. Get your API keys

OpenRouter API key (free, no credit card):

1. Go to openrouter.ai
2. Sign up → Profile → Keys → Create Key
3. Copy the key (starts with sk-or-...)

GitHub Personal Access Token (free):

1. Go to GitHub → Settings → Developer settings
2. Personal access tokens → Tokens (classic) → Generate new token
3. Check only the repo scope → Generate → Copy the token (starts with ghp_...)

3. Set up environment variables

cp .env.example .env

Open .env and fill in your keys:

OPENROUTER_API_KEY=sk-or-your-key-here
GITHUB_TOKEN=ghp_your-token-here
LLM_MODEL=qwen/qwen3-coder:free

4. Install backend dependencies

cd backend
pip install "numpy<2"
pip install -r requirements.txt

Windows note: If faiss-cpu fails to install, run pip install faiss-cpu --prefer-binary instead.

5. Install frontend dependencies

cd ../frontend
npm install

---

Running the App

You need two terminals open simultaneously.

Terminal 1 — Backend:

cd backend
uvicorn main:app --reload

Backend runs at http://127.0.0.1:8000

Terminal 2 — Frontend:

cd frontend
npm run dev

Frontend runs at http://localhost:5173

Open http://localhost:5173 in your browser.

---

How to Use

1. Paste any public GitHub repository URL into the input field
   • Example: https://github.com/tiangolo/fastapi
2. Click Generate Docs and wait 10–30 seconds
3. Documentation appears for every Python file in the repo
4. Click any file card to expand and read its docs
5. Use the Copy or Download .md button on each card
6. Click Download All as ZIP to get everything at once
7. Type a question in the search bar to query the codebase
   • Example: "How do I handle authentication?"
8. Click Generate README to create a README for that repo
9. Click Generate .gitignore for a project-specific gitignore

---

API Endpoints

Method	Endpoint	Description
POST	/generate-docs	Generate docs for a GitHub repo
POST	/ask	Ask a natural language question
POST	/generate-readme	Generate a README.md for the repo
POST	/generate-gitignore	Generate a .gitignore for the repo

Example request:

curl -X POST http://localhost:8000/generate-docs \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/tiangolo/fastapi"}'

---

Environment Variables

Variable	Description	Required
OPENROUTER_API_KEY	Your OpenRouter API key	Yes
GITHUB_TOKEN	GitHub personal access token	Yes
LLM_MODEL	Model to use (default: qwen/qwen3-coder:free)	No

---

Known Limitations

• Free tier rate limits: OpenRouter free tier allows 50 requests/day and 20 requests/minute. RepoAnalyzer batches all files into one request to stay within this limit.
• Python only: The AST parser currently supports Python files only. JavaScript and other languages are planned for a future update.
• Public repos only: Private repositories require additional GitHub token scopes.
• Context window: Very large repos (100+ files) may exceed the model's context window. RepoAnalyzer will document as many files as fit.

---

Troubleshooting

uvicorn main:app --reload gives NumPy error:

pip install "numpy<2" --force-reinstall

Search returns 0 results: Generate docs first before searching — the search index is built during doc generation.

Rate limit error but OpenRouter shows 0 requests: Your .env file is not being loaded. Make sure load_dotenv() is called at the top of doc_generator.py and your .env file is in the backend/ folder.

npm run dev fails: Make sure you ran npm install inside the frontend/ folder first.

---

Roadmap

• JavaScript / TypeScript support
• Private repository support
• GitHub Action for auto-updating docs on push
• Change detection — only re-document modified files
• Architecture diagram generation
• Multi-language support (Java, Go, Rust)

---

License

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

---

Acknowledgements

• OpenRouter for free LLM access
• FAISS by Meta for vector search
• sentence-transformers for local embeddings
• FastAPI for the backend framework