Metadata-Version: 2.4
Name: memvid-rs
Version: 2.1.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Multimedia :: Video
Requires-Dist: numpy>=1.20.0
Requires-Dist: sentence-transformers>=2.2.0 ; extra == 'full'
Requires-Dist: faiss-cpu>=1.7.0 ; extra == 'full'
Requires-Dist: pypdf2>=3.0.0 ; extra == 'full'
Provides-Extra: full
License-File: LICENSE
Summary: High-performance AI memory library with full-text and semantic search (Rust bindings for memvid v2)
Author-email: DrivenByCode <jaykey1004@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/drivenbycode/memvid-rs
Project-URL: Repository, https://github.com/drivenbycode/memvid-rs

# memvid-rs (Python Bindings)

[![🇰🇷 한국어 (Korean)](https://img.shields.io/badge/lang-Korean-blue.svg)](README_ko.md)
[![PyPI version](https://badge.fury.io/py/memvid-rs.svg)](https://badge.fury.io/py/memvid-rs)

**Memvid-rs** provides high-performance Python bindings for [memvid-core v2](https://github.com/memvid/memvid), the engine behind the memvid ecosystem. It is a crash-safe, single-file AI memory designed for RAG and long-term agent memory.

> **Attribution**: This project wraps [memvid-core](https://github.com/memvid/memvid) with PyO3 bindings. API is designed to be compatible with `memvid-sdk`.

## 🚀 Key Features

-   **Single-File Memory**: All data (text, index, metadata) stored in portable `.mv2` format.
-   **Full-Text & RAG**: BM25 ranking via embedded Tantivy index with built-in RAG (`ask`) support.
-   **Extreme Performance**: Rust-core ensures sub-millisecond lookups and efficient batch ingestion.
-   **Crash-Safe**: WAL-based append-only architecture protects your data.
-   **Compatibility**: Drop-in replacement for `memvid-sdk` Python users needing more speed.

## 📦 Installation

```bash
pip install memvid-rs
```

## 💻 Quick Start

```python
from memvid_rs import use

# Use 'auto' mode to create or open memory
with use("ai_agent", "data.mv2", mode="auto") as mv:
    # Add document with metadata and auto-indexing
    mv.put(
        text="Memvid-RS is a ultra-fast Rust implementation.",
        title="Performance Note",
        label="tech",
        tags=["rust", "fast"]
    )
    
    # Batch ingestion (100x faster than individual put)
    mv.put_many([
        {"text": "Sample doc 1", "title": "Doc 1"},
        {"text": "Sample doc 2", "title": "Doc 2"},
    ])
    
    mv.commit()
    
    # Full-text search
    results = mv.find("rust implementation", k=5)
    print(f"Search results: {results['hits']}")
    
    # RAG Question Answering
    answer = mv.ask("What is Memvid-RS?")
    print(f"AI Answer: {answer['answer']}")
```

## 🔧 API Reference

### Top-level Functions
- `use(profile, path, mode="auto", read_only=False)`: Flexible entry point.
- `create(path, capacity_gb=1)`: Create new memory.
- `open(path)`: Open existing memory.

### `Memory` / `MemvidMemory` Methods

| Method | Description |
|--------|-------------|
| `put(text, title, ...)` | Insert document with metadata |
| `put_many([docs])` | Batch insert multiple documents |
| `find(query, k)` | Full-text search (BM25) |
| `ask(question, k)` | RAG-based question answering |
| `append(text)` | Low-level text append |
| `commit()` / `seal()` | Flush writes to disk |
| `stats()` | Get frame count and size in bytes |
| `timeline(limit)` | Retrieve recent documents |

## ⚠️ Breaking Changes from v1

- **QR video encoding removed** - v2 uses binary `.mv2` format for 1000x better density.
- **API redesigned** - Now follows the `memvid-sdk` v2 patterns.

## 📄 License

MIT License

