repoatlas-cli 0.2.0__tar.gz

repoatlas_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nishant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

repoatlas_cli-0.2.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: repoatlas-cli
+Version: 0.2.0
+Summary: Ask natural-language questions about any code repository — powered by local LLMs and ChromaDB. Zero server setup.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/yourusername/repolens
+Keywords: rag,llm,code-search,ollama,chromadb,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+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
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: httpx>=0.27
+Requires-Dist: chromadb>=0.6
+Requires-Dist: pyyaml>=6
+Provides-Extra: openai
+Requires-Dist: openai>=1.30; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.28; extra == "anthropic"
+Provides-Extra: groq
+Requires-Dist: groq>=0.9; extra == "groq"
+Provides-Extra: all
+Requires-Dist: openai>=1.30; extra == "all"
+Requires-Dist: anthropic>=0.28; extra == "all"
+Requires-Dist: groq>=0.9; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# RepoAtlas
+
+> Ask natural-language questions about any code repository — powered by local LLMs and ChromaDB. Runs fully offline. Zero server setup.
+
+```
+repoatlas init
+repoatlas index /path/to/myproject
+repoatlas ask "how does authentication work here?"
+```
+
+---
+
+## What it is
+
+RepoAtlas is a CLI tool that turns any code repository into a searchable knowledge base. Point it at a repo, index it once, then ask questions in plain English and get answers grounded in the actual code — not generic guesses.
+
+It combines **AST-based chunking**, **vector embeddings**, and a **local LLM** into a standard RAG (Retrieval-Augmented Generation) pipeline — running entirely on your own machine, with no data leaving your network.
+
+**No Postgres. No server. No connection strings.** ChromaDB stores everything in a local directory (`~/.repoatlas/chroma_db`) that just works.
+
+---
+
+## Why local-first?
+
+- **Privacy / compliance** — banking, defense, legal, and other regulated environments forbid sending proprietary code to cloud AI APIs. RepoAtlas works with zero network access by default.
+- **Air-gapped environments** — cloud-based agents don't work here at all.
+- **No API costs** — the default stack (Ollama + `nomic-embed-text` + `qwen2.5-coder:3b`) is entirely free.
+- Cloud providers (OpenAI, Anthropic, Groq) are available as opt-in backends for users with weaker hardware.
+
+---
+
+## How it works
+
+```
+Repo files
+    │
+    ▼
+[Chunker]        AST-based for .py (top-level functions & classes)
+                 Line-window (50 lines, 10-line overlap) for all other files
+    │
+    ▼
+[Embedder]       nomic-embed-text via Ollama → 768-dim vectors
+    │
+    ▼
+[ChromaDB]       Local embedded vector store — no server, just a directory
+    │
+    ▼  (at query time)
+[Retriever]      Embeds the question, cosine-similarity search → top-k chunks
+    │
+    ▼
+[LLM]            Chunks + question → prompt → grounded answer
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [Ollama](https://ollama.com/) (for local mode)
+
+That's it. ChromaDB is installed automatically as a Python dependency — no server setup needed.
+
+---
+
+## Installation
+
+```bash
+pip install repoatlas
+```
+
+For cloud provider support (optional):
+```bash
+pip install "repoatlas[openai]"
+pip install "repoatlas[anthropic]"
+pip install "repoatlas[groq]"
+pip install "repoatlas[all]"     # all cloud providers
+```
+
+---
+
+## Quickstart
+
+### 1. Run setup (first time only)
+
+```bash
+repoatlas init
+```
+
+This will:
+- Check that Ollama is installed and running
+- Pull the required models (`nomic-embed-text`, `qwen2.5-coder:3b`)
+- Confirm the ChromaDB storage path
+- Write `~/.repoatlas/config.yaml` so you never have to configure again
+
+### 2. Index a repository
+
+```bash
+repoatlas index /path/to/myproject
+```
+
+### 3. Ask questions
+
+```bash
+repoatlas ask "how does authentication work?"
+repoatlas ask "where is the database connection handled?"
+repoatlas ask "how do I add a new API endpoint?"
+```
+
+---
+
+## Usage
+
+### `repoatlas init`
+
+Interactive first-time setup. Checks Ollama, pulls models, writes config.
+
+```bash
+repoatlas init [--chroma-path PATH] [--chat-model MODEL] [--embed-model MODEL]
+```
+
+### `repoatlas index`
+
+```bash
+repoatlas index <repo_path> [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--reset` | off | Wipe entire ChromaDB collection before indexing |
+| `--chroma-path` | `~/.repoatlas/chroma_db` | ChromaDB storage directory |
+| `--embed-model` | `nomic-embed-text` | Ollama embedding model |
+
+### `repoatlas ask`
+
+```bash
+repoatlas ask <question> [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--repo` | (all repos) | Restrict retrieval to a specific repo path |
+| `--top-k` | 5 | Number of chunks to retrieve (1–20) |
+| `--provider` | `ollama` | `ollama` \| `openai` \| `anthropic` \| `groq` |
+| `--model` | provider default | Chat model override |
+| `--chroma-path` | `~/.repoatlas/chroma_db` | ChromaDB storage directory |
+| `--no-sources` | off | Hide source citations |
+
+---
+
+## Using cloud providers
+
+```bash
+# OpenAI
+export OPENAI_API_KEY=sk-...
+repoatlas ask "explain the auth flow" --provider openai --model gpt-4o
+
+# Anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+repoatlas ask "explain the auth flow" --provider anthropic
+
+# Groq (fast inference, free tier available)
+export GROQ_API_KEY=gsk_...
+repoatlas ask "explain the auth flow" --provider groq
+```
+
+---
+
+## Configuration
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `REPOATLAS_CHROMA_PATH` | ChromaDB storage path (default: `~/.repoatlas/chroma_db`) |
+| `REPOATLAS_PROVIDER` | Default LLM provider (`ollama`) |
+| `REPOATLAS_MODEL` | Default chat model |
+| `REPOATLAS_EMBED_MODEL` | Embedding model (default: `nomic-embed-text`) |
+| `OLLAMA_BASE_URL` | Ollama server URL (default: `http://localhost:11434`) |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `GROQ_API_KEY` | Groq API key |
+
+### Config file (`~/.repoatlas/config.yaml`)
+
+After running `repoatlas init`, settings are persisted here. Environment variables override the config file.
+
+```yaml
+chroma_path: ~/.repoatlas/chroma_db
+provider: ollama
+chat_model: qwen2.5-coder:3b
+embed_model: nomic-embed-text
+ollama_base_url: http://localhost:11434
+```
+
+---
+
+## Multiple repositories
+
+RepoAtlas can hold multiple repos in the same ChromaDB — use `--repo` when querying to restrict to one:
+
+```bash
+repoatlas index /path/to/project-a
+repoatlas index /path/to/project-b
+
+repoatlas ask "how does auth work?" --repo /path/to/project-a
+repoatlas ask "how does auth work?" --repo /path/to/project-b
+```
+
+---
+
+## Project structure
+
+```
+RepoAtlas/
+├── db/
+│   └── chroma.py       — ChromaDB client + collection helpers
+├── indexer/
+│   ├── chunker.py      — AST chunker (Python) + line-window fallback (all files)
+│   ├── embedder.py     — Ollama /api/embeddings wrapper
+│   └── ingestion.py    — Repo walker + indexing pipeline
+├── api/
+│   └── retriever.py    — ChromaDB cosine-similarity retrieval
+├── app/
+│   ├── providers.py    — Pluggable LLM backends (Ollama / OpenAI / Anthropic / Groq)
+│   └── rag.py          — RAG orchestration (retrieve → prompt → generate)
+├── cli/
+│   └── main.py         — Typer CLI (init, index, ask)
+└── tests/
+    ├── test_chunker.py  — Unit tests for chunking logic
+    └── test_retriever.py — Integration tests for retrieval
+```
+
+---
+
+## Running tests
+
+```bash
+# Unit tests (no Ollama required)
+pytest tests/test_chunker.py -v
+
+# Integration tests (requires Ollama running)
+pytest tests/ -v
+```
+
+---
+
+## Roadmap
+
+- [ ] Tree-sitter chunking for JS / Go / Rust / Java
+- [ ] `repoatlas search` — raw chunk retrieval without LLM
+- [ ] `repoatlas watch` — incremental re-indexing on file change
+- [ ] Web UI
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

repoatlas_cli-0.2.0/README.md

@@ -0,0 +1,258 @@
+# RepoAtlas
+
+> Ask natural-language questions about any code repository — powered by local LLMs and ChromaDB. Runs fully offline. Zero server setup.
+
+```
+repoatlas init
+repoatlas index /path/to/myproject
+repoatlas ask "how does authentication work here?"
+```
+
+---
+
+## What it is
+
+RepoAtlas is a CLI tool that turns any code repository into a searchable knowledge base. Point it at a repo, index it once, then ask questions in plain English and get answers grounded in the actual code — not generic guesses.
+
+It combines **AST-based chunking**, **vector embeddings**, and a **local LLM** into a standard RAG (Retrieval-Augmented Generation) pipeline — running entirely on your own machine, with no data leaving your network.
+
+**No Postgres. No server. No connection strings.** ChromaDB stores everything in a local directory (`~/.repoatlas/chroma_db`) that just works.
+
+---
+
+## Why local-first?
+
+- **Privacy / compliance** — banking, defense, legal, and other regulated environments forbid sending proprietary code to cloud AI APIs. RepoAtlas works with zero network access by default.
+- **Air-gapped environments** — cloud-based agents don't work here at all.
+- **No API costs** — the default stack (Ollama + `nomic-embed-text` + `qwen2.5-coder:3b`) is entirely free.
+- Cloud providers (OpenAI, Anthropic, Groq) are available as opt-in backends for users with weaker hardware.
+
+---
+
+## How it works
+
+```
+Repo files
+    │
+    ▼
+[Chunker]        AST-based for .py (top-level functions & classes)
+                 Line-window (50 lines, 10-line overlap) for all other files
+    │
+    ▼
+[Embedder]       nomic-embed-text via Ollama → 768-dim vectors
+    │
+    ▼
+[ChromaDB]       Local embedded vector store — no server, just a directory
+    │
+    ▼  (at query time)
+[Retriever]      Embeds the question, cosine-similarity search → top-k chunks
+    │
+    ▼
+[LLM]            Chunks + question → prompt → grounded answer
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [Ollama](https://ollama.com/) (for local mode)
+
+That's it. ChromaDB is installed automatically as a Python dependency — no server setup needed.
+
+---
+
+## Installation
+
+```bash
+pip install repoatlas
+```
+
+For cloud provider support (optional):
+```bash
+pip install "repoatlas[openai]"
+pip install "repoatlas[anthropic]"
+pip install "repoatlas[groq]"
+pip install "repoatlas[all]"     # all cloud providers
+```
+
+---
+
+## Quickstart
+
+### 1. Run setup (first time only)
+
+```bash
+repoatlas init
+```
+
+This will:
+- Check that Ollama is installed and running
+- Pull the required models (`nomic-embed-text`, `qwen2.5-coder:3b`)
+- Confirm the ChromaDB storage path
+- Write `~/.repoatlas/config.yaml` so you never have to configure again
+
+### 2. Index a repository
+
+```bash
+repoatlas index /path/to/myproject
+```
+
+### 3. Ask questions
+
+```bash
+repoatlas ask "how does authentication work?"
+repoatlas ask "where is the database connection handled?"
+repoatlas ask "how do I add a new API endpoint?"
+```
+
+---
+
+## Usage
+
+### `repoatlas init`
+
+Interactive first-time setup. Checks Ollama, pulls models, writes config.
+
+```bash
+repoatlas init [--chroma-path PATH] [--chat-model MODEL] [--embed-model MODEL]
+```
+
+### `repoatlas index`
+
+```bash
+repoatlas index <repo_path> [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--reset` | off | Wipe entire ChromaDB collection before indexing |
+| `--chroma-path` | `~/.repoatlas/chroma_db` | ChromaDB storage directory |
+| `--embed-model` | `nomic-embed-text` | Ollama embedding model |
+
+### `repoatlas ask`
+
+```bash
+repoatlas ask <question> [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--repo` | (all repos) | Restrict retrieval to a specific repo path |
+| `--top-k` | 5 | Number of chunks to retrieve (1–20) |
+| `--provider` | `ollama` | `ollama` \| `openai` \| `anthropic` \| `groq` |
+| `--model` | provider default | Chat model override |
+| `--chroma-path` | `~/.repoatlas/chroma_db` | ChromaDB storage directory |
+| `--no-sources` | off | Hide source citations |
+
+---
+
+## Using cloud providers
+
+```bash
+# OpenAI
+export OPENAI_API_KEY=sk-...
+repoatlas ask "explain the auth flow" --provider openai --model gpt-4o
+
+# Anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+repoatlas ask "explain the auth flow" --provider anthropic
+
+# Groq (fast inference, free tier available)
+export GROQ_API_KEY=gsk_...
+repoatlas ask "explain the auth flow" --provider groq
+```
+
+---
+
+## Configuration
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `REPOATLAS_CHROMA_PATH` | ChromaDB storage path (default: `~/.repoatlas/chroma_db`) |
+| `REPOATLAS_PROVIDER` | Default LLM provider (`ollama`) |
+| `REPOATLAS_MODEL` | Default chat model |
+| `REPOATLAS_EMBED_MODEL` | Embedding model (default: `nomic-embed-text`) |
+| `OLLAMA_BASE_URL` | Ollama server URL (default: `http://localhost:11434`) |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `GROQ_API_KEY` | Groq API key |
+
+### Config file (`~/.repoatlas/config.yaml`)
+
+After running `repoatlas init`, settings are persisted here. Environment variables override the config file.
+
+```yaml
+chroma_path: ~/.repoatlas/chroma_db
+provider: ollama
+chat_model: qwen2.5-coder:3b
+embed_model: nomic-embed-text
+ollama_base_url: http://localhost:11434
+```
+
+---
+
+## Multiple repositories
+
+RepoAtlas can hold multiple repos in the same ChromaDB — use `--repo` when querying to restrict to one:
+
+```bash
+repoatlas index /path/to/project-a
+repoatlas index /path/to/project-b
+
+repoatlas ask "how does auth work?" --repo /path/to/project-a
+repoatlas ask "how does auth work?" --repo /path/to/project-b
+```
+
+---
+
+## Project structure
+
+```
+RepoAtlas/
+├── db/
+│   └── chroma.py       — ChromaDB client + collection helpers
+├── indexer/
+│   ├── chunker.py      — AST chunker (Python) + line-window fallback (all files)
+│   ├── embedder.py     — Ollama /api/embeddings wrapper
+│   └── ingestion.py    — Repo walker + indexing pipeline
+├── api/
+│   └── retriever.py    — ChromaDB cosine-similarity retrieval
+├── app/
+│   ├── providers.py    — Pluggable LLM backends (Ollama / OpenAI / Anthropic / Groq)
+│   └── rag.py          — RAG orchestration (retrieve → prompt → generate)
+├── cli/
+│   └── main.py         — Typer CLI (init, index, ask)
+└── tests/
+    ├── test_chunker.py  — Unit tests for chunking logic
+    └── test_retriever.py — Integration tests for retrieval
+```
+
+---
+
+## Running tests
+
+```bash
+# Unit tests (no Ollama required)
+pytest tests/test_chunker.py -v
+
+# Integration tests (requires Ollama running)
+pytest tests/ -v
+```
+
+---
+
+## Roadmap
+
+- [ ] Tree-sitter chunking for JS / Go / Rust / Java
+- [ ] `repoatlas search` — raw chunk retrieval without LLM
+- [ ] `repoatlas watch` — incremental re-indexing on file change
+- [ ] Web UI
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

repoatlas_cli-0.2.0/api/retriever.py

@@ -0,0 +1,80 @@
+"""
+Vector retrieval — embeds a question and finds the most similar code chunks
+using ChromaDB cosine similarity. No SQL, no server.
+"""
+from typing import Optional
+
+import chromadb
+
+from indexer.embedder import get_embedding
+
+# --------------------------------------------------------------------------- #
+# Retrieval
+# --------------------------------------------------------------------------- #
+
+
+def retrieve(
+    question: str,
+    collection: chromadb.Collection,
+    repo_path: Optional[str] = None,
+    top_k: int = 5,
+    embed_model: Optional[str] = None,
+) -> list[dict]:
+    """
+    Embed *question* and return the *top_k* most similar chunks.
+
+    Parameters
+    ----------
+    question   : str — natural-language question from the user
+    collection : chromadb.Collection — the RepoAtlas chunks collection
+    repo_path  : str, optional — restrict results to a specific indexed repo
+    top_k      : int — number of chunks to return (default 5)
+    embed_model: str, optional — override the Ollama embedding model
+
+    Returns
+    -------
+    list of dicts, each with keys:
+        repo_path, file_path, chunk_type, name,
+        start_line, end_line, code, similarity
+    """
+    kwargs = {"model": embed_model} if embed_model else {}
+    q_embedding = get_embedding(question, **kwargs)
+
+    query_kwargs: dict = {
+        "query_embeddings": [q_embedding],
+        "n_results": top_k,
+        "include": ["documents", "metadatas", "distances"],
+    }
+
+    if repo_path:
+        query_kwargs["where"] = {"repo_path": repo_path}
+
+    try:
+        results = collection.query(**query_kwargs)
+    except Exception as exc:
+        # ChromaDB raises if collection is empty or top_k > collection size
+        msg = str(exc).lower()
+        if any(k in msg for k in ("no elements", "cannot query", "index not found", "greater than")):
+            return []
+        raise
+
+    docs  = results.get("documents",  [[]])[0]
+    metas = results.get("metadatas",  [[]])[0]
+    dists = results.get("distances",  [[]])[0]
+
+    chunks = []
+    for doc, meta, dist in zip(docs, metas, dists):
+        # cosine space: distance ∈ [0, 2], but in practice [0, 1] for normalised
+        # vectors. similarity = 1 − distance gives a clean 0–1 score.
+        chunks.append({
+            "repo_path":  meta.get("repo_path", ""),
+            "file_path":  meta.get("file_path", ""),
+            "chunk_type": meta.get("chunk_type", ""),
+            "name":       meta.get("name", ""),
+            "start_line": meta.get("start_line", 0),
+            "end_line":   meta.get("end_line", 0),
+            "code":       doc,
+            "similarity": round(1.0 - dist, 4),
+        })
+
+    return chunks