Metadata-Version: 2.4
Name: recall-py
Version: 0.1.1
Summary: Local-first conversation cache, RAG, and routing to reduce cloud LLM spend.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: usearch>=2.0.0
Requires-Dist: typer>=0.15.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: ty>=0.0.54; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25.0; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/logo.svg" alt="RecallPy" width="480" />
</p>

<p align="center">
  <a href="https://pypi.org/project/recall-py/"><img src="https://img.shields.io/pypi/v/recall-py?style=flat&label=PyPI" alt="PyPI" /></a>
  <a href="https://pypi.org/project/recall-py/"><img src="https://img.shields.io/pypi/pyversions/recall-py?style=flat&label=Python" alt="Python versions" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat" alt="License" /></a>
  <a href="https://github.com/rehanpunjwani/TokenGuard/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/rehanpunjwani/TokenGuard/ci.yml?style=flat&label=CI" alt="CI" /></a>
  <a href="https://rehanpunjwani.github.io/TokenGuard"><img src="https://img.shields.io/badge/docs-mkdocs-4F46E5?style=flat" alt="Docs" /></a>
</p>

---

**RecallPy** is a Python library and CLI that helps you cut cloud LLM costs by caching conversations, retrieving relevant context via RAG, and routing queries to local models when appropriate. It integrates natively with Cursor, Claude Code, and any OpenAI-compatible client.

## Key features

- **RAG memory** — every conversation is chunked, embedded, and stored in SQLite for semantic retrieval
- **Local draft answering** — uses a cheap local model (Ollama) to answer common questions
- **Intelligent routing** — auto-escalates to cloud models when local confidence is low
- **OpenAI-compatible proxy** — drop-in caching + compression for existing clients
- **IDE-native MCP tools** — `handle_query`, `ingest_turn`, `escalate_pack` for Cursor / Claude Code
- **Token savings tracking** — see exactly how many cloud tokens you avoided

## Quick start

```bash
python3.12 -m pip install recall-py
recall-py onboard
recall-py doctor
```

## Library usage

```python
import sqlite3
from recall_py.engine import handle_query, ingest_turn
from recall_py.ollama_client import OllamaClient
from recall_py.settings import AppSettings

settings = AppSettings.load()
conn = sqlite3.connect(settings.resolved_db_path())
ollama = OllamaClient(settings.ollama)

result = await handle_query(
    conn, settings, ollama,
    query="How does the routing policy work?",
    thread_id=None,
)

# result.context_pack.citations has the relevant context

await ingest_turn(
    conn, settings, ollama,
    thread_id=result["thread_id"],
    role="assistant",
    content="The routing policy...",
    title="my-session",
    workspace_fingerprint=result["workspace_fingerprint"],
    provider="my-app",
)
```

## CLI

| Command | Purpose |
|---------|---------|
| `recall-py onboard` | First-time setup: config, DB, Ollama, MCP snippet |
| `recall-py serve` | HTTP API (health + optional proxy) |
| `recall-py mcp-stdio` | MCP server for IDE integration |
| `recall-py doctor` | Check DB, migrations, Ollama |
| `recall-py metrics` | Token savings overview |
| `recall-py index` | Index workspace docs into RAG memory |

## Documentation

Full documentation is available at **[rehanpunjwani.github.io/TokenGuard](https://rehanpunjwani.github.io/TokenGuard/)**.

## Installation options

See the [Getting Started guide](https://rehanpunjwani.github.io/TokenGuard/getting-started/) for pipx, uv, and source installs.

## Requirements

- Python 3.12+
- [Ollama](https://ollama.com/) with `nomic-embed-text` and `llama3.2` (configurable)

## Architecture

RecallPy stores every user and assistant message in SQLite, chunks them, and embeds each chunk via Ollama. On each query, it retrieves the most semantically relevant chunks and optionally drafts a local answer. When the local draft is too uncertain, it signals escalation — you paste the context pack into your cloud model instead. All token operations are tracked for savings reporting.

[Read the architecture docs](https://rehanpunjwani.github.io/TokenGuard/architecture/)

## Docker

```bash
bash scripts/docker-up.sh
```

Starts RecallPy + Ollama with a single command. See [docker-compose.yml](docker-compose.yml).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and the [Development guide](https://rehanpunjwani.github.io/TokenGuard/development/) for technical setup.

## License

MIT
