Metadata-Version: 2.4
Name: echocache
Version: 1.0.2
Summary: Official Python SDK for EchoCache — Dynamic Semantic Cache for LLM APIs
Home-page: https://echocache.vercel.app
Author: EchoCache Team
Author-email: echocache322@gmail.com
Project-URL: Source, https://github.com/echo-cache/echocache-python
Project-URL: Tracker, https://github.com/echo-cache/echocache-python/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# EchoCache Python SDK

Official Python SDK for [EchoCache](https://echocache.vercel.app) — The Enterprise High-Performance Semantic Caching Layer for AI & LLM APIs.

Reduce LLM API bills by **up to 80%** and accelerate response times from **~1.8s down to <25ms** using vector similarity lookups.

> 🔑 **Get Started**: Create your account and get your free API key at [https://echocache.vercel.app](https://echocache.vercel.app).

---

## ⚡ Key Features

- **Semantic Vector Match**: Deduplicates semantically similar queries (e.g. *"How's the weather in NYC?"* matches *"What is New York weather like?"*).
- **Sub-30ms Latency**: Instant cache HIT responses powered by vector similarity search.
- **Zero-Break Reliability**: If the cache server is unreachable or rate-limited, the SDK automatically falls back to your LLM generator seamlessly.
- **Multi-Tenant Namespaces**: Segregate cache entries by project (`echocache://ec_prod_xxx@echocache.vercel.app/proj_name`).
- **Automatic FIFO Eviction**: Built-in entry and storage eviction to prevent DB bloat.

---

## 📦 Installation

```bash
pip install echocache
```

---

## 🚀 Quickstart

### 1. Get Your Connection String
Sign in to [EchoCache Dashboard](https://echocache.vercel.app/dashboard), create a project, and copy your connection URI:
`echocache://ec_prod_YOUR_API_KEY@echocache.vercel.app/proj_default`

### 2. Basic Usage

```python
import os
from echocache import EchoCache
import openai

# 1. Initialize EchoCache client using connection URI from https://echocache.vercel.app
echo = EchoCache(os.environ["ECHOCACHE_CONNECTION_STRING"])

# 2. Define your LLM generator function
def generate_llm_response(prompt: str) -> str:
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

# 3. Ask EchoCache (returns cached answer on HIT, or calls generator on MISS)
prompt = "What is the capital of France?"
answer = echo.ask(prompt, generate_llm_response)

print("Response:", answer)
```

---

## 🔌 Connection String Formats

EchoCache supports connection URIs obtained from [https://echocache.vercel.app](https://echocache.vercel.app):

```python
# Format: echocache://<api_key>@<host>/<project_id>
echo = EchoCache("echocache://ec_prod_your_key_here@echocache.vercel.app/proj_default")

# Or passing dictionary options:
echo = EchoCache("ec_prod_your_key_here", {
    "baseUrl": "https://echocache.vercel.app",
    "projectId": "proj_production"
})
```

---

## ⚙️ Environment Variables

Set `ECHOCACHE_CONNECTION_STRING` in your environment:

```bash
export ECHOCACHE_CONNECTION_STRING="echocache://ec_prod_xxxx@echocache.vercel.app/proj_default"
```

Then initialize without arguments:

```python
echo = EchoCache()
```

---

## 🔒 Security & Privacy

- All requests are authenticated via `Bearer` token authorization.
- Connection URIs support TLS/SSL encryption (`https://`).
- EchoCache architecture never stores full credit cards or unauthenticated credentials.

---

## 📄 License

MIT © EchoCache Team ([https://echocache.vercel.app](https://echocache.vercel.app))
