Metadata-Version: 2.5
Name: protorag
Version: 0.1.0
Summary: Zero-infrastructure in-memory RAG prototyping framework for Python.
Project-URL: Homepage, https://github.com/eabjab/protoRAG
Project-URL: Issues, https://github.com/eabjab/protoRAG/issues
Author-email: Ethan Buege <buege.ethan@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,bm25,embeddings,llm,prototyping,rag,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software 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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: fastembed>=0.3.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: usearch>=2.11.0
Provides-Extra: chroma
Requires-Dist: chromadb>=0.4.22; extra == 'chroma'
Provides-Extra: dev
Requires-Dist: black>=23.7.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: chromadb>=0.4.22; extra == 'full'
Requires-Dist: sentence-transformers>=2.3.0; extra == 'full'
Requires-Dist: torch>=2.0.0; extra == 'full'
Requires-Dist: transformers>=4.36.0; extra == 'full'
Provides-Extra: sentence-transformers
Requires-Dist: sentence-transformers>=2.3.0; extra == 'sentence-transformers'
Requires-Dist: torch>=2.0.0; extra == 'sentence-transformers'
Description-Content-Type: text/markdown

# protoRAG

Zero-infrastructure, in-memory RAG prototyping framework for Python.
Vector, BM25, and hybrid search with pluggable backends, durable
persistence, and Hugging Face tool integration — all in one process, no
external service.

## Features

- **Hybrid retrieval** — vector + Okapi BM25 with RRF or linear score
  fusion, exact-match metadata filters
- **Pluggable backends** — vector stores: `numpy`, `usearch` (default),
  `chromadb`; embedders: `fastembed` (default, CPU/ONNX), `torch`,
  `sentence-transformers`
- **CPU-first** — the base install needs no GPU and no PyTorch
- **Durable indexes** — atomic `save()` / `load()` with a self-describing
  manifest and explicit compatibility errors; score round-trip < 1e-5
- **Agent-ready** — `to_tool()` emits a valid HF transformers tool schema
  and a plain callable (optional smolagents wrapper)
- **Strictly typed** — `mypy --strict` clean, `py.typed` marker included

## Installation

Python 3.9 – 3.13.

```bash
pip install protorag                 # core: numpy + fastembed + usearch
pip install "protorag[full]"         # + PyTorch / transformers / sentence-transformers / chromadb
pip install "protorag[chroma]"       # + chromadb only
```

## Quickstart

```python
from protorag import ProtoRAG, SearchMode

rag = ProtoRAG(vector_backend="numpy", embedding_backend="fastembed")
rag.add_texts(
    [
        "The Apollo 11 mission landed humans on the Moon in July 1969.",
        "Python is a high-level, general-purpose programming language.",
        "Transformers and self-attention mechanisms revolutionized "
        "natural language processing.",
    ],
    metadatas=[
        {"source": "history"},
        {"source": "programming"},
        {"source": "nlp"},
    ],
)

for hit in rag.search("Apollo 11 Moon 1969", top_k=1, mode=SearchMode.BM25):
    print(hit.score, hit.content, hit.metadata)

# Hybrid is the default mode:
rag.search("Apollo space mission NLP", top_k=2)

# Persistence + agent tooling:
rag.save("./my_index")
rag2 = ProtoRAG.load("./my_index")
tool = rag2.to_tool(name="my_kb", description="A knowledge base.")
tool(query="What happened on the Moon in 1969?")
tool.to_json_schema()
```

## Documentation

- [Getting started](docs/getting-started.md) — installation, backends,
  hybrid search, persistence, tool integration
- [Architecture](docs/architecture.md) — component map, score conventions,
  fusion math, serialization format, performance targets

## Development

```bash
pip install ".[dev]"
ruff check src/protorag     # lint
mypy --strict src/protorag  # type check
pytest -m "not network" -q  # offline test suite
pytest -q                   # full suite (downloads the default BGE model once)
```

CI (`.github/workflows/`): `test-cpu.yml` runs the py3.9–3.13 matrix with
lint + mypy + offline tests; `test-full.yml` runs the full suite with
PyTorch backends and network tests; `release.yml` builds and publishes on
`v*` tags.

## License

[Apache License 2.0](LICENSE)
