Metadata-Version: 2.4
Name: betterdb-semantic-cache
Version: 0.1.2
Summary: Semantic cache for AI workloads backed by Valkey vector search. Embeddings-based similarity matching with OpenTelemetry and Prometheus instrumentation.
Project-URL: Repository, https://github.com/BetterDB-inc/monitor
License: MIT
Keywords: embeddings,langchain,langgraph,llm,opentelemetry,prometheus,redis,semantic-cache,valkey,vector-search
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: prometheus-client>=0.19.0
Requires-Dist: valkey[asyncio]>=6.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.20.0; extra == 'all'
Requires-Dist: boto3>=1.26.0; extra == 'all'
Requires-Dist: httpx>=0.25.0; extra == 'all'
Requires-Dist: langchain-core>=0.2.0; extra == 'all'
Requires-Dist: langgraph>=0.1.0; extra == 'all'
Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: posthog>=3.0.0; extra == 'all'
Provides-Extra: analytics
Requires-Dist: posthog>=3.0.0; extra == 'analytics'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == 'anthropic'
Provides-Extra: bedrock
Requires-Dist: boto3>=1.26.0; extra == 'bedrock'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: httpx
Requires-Dist: httpx>=0.25.0; extra == 'httpx'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.1.0; extra == 'langgraph'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# betterdb-semantic-cache

Semantic cache for AI workloads backed by Valkey vector search. Embeddings-based similarity matching with OpenTelemetry and Prometheus instrumentation.

## Installation

```bash
pip install betterdb-semantic-cache
# With OpenAI embeddings:
pip install betterdb-semantic-cache[openai]
# All extras:
pip install betterdb-semantic-cache[all]
```

## Quick start

```python
import asyncio
import valkey.asyncio as valkey
from betterdb_semantic_cache import SemanticCache, SemanticCacheOptions
from betterdb_semantic_cache.embed.openai import create_openai_embed

async def main():
    client = valkey.Valkey(host="localhost", port=6399)
    cache = SemanticCache(SemanticCacheOptions(
        client=client,
        embed_fn=create_openai_embed(),
        default_threshold=0.12,
    ))
    await cache.initialize()

    result = await cache.check("What is the capital of France?")
    if not result.hit:
        await cache.store("What is the capital of France?", "Paris")

asyncio.run(main())
```

## Telemetry

The published wheel includes anonymous product analytics powered by PostHog.
When a baked API key is present in the package (injected at publish time),
**aggregate usage statistics** (hit rate, cost saved) are collected on a
per-instance basis — no prompt text, responses, or personally-identifiable
information is ever sent.

**To opt out**, set the environment variable before starting your process:

```bash
export BETTERDB_TELEMETRY=false   # also accepts: 0, no, off
```

You can also disable it programmatically:

```python
from betterdb_semantic_cache.types import AnalyticsOptions
cache = SemanticCache(SemanticCacheOptions(
    ...,
    analytics=AnalyticsOptions(disabled=True),
))
```
