Metadata-Version: 2.4
Name: smartmemo
Version: 0.0.2
Summary: Semantic memory for LLM agent calls with an equivalence-first cache architecture.
Project-URL: Repository, https://github.com/awesome-pro/smartmemo
Project-URL: Issues, https://github.com/awesome-pro/smartmemo/issues
Project-URL: Changelog, https://github.com/awesome-pro/smartmemo/blob/main/CHANGELOG.md
Author: Abhinandan
License-Expression: MIT
License-File: LICENSE
Keywords: agents,embeddings,equivalence,llm,semantic-cache,semantic-memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.11
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: dev
Requires-Dist: pyright<2,>=1.1.400; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Provides-Extra: llm
Requires-Dist: anthropic<1,>=0.60; extra == 'llm'
Requires-Dist: openai<3,>=1.70; extra == 'llm'
Provides-Extra: ml
Requires-Dist: faiss-cpu<2,>=1.8; extra == 'ml'
Requires-Dist: sentence-transformers<6,>=3; extra == 'ml'
Requires-Dist: torch<3,>=2.3; extra == 'ml'
Description-Content-Type: text/markdown

# SmartMemo

SmartMemo is a semantic memory and caching layer for LLM agent calls. Its core thesis is
simple: cosine similarity is a useful candidate selector, but it is not semantic
equivalence. SmartMemo uses embedding search to find likely cache candidates, then can use
a learned equivalence classifier to decide whether a cached response is safe to reuse.

The current implementation ships the baseline and the first classifier-gated cache path:

- async `SmartMemo.get_or_call(...)`
- SQLite persistence
- embedding provider protocol
- FAISS-backed vector search when `smartmemo[ml]` is installed
- dependency-light in-memory search for tests and smoke demos
- measured cosine-baseline benchmark fixtures for customer-support prompts
- classifier training, evaluation, checkpoint inference, and optional classifier-gated hits

By default, SmartMemo keeps the lightweight cosine baseline. When you provide a classifier
checkpoint, cosine search becomes the candidate selector and the learned classifier makes
the final cache-hit decision. SmartMemo does not ship a production pretrained classifier yet.

## Install

```bash
pip install smartmemo
pip install "smartmemo[ml]"
```

For local development:

```bash
uv sync --all-extras
uv run pytest
uv run ruff check
uv run pyright
```

## Minimal Example

```python
from smartmemo import SmartMemo

cache = SmartMemo(domain="customer-support")

async def call_llm(prompt: str) -> str:
    return "fresh LLM response"

result = await cache.get_or_call(
    prompt="Summarize this customer's latest billing ticket",
    llm_function=call_llm,
)

print(result.response)
print(result.was_cache_hit)
```

## Baseline Benchmark

The customer-support benchmark is intentionally designed to show the baseline failure
mode: prompts about the same object can require opposite actions.

```bash
uv run python benchmarks/cosine_baseline_customer_support.py
```

The numbers from that benchmark are the only performance claims this implementation makes.

## Classifier Pipeline

SmartMemo includes a trainable pair classifier over prompt embeddings:

```bash
uv run smartmemo train-classifier \
  --data data/fixtures/customer_support_pairs.jsonl \
  --out models/classifier-smoke.pt \
  --embedding-provider hash \
  --embedding-dim 64 \
  --epochs 2
```

Use the hash provider only for smoke checks. Real experiments should install
`smartmemo[ml]` and use the SentenceTransformers embedding provider.

Use a trained checkpoint for classifier-gated cache decisions:

```python
from smartmemo import ClassifierConfig, SmartMemo

cache = SmartMemo(
    domain="customer-support",
    classifier=ClassifierConfig(model_path="models/classifier-smoke.pt"),
)
```

When the classifier is active, `CacheResult.classifier_score` is populated for classifier
hits and classifier-gated misses that had candidates.

## Release

Version `0.0.2` is configured for PyPI as `smartmemo`. The repository publishes through
GitHub Actions trusted publishing from `.github/workflows/publish-pypi.yml` with the
`pypi` environment.

```bash
git tag v0.0.2
git push origin v0.0.2
```

That tag builds the source distribution and wheel, then uploads them to PyPI.
