Metadata-Version: 2.4
Name: rag-cachex
Version: 0.1.1
Summary: A context-aware, multi-level caching system for Retrieval-Augmented Generation (RAG) applications.
Project-URL: Homepage, https://github.com/Utk-858/Context-aware-cache
Project-URL: Repository, https://github.com/Utk-858/Context-aware-cache
Project-URL: Bug-Tracker, https://github.com/Utk-858/Context-aware-cache/issues
Author-email: Utkarsh Bansal <utkarsh08bansal@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: prometheus-client>=0.17.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml
Requires-Dist: redis>=5.0.0
Provides-Extra: all
Requires-Dist: faiss-cpu>=1.7.4; extra == 'all'
Requires-Dist: numpy>=1.20.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.2; extra == 'all'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.2; extra == 'embeddings'
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.7.4; extra == 'faiss'
Requires-Dist: numpy>=1.20.0; extra == 'faiss'
Provides-Extra: perf
Requires-Dist: fastapi>=0.100.0; extra == 'perf'
Requires-Dist: uvicorn>=0.20.0; extra == 'perf'
Description-Content-Type: text/markdown

# RAGCache

[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/rag-cache/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Support](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://pypi.org/project/rag-cache/)
[![CI Build Status](https://github.com/Utk-858/Context-aware-cashe/actions/workflows/ci.yml/badge.svg)](https://github.com/Utk-858/Context-aware-cashe/actions/workflows/ci.yml)

RAGCache is a **context-aware, multi-level caching system** designed to accelerate and optimize Retrieval-Augmented Generation (RAG) pipelines. Unlike traditional exact-match KV caches, RAGCache utilizes semantic similarity, context stability validation, and user intent classification to safely reuse LLM responses while strictly preserving correctness.

---

## 🚀 Key Features

* **Dual-Layer Caching (L1 & L2)**:
  - **L1 (Retrieval Cache)**: Low-latency exact-match string cache mapping queries directly to document IDs, bypassing heavy vector search lookups.
  - **L2 (Generation Cache)**: High-performance semantic cache mapping queries and contexts to LLM responses.
* **Context Stability Validation**: Analyzes document overlaps using Jaccard Similarity to reject cache hits if retrieved context documents have drifted.
* **Intent-Aware Caching**: Classifies queries (e.g. action, informational) to bypass caching automatically for mutation operations.
* **Strict Tenant Isolation**: Restricts cache retrieval scope dynamically to prevent context leakages across different users and tenants.
* **Prometheus Observability**: Native latency histograms, cache hit-rate counters, and memory tracking.
* **Optimization ROI**: Speeds up RAG pipelines by **2.3x** and reduces API token costs by up to **60%** with zero loss in contextual accuracy.

---

## 📐 Architecture Overview

```
                        User Query
                            │
                            ▼
                    ┌──────────────┐
                    │  L1 Cache    ├─────────► Hit (Yields Doc IDs)
                    └──────┬───────┘                 │
                           │ Miss                    │
                           ▼                         │
                    ┌──────────────┐                 │
                    │ Vector DB    │◄────────────────┘
                    └──────┬───────┘
                           │ doc_ids
                           ▼
                    ┌──────────────┐
                    │  L2 Cache    ├─────────► Hit (Returns LLM Response)
                    └──────┬───────┘
                           │ Miss
                           ▼
                    ┌──────────────┐
                    │  Expensive   │
                    │   LLM API    │
                    └──────────────┘
```

For a deep dive into caching layers and algorithms, read the [Architecture Guide](file:///Users/utkarshbansal/Context-aware-cashe/docs/architecture.md).

---

## 📦 Installation

Install the core library (includes Redis support and Prometheus telemetry):
```bash
pip install rag-cache
```

### Optional Backends:
- **Local FAISS Vector DB**:
  ```bash
  pip install "rag-cache[faiss]"
  ```
- **Local Sentence-Transformers Embeddings**:
  ```bash
  pip install "rag-cache[embeddings]"
  ```
- **Full Installation (All Backends)**:
  ```bash
  pip install "rag-cache[all]"
  ```

---

## ⚡ Quick Start

Get running in less than 2 minutes using our high-level facade:

```python
from rag_cache import RAGCache

# Initialize dual-layer cache facade
cache = RAGCache()

# Wrap your existing RAG execution function
def query_rag_pipeline(query: str):
    # Pass query, retriever callback, and LLM callback
    result = cache.run(
        query=query,
        retriever=lambda q: ["doc_abc", "doc_xyz"],
        llm=lambda q, doc_ids: "Context-aware systems ensure LLM correctness."
    )
    return result["answer"]

# Executes LLM call (miss)
print(query_rag_pipeline("What is context-aware caching?"))

# Returns cached response immediately (semantic hit!)
print(query_rag_pipeline("Explain context-aware caching."))
```

For more execution models and advanced configurations, see the [Quick Start Guide](file:///Users/utkarshbansal/Context-aware-cashe/docs/quickstart.md).

---

## ⚙️ Configuration

RAGCache supports configuration loading with the following precedence:
1. **Keyword overrides** in constructor (e.g. `RAGCache(redis_url="...")`).
2. **Environment variables** (`REDIS_URL`, `L1_TTL`, `L2_TTL`, `SIMILARITY_THRESHOLD`).
3. **YAML configuration file** (e.g. loaded via `RAGCache.from_config("config.yaml")`).
4. **Built-in defaults**.

See [config_example.yaml](file:///Users/utkarshbansal/Context-aware-cashe/examples/config_example.yaml) for a complete template configuration.

---

## 🔒 Tenant Isolation

Ensure user data boundaries are strictly isolated by passing a `tenant_id` to caching endpoints:

```python
result = cache.run(
    query=query,
    retriever=retriever_fn,
    llm=llm_fn,
    tenant_id="customer_company_a",
    scope="tenant"  # Options: "tenant" (default), "user", or "global"
)
```

For details on namespacing strategies in Redis, see [Architecture Guide](file:///Users/utkarshbansal/Context-aware-cashe/docs/architecture.md).

---

## 📊 Metrics & Telemetry

RAGCache collects statistics out-of-the-box using Prometheus:
- Cache hits/misses split by L1 and L2 layers.
- Operational latency histograms for Redis, FAISS, and Embeddings.
- Eviction count and Redis memory usage.

To enable the HTTP telemetry server, set the `prometheus_port` config parameter:
```python
cache = RAGCache(prometheus_port=8000)
```
Scrape metrics at `http://localhost:8000/metrics`. We provision pre-built Grafana dashboards under `config/grafana/dashboards`.

---

## 🧪 Calibration & Benchmarking

To optimize caching threshold parameters for your specific RAG datasets, run the offline calibration script:
```bash
python tools/calibration/calibrate.py
```
This runs a threshold sweep to recommend optimal parameters under **Safety-First**, **Max F1**, and **Balanced** profiles. Read the [Benchmark Documentation](file:///Users/utkarshbansal/Context-aware-cashe/docs/benchmarks.md) for more details.

---

## 📄 License

This project is licensed under the MIT License. See [LICENSE](file:///Users/utkarshbansal/Context-aware-cashe/LICENSE) for details.
