raggrep 0.15.0 → 0.17.0

package/README.md

@@ -12,7 +12,9 @@ RAGgrep indexes your code and lets you search it using natural language. Everyth
 - **Local-first** — All indexing and search happens on your machine. No cloud dependencies.
 - **Incremental** — Only re-indexes files that have changed. Instant search when nothing changed.
 - **Watch mode** — Keep the index fresh in real-time as you code.
-- **Hybrid search** — Combines semantic similarity with keyword matching for best results.
+- **Hybrid search** — Combines semantic similarity, keyword matching, and exact text matching for best results.
+- **Exact match track** — Finds identifiers in ANY file type (YAML, .env, config, not just code) with grep-like precision.
+- **Fusion boosting** — Semantic results containing exact matches get boosted (1.5x) for better ranking.
 - **Literal boosting** — Exact identifier matches get priority. Use backticks for precise matching: `` `AuthService` ``.
 - **Phrase matching** — Exact phrases in documentation are found even when semantic similarity is low.
 - **Semantic expansion** — Domain-specific synonyms improve recall (function ↔ method, auth ↔ authentication).
@@ -40,6 +42,59 @@ That's it. The first query creates the index automatically. Subsequent queries a
 
 ### Example Output
 
+**Natural Language Query:**
+```
+Index updated: 42 indexed
+
+RAGgrep Search
+=============
+
+Searching for: "user authentication"
+
+Found 3 results:
+
+1. src/auth/authService.ts:24-55 (login)
+   Score: 34.4% | Type: function | via TypeScript | exported
+      export async function login(credentials: LoginCredentials): Promise<AuthResult> {
+        const { email, password } = credentials;
+
+2. src/auth/session.ts:10-25 (createSession)
+   Score: 28.2% | Type: function | via TypeScript | exported
+      export function createSession(user: User): Session {
+
+3. src/users/types.ts:3-12 (User)
+   Score: 26.0% | Type: interface | via TypeScript | exported
+      export interface User {
+        id: string;
+```
+
+**Exact Identifier Query (shows both tracks):**
+```
+Index updated: 42 indexed
+
+Searching for: "AUTH_SERVICE_URL"
+
+┌─ Exact Matches (4 files, 6 matches) ─┐
+│  Query: "AUTH_SERVICE_URL"
+└─────────────────────────────────────────────────────────────────────┘
+
+  1. config.yaml (2 matches)
+     8 │   auth:
+     9 │     url: AUTH_SERVICE_URL
+  ► 10 │     grpc_url: AUTH_SERVICE_GRPC_URL
+     11 │     timeout: 5000
+
+  2. .env.example (1 match)
+     2 │ AUTH_SERVICE_URL=https://auth.example.com
+  ►  3 │ AUTH_SERVICE_GRPC_URL=grpc://auth.example.com:9000
+
+┌─ Semantic Results (boosted by exact matches) ─┐
+└─────────────────────────────────────────────────────────────────────┘
+
+1. src/auth/authService.ts:2-10 (AuthService)
+   Score: 45.2% | Type: class | via TypeScript | exported | exact match
+      export class AuthService {
+        private baseUrl = AUTH_SERVICE_URL;
 ```
 Index updated: 42 indexed
 
@@ -97,17 +152,20 @@ raggrep reset            # Clear the index
 ### Query Options
 
 ```bash
-raggrep query "user login"                    # Basic search
+raggrep query "user login"                    # Natural language query
+raggrep query -C ~/projects/my-app "login"    # Search a project without cd
+raggrep query "AUTH_SERVICE_URL"             # Exact identifier (auto-triggers exact match)
+raggrep query "\`AuthService\`"              # Backticks force exact match
 raggrep query "error handling" --top 5        # Limit results
 raggrep query "database" --min-score 0.2      # Set minimum score threshold
 raggrep query "interface" --type ts           # Filter by file extension
 raggrep query "auth" --filter src/auth        # Filter by path
 raggrep query "api" -f src/api -f src/routes  # Multiple path filters
-raggrep query "\`AuthService\` class"         # Exact identifier match (backticks)
 ```
 
 | Flag              | Short | Description                                                |
 | ----------------- | ----- | ---------------------------------------------------------- |
+| `--dir <path>`    | `-C`  | Project directory to search (default: current directory)   |
 | `--top <n>`       | `-k`  | Number of results to return (default: 10)                  |
 | `--min-score <n>` | `-s`  | Minimum similarity score 0-1 (default: 0.15)               |
 | `--type <ext>`    | `-t`  | Filter by file extension (e.g., ts, tsx, js)               |
@@ -150,10 +208,35 @@ raggrep query "config" --filter "*.json" --filter "*.yaml" --filter config/
 
 This is useful when you know whether you're looking for code or documentation.
 
+### Exact Match Search
+
+For identifier-like queries (SCREAMING_SNAKE_CASE, camelCase, PascalCase), RAGgrep automatically runs exact match search:
+
+```bash
+# Finds AUTH_SERVICE_URL in ALL file types (YAML, .env, config, etc.)
+raggrep query "AUTH_SERVICE_URL"
+
+# Finds the function by exact name
+raggrep query "getUserById"
+
+# Use backticks for explicit exact matching (even natural words)
+raggrep query "`configuration`"
+```
+
+**What Gets Searched:**
+- **Source code**: `.ts`, `.js`, `.py`, `.go`, `.rs`
+- **Config files**: `.yaml`, `.yml`, `.json`, `.toml`, `.env`
+- **Documentation**: `.md`, `.txt`
+
+**Ignored:** `node_modules`, `.git`, `dist`, `build`, `.cache`, etc.
+
+Exact matches are shown in a separate section with line numbers and context. Semantic results containing the same identifier get boosted (1.5x score multiplier).
+
 ### Index Options
 
 ```bash
 raggrep index                        # Index current directory
+raggrep index --dir ../other-repo    # Index another path without cd
 raggrep index --watch                # Watch mode - re-index on file changes
 raggrep index --verbose              # Show detailed progress
 raggrep index --concurrency 8        # Set parallel workers (default: auto)
@@ -162,18 +245,21 @@ raggrep index --model bge-small-en-v1.5  # Use specific embedding model
 
 | Flag                | Short | Description                                             |
 | ------------------- | ----- | ------------------------------------------------------- |
+| `--dir <path>`      | `-C`  | Project directory to index (default: current directory) |
 | `--watch`           | `-w`  | Watch for file changes and re-index automatically       |
 | `--verbose`         | `-v`  | Show detailed progress                                  |
 | `--concurrency <n>` | `-c`  | Number of parallel workers (default: auto based on CPU) |
-| `--model <name>`    | `-m`  | Embedding model to use                                  |
+| `--model <name>`    | `-m`  | Override TypeScript module embedding model (saved config otherwise) |
 | `--help`            | `-h`  | Show help message                                       |
 
 ### Other Commands
 
 ```bash
-raggrep status           # Show index status and statistics
-raggrep reset            # Clear the index completely
-raggrep --version        # Show version
+raggrep status                    # Show index status and statistics
+raggrep status --dir ./packages/api
+raggrep reset                     # Clear the index for the current directory
+raggrep reset -C ~/projects/my-app
+raggrep --version                 # Show version
 ```
 
 ## How It Works
@@ -183,7 +269,25 @@ raggrep --version        # Show version
 3. **Files changed** — Re-indexes only modified files automatically
 4. **Files deleted** — Stale entries cleaned up automatically
 
-The index is stored in a system temp directory, keeping your project clean.
+The index is stored under **`.raggrep/`** in the project directory you index or pass with **`--dir` / `-C`** (by default, the current working directory). Add `.raggrep/` to `.gitignore` if you do not want index files in version control.
+
+## Embeddings and benchmarks
+
+Indexing uses Transformers.js–style **local ONNX** models. Unless you change `.raggrep/config.json` or pass **`raggrep index --model`**, a fresh install uses this stack:
+
+| | Default |
+|---|--------|
+| **Runtime** | **`huggingface`** (`@huggingface/transformers`). Set `embeddingRuntime` to `"xenova"` on a module in `.raggrep/config.json` to use `@xenova/transformers` instead. |
+| **Model** | **`bge-small-en-v1.5`** on each embedding-backed module (TypeScript, Python, Go, Rust, JSON, markdown). |
+
+**Benchmarks** (clone [next-convex-starter-app](https://github.com/conradkoh/next-convex-starter-app) at a pinned commit; see each script for options):
+
+| Command | What it measures | Source |
+|--------|------------------|--------|
+| `bun run bench:embeddings` | Embedding throughput (runtime × model matrix; **nomic** omitted from the harness for now) | [`scripts/benchmark-embedding-runtimes.ts`](./scripts/benchmark-embedding-runtimes.ts) |
+| `bun run bench:retrieval` | Index + hybrid search time and accuracy vs golden queries | [`scripts/benchmark-retrieval-quality.ts`](./scripts/benchmark-retrieval-quality.ts) |
+
+Golden query set: [`scripts/eval/golden-queries-next-convex.json`](./scripts/eval/golden-queries-next-convex.json). Retrieval runs write `scripts/benchmarks/<benchmark-name>.result.md` and resumable `*.cache.json` (ignored by git by default).
 
 ## What Gets Indexed