Metadata-Version: 2.4
Name: ragrep
Version: 0.2.1
Summary: Local semantic code recall with mxbai embeddings and SQLite
Author-email: RAGrep Team <ragrep@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pierce403/ragrep
Project-URL: Repository, https://github.com/pierce403/ragrep
Project-URL: Issues, https://github.com/pierce403/ragrep/issues
Keywords: semantic-search,embeddings,sqlite,code-search,local
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sentence-transformers>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# RAGrep

RAGrep is a dead-simple local semantic recall tool for code and text files.

It uses:
- `mxbai-embed-large` embeddings in-process (no server)
- a single local SQLite database file: `.ragrep.db`

No ChromaDB. No remote API keys.

## Install

```bash
pip install ragrep
```

## Embedding Model Storage

RAGrep downloads the embedding model automatically on first use.

Default model directories:
- Linux: `~/.config/ragrep/models`
- macOS: `~/Library/Application Support/ragrep/models`
- Windows: `%APPDATA%\\ragrep\\models`

Override with:
- env var: `RAGREP_MODEL_DIR`
- CLI flag: `--model-dir`
- Python API: `RAGrep(model_dir="...")`

## GPU Usage

RAGrep can use GPU for embeddings when available.

- Default behavior: `RAGREP_DEVICE=auto` (prefers `cuda`, then `mps`, then `cpu`)
- Override via env: `RAGREP_DEVICE=cpu|cuda|mps|cuda:0`
- Override via CLI: `--device ...`
- Override via Python API: `RAGrep(embedding_device="...")`
- Note: GPU usage requires a GPU-capable PyTorch build in your environment.
- Check runtime GPU support: `ragrep --check-gpu` (or `ragrep --check-gpu --json`)

## CLI Usage

Recall is the default command.

```bash
# Implied recall (auto-indexes when needed)
ragrep "authentication middleware"

# Explicit recall (same behavior)
ragrep recall "authentication middleware"

# Build/update index manually
ragrep index .

# Show stats
ragrep stats

# Stats alias
ragrep --stats
```

When `--path` is omitted, auto-indexing uses the previously indexed root if one exists;
otherwise it uses the current directory.

Indexing is incremental by default:
- new files are added
- modified files are re-embedded
- removed files are deleted from the index

CLI runs that index files print newly indexed file paths to stdout.

Useful flags:

```bash
ragrep "query text" --path . --limit 10 --db-path ./.ragrep.db
ragrep "query text" --model-dir ~/.config/ragrep/models --json
ragrep "query text" --device auto
ragrep index . --force
```

## Python Usage

```python
from ragrep import RAGrep

rag = RAGrep(
    db_path="./.ragrep.db",
    embedding_model="mxbai-embed-large",
    embedding_device="auto",
)
rag.index(".")

result = rag.recall("database transactions", limit=5)
for match in result["matches"]:
    print(match["score"], match["metadata"]["source"])

print(rag.stats())
rag.close()
```

Library methods:
- `index(path=".", force=False)`
- `recall(query, limit=20, path=".", auto_index=True)`
- `stats()`

Backwards-compatible aliases still available:
- `RAGSystem` (alias of `RAGrep`)
- `dump(...)` (alias of `recall(..., auto_index=False)` result list)

## Local Database

RAGrep stores everything in one SQLite file (default `./.ragrep.db`):
- indexed files and mtimes
- chunked source text
- embedding vectors
- index metadata (model, chunk settings, root path)

## Development

```bash
pip install -e .[dev]
python -m unittest discover -s tests -p 'test_*.py'
python -m build
twine check dist/*
```

## License

MIT
