askmycode 0.1.0__tar.gz

askmycode-0.1.0/.askmycode.toml

@@ -0,0 +1,12 @@
+# askmycode project configuration
+# Commit this file to share settings with your team.
+
+[askmycode]
+# LLM provider: gemini (default), openai, anthropic, ollama
+# provider = "gemini"
+
+# Model override (leave blank for provider default)
+# model = "gemini-2.5-flash-lite"
+
+# Number of code chunks retrieved per question (default: 8)
+# n_results = 8

askmycode-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/pip install *)"
+    ]
+  }
+}

askmycode-0.1.0/.github/workflows/askmycode.yml

@@ -0,0 +1,77 @@
+name: askmycode — Answer PR questions
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  answer:
+    # Trigger only on PR comments that start with /ask
+    if: >
+      github.event.issue.pull_request != null &&
+      startsWith(github.event.comment.body, '/ask ')
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install askmycode
+        run: pip install askmycode
+
+      - name: Index codebase
+        env:
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+        run: askmycode index .
+
+      - name: Extract question from comment
+        id: question
+        run: |
+          COMMENT="${{ github.event.comment.body }}"
+          QUESTION="${COMMENT#/ask }"
+          echo "question=$QUESTION" >> "$GITHUB_OUTPUT"
+
+      - name: Ask question
+        id: answer
+        env:
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+        run: |
+          ANSWER=$(askmycode ask "${{ steps.question.outputs.question }}" --sources)
+          # Store multi-line output safely
+          {
+            echo "answer<<EOF"
+            echo "$ANSWER"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Post answer as PR comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const question = `${{ steps.question.outputs.question }}`;
+            const answer = `${{ steps.answer.outputs.answer }}`;
+            const body = [
+              `**Q: ${question}**`,
+              "",
+              answer,
+              "",
+              "_— answered by [askmycode](https://github.com/NewtYao/askmycode)_"
+            ].join("\n");
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body
+            });

askmycode-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+
+# askmycode index (don't commit the vector DB)
+.askmycode/
+
+# macOS
+.DS_Store

askmycode-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,260 @@
+# 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/askmycode/__init__.py

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