Metadata-Version: 2.4
Name: kkachi
Version: 0.1.7
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Requires-Dist: hypothesis>=6.0 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: High-performance LLM prompt optimization library
Keywords: llm,optimization,dspy,prompting,ai
Author-email: terekete <spicyzhug@gmail.com>
License: AGPL-3.0-or-later
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://docs.rs/kkachi
Project-URL: Homepage, https://github.com/lituus-io/kkachi
Project-URL: Repository, https://github.com/lituus-io/kkachi

# kkachi-python

Python bindings for the [kkachi](https://github.com/lituus-io/kkachi) LLM optimization library.

## Installation

```bash
pip install kkachi
```

## Usage

```python
from kkachi import Signature, Example

sig = Signature("question -> answer")
ex = Example({"question": "What is 2+2?", "answer": "4"})
```

## Memory / RAG with Persistent Storage

The `Memory` class provides a vector store for RAG (Retrieval-Augmented Generation) with full CRUD operations and optional persistent storage using DuckDB.

### Basic Usage (In-Memory)

```python
from kkachi import Memory

# Create in-memory store
mem = Memory()

# CREATE: Add documents
doc_id = mem.add("Document content here")
mem.add_with_id("custom-id", "Another document")
mem.add_tagged("category", "Tagged document")

# READ: Retrieve documents
content = mem.get(doc_id)
results = mem.search("query text", k=3)

# UPDATE: Modify existing documents
mem.update(doc_id, "Updated content")

# DELETE: Remove documents
mem.remove(doc_id)
```

### Persistent Storage

Enable DuckDB-backed persistent storage to preserve data across program restarts:

```python
from kkachi import Memory

# Create or open a persistent database
mem = Memory().persist("./my_rag_db.db")

# Add documents (persists to disk)
mem.add("Important knowledge that survives restarts")
mem.add("More documents here")

# Data persists across program runs
results = mem.search("knowledge", k=3)

# Close and reopen
del mem
mem = Memory().persist("./my_rag_db.db")  # Data is still there!
```

The database file will be created if it doesn't exist. Subsequent calls to `.persist()` with the same path will reopen the existing database.

**Requirements**:
- The `storage` feature is enabled by default in pip package
- DuckDB native library (usually handled automatically)

### Complete Example

See `examples/memory_persist.py` for a complete demonstration of CRUD operations with persistent storage.

