Metadata-Version: 2.4
Name: echostate
Version: 0.1.1
Summary: Semantic, event-sourced state for intelligent systems
Author: EchoState Contributors
License: MIT
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.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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: sentence-transformers>=2.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# EchoState

**Semantic, event-sourced state for intelligent systems**

EchoState is a Python library that gives your applications **permanent memory** and **semantic search**. Every change you make is saved permanently, and you can search by meaning, not just exact words.

> Think of EchoState as **Git + SQLite + Vector Search — for runtime state**.

## Why EchoState?

Building AI agents or long-running applications? You need:
- ✅ **Memory that persists** - Data survives restarts
- ✅ **Search by meaning** - Find "refund requests" even if stored as "reimbursement"
- ✅ **Complete history** - See every change that happened
- ✅ **Auditability** - Prove what happened and when

EchoState provides all of this with a simple, Pythonic interface.

## Features (v0.1)

- ✅ Event-sourced state with deterministic replay
- ✅ SQLite-based persistence
- ✅ Semantic search over explicitly indexed keys
- ✅ History inspection and time-travel snapshots
- ✅ Rebuildable vector index

## Quick Start

```python
from echostate import EchoState

# Create a state instance
state = EchoState(
    name="agent_state",
    persist="sqlite:///state.db",
    index_keys=["notes", "profile"],
)

# Write state
state.set("profile.tier", "Gold", metadata={"user_id": "u-42"})
state.append("notes", "Customer requested refund", metadata={"trace_id": "t-123"})

# Semantic search
results = state.search("refund duplicate charge", k=5)
for hit in results:
    print(f"{hit.path}: {hit.text} (score: {hit.score})")

# Inspect history
events = state.history("notes", filters={"user_id": "u-42"}, limit=100)

# Time-travel snapshot
past_state = state.snapshot(at="2026-01-05T10:30:00Z")
```

## Documentation

- 📖 **[User Manual](https://github.com/skamath17/echostate/blob/main/USER_MANUAL.md)** - Complete guide with API reference, examples, and use cases

## Installation

```bash
pip install echostate
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black echostate/

# Lint
ruff check echostate/
```

## License

MIT
