askmycode 0.1.0__py3-none-any.whl

askmycode/__init__.py

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

askmycode/cli.py

@@ -0,0 +1,324 @@
+import os
+from pathlib import Path
+
+import typer
+from google.genai.errors import ClientError, ServerError
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from google.genai import types as genai_types
+
+from askmycode import config, indexer, llm, manifest, project_config, retriever, store
+
+app = typer.Typer(
+    name="askmycode",
+    help="Ask questions about any codebase using AI — your code stays private.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def index(
+    path: Path = typer.Argument(Path("."), help="Path to the codebase to index"),
+) -> None:
+    """Scan and index a codebase so you can ask questions about it."""
+    path = path.resolve()
+    if not path.exists():
+        console.print(f"[red]Path does not exist:[/red] {path}")
+        raise typer.Exit(1)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+        transient=True,
+    ) as progress:
+        task = progress.add_task("Starting...", total=None)
+
+        def on_progress(msg: str) -> None:
+            progress.update(task, description=msg)
+
+        n_files, n_chunks = indexer.index_directory(path, progress_callback=on_progress)
+
+    if n_files == 0:
+        console.print("[yellow]No supported files found.[/yellow]")
+        raise typer.Exit(0)
+
+    console.print(f"[green]Indexed {n_files} files → {n_chunks} chunks[/green]  (.askmycode/)")
+    console.print('[dim]Now run:  askmycode ask "your question"[/dim]')
+
+
+@app.command()
+def ask(
+    question: str = typer.Argument(..., help="Question about your codebase"),
+    project: Path = typer.Option(Path("."), "--project", "-p", help="Path to the indexed project"),
+    n_results: int = typer.Option(8, "--results", "-n", help="Chunks to retrieve"),
+    sources: bool = typer.Option(False, "--sources", "-s", help="Show source files used to answer"),
+    provider: str = typer.Option("", "--provider", help="LLM provider: gemini, openai, anthropic, ollama"),
+    model: str = typer.Option("", "--model", help="Model name override"),
+) -> None:
+    """Ask a question about your indexed codebase."""
+    project = project.resolve()
+    pcfg = project_config.load(project)
+    provider = provider or pcfg["provider"] or config.get_provider()
+    model = model or pcfg["model"] or config.get_model()
+    n_results = n_results if n_results != 8 else pcfg["n_results"]
+
+    api_key = config.get_api_key(provider)
+    if not api_key and provider != "ollama":
+        console.print(f"[red]No API key found for provider '{provider}'.[/red]")
+        console.print(f"  [bold]export {provider.upper()}_API_KEY=your-key[/bold]")
+        console.print("  [bold]askmycode config set-key YOUR_KEY[/bold]")
+        raise typer.Exit(1)
+
+    if not (project / ".askmycode").exists():
+        console.print(f"[red]No index found.[/red]  Run first:")
+        console.print(f"  [bold]askmycode index {project}[/bold]")
+        raise typer.Exit(1)
+
+    with console.status("Searching codebase..."):
+        context, metadatas = retriever.retrieve(question, project, n_results=n_results)
+
+    if not context:
+        console.print("[yellow]No relevant code found for that question.[/yellow]")
+        raise typer.Exit(0)
+
+    file_tree = llm.build_file_tree(list(manifest.load(project).keys()))
+
+    console.print()
+    try:
+        for chunk in llm.answer_stream(
+            question, context, api_key or "", file_tree=file_tree,
+            provider=provider, model=model,
+        ):
+            console.print(chunk, end="")
+        console.print("\n")
+    except ClientError as e:
+        if "429" in str(e) or "RESOURCE_EXHAUSTED" in str(e):
+            console.print("\n[red]Quota exceeded.[/red] Your API key has no free tier quota.")
+            console.print("Get a fresh key at [bold]aistudio.google.com[/bold] → Get API key → Create API key in new project")
+            console.print("Then run: [bold]askmycode config set-key YOUR_NEW_KEY[/bold]")
+        elif "401" in str(e) or "API_KEY_INVALID" in str(e):
+            console.print("\n[red]Invalid API key.[/red] Run: [bold]askmycode config set-key YOUR_KEY[/bold]")
+        else:
+            console.print(f"\n[red]API error:[/red] {e}")
+        raise typer.Exit(1)
+    except ServerError as e:
+        console.print(f"\n[red]Gemini server error:[/red] {e}")
+        raise typer.Exit(1)
+
+    if sources and metadatas:
+        seen: set = set()
+        console.print("[dim]─── Sources ────────────────────────────[/dim]")
+        for m in metadatas:
+            key = (m.get("file_path", ""), m.get("start_line", ""))
+            if key in seen:
+                continue
+            seen.add(key)
+            console.print(f"[dim]  {m.get('file_path')}:{m.get('start_line')}–{m.get('end_line')}[/dim]")
+
+
+@app.command()
+def init(
+    path: Path = typer.Argument(Path("."), help="Project root to initialise"),
+) -> None:
+    """Set up askmycode for a project: update .gitignore and suggest first steps."""
+    path = path.resolve()
+
+    # Detect project type from marker files
+    markers: dict[str, list[str]] = {
+        "Python":     ["pyproject.toml", "setup.py", "requirements.txt"],
+        "Node/TS":    ["package.json"],
+        "Go":         ["go.mod"],
+        "Rust":       ["Cargo.toml"],
+        "Java/Kotlin":["pom.xml", "build.gradle", "build.gradle.kts"],
+        "Ruby":       ["Gemfile"],
+    }
+    detected = "Unknown"
+    for lang, files in markers.items():
+        if any((path / f).exists() for f in files):
+            detected = lang
+            break
+
+    # Ensure .askmycode/ is in .gitignore
+    gitignore = path / ".gitignore"
+    entry = ".askmycode/"
+    if gitignore.exists():
+        content = gitignore.read_text()
+        if entry not in content:
+            gitignore.write_text(content.rstrip() + f"\n{entry}\n")
+            console.print(f"[green]Added {entry} to .gitignore[/green]")
+        else:
+            console.print(f"[dim]{entry} already in .gitignore[/dim]")
+    else:
+        gitignore.write_text(f"{entry}\n")
+        console.print(f"[green]Created .gitignore with {entry}[/green]")
+
+    console.print(f"\n[bold]Detected project type:[/bold] {detected}")
+
+    # Suggested starter questions per language
+    suggestions: dict[str, list[str]] = {
+        "Python":     ["how is the project structured?", "where is the entry point?", "how are dependencies managed?"],
+        "Node/TS":    ["what does the main script do?", "how is routing handled?", "what testing framework is used?"],
+        "Go":         ["what is the main package?", "how is error handling done?", "where are the HTTP handlers?"],
+        "Rust":       ["what does the main function do?", "how are errors propagated?", "what external crates are used?"],
+        "Java/Kotlin":["what is the application entry point?", "how is the project layered?", "where are the models defined?"],
+        "Ruby":       ["what does the application do?", "how is routing set up?", "where is business logic?"],
+        "Unknown":    ["how is the project structured?", "what does this codebase do?", "where is the main entry point?"],
+    }
+    console.print("\n[bold]Suggested first questions:[/bold]")
+    for q in suggestions.get(detected, suggestions["Unknown"]):
+        console.print(f'  askmycode ask "{q}"')
+
+    console.print("\n[bold]Next steps:[/bold]")
+    console.print(f"  1. askmycode index {path}")
+    console.print(f'  2. askmycode ask "how is the project structured?"')
+
+
+@app.command()
+def chat(
+    project: Path = typer.Option(Path("."), "--project", "-p", help="Path to the indexed project"),
+    n_results: int = typer.Option(8, "--results", "-n", help="Chunks to retrieve per turn"),
+    provider: str = typer.Option("", "--provider", help="LLM provider: gemini, openai, anthropic, ollama"),
+    model: str = typer.Option("", "--model", help="Model name override"),
+) -> None:
+    """Start an interactive multi-turn chat session about your codebase."""
+    project = project.resolve()
+    pcfg = project_config.load(project)
+    provider = provider or pcfg["provider"] or config.get_provider()
+    model = model or pcfg["model"] or config.get_model()
+    n_results = n_results if n_results != 8 else pcfg["n_results"]
+
+    api_key = config.get_api_key(provider)
+    if not api_key and provider != "ollama":
+        console.print(f"[red]No API key found for provider '{provider}'.[/red]  Run: [bold]askmycode config set-key YOUR_KEY[/bold]")
+        raise typer.Exit(1)
+
+    if not (project / ".askmycode").exists():
+        console.print(f"[red]No index found.[/red]  Run: [bold]askmycode index {project}[/bold]")
+        raise typer.Exit(1)
+
+    console.print("[bold]askmycode chat[/bold] — type your question, [dim]exit[/dim] or Ctrl+C to quit.\n")
+
+    history: list[genai_types.Content] = []
+    file_tree = llm.build_file_tree(list(manifest.load(project).keys()))
+
+    while True:
+        try:
+            question = console.input("[bold cyan]You:[/bold cyan] ").strip()
+        except (KeyboardInterrupt, EOFError):
+            console.print("\n[dim]Bye.[/dim]")
+            break
+
+        if not question:
+            continue
+        if question.lower() in ("exit", "quit", "q"):
+            console.print("[dim]Bye.[/dim]")
+            break
+
+        with console.status("Searching codebase..."):
+            context, _ = retriever.retrieve(question, project, n_results=n_results)
+
+        if not context:
+            console.print("[yellow]No relevant code found for that question.[/yellow]\n")
+            continue
+
+        console.print("[bold green]Assistant:[/bold green] ", end="")
+        answer_parts: list[str] = []
+        try:
+            for chunk in llm.answer_stream(
+                question, context, api_key or "", history=history,
+                file_tree=file_tree, provider=provider, model=model,
+            ):
+                console.print(chunk, end="")
+                answer_parts.append(chunk)
+            console.print("\n")
+        except (ClientError, ServerError) as e:
+            console.print(f"\n[red]Error:[/red] {e}\n")
+            continue
+
+        # Append this turn to history for follow-up context
+        user_turn = f"Context:\n{context}\n\nQuestion: {question}"
+        history.append(llm._make_turn("user", user_turn))
+        history.append(llm._make_turn("model", "".join(answer_parts)))
+
+
+@app.command()
+def stats(
+    project: Path = typer.Option(Path("."), "--project", "-p", help="Path to the indexed project"),
+) -> None:
+    """Show index statistics for a project."""
+    import datetime
+    project = project.resolve()
+    index_path = project / ".askmycode"
+
+    if not index_path.exists():
+        console.print(f"[red]No index found.[/red]  Run: [bold]askmycode index {project}[/bold]")
+        raise typer.Exit(1)
+
+    mf = manifest.load(project)
+    client = store.get_client(project)
+    collection = store.get_collection(client)
+    n_chunks = collection.count()
+
+    last_modified = max((e["mtime"] for e in mf.values()), default=None)
+    last_indexed = (
+        datetime.datetime.fromtimestamp(last_modified).strftime("%Y-%m-%d %H:%M:%S")
+        if last_modified else "unknown"
+    )
+
+    console.print(f"[bold]Files indexed:[/bold]  {len(mf)}")
+    console.print(f"[bold]Total chunks:[/bold]   {n_chunks}")
+    console.print(f"[bold]Last indexed:[/bold]   {last_indexed}")
+    console.print(f"[bold]Index location:[/bold] {index_path}")
+
+
+_config_app = typer.Typer(help="Manage configuration.")
+app.add_typer(_config_app, name="config")
+
+
+@_config_app.command("set-key")
+def config_set_key(
+    api_key: str = typer.Argument(..., help="Your API key"),
+) -> None:
+    """Save your API key to ~/.config/askmycode/config.json."""
+    config.set_api_key(api_key)
+    console.print("[green]API key saved.[/green]")
+
+
+@_config_app.command("set-provider")
+def config_set_provider(
+    provider: str = typer.Argument(..., help="Provider: gemini, openai, anthropic, ollama"),
+) -> None:
+    """Set the default LLM provider."""
+    valid = {"gemini", "openai", "anthropic", "ollama"}
+    if provider not in valid:
+        console.print(f"[red]Unknown provider.[/red] Choose: {', '.join(sorted(valid))}")
+        raise typer.Exit(1)
+    config.set_provider(provider)
+    console.print(f"[green]Provider set to '{provider}'.[/green]")
+
+
+@_config_app.command("set-model")
+def config_set_model(
+    model: str = typer.Argument(..., help="Model name, e.g. gpt-4o, llama3, claude-opus-4-7"),
+) -> None:
+    """Set the default model name."""
+    config.set_model(model)
+    console.print(f"[green]Model set to '{model}'.[/green]")
+
+
+@_config_app.command("show")
+def config_show() -> None:
+    """Show current configuration."""
+    console.print(f"[bold]Provider:[/bold] {config.get_provider()}")
+    console.print(f"[bold]Model:[/bold]    {config.get_model() or '(default for provider)'}")
+    key = config.get_api_key(config.get_provider())
+    masked = (key[:8] + "..." + key[-4:]) if key and len(key) > 12 else ("(not set)" if not key else key)
+    console.print(f"[bold]API key:[/bold]  {masked}")
+
+
+if __name__ == "__main__":
+    app()

askmycode/config.py

@@ -0,0 +1,56 @@
+import json
+import os
+from pathlib import Path
+
+_CONFIG_DIR = Path.home() / ".config" / "askmycode"
+_CONFIG_FILE = _CONFIG_DIR / "config.json"
+
+_ENV_KEYS = {
+    "gemini": "GEMINI_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+}
+
+
+def _load() -> dict:
+    if _CONFIG_FILE.exists():
+        return json.loads(_CONFIG_FILE.read_text())
+    return {}
+
+
+def _save(data: dict) -> None:
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    _CONFIG_FILE.write_text(json.dumps(data, indent=2))
+
+
+def get_api_key(provider: str = "gemini") -> str | None:
+    env_var = _ENV_KEYS.get(provider, f"{provider.upper()}_API_KEY")
+    if key := os.environ.get(env_var):
+        return key
+    return _load().get("api_key")
+
+
+def set_api_key(key: str) -> None:
+    data = _load()
+    data["api_key"] = key
+    _save(data)
+
+
+def get_provider() -> str:
+    return os.environ.get("ASKMYCODE_PROVIDER") or _load().get("provider", "gemini")
+
+
+def set_provider(provider: str) -> None:
+    data = _load()
+    data["provider"] = provider
+    _save(data)
+
+
+def get_model() -> str:
+    return os.environ.get("ASKMYCODE_MODEL") or _load().get("model", "")
+
+
+def set_model(model: str) -> None:
+    data = _load()
+    data["model"] = model
+    _save(data)

askmycode/embedder.py

@@ -0,0 +1,26 @@
+import io
+import os
+import sys
+from functools import lru_cache
+
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+MODEL_NAME = "all-MiniLM-L6-v2"
+
+
+@lru_cache(maxsize=1)
+def _get_model():
+    # Import and load inside the function so we can suppress all stderr noise
+    # (HF Hub unauthenticated warning + tqdm progress bars) in one redirect.
+    old_stderr = sys.stderr
+    sys.stderr = io.StringIO()
+    try:
+        from sentence_transformers import SentenceTransformer
+        return SentenceTransformer(MODEL_NAME)
+    finally:
+        sys.stderr = old_stderr
+
+
+def embed(texts: list[str]) -> list[list[float]]:
+    model = _get_model()
+    return model.encode(texts, show_progress_bar=False).tolist()

askmycode/indexer.py

@@ -0,0 +1,180 @@
+import ast
+from pathlib import Path
+from typing import Callable, Optional
+
+import pathspec
+
+from askmycode import embedder, manifest, store
+
+_CODE_EXTENSIONS = {
+    ".py", ".js", ".ts", ".jsx", ".tsx", ".go", ".rs", ".java",
+    ".c", ".cpp", ".h", ".hpp", ".rb", ".php", ".swift", ".kt",
+    ".scala", ".sh", ".bash", ".yaml", ".yml", ".toml", ".json",
+    ".md", ".sql", ".css", ".html", ".vue", ".svelte",
+}
+_MAX_FILE_BYTES = 1024 * 1024  # 1 MB
+_CHUNK_LINES = 60
+_OVERLAP_LINES = 15
+_EMBED_BATCH = 64
+
+_DEFAULT_IGNORES = [
+    ".git", ".askmycode", "__pycache__", "node_modules",
+    ".venv", "venv", "dist", "build", ".next", "coverage",
+]
+
+
+def _load_gitignore(root: Path) -> pathspec.PathSpec:
+    patterns = list(_DEFAULT_IGNORES)
+    gitignore = root / ".gitignore"
+    if gitignore.exists():
+        patterns += gitignore.read_text().splitlines()
+    return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
+
+
+def _scan_files(root: Path) -> list[Path]:
+    spec = _load_gitignore(root)
+    files = []
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if path.suffix.lower() not in _CODE_EXTENSIONS:
+            continue
+        if path.stat().st_size > _MAX_FILE_BYTES:
+            continue
+        if spec.match_file(str(path.relative_to(root))):
+            continue
+        files.append(path)
+    return sorted(files)
+
+
+def _ast_chunks(content: str, lines: list[str], relative: str) -> list[dict] | None:
+    """Split a Python file at top-level function/class boundaries using AST.
+    Returns None if parsing fails (falls back to sliding window)."""
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return None
+
+    top_nodes = [
+        n for n in ast.walk(tree)
+        if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
+        and isinstance(getattr(n, "col_offset", -1), int) and n.col_offset == 0
+    ]
+    if not top_nodes:
+        return None
+
+    # Sort by line number and build boundary ranges
+    top_nodes.sort(key=lambda n: n.lineno)
+    boundaries: list[tuple[int, int]] = []
+    for i, node in enumerate(top_nodes):
+        start = node.lineno - 1
+        end = (top_nodes[i + 1].lineno - 2) if i + 1 < len(top_nodes) else len(lines)
+        boundaries.append((start, end))
+
+    # Module-level code before the first definition
+    if boundaries and boundaries[0][0] > 0:
+        boundaries.insert(0, (0, boundaries[0][0]))
+
+    chunks = []
+    for start, end in boundaries:
+        body = "\n".join(lines[start:end]).strip()
+        if body:
+            chunks.append({
+                "id": f"{relative}:{start}",
+                "content": f"# {relative}  (lines {start + 1}–{end})\n\n{body}",
+                "file_path": relative,
+                "start_line": start + 1,
+                "end_line": end,
+            })
+    return chunks or None
+
+
+def _sliding_chunks(lines: list[str], relative: str) -> list[dict]:
+    chunks = []
+    i = 0
+    while i < len(lines):
+        end = min(i + _CHUNK_LINES, len(lines))
+        body = "\n".join(lines[i:end]).strip()
+        if body:
+            chunks.append({
+                "id": f"{relative}:{i}",
+                "content": f"# {relative}  (lines {i + 1}–{end})\n\n{body}",
+                "file_path": relative,
+                "start_line": i + 1,
+                "end_line": end,
+            })
+        i += _CHUNK_LINES - _OVERLAP_LINES
+    return chunks
+
+
+def _chunk_file(path: Path, root: Path) -> list[dict]:
+    try:
+        content = path.read_text(encoding="utf-8", errors="ignore")
+    except Exception:
+        return []
+
+    lines = content.splitlines()
+    relative = str(path.relative_to(root))
+
+    if path.suffix == ".py":
+        result = _ast_chunks(content, lines, relative)
+        if result is not None:
+            return result
+
+    return _sliding_chunks(lines, relative)
+
+
+def index_directory(
+    root: Path,
+    progress_callback: Optional[Callable[[str], None]] = None,
+) -> tuple[int, int]:
+    def log(msg: str) -> None:
+        if progress_callback:
+            progress_callback(msg)
+
+    log("Scanning files...")
+    files = _scan_files(root)
+    current_relatives = {str(p.relative_to(root)) for p in files}
+
+    mf = manifest.load(root)
+    client = store.get_client(root)
+    collection = store.get_collection(client)
+
+    # Remove chunks for files that were deleted since last index
+    deleted = [rel for rel in mf if rel not in current_relatives]
+    if deleted:
+        log(f"Removing {len(deleted)} deleted file(s)...")
+        store.delete_by_files(collection, deleted)
+        for rel in deleted:
+            del mf[rel]
+
+    # Only process files that are new or changed
+    changed_files = [p for p in files if manifest.is_changed(p, mf, str(p.relative_to(root)))]
+    skipped = len(files) - len(changed_files)
+
+    if not changed_files:
+        log(f"Nothing changed — {len(files)} files already up to date.")
+        return len(files), 0
+
+    if skipped:
+        log(f"Skipping {skipped} unchanged file(s)...")
+
+    all_chunks: list[dict] = []
+    for i, path in enumerate(changed_files):
+        log(f"Reading ({i + 1}/{len(changed_files)})  {path.name}")
+        all_chunks.extend(_chunk_file(path, root))
+
+    if all_chunks:
+        for i in range(0, len(all_chunks), _EMBED_BATCH):
+            batch = all_chunks[i: i + _EMBED_BATCH]
+            log(f"Embedding chunks {i + 1}–{min(i + _EMBED_BATCH, len(all_chunks))} / {len(all_chunks)}")
+            embeddings = embedder.embed([c["content"] for c in batch])
+            store.upsert_chunks(collection, batch, embeddings)
+
+    # Update manifest for changed files
+    for path in changed_files:
+        rel = str(path.relative_to(root))
+        mf[rel] = manifest.file_key(path)
+    manifest.save(root, mf)
+
+    return len(files), len(all_chunks)

askmycode/llm.py

@@ -0,0 +1,177 @@
+from typing import Iterator
+from google import genai
+from google.genai import types
+
+_SYSTEM = """\
+You are a helpful assistant that answers questions about a software codebase.
+You are given relevant code snippets retrieved from the codebase and a question.
+- Answer based on the provided snippets.
+- Reference specific file paths and line numbers when relevant.
+- If the answer cannot be determined from the snippets, say so clearly.
+- Keep answers concise and developer-focused.
+"""
+
+# ── Gemini (default) ──────────────────────────────────────────────────────────
+
+_GEMINI_MODEL = "gemini-2.5-flash-lite"
+
+
+def _make_turn(role: str, text: str) -> types.Content:
+    return types.Content(role=role, parts=[types.Part(text=text)])
+
+
+def build_file_tree(file_paths: list[str]) -> str:
+    if not file_paths:
+        return ""
+    lines = ["Project structure:"] + sorted(f"  {p}" for p in file_paths)
+    return "\n".join(lines)
+
+
+def _build_user_turn(question: str, context: str, file_tree: str) -> str:
+    tree_section = f"{file_tree}\n\n" if file_tree else ""
+    return (
+        f"{tree_section}"
+        f"Relevant code snippets:\n\n"
+        f"{context}\n\n"
+        f"Question: {question}"
+    )
+
+
+def _stream_gemini(
+    question: str,
+    context: str,
+    api_key: str,
+    history: list[types.Content] | None,
+    file_tree: str,
+    model: str,
+) -> Iterator[str]:
+    client = genai.Client(api_key=api_key)
+    user_turn = _build_user_turn(question, context, file_tree)
+    contents = list(history or []) + [_make_turn("user", user_turn)]
+    for chunk in client.models.generate_content_stream(
+        model=model,
+        contents=contents,
+        config=types.GenerateContentConfig(system_instruction=_SYSTEM),
+    ):
+        if chunk.text:
+            yield chunk.text
+
+
+# ── OpenAI ────────────────────────────────────────────────────────────────────
+
+def _stream_openai(
+    question: str,
+    context: str,
+    api_key: str,
+    history: list[dict] | None,
+    file_tree: str,
+    model: str,
+) -> Iterator[str]:
+    from openai import OpenAI
+    client = OpenAI(api_key=api_key)
+    user_turn = _build_user_turn(question, context, file_tree)
+    messages = [{"role": "system", "content": _SYSTEM}]
+    for h in history or []:
+        messages.append({"role": h["role"], "content": h["content"]})
+    messages.append({"role": "user", "content": user_turn})
+    with client.chat.completions.create(model=model, messages=messages, stream=True) as stream:
+        for chunk in stream:
+            delta = chunk.choices[0].delta.content
+            if delta:
+                yield delta
+
+
+# ── Anthropic / Claude ────────────────────────────────────────────────────────
+
+def _stream_anthropic(
+    question: str,
+    context: str,
+    api_key: str,
+    history: list[dict] | None,
+    file_tree: str,
+    model: str,
+) -> Iterator[str]:
+    import anthropic
+    client = anthropic.Anthropic(api_key=api_key)
+    user_turn = _build_user_turn(question, context, file_tree)
+    messages = []
+    for h in history or []:
+        messages.append({"role": h["role"], "content": h["content"]})
+    messages.append({"role": "user", "content": user_turn})
+    with client.messages.stream(
+        model=model,
+        max_tokens=2048,
+        system=_SYSTEM,
+        messages=messages,
+    ) as stream:
+        for text in stream.text_stream:
+            yield text
+
+
+# ── Ollama (local) ────────────────────────────────────────────────────────────
+
+def _stream_ollama(
+    question: str,
+    context: str,
+    history: list[dict] | None,
+    file_tree: str,
+    model: str,
+    base_url: str,
+) -> Iterator[str]:
+    import requests, json
+    user_turn = _build_user_turn(question, context, file_tree)
+    messages = [{"role": "system", "content": _SYSTEM}]
+    for h in history or []:
+        messages.append({"role": h["role"], "content": h["content"]})
+    messages.append({"role": "user", "content": user_turn})
+    resp = requests.post(
+        f"{base_url}/api/chat",
+        json={"model": model, "messages": messages, "stream": True},
+        stream=True,
+        timeout=120,
+    )
+    resp.raise_for_status()
+    for line in resp.iter_lines():
+        if line:
+            data = json.loads(line)
+            text = data.get("message", {}).get("content", "")
+            if text:
+                yield text
+
+
+# ── Public interface ──────────────────────────────────────────────────────────
+
+def answer_stream(
+    question: str,
+    context: str,
+    api_key: str,
+    history=None,
+    file_tree: str = "",
+    provider: str = "gemini",
+    model: str = "",
+    ollama_url: str = "http://localhost:11434",
+) -> Iterator[str]:
+    """Stream an answer from the configured provider."""
+    if provider == "gemini":
+        yield from _stream_gemini(
+            question, context, api_key, history, file_tree,
+            model=model or _GEMINI_MODEL,
+        )
+    elif provider == "openai":
+        yield from _stream_openai(
+            question, context, api_key, history, file_tree,
+            model=model or "gpt-4o-mini",
+        )
+    elif provider == "anthropic":
+        yield from _stream_anthropic(
+            question, context, api_key, history, file_tree,
+            model=model or "claude-sonnet-4-6",
+        )
+    elif provider == "ollama":
+        yield from _stream_ollama(
+            question, context, history, file_tree,
+            model=model or "llama3",
+            base_url=ollama_url,
+        )
+    else:
+        raise ValueError(f"Unknown provider: {provider!r}. Choose: gemini, openai, anthropic, ollama")

askmycode/manifest.py

@@ -0,0 +1,34 @@
+import json
+from pathlib import Path
+
+_MANIFEST_FILE = ".askmycode/manifest.json"
+
+
+def _path(project_root: Path) -> Path:
+    return project_root / _MANIFEST_FILE
+
+
+def load(project_root: Path) -> dict:
+    p = _path(project_root)
+    if p.exists():
+        return json.loads(p.read_text())
+    return {}
+
+
+def save(project_root: Path, manifest: dict) -> None:
+    p = _path(project_root)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(manifest, indent=2))
+
+
+def file_key(path: Path) -> dict:
+    stat = path.stat()
+    return {"mtime": stat.st_mtime, "size": stat.st_size}
+
+
+def is_changed(path: Path, manifest: dict, relative: str) -> bool:
+    if relative not in manifest:
+        return True
+    entry = manifest[relative]
+    stat = path.stat()
+    return stat.st_mtime != entry["mtime"] or stat.st_size != entry["size"]

askmycode/project_config.py

@@ -0,0 +1,33 @@
+"""Per-project configuration loaded from .askmycode.toml."""
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ImportError:
+        tomllib = None  # type: ignore[assignment]
+
+_CONFIG_FILE = ".askmycode.toml"
+
+_DEFAULTS: dict = {
+    "provider": "",
+    "model": "",
+    "n_results": 8,
+    "include": [],
+    "exclude": [],
+}
+
+
+def load(project_root: Path) -> dict:
+    path = project_root / _CONFIG_FILE
+    if not path.exists() or tomllib is None:
+        return dict(_DEFAULTS)
+    try:
+        data = tomllib.loads(path.read_text())
+        cfg = dict(_DEFAULTS)
+        cfg.update(data.get("askmycode", {}))
+        return cfg
+    except Exception:
+        return dict(_DEFAULTS)

askmycode/reranker.py

@@ -0,0 +1,28 @@
+import io
+import os
+import sys
+from functools import lru_cache
+
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+_RERANK_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+
+
+@lru_cache(maxsize=1)
+def _get_cross_encoder():
+    old_stderr = sys.stderr
+    sys.stderr = io.StringIO()
+    try:
+        from sentence_transformers.cross_encoder import CrossEncoder
+        return CrossEncoder(_RERANK_MODEL)
+    finally:
+        sys.stderr = old_stderr
+
+
+def rerank(question: str, documents: list[str], top_k: int) -> list[int]:
+    """Return indices of the top_k documents sorted by relevance to question."""
+    model = _get_cross_encoder()
+    pairs = [(question, doc) for doc in documents]
+    scores = model.predict(pairs)
+    ranked = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)
+    return ranked[:top_k]

askmycode/retriever.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+
+from askmycode import embedder, reranker, store
+
+_FETCH_MULTIPLIER = 3  # fetch this many extra candidates for re-ranking
+
+
+def retrieve(
+    question: str,
+    project_root: Path,
+    n_results: int = 8,
+) -> tuple[str, list[dict]]:
+    """Return (context_string, sources) where sources is a list of metadata dicts."""
+    client = store.get_client(project_root)
+    collection = store.get_collection(client)
+
+    fetch_n = min(n_results * _FETCH_MULTIPLIER, collection.count())
+    if fetch_n == 0:
+        return "", []
+
+    query_embedding = embedder.embed([question])[0]
+    results = store.search(collection, query_embedding, n_results=fetch_n)
+
+    documents: list[str] = results.get("documents", [[]])[0]
+    metadatas: list[dict] = results.get("metadatas", [[]])[0]
+
+    if not documents:
+        return "", []
+
+    # Re-rank candidates and keep the top n_results
+    top_indices = reranker.rerank(question, documents, top_k=n_results)
+    documents = [documents[i] for i in top_indices]
+    metadatas = [metadatas[i] for i in top_indices]
+
+    return "\n\n---\n\n".join(documents), metadatas

askmycode/store.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+import chromadb
+
+_INDEX_DIR = ".askmycode/chroma"
+
+
+def get_client(project_root: Path) -> chromadb.PersistentClient:
+    index_path = project_root / _INDEX_DIR
+    index_path.mkdir(parents=True, exist_ok=True)
+    return chromadb.PersistentClient(path=str(index_path))
+
+
+def get_collection(client: chromadb.PersistentClient) -> chromadb.Collection:
+    return client.get_or_create_collection(
+        name="codebase",
+        metadata={"hnsw:space": "cosine"},
+    )
+
+
+def upsert_chunks(
+    collection: chromadb.Collection,
+    chunks: list[dict],
+    embeddings: list[list[float]],
+) -> None:
+    collection.upsert(
+        ids=[c["id"] for c in chunks],
+        embeddings=embeddings,
+        documents=[c["content"] for c in chunks],
+        metadatas=[
+            {k: v for k, v in c.items() if k not in ("id", "content")}
+            for c in chunks
+        ],
+    )
+
+
+def delete_by_files(collection: chromadb.Collection, file_paths: list[str]) -> None:
+    """Remove all chunks belonging to the given relative file paths."""
+    for file_path in file_paths:
+        results = collection.get(where={"file_path": file_path}, include=[])
+        ids = results.get("ids", [])
+        if ids:
+            collection.delete(ids=ids)
+
+
+def search(
+    collection: chromadb.Collection,
+    query_embedding: list[float],
+    n_results: int = 8,
+) -> dict:
+    return collection.query(
+        query_embeddings=[query_embedding],
+        n_results=n_results,
+        include=["documents", "metadatas", "distances"],
+    )

askmycode-0.1.0.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: askmycode
+Version: 0.1.0
+Summary: Ask questions about any codebase using AI — your code stays private
+Project-URL: Homepage, https://github.com/NewtYao/askmycode
+Project-URL: Issues, https://github.com/NewtYao/askmycode/issues
+License: MIT
+Keywords: ai,cli,codebase,developer-tools,embeddings,qa,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: chromadb>=0.5.0
+Requires-Dist: google-genai>=2.0.0
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# askmycode
+
+**Ask questions about any codebase in plain English. Your code never leaves your machine.**
+
+```
+$ askmycode ask "how does authentication work?"
+
+Authentication is handled in src/auth/middleware.py (lines 12–45).
+The require_auth decorator validates a JWT from the Authorization header,
+looks up the user in the session store (Redis), and attaches the user object
+to the request context. Unauthenticated requests are rejected with a 401...
+```
+
+![demo](demo.gif)
+
+[![PyPI version](https://img.shields.io/pypi/v/askmycode.svg)](https://pypi.org/project/askmycode/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Why askmycode?
+
+Most AI coding tools send your entire codebase to a remote server. **askmycode doesn't.**
+
+- **Your code stays local.** Only the question + a few relevant snippets reach the AI.
+- **Works on any codebase** — Python, Go, TypeScript, Rust, Java, and more.
+- **No more grepping.** Ask "where is the rate limiter?" instead of `grep -r "rate" .`
+- **Onboarding superpower.** New to a repo? Ask questions instead of reading every file.
+- **Multi-provider.** Gemini (free tier), OpenAI, Claude, or fully offline via Ollama.
+
+---
+
+## How it works
+
+```
+Your code  ──►  chunked locally  ──►  embedded locally  ──►  stored in local vector DB
+                                                                        │
+Your question ──► embed locally ──► find top chunks ──► send to AI ──► Answer
+                                         ↑
+                           only ~500 lines of relevant code
+                           travel to the AI, not your whole repo
+```
+
+Embeddings run on your machine via `sentence-transformers`. Only the retrieved snippets and your question are sent to the LLM.
+
+---
+
+## Install
+
+```bash
+pip install askmycode
+```
+
+Or from source:
+```bash
+git clone https://github.com/NewtYao/askmycode
+cd askmycode
+pip install -e .
+```
+
+---
+
+## Quick start
+
+**1. Set your API key**
+```bash
+askmycode config set-key YOUR_GEMINI_KEY   # get a free key at aistudio.google.com
+```
+
+**2. Initialise your project** *(optional — sets up .gitignore and suggests starter questions)*
+```bash
+cd your-project/
+askmycode init .
+```
+
+**3. Index your codebase** *(run once; re-run after big changes)*
+```bash
+askmycode index .
+```
+
+**4. Ask questions**
+```bash
+askmycode ask "where is the database connection configured?"
+askmycode ask "how does the retry logic work?"
+askmycode ask "what does UserService do?"
+```
+
+---
+
+## Commands
+
+### `askmycode ask`
+```bash
+askmycode ask "your question"
+  --sources, -s       Show which files and lines were used to answer
+  --results, -n INT   Chunks to retrieve (default: 8)
+  --provider TEXT     gemini | openai | anthropic | ollama
+  --model TEXT        Model name override
+  --project, -p PATH  Path to indexed project (default: .)
+```
+
+```bash
+# Show sources alongside the answer
+askmycode ask "how is caching implemented?" --sources
+
+# Use a different provider for one question
+askmycode ask "what does this codebase do?" --provider openai
+```
+
+### `askmycode chat`
+Multi-turn conversation — follow-up questions remember previous answers.
+```bash
+askmycode chat
+
+You: how does auth work?
+Assistant: ...
+
+You: what about the refresh token flow?   # remembers the previous answer
+Assistant: ...
+```
+
+### `askmycode index`
+```bash
+askmycode index .                 # index current directory
+askmycode index /path/to/project  # index a specific path
+```
+
+Re-indexing is **incremental** — only changed files are re-embedded.
+
+### `askmycode stats`
+```bash
+askmycode stats
+
+Files indexed:  42
+Total chunks:   187
+Last indexed:   2026-05-23 14:30:01
+Index location: /your/project/.askmycode
+```
+
+### `askmycode init`
+```bash
+askmycode init .
+```
+Detects your project type (Python, Go, Node, Rust...), adds `.askmycode/` to `.gitignore`, and prints suggested first questions.
+
+### `askmycode config`
+```bash
+askmycode config set-key   YOUR_API_KEY
+askmycode config set-provider  gemini      # gemini | openai | anthropic | ollama
+askmycode config set-model     gpt-4o      # optional model override
+askmycode config show
+```
+
+---
+
+## Multiple providers
+
+| Provider | Command | Notes |
+|---|---|---|
+| **Gemini** (default) | `config set-provider gemini` | Free tier at aistudio.google.com |
+| **OpenAI** | `config set-provider openai` | Requires `OPENAI_API_KEY` |
+| **Claude** | `config set-provider anthropic` | Requires `ANTHROPIC_API_KEY` |
+| **Ollama** | `config set-provider ollama` | 100% offline, no API key |
+
+### Fully offline with Ollama
+```bash
+# 1. Install Ollama: https://ollama.com
+# 2. Pull a model
+ollama pull llama3
+
+# 3. Use it
+askmycode config set-provider ollama
+askmycode config set-model llama3
+askmycode ask "how does this work?"   # zero internet required
+```
+
+---
+
+## Per-project config
+
+Commit an `.askmycode.toml` to share settings with your team:
+
+```toml
+[askmycode]
+provider = "gemini"
+model = "gemini-2.5-flash-lite"
+n_results = 10
+```
+
+---
+
+## GitHub Action
+
+Add AI-powered Q&A directly to your pull requests. Team members comment `/ask <question>` and get an instant answer.
+
+**Setup:**
+1. Add your API key as a repository secret: `GEMINI_API_KEY`
+2. Create `.github/workflows/askmycode.yml` (see [example](.github/workflows/askmycode.yml))
+
+**Usage in a PR:**
+```
+/ask where is error handling for the payment flow?
+```
+
+The bot replies with the answer + source file references, inline in the PR.
+
+---
+
+## Privacy
+
+| What happens | Where it goes |
+|---|---|
+| Your full codebase | **Stays on your machine** |
+| Embeddings (vector index) | **Stored in `.askmycode/` in your project** |
+| Your question + ~500 lines of relevant code | Sent to the LLM API |
+
+Use `--provider ollama` for zero data leaving your machine.
+
+---
+
+## Supported file types
+
+Python · JavaScript · TypeScript · Go · Rust · Java · C/C++ · Ruby · PHP · Swift · Kotlin · Scala · Shell · SQL · YAML · JSON · TOML · Markdown · HTML · CSS · Vue · Svelte
+
+Python files are chunked at **function and class boundaries** using AST parsing, giving higher-quality retrieval than fixed-size splitting.
+
+---
+
+## How retrieval works (technical)
+
+1. **Index:** Files are chunked (AST-aware for Python, sliding window for others), embedded with `all-MiniLM-L6-v2`, and stored in a local ChromaDB.
+2. **Query:** Your question is embedded. The top `n × 3` candidates are fetched by cosine similarity, then re-ranked with a cross-encoder (`ms-marco-MiniLM-L-6-v2`) for higher precision.
+3. **Answer:** The top N chunks + a project file tree are sent to the LLM with a developer-focused system prompt. The answer streams back in real time.
+
+---
+
+## Roadmap
+
+- [ ] VS Code extension
+- [ ] Watch mode (auto re-index on file save)
+- [ ] Semantic diff Q&A (`askmycode ask` about uncommitted changes)
+- [ ] Kotlin / Swift AST chunking
+- [ ] Web UI
+
+---
+
+## Contributing
+
+PRs welcome. Run the tool against itself to test:
+```bash
+askmycode index .
+askmycode ask "how does the indexer work?"
+```
+
+---
+
+## License
+
+MIT

askmycode-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+askmycode/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+askmycode/cli.py,sha256=ZLnz2bcqi5avUtCs_nDL5qoAAD7FC0EIs6HokMUPBM0,13256
+askmycode/config.py,sha256=NhriG4MtCobu-wy4axZjaHnpWUdtMSiZ3TVw-i7mgGA,1260
+askmycode/embedder.py,sha256=F6ILzkBJ_KU3vK7_jko3UPRM5uI2lX41sWgwfuDCmqg,715
+askmycode/indexer.py,sha256=3Isqm5uYY9GmZRQV-aDFI5IVdXCBSaQ9MJtDkL1Fouk,5838
+askmycode/llm.py,sha256=HTnTYL8HUA2sgq_VqT5eRE0-zD0LxO8mGUNeVTnpuRA,6179
+askmycode/manifest.py,sha256=vaG4QFstF6uuEJ2sFMHwyE8Vg3x5edoW9kGLi6kyaXQ,856
+askmycode/project_config.py,sha256=3KUXIzPdnr3ndbnuHF4Qk_Utw7qputloJaDtFfru4aQ,784
+askmycode/reranker.py,sha256=_RB8bQZs1JD01-VkSu7d1kC7rRSeLL97EgjnWMqqiZ4,832
+askmycode/retriever.py,sha256=1IngYhXszKLxc4A06jSr2BOEGMwvskwYmZ_TWzX6sVU,1128
+askmycode/store.py,sha256=QdIq5ZKkBLMlc-j-Lf6TJVbI2yBE-RXfedhrPd251Tc,1545
+askmycode-0.1.0.dist-info/METADATA,sha256=0Rnnw48uv6eXzwpJpymnUd3lmcISgg1HADlSwThzkB4,8284
+askmycode-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+askmycode-0.1.0.dist-info/entry_points.txt,sha256=t_P3Y-FDI4c3VGAnd8DV9e5Jcjx7uu4H3RiOPWix8sc,48
+askmycode-0.1.0.dist-info/RECORD,,

askmycode-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

askmycode-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+askmycode = askmycode.cli:app