repoask 0.1.0__tar.gz

repoask-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: repoask
+Version: 0.1.0
+Summary: AI-powered repository assistant — ask questions about any codebase
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: pydantic>=2
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: chromadb>=0.5
+Requires-Dist: sentence-transformers>=3
+Requires-Dist: openai>=1
+Requires-Dist: anthropic>=0.28
+Requires-Dist: groq>=0.9
+Requires-Dist: pathspec>=0.12
+
+# RepoAsk
+
+Ask questions about any codebase using AI. RepoAsk indexes your repository with a RAG pipeline — chunking code by AST symbols, embedding them locally, and answering questions with citations to exact file paths and line numbers.
+
+No server, no database setup. Everything is stored as local files inside your project.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- An API key for at least one LLM provider (Groq, OpenAI, or Anthropic)
+
+---
+
+## Installation
+
+RepoAsk is a CLI tool — install it with `pipx` so it gets its own isolated environment and is available system-wide.
+
+```bash
+# Install pipx if you don't have it
+brew install pipx
+pipx ensurepath
+
+# Install repoask
+pipx install repoask
+```
+
+> **macOS / Homebrew users:** Do not use `pip install` directly — Homebrew manages its Python environment and will block it. `pipx` is the correct tool for installing Python CLI applications.
+
+**Alternative — manual venv (for development or local builds):**
+
+```bash
+python3 -m venv ~/.venvs/repoask
+source ~/.venvs/repoask/bin/activate
+pip install repoask
+```
+
+---
+
+## Quick Start
+
+**1. Configure your providers and API keys (once, globally)**
+
+```bash
+repoask init
+```
+
+This walks you through choosing an embedding provider and an LLM provider, then saves your config to `~/.repoask/config.toml`.
+
+**2. Index a repository**
+
+```bash
+cd /path/to/your/repo
+repoask index
+```
+
+RepoAsk scans all Python, JavaScript, and TypeScript files, extracts symbols (functions, classes, interfaces) using tree-sitter, generates embeddings, and stores everything locally under `.repoask/`.
+
+**3. Ask a question**
+
+```bash
+repoask ask "How does authentication work?"
+```
+
+Or start an interactive session:
+
+```bash
+repoask chat
+```
+
+---
+
+## Commands
+
+### `repoask init`
+Interactive setup wizard. Sets your embedding provider, LLM provider, models, and API keys. Saves to `~/.repoask/config.toml`.
+
+### `repoask index`
+Scans and indexes the current repository. Only re-indexes files that have changed since the last run (incremental by default).
+
+```bash
+repoask index           # incremental (default)
+repoask index --full    # force a complete re-index
+```
+
+### `repoask ask "<question>"`
+One-shot question. Retrieves relevant code chunks, builds context, and streams an answer.
+
+```bash
+repoask ask "Where is the database connection initialized?"
+repoask ask "What does the UserService class do?"
+repoask ask "How are API errors handled?" --top-k 15
+repoask ask "Show me all route handlers" --lang typescript
+```
+
+Options:
+- `--top-k N` — number of chunks to retrieve (default: 10)
+- `--lang LANG` — filter results to a specific language (`python`, `javascript`, `typescript`)
+
+### `repoask chat`
+Interactive multi-turn session. Maintains conversation context within the session and persists history to disk between sessions.
+
+```
+Commands inside chat:
+  /clear    clear the current session context
+  /quit     exit
+```
+
+Options:
+- `--top-k N` — number of chunks to retrieve per turn (default: 10)
+- `--no-history` — skip persisting this session to disk
+
+### `repoask status`
+Shows index statistics for the current repository.
+
+```
+Repository     /path/to/your/repo
+Index path     /path/to/your/repo/.repoask
+Embedding      huggingface / sentence-transformers/all-MiniLM-L6-v2
+LLM            groq / llama3-8b-8192
+Chunks         1,842
+Files indexed  74
+Last indexed   2026-06-22 14:30:01
+```
+
+### `repoask config`
+Displays the current global configuration with API keys masked.
+
+---
+
+## Supported Providers
+
+### Embedding
+| Provider | Models | Notes |
+|---|---|---|
+| `huggingface` | `sentence-transformers/all-MiniLM-L6-v2` (default) | Runs locally, no API key needed |
+| `openai` | `text-embedding-3-small`, `text-embedding-3-large` | Requires OpenAI API key |
+
+### LLM
+| Provider | Example Models | Notes |
+|---|---|---|
+| `groq` | `llama3-8b-8192`, `mixtral-8x7b-32768` | Fast, free tier available |
+| `openai` | `gpt-4o-mini`, `gpt-4o` | Requires OpenAI API key |
+| `anthropic` | `claude-haiku-4-5-20251001`, `claude-sonnet-4-6` | Requires Anthropic API key |
+
+---
+
+## Configuration
+
+Config is stored in TOML format. RepoAsk merges two config files in order:
+
+1. **Global** `~/.repoask/config.toml` — API keys and provider defaults, shared across all repos
+2. **Per-repo** `.repoask/config.toml` — overrides for a specific project (optional)
+
+### Full config reference
+
+```toml
+[embedding]
+provider = "huggingface"
+model = "sentence-transformers/all-MiniLM-L6-v2"
+api_key = ""
+
+[llm]
+provider = "groq"
+model = "llama3-8b-8192"
+api_key = "gsk_..."
+temperature = 0.2
+max_tokens = 2048
+
+[indexing]
+ignore_patterns = [
+    ".git", "node_modules", "__pycache__", "dist", "build",
+    ".venv", "venv", "*.lock", "*.min.js", "*.min.css",
+    "*.pyc", ".DS_Store", "coverage", ".next", ".nuxt",
+]
+max_file_size_kb = 500
+languages = ["python", "javascript", "typescript"]
+
+[store]
+path = ".repoask"
+```
+
+---
+
+## Local Index Files
+
+When you run `repoask index`, a `.repoask/` directory is created inside your repository:
+
+```
+.repoask/
+├── chroma/        # vector store (ChromaDB, file-based)
+├── tracker.db     # file hash registry for incremental indexing (SQLite)
+└── history.db     # chat session history (SQLite)
+```
+
+No external database or server is required. Add `.repoask/` to your `.gitignore` to avoid committing the index.
+
+```bash
+echo ".repoask/" >> .gitignore
+```
+
+---
+
+## How It Works
+
+1. **Scan** — traverses the repository, respecting `.gitignore` and configured ignore patterns
+2. **Chunk** — parses each file with tree-sitter and extracts symbols (functions, classes, interfaces) as individual chunks instead of fixed token windows
+3. **Embed** — converts each chunk to a vector embedding using your configured provider
+4. **Store** — saves chunks + embeddings + metadata (file path, symbol name, line numbers) to a local ChromaDB collection
+5. **Retrieve** — when you ask a question, it embeds the question and finds the most similar chunks via cosine similarity
+6. **Build context** — enriches the top-K hits with import-referenced definitions and assembles a structured context block
+7. **Answer** — sends the context + question to your LLM with a prompt that requires citations and disallows hallucination
+
+---
+
+## Tips
+
+- Run `repoask index` after pulling new changes — it only re-embeds what changed.
+- Use `--lang` to narrow answers when you know which part of the stack is relevant.
+- Increase `--top-k` for broad architectural questions; lower it for specific function lookups.
+- HuggingFace embedding (`all-MiniLM-L6-v2`) is free and fast enough for most repos. Switch to `text-embedding-3-small` if you want higher retrieval quality on large codebases.
+- Groq is the recommended LLM provider for speed and cost — the free tier is sufficient for most usage.

repoask-0.1.0/README.md

@@ -0,0 +1,223 @@
+# RepoAsk
+
+Ask questions about any codebase using AI. RepoAsk indexes your repository with a RAG pipeline — chunking code by AST symbols, embedding them locally, and answering questions with citations to exact file paths and line numbers.
+
+No server, no database setup. Everything is stored as local files inside your project.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- An API key for at least one LLM provider (Groq, OpenAI, or Anthropic)
+
+---
+
+## Installation
+
+RepoAsk is a CLI tool — install it with `pipx` so it gets its own isolated environment and is available system-wide.
+
+```bash
+# Install pipx if you don't have it
+brew install pipx
+pipx ensurepath
+
+# Install repoask
+pipx install repoask
+```
+
+> **macOS / Homebrew users:** Do not use `pip install` directly — Homebrew manages its Python environment and will block it. `pipx` is the correct tool for installing Python CLI applications.
+
+**Alternative — manual venv (for development or local builds):**
+
+```bash
+python3 -m venv ~/.venvs/repoask
+source ~/.venvs/repoask/bin/activate
+pip install repoask
+```
+
+---
+
+## Quick Start
+
+**1. Configure your providers and API keys (once, globally)**
+
+```bash
+repoask init
+```
+
+This walks you through choosing an embedding provider and an LLM provider, then saves your config to `~/.repoask/config.toml`.
+
+**2. Index a repository**
+
+```bash
+cd /path/to/your/repo
+repoask index
+```
+
+RepoAsk scans all Python, JavaScript, and TypeScript files, extracts symbols (functions, classes, interfaces) using tree-sitter, generates embeddings, and stores everything locally under `.repoask/`.
+
+**3. Ask a question**
+
+```bash
+repoask ask "How does authentication work?"
+```
+
+Or start an interactive session:
+
+```bash
+repoask chat
+```
+
+---
+
+## Commands
+
+### `repoask init`
+Interactive setup wizard. Sets your embedding provider, LLM provider, models, and API keys. Saves to `~/.repoask/config.toml`.
+
+### `repoask index`
+Scans and indexes the current repository. Only re-indexes files that have changed since the last run (incremental by default).
+
+```bash
+repoask index           # incremental (default)
+repoask index --full    # force a complete re-index
+```
+
+### `repoask ask "<question>"`
+One-shot question. Retrieves relevant code chunks, builds context, and streams an answer.
+
+```bash
+repoask ask "Where is the database connection initialized?"
+repoask ask "What does the UserService class do?"
+repoask ask "How are API errors handled?" --top-k 15
+repoask ask "Show me all route handlers" --lang typescript
+```
+
+Options:
+- `--top-k N` — number of chunks to retrieve (default: 10)
+- `--lang LANG` — filter results to a specific language (`python`, `javascript`, `typescript`)
+
+### `repoask chat`
+Interactive multi-turn session. Maintains conversation context within the session and persists history to disk between sessions.
+
+```
+Commands inside chat:
+  /clear    clear the current session context
+  /quit     exit
+```
+
+Options:
+- `--top-k N` — number of chunks to retrieve per turn (default: 10)
+- `--no-history` — skip persisting this session to disk
+
+### `repoask status`
+Shows index statistics for the current repository.
+
+```
+Repository     /path/to/your/repo
+Index path     /path/to/your/repo/.repoask
+Embedding      huggingface / sentence-transformers/all-MiniLM-L6-v2
+LLM            groq / llama3-8b-8192
+Chunks         1,842
+Files indexed  74
+Last indexed   2026-06-22 14:30:01
+```
+
+### `repoask config`
+Displays the current global configuration with API keys masked.
+
+---
+
+## Supported Providers
+
+### Embedding
+| Provider | Models | Notes |
+|---|---|---|
+| `huggingface` | `sentence-transformers/all-MiniLM-L6-v2` (default) | Runs locally, no API key needed |
+| `openai` | `text-embedding-3-small`, `text-embedding-3-large` | Requires OpenAI API key |
+
+### LLM
+| Provider | Example Models | Notes |
+|---|---|---|
+| `groq` | `llama3-8b-8192`, `mixtral-8x7b-32768` | Fast, free tier available |
+| `openai` | `gpt-4o-mini`, `gpt-4o` | Requires OpenAI API key |
+| `anthropic` | `claude-haiku-4-5-20251001`, `claude-sonnet-4-6` | Requires Anthropic API key |
+
+---
+
+## Configuration
+
+Config is stored in TOML format. RepoAsk merges two config files in order:
+
+1. **Global** `~/.repoask/config.toml` — API keys and provider defaults, shared across all repos
+2. **Per-repo** `.repoask/config.toml` — overrides for a specific project (optional)
+
+### Full config reference
+
+```toml
+[embedding]
+provider = "huggingface"
+model = "sentence-transformers/all-MiniLM-L6-v2"
+api_key = ""
+
+[llm]
+provider = "groq"
+model = "llama3-8b-8192"
+api_key = "gsk_..."
+temperature = 0.2
+max_tokens = 2048
+
+[indexing]
+ignore_patterns = [
+    ".git", "node_modules", "__pycache__", "dist", "build",
+    ".venv", "venv", "*.lock", "*.min.js", "*.min.css",
+    "*.pyc", ".DS_Store", "coverage", ".next", ".nuxt",
+]
+max_file_size_kb = 500
+languages = ["python", "javascript", "typescript"]
+
+[store]
+path = ".repoask"
+```
+
+---
+
+## Local Index Files
+
+When you run `repoask index`, a `.repoask/` directory is created inside your repository:
+
+```
+.repoask/
+├── chroma/        # vector store (ChromaDB, file-based)
+├── tracker.db     # file hash registry for incremental indexing (SQLite)
+└── history.db     # chat session history (SQLite)
+```
+
+No external database or server is required. Add `.repoask/` to your `.gitignore` to avoid committing the index.
+
+```bash
+echo ".repoask/" >> .gitignore
+```
+
+---
+
+## How It Works
+
+1. **Scan** — traverses the repository, respecting `.gitignore` and configured ignore patterns
+2. **Chunk** — parses each file with tree-sitter and extracts symbols (functions, classes, interfaces) as individual chunks instead of fixed token windows
+3. **Embed** — converts each chunk to a vector embedding using your configured provider
+4. **Store** — saves chunks + embeddings + metadata (file path, symbol name, line numbers) to a local ChromaDB collection
+5. **Retrieve** — when you ask a question, it embeds the question and finds the most similar chunks via cosine similarity
+6. **Build context** — enriches the top-K hits with import-referenced definitions and assembles a structured context block
+7. **Answer** — sends the context + question to your LLM with a prompt that requires citations and disallows hallucination
+
+---
+
+## Tips
+
+- Run `repoask index` after pulling new changes — it only re-embeds what changed.
+- Use `--lang` to narrow answers when you know which part of the stack is relevant.
+- Increase `--top-k` for broad architectural questions; lower it for specific function lookups.
+- HuggingFace embedding (`all-MiniLM-L6-v2`) is free and fast enough for most repos. Switch to `text-embedding-3-small` if you want higher retrieval quality on large codebases.
+- Groq is the recommended LLM provider for speed and cost — the free tier is sufficient for most usage.

repoask-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "repoask"
+version = "0.1.0"
+description = "AI-powered repository assistant — ask questions about any codebase"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    # CLI
+    "typer>=0.12",
+    "rich>=13",
+    # Config
+    "tomli>=2.0; python_version < '3.11'",
+    "tomli-w>=1.0",
+    "pydantic>=2",
+    # Parsing
+    "tree-sitter>=0.23",
+    "tree-sitter-python>=0.23",
+    "tree-sitter-javascript>=0.23",
+    "tree-sitter-typescript>=0.23",
+    # Vector store
+    "chromadb>=0.5",
+    # Embeddings
+    "sentence-transformers>=3",
+    "openai>=1",
+    "anthropic>=0.28",
+    "groq>=0.9",
+    # Gitignore handling
+    "pathspec>=0.12",
+]
+
+[project.scripts]
+repoask = "repoask.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]

repoask-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

repoask-0.1.0/src/repoask/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

repoask-0.1.0/src/repoask/chat/assistant.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+from ..providers.base import LLMProvider, Message
+from ..retrieval.context_builder import build_context
+from ..retrieval.retriever import Retriever
+from ..store.chroma import VectorStore
+
+SYSTEM_PROMPT = """\
+You are RepoAsk, an expert repository assistant.
+You answer questions about the codebase using ONLY the context provided below.
+When answering:
+- Cite the exact file path and line numbers from the context (e.g. `src/foo.py:42`).
+- If multiple functions are relevant, reference all of them.
+- If the answer cannot be found in the provided context, say: "I don't have enough context to answer that — try re-indexing or narrowing your question to a specific file."
+- Do NOT invent code or behaviour that is not present in the context.
+- Keep answers concise but complete. Use markdown code blocks for code snippets.
+"""
+
+
+class ChatSession:
+    """Holds the in-memory message history for a single interactive session."""
+
+    def __init__(
+        self,
+        llm: LLMProvider,
+        retriever: Retriever,
+        store: VectorStore,
+        history_db: Path | None = None,
+        top_k: int = 10,
+    ):
+        self._llm = llm
+        self._retriever = retriever
+        self._store = store
+        self._top_k = top_k
+        self._messages: list[Message] = []
+        self._history_db = history_db
+        self._session_id = str(int(time.time()))
+
+        if history_db:
+            self._init_history_db()
+
+    # ------------------------------------------------------------------ #
+    # Persistent history
+    # ------------------------------------------------------------------ #
+
+    def _init_history_db(self) -> None:
+        assert self._history_db
+        self._history_db.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(self._history_db))
+        self._conn.execute(
+            "CREATE TABLE IF NOT EXISTS messages "
+            "(id INTEGER PRIMARY KEY AUTOINCREMENT, "
+            "session_id TEXT, role TEXT, content TEXT, created_at REAL)"
+        )
+        self._conn.commit()
+
+    def _persist_message(self, message: Message) -> None:
+        if not self._history_db:
+            return
+        self._conn.execute(
+            "INSERT INTO messages (session_id, role, content, created_at) VALUES (?, ?, ?, ?)",
+            (self._session_id, message.role, message.content, time.time()),
+        )
+        self._conn.commit()
+
+    def load_last_session(self, n_messages: int = 10) -> None:
+        """Optionally seed RAM context with the tail of the previous session."""
+        if not self._history_db or not self._history_db.exists():
+            return
+        rows = self._conn.execute(
+            "SELECT role, content FROM messages "
+            "WHERE session_id = (SELECT session_id FROM messages ORDER BY created_at DESC LIMIT 1) "
+            "ORDER BY created_at DESC LIMIT ?",
+            (n_messages,),
+        ).fetchall()
+        for role, content in reversed(rows):
+            self._messages.append(Message(role=role, content=content))
+
+    # ------------------------------------------------------------------ #
+    # Core ask
+    # ------------------------------------------------------------------ #
+
+    def ask(self, question: str, stream: bool = True):
+        # 1. Retrieve relevant chunks
+        hits = self._retriever.retrieve(question, top_k=self._top_k)
+
+        # 2. Build context
+        context = build_context(hits, self._store, question)
+
+        # 3. Compose messages
+        user_content = f"## Retrieved context\n\n{context}\n\n## Question\n\n{question}"
+        user_msg = Message(role="user", content=user_content)
+        self._messages.append(user_msg)
+        self._persist_message(user_msg)
+
+        full_messages = [Message(role="system", content=SYSTEM_PROMPT)] + self._messages
+
+        # 4. Call LLM
+        if stream:
+            return self._stream_response(full_messages)
+        else:
+            response_text = self._llm.chat(full_messages, stream=False)
+            assistant_msg = Message(role="assistant", content=response_text)
+            self._messages.append(assistant_msg)
+            self._persist_message(assistant_msg)
+            return response_text
+
+    def _stream_response(self, messages: list[Message]):
+        chunks = []
+        for chunk in self._llm.chat(messages, stream=True):
+            chunks.append(chunk)
+            yield chunk
+        full_text = "".join(chunks)
+        assistant_msg = Message(role="assistant", content=full_text)
+        self._messages.append(assistant_msg)
+        self._persist_message(assistant_msg)
+
+    def clear(self) -> None:
+        self._messages.clear()