Metadata-Version: 2.4
Name: busbot-memory
Version: 0.1.0
Summary: LLM-powered working memory for Vietnamese bus booking bots
Author-email: QuocAnh <quocanhnguyen.work@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/biva-ai/busbot-memory
Project-URL: Documentation, https://github.com/biva-ai/busbot-memory#readme
Project-URL: Repository, https://github.com/biva-ai/busbot-memory.git
Project-URL: Issues, https://github.com/biva-ai/busbot-memory/issues
Keywords: llm,memory,chatbot,bus-booking,vietnamese,groq,voice-bot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: groq>=0.4.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: redis>=5.0.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"

# BusBotMemory SDK

LLM-powered working memory for Vietnamese bus booking bots.

## Installation

```bash
pip install busbot-memory
```

Or install from source:
```bash
cd busbot-memory
pip install -e .
```

## Quick Start

```python
import asyncio
from busbot_memory import BusBotMemory, BusBotConfig

async def main():
    # Configure (set GROQ_API_KEY env var or pass directly)
    config = BusBotConfig(groq_api_key="gsk_xxx")
    
    # Initialize memory for a session
    memory = BusBotMemory(
        session_id="call_001",
        customer_id="0987654321",
        config=config
    )
    
    # Process messages
    result = await memory.process("đặt 2 vé đi đà nẵng ngày mai 8h sáng")
    
    print(result.state.slots)
    # {"destination": "Đà Nẵng", "date": "ngày mai", "time": "08:00", "quantity": 2}

asyncio.run(main())
```

## Features

- **LLM-powered extraction**: Uses Groq (llama-3.3-70b) for accurate entity extraction
- **Change-of-mind detection**: Automatically detects when user changes their booking
- **State tracking**: Maintains structured booking state with missing slot tracking
- **Low latency**: Optimized for < 250ms processing time
- **Fallback support**: Falls back to regex when LLM is unavailable

## Configuration

```python
config = BusBotConfig(
    # LLM Provider (at least one required)
    groq_api_key="gsk_xxx",           # Primary - fast & free
    openai_api_key="sk-xxx",          # Optional fallback
    
    # Performance
    latency_target_ms=250,
    enable_fallback=True,             # Use regex if LLM fails
    
    # Memory settings
    max_working_items=20,
    max_context_window=5,
)
```

## ProcessResult

```python
result = await memory.process(message)

result.entities       # Extracted entities
result.state          # BookingState object
result.is_noise       # Is filler message ("ừ", "ok")
result.is_change      # Did user change their mind
result.changes        # List of changes made
result.intent         # Detected intent
result.latency_ms     # Processing time
```

## License

MIT
