busbot-memory 0.1.0__tar.gz

busbot_memory-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+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

busbot_memory-0.1.0/README.md

@@ -0,0 +1,85 @@
+# 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

busbot_memory-0.1.0/busbot_memory/__init__.py

@@ -0,0 +1,15 @@
+"""BusBot Memory SDK - LLM-powered working memory for bus booking bots"""
+
+from busbot_memory.core.manager import BusBotMemory
+from busbot_memory.core.models import BookingState, MemoryItem, ProcessResult
+from busbot_memory.core.config import BusBotConfig
+from busbot_memory.version import __version__
+
+__all__ = [
+    "BusBotMemory",
+    "BookingState", 
+    "MemoryItem",
+    "ProcessResult",
+    "BusBotConfig",
+    "__version__",
+]

busbot_memory-0.1.0/busbot_memory/core/__init__.py

@@ -0,0 +1,21 @@
+"""Core module exports"""
+
+from busbot_memory.core.models import (
+    BookingState,
+    MemoryItem,
+    MemoryMetadata,
+    ExtractionResult,
+    ProcessResult,
+    Intent,
+)
+from busbot_memory.core.config import BusBotConfig
+
+__all__ = [
+    "BookingState",
+    "MemoryItem",
+    "MemoryMetadata",
+    "ExtractionResult",
+    "ProcessResult",
+    "Intent",
+    "BusBotConfig",
+]

busbot_memory-0.1.0/busbot_memory/core/config.py

@@ -0,0 +1,60 @@
+"""Configuration for BusBot Memory SDK"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class BusBotConfig:
+    """
+    SDK Configuration
+    
+    Example:
+        config = BusBotConfig(
+            groq_api_key="gsk_xxx",
+            redis_url="redis://localhost:6379",
+            domain="bus_booking"
+        )
+    """
+    # LLM Provider
+    groq_api_key: Optional[str] = field(
+        default_factory=lambda: os.getenv("GROQ_API_KEY")
+    )
+    groq_model: str = "llama-3.3-70b-versatile"
+    groq_fallback_model: str = "llama-3.1-8b-instant"
+    
+    # OpenAI (optional, for higher quality)
+    openai_api_key: Optional[str] = field(
+        default_factory=lambda: os.getenv("OPENAI_API_KEY")
+    )
+    openai_model: str = "gpt-4o-mini"
+    
+    # Storage
+    redis_url: Optional[str] = field(
+        default_factory=lambda: os.getenv("REDIS_URL")
+    )
+    session_ttl_seconds: int = 3600       # 1 hour
+    user_memory_ttl_days: int = 30        # 30 days
+    
+    # Domain
+    domain: str = "bus_booking"
+    
+    # Memory settings
+    max_working_items: int = 20
+    max_context_window: int = 5
+    
+    # Performance
+    latency_target_ms: int = 250
+    enable_fallback: bool = True          # Fallback to regex if LLM fails
+    enable_metrics: bool = True           # Track latency metrics
+    
+    # Logging
+    log_level: str = "INFO"
+    log_extractions: bool = False         # Log LLM extraction results
+    
+    def validate(self) -> bool:
+        """Validate configuration"""
+        if not self.groq_api_key and not self.openai_api_key:
+            raise ValueError("At least one of groq_api_key or openai_api_key must be set")
+        return True

busbot_memory-0.1.0/busbot_memory/core/manager.py

@@ -0,0 +1,244 @@
+"""
+BusBotMemory - Main SDK Entry Point
+
+This is the primary class users will interact with.
+"""
+
+import time
+import logging
+from typing import Optional, List
+from collections import deque
+
+from busbot_memory.core.config import BusBotConfig
+from busbot_memory.core.models import (
+    BookingState,
+    MemoryItem,
+    MemoryMetadata,
+    ProcessResult,
+    ExtractionResult,
+)
+from busbot_memory.extractors.llm import LLMExtractor
+from busbot_memory.extractors.regex import RegexExtractor
+from busbot_memory.state.manager import StateManager
+
+logger = logging.getLogger(__name__)
+
+
+class BusBotMemory:
+    """
+    LLM-powered working memory for bus booking bots
+    
+    Example:
+        from busbot_memory import BusBotMemory, BusBotConfig
+        
+        config = BusBotConfig(groq_api_key="gsk_xxx")
+        memory = BusBotMemory(
+            session_id="call_001",
+            customer_id="0987654321",
+            config=config
+        )
+        
+        result = await memory.process("đặt 2 vé đi đà nẵng ngày mai")
+        print(result.state.slots)  # {"destination": "Đà Nẵng", "quantity": 2, ...}
+    """
+    
+    def __init__(
+        self,
+        session_id: str,
+        customer_id: Optional[str] = None,
+        config: Optional[BusBotConfig] = None,
+    ):
+        self.session_id = session_id
+        self.customer_id = customer_id
+        self.config = config or BusBotConfig()
+        
+        # Validate config
+        self.config.validate()
+        
+        # Initialize components
+        self._llm_extractor = LLMExtractor(self.config)
+        self._regex_extractor = RegexExtractor()
+        self._state_manager = StateManager()
+        
+        # Working memory storage
+        self._memory: deque = deque(maxlen=self.config.max_working_items)
+        
+        # Booking state
+        self._state: BookingState = self._state_manager.create_initial_state()
+        
+        # User memory (persistent info)
+        self._user_memory: dict = {}
+        
+        # Metrics
+        self._latencies: List[int] = []
+        
+        logger.info(f"BusBotMemory initialized: session={session_id}")
+    
+    async def process(self, message: str, role: str = "user") -> ProcessResult:
+        """
+        Process a message and update memory + state
+        
+        This is the main entry point for the SDK.
+        
+        Args:
+            message: The message to process
+            role: "user" or "assistant"
+            
+        Returns:
+            ProcessResult with entities, state, changes, and latency
+        """
+        start_time = time.perf_counter()
+        
+        # Build context from recent memory
+        context = self._build_context()
+        
+        # Extract entities using LLM (with fallback)
+        try:
+            extraction = await self._llm_extractor.extract(message, context)
+        except Exception as e:
+            logger.warning(f"LLM extraction failed: {e}")
+            if self.config.enable_fallback:
+                extraction = await self._regex_extractor.extract(message, context)
+            else:
+                raise
+        
+        # Skip state update for noise messages
+        changes = []
+        if not extraction.is_noise:
+            # Update state
+            self._state, changes = self._state_manager.update(
+                self._state,
+                extraction
+            )
+            
+            # Add to memory
+            self._add_to_memory(message, role, extraction)
+            
+            # Extract user info if present
+            self._extract_user_info(extraction)
+        
+        # Calculate latency
+        latency_ms = int((time.perf_counter() - start_time) * 1000)
+        self._latencies.append(latency_ms)
+        
+        if self.config.enable_metrics:
+            logger.debug(f"Process latency: {latency_ms}ms")
+        
+        return ProcessResult(
+            entities=extraction.entities,
+            state=self._state,
+            is_noise=extraction.is_noise,
+            is_change=extraction.is_change,
+            changes=changes,
+            intent=extraction.intent,
+            confidence=extraction.confidence,
+            latency_ms=latency_ms,
+        )
+    
+    def _build_context(self) -> str:
+        """Build context string from recent memory"""
+        if not self._memory:
+            return "Đây là tin nhắn đầu tiên trong cuộc hội thoại."
+        
+        recent = list(self._memory)[-self.config.max_context_window:]
+        
+        lines = []
+        for item in recent:
+            role_label = "User" if item.role == "user" else "Bot"
+            lines.append(f"{role_label}: {item.content}")
+        
+        # Add current state summary
+        if self._state.slots:
+            state_str = ", ".join(f"{k}={v}" for k, v in self._state.slots.items())
+            lines.append(f"Current booking: {state_str}")
+        
+        return "\n".join(lines)
+    
+    def _add_to_memory(
+        self,
+        message: str,
+        role: str,
+        extraction: ExtractionResult
+    ):
+        """Add message to working memory"""
+        item = MemoryItem(
+            content=message,
+            key=f"{role}_{len(self._memory)}",
+            role=role,
+            metadata=MemoryMetadata(
+                confidence=extraction.confidence,
+                tags=list(extraction.entities.keys()),
+            ),
+        )
+        self._memory.append(item)
+    
+    def _extract_user_info(self, extraction: ExtractionResult):
+        """Extract and store user information"""
+        user_fields = ["customer_name", "customer_phone"]
+        for field in user_fields:
+            if field in extraction.entities:
+                self._user_memory[field] = extraction.entities[field]
+    
+    # ========================================================================
+    # State Access
+    # ========================================================================
+    
+    @property
+    def state(self) -> BookingState:
+        """Get current booking state"""
+        return self._state
+    
+    @property
+    def memory(self) -> List[MemoryItem]:
+        """Get all memory items"""
+        return list(self._memory)
+    
+    @property
+    def user_memory(self) -> dict:
+        """Get user persistent memory"""
+        return self._user_memory.copy()
+    
+    # ========================================================================
+    # Metrics
+    # ========================================================================
+    
+    def get_metrics(self) -> dict:
+        """Get performance metrics"""
+        if not self._latencies:
+            return {"count": 0}
+        
+        sorted_latencies = sorted(self._latencies)
+        
+        return {
+            "count": len(self._latencies),
+            "avg_ms": sum(self._latencies) // len(self._latencies),
+            "p50_ms": sorted_latencies[len(sorted_latencies) // 2],
+            "p95_ms": sorted_latencies[int(len(sorted_latencies) * 0.95)],
+            "max_ms": max(self._latencies),
+        }
+    
+    # ========================================================================
+    # Serialization
+    # ========================================================================
+    
+    def to_dict(self) -> dict:
+        """Export memory state for persistence"""
+        return {
+            "session_id": self.session_id,
+            "customer_id": self.customer_id,
+            "state": self._state.to_dict(),
+            "memory": [item.to_dict() for item in self._memory],
+            "user_memory": self._user_memory,
+            "metrics": self.get_metrics(),
+        }
+    
+    def load_state(self, state_dict: dict):
+        """Load state from dict (e.g., from Redis)"""
+        if "state" in state_dict:
+            self._state = BookingState.from_dict(state_dict["state"])
+        if "user_memory" in state_dict:
+            self._user_memory = state_dict["user_memory"]
+        if "memory" in state_dict:
+            self._memory.clear()
+            for item_dict in state_dict["memory"]:
+                self._memory.append(MemoryItem.from_dict(item_dict))