busbot-memory 0.1.0__py3-none-any.whl

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/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/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/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))

busbot_memory/core/models.py

@@ -0,0 +1,193 @@
+"""Core data models for BusBot Memory SDK"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from enum import Enum
+
+
+class Intent(str, Enum):
+    """Possible user intents"""
+    BOOK_TICKET = "book_ticket"
+    CANCEL = "cancel"
+    RESCHEDULE = "reschedule"
+    INQUIRY = "inquiry"
+    COMPLAINT = "complaint"
+    CONFIRM = "confirm"
+    GREETING = "greeting"
+    UNCLEAR = "unclear"
+
+
+@dataclass
+class BookingState:
+    """
+    Structured booking state - tracks all slot values
+    
+    Example:
+        state = BookingState(
+            intent=Intent.BOOK_TICKET,
+            slots={"destination": "Đà Nẵng", "time": "08:00"},
+            missing_slots=["customer_name", "phone"]
+        )
+    """
+    intent: str = Intent.UNCLEAR.value
+    slots: Dict[str, Any] = field(default_factory=dict)
+    missing_slots: List[str] = field(default_factory=list)
+    confidence: float = 0.0
+    last_updated: str = field(default_factory=lambda: datetime.now().isoformat())
+    
+    # Slot definitions for bus booking domain
+    SLOT_TYPES = [
+        "departure",       # Điểm đi
+        "destination",     # Điểm đến
+        "date",            # Ngày đi
+        "time",            # Giờ đi
+        "quantity",        # Số vé
+        "seat_type",       # Loại ghế
+        "customer_name",   # Tên khách
+        "customer_phone",  # SĐT khách
+    ]
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "intent": self.intent,
+            "slots": self.slots,
+            "missing_slots": self.missing_slots,
+            "confidence": self.confidence,
+            "last_updated": self.last_updated,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BookingState":
+        return cls(
+            intent=data.get("intent", Intent.UNCLEAR.value),
+            slots=data.get("slots", {}),
+            missing_slots=data.get("missing_slots", []),
+            confidence=data.get("confidence", 0.0),
+            last_updated=data.get("last_updated", datetime.now().isoformat()),
+        )
+    
+    def update_slots(self, new_slots: Dict[str, Any]) -> List[str]:
+        """
+        Update slots and return list of changes made
+        
+        Returns:
+            List of change descriptions, e.g. ["destination: Hải Phòng → Đà Nẵng"]
+        """
+        changes = []
+        for key, new_value in new_slots.items():
+            if new_value is None:
+                continue
+            old_value = self.slots.get(key)
+            if old_value != new_value:
+                if old_value:
+                    changes.append(f"{key}: {old_value} → {new_value}")
+                else:
+                    changes.append(f"{key}: {new_value}")
+                self.slots[key] = new_value
+                
+                # Remove from missing if was missing
+                if key in self.missing_slots:
+                    self.missing_slots.remove(key)
+        
+        self.last_updated = datetime.now().isoformat()
+        self._update_confidence()
+        return changes
+    
+    def _update_confidence(self):
+        """Calculate confidence based on filled slots"""
+        filled = len(self.slots)
+        total = filled + len(self.missing_slots)
+        self.confidence = filled / total if total > 0 else 0.0
+
+
+@dataclass
+class MemoryMetadata:
+    """Metadata for memory items"""
+    memory_type: str = "working"  # working, user, long_term
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    confidence: float = 1.0
+    source: str = "conversation"
+    tags: List[str] = field(default_factory=list)
+    usage_count: int = 0
+    importance: float = 0.5
+    is_obsolete: bool = False
+    superseded_by: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class MemoryItem:
+    """Single memory item in working memory"""
+    id: str = field(default_factory=lambda: datetime.now().strftime("%Y%m%d%H%M%S%f"))
+    content: str = ""
+    key: str = ""
+    role: str = "user"  # user, assistant
+    metadata: MemoryMetadata = field(default_factory=MemoryMetadata)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "content": self.content,
+            "key": self.key,
+            "role": self.role,
+            "metadata": self.metadata.to_dict(),
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MemoryItem":
+        metadata = MemoryMetadata(**data.get("metadata", {}))
+        return cls(
+            id=data.get("id", ""),
+            content=data.get("content", ""),
+            key=data.get("key", ""),
+            role=data.get("role", "user"),
+            metadata=metadata,
+        )
+
+
+@dataclass
+class ExtractionResult:
+    """Result from LLM entity extraction"""
+    entities: Dict[str, Any] = field(default_factory=dict)
+    intent: str = Intent.UNCLEAR.value
+    is_noise: bool = False
+    is_change: bool = False
+    changed_fields: List[str] = field(default_factory=list)
+    confidence: float = 0.0
+    raw_response: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ProcessResult:
+    """
+    Final result from memory.process() call
+    
+    This is the main output that users of the SDK will work with.
+    """
+    entities: Dict[str, Any] = field(default_factory=dict)
+    state: BookingState = field(default_factory=BookingState)
+    is_noise: bool = False
+    is_change: bool = False
+    changes: List[str] = field(default_factory=list)
+    intent: str = Intent.UNCLEAR.value
+    confidence: float = 0.0
+    latency_ms: int = 0
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "entities": self.entities,
+            "state": self.state.to_dict(),
+            "is_noise": self.is_noise,
+            "is_change": self.is_change,
+            "changes": self.changes,
+            "intent": self.intent,
+            "confidence": self.confidence,
+            "latency_ms": self.latency_ms,
+        }

busbot_memory/domains/__init__.py

@@ -0,0 +1 @@
+"""Domains module - placeholder for Phase 2"""

busbot_memory/extractors/__init__.py

@@ -0,0 +1,7 @@
+"""Extractors module exports"""
+
+from busbot_memory.extractors.base import BaseExtractor
+from busbot_memory.extractors.llm import LLMExtractor
+from busbot_memory.extractors.regex import RegexExtractor
+
+__all__ = ["BaseExtractor", "LLMExtractor", "RegexExtractor"]

busbot_memory/extractors/base.py

@@ -0,0 +1,27 @@
+"""Base extractor interface"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+from busbot_memory.core.models import ExtractionResult
+
+
+class BaseExtractor(ABC):
+    """Abstract base class for entity extractors"""
+    
+    @abstractmethod
+    async def extract(
+        self,
+        message: str,
+        context: Optional[str] = None
+    ) -> ExtractionResult:
+        """
+        Extract entities from message
+        
+        Args:
+            message: User message to extract from
+            context: Optional conversation context
+            
+        Returns:
+            ExtractionResult with entities, intent, and flags
+        """
+        pass

busbot_memory/extractors/llm.py

@@ -0,0 +1,197 @@
+"""LLM-based entity extractor using Groq"""
+
+import json
+import logging
+from typing import Optional
+
+from busbot_memory.extractors.base import BaseExtractor
+from busbot_memory.core.models import ExtractionResult
+from busbot_memory.core.config import BusBotConfig
+
+logger = logging.getLogger(__name__)
+
+
+# Optimized prompt for Vietnamese bus booking - compact for low latency
+EXTRACTION_PROMPT = """Bạn là NLU system cho đặt vé xe Việt Nam. Extract thông tin từ tin nhắn.
+
+OUTPUT JSON:
+{
+  "entities": {
+    "departure": "điểm đi nếu có",
+    "destination": "điểm đến nếu có", 
+    "date": "YYYY-MM-DD hoặc 'ngày mai'/'hôm nay' nếu có",
+    "time": "HH:MM nếu có (8 giờ sáng = 08:00, 2 giờ chiều = 14:00)",
+    "quantity": số nguyên nếu có,
+    "seat_type": "ghế ngồi|giường nằm|limousine nếu có",
+    "customer_name": "họ tên nếu có",
+    "customer_phone": "số điện thoại nếu có"
+  },
+  "intent": "book_ticket|cancel|reschedule|inquiry|complaint|confirm|greeting|unclear",
+  "is_noise": true nếu chỉ là filler ("ừ","ok","dạ","chờ xíu"),
+  "is_change": true nếu đổi thông tin đã cung cấp trước đó,
+  "changed_fields": ["field1"] nếu is_change=true,
+  "confidence": 0.0-1.0
+}
+
+RULES:
+- Chỉ điền field nếu có info, bỏ null
+- is_noise=true với câu filler vô nghĩa
+- Chỉ trả JSON, không giải thích
+
+CONTEXT: {context}
+MESSAGE: {message}"""
+
+
+class LLMExtractor(BaseExtractor):
+    """
+    LLM-based entity extractor using Groq (primary) or OpenAI (fallback)
+    
+    Example:
+        extractor = LLMExtractor(config)
+        result = await extractor.extract("đặt 2 vé đi đà nẵng ngày mai")
+    """
+    
+    def __init__(self, config: BusBotConfig):
+        self.config = config
+        self._groq_client = None
+        self._openai_client = None
+    
+    @property
+    def groq_client(self):
+        """Lazy init Groq client"""
+        if self._groq_client is None and self.config.groq_api_key:
+            try:
+                from groq import AsyncGroq
+                self._groq_client = AsyncGroq(api_key=self.config.groq_api_key)
+            except ImportError:
+                logger.warning("groq package not installed")
+        return self._groq_client
+    
+    @property
+    def openai_client(self):
+        """Lazy init OpenAI client"""
+        if self._openai_client is None and self.config.openai_api_key:
+            try:
+                from openai import AsyncOpenAI
+                self._openai_client = AsyncOpenAI(api_key=self.config.openai_api_key)
+            except ImportError:
+                logger.warning("openai package not installed")
+        return self._openai_client
+    
+    async def extract(
+        self,
+        message: str,
+        context: Optional[str] = None
+    ) -> ExtractionResult:
+        """
+        Extract entities using Groq LLM
+        
+        Falls back to OpenAI if Groq fails and openai_api_key is configured.
+        """
+        try:
+            return await self._extract_with_groq(message, context)
+        except Exception as e:
+            logger.warning(f"Groq extraction failed: {e}")
+            
+            if self.openai_client:
+                logger.info("Falling back to OpenAI")
+                return await self._extract_with_openai(message, context)
+            
+            raise
+    
+    async def _extract_with_groq(
+        self,
+        message: str,
+        context: Optional[str] = None
+    ) -> ExtractionResult:
+        """Extract using Groq"""
+        if not self.groq_client:
+            raise RuntimeError("Groq client not available")
+        
+        prompt = EXTRACTION_PROMPT.format(
+            message=message,
+            context=context or "Không có context"
+        )
+        
+        try:
+            response = await self.groq_client.chat.completions.create(
+                model=self.config.groq_model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0.1,
+                max_tokens=500,
+                response_format={"type": "json_object"},
+            )
+            
+            raw = response.choices[0].message.content
+            return self._parse_response(raw)
+            
+        except Exception as e:
+            # Try fallback model
+            logger.warning(f"Primary model failed, trying fallback: {e}")
+            
+            response = await self.groq_client.chat.completions.create(
+                model=self.config.groq_fallback_model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0.1,
+                max_tokens=500,
+            )
+            
+            raw = response.choices[0].message.content
+            return self._parse_response(raw)
+    
+    async def _extract_with_openai(
+        self,
+        message: str,
+        context: Optional[str] = None
+    ) -> ExtractionResult:
+        """Extract using OpenAI"""
+        if not self.openai_client:
+            raise RuntimeError("OpenAI client not available")
+        
+        prompt = EXTRACTION_PROMPT.format(
+            message=message,
+            context=context or "Không có context"
+        )
+        
+        response = await self.openai_client.chat.completions.create(
+            model=self.config.openai_model,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0.1,
+            max_tokens=500,
+            response_format={"type": "json_object"},
+        )
+        
+        raw = response.choices[0].message.content
+        return self._parse_response(raw)
+    
+    def _parse_response(self, raw: str) -> ExtractionResult:
+        """Parse LLM response into ExtractionResult"""
+        try:
+            # Clean up response if needed
+            raw = raw.strip()
+            if raw.startswith("```"):
+                raw = raw.split("```")[1]
+                if raw.startswith("json"):
+                    raw = raw[4:]
+            
+            data = json.loads(raw)
+            
+            # Extract entities, removing null values
+            entities = {k: v for k, v in data.get("entities", {}).items() if v is not None}
+            
+            return ExtractionResult(
+                entities=entities,
+                intent=data.get("intent", "unclear"),
+                is_noise=data.get("is_noise", False),
+                is_change=data.get("is_change", False),
+                changed_fields=data.get("changed_fields", []),
+                confidence=data.get("confidence", 0.5),
+                raw_response=raw,
+            )
+            
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse LLM response: {e}\nRaw: {raw}")
+            return ExtractionResult(
+                confidence=0.0,
+                raw_response=raw,
+            )

busbot_memory/extractors/regex.py

@@ -0,0 +1,128 @@
+"""Regex-based entity extractor (fallback)"""
+
+import re
+from typing import Optional
+
+from busbot_memory.extractors.base import BaseExtractor
+from busbot_memory.core.models import ExtractionResult
+
+
+# Vietnam provinces/cities
+LOCATIONS = (
+    r"Hà Nội|Hải Phòng|Hải Dương|Nam Định|Ninh Bình|Thái Bình|Vĩnh Phúc|Bắc Ninh|"
+    r"Bắc Giang|Quảng Ninh|Lạng Sơn|Cao Bằng|Hòa Bình|Sơn La|Lai Châu|Điện Biên|"
+    r"Lào Cai|Yên Bái|Phú Thọ|Tuyên Quang|Thái Nguyên|Hà Giang|Sài Gòn|TP HCM|"
+    r"TP\.?\s*HCM|Hồ Chí Minh|Đà Nẵng|Huế|Quảng Nam|Quảng Ngãi|Bình Định|Phú Yên|"
+    r"Khánh Hòa|Nha Trang|Ninh Thuận|Bình Thuận|Đà Lạt|Lâm Đồng|Bình Phước|Tây Ninh|"
+    r"Bình Dương|Đồng Nai|Vũng Tàu|Bà Rịa|Long An|Tiền Giang|Mỹ Tho|Bến Tre|Trà Vinh|"
+    r"Vĩnh Long|Cần Thơ|Đồng Tháp|An Giang|Kiên Giang|Hậu Giang|Sóc Trăng|Bạc Liêu|"
+    r"Cà Mau|Nghệ An|Vinh|Hà Tĩnh|Quảng Bình|Quảng Trị|Kon Tum|Gia Lai|Đắk Lắk|"
+    r"Đắk Nông|Buôn Ma Thuột"
+)
+
+PATTERNS = {
+    "location": rf"\b({LOCATIONS})\b",
+    "time": r"\b(\d{1,2})\s*(?:h|giờ|:|g)\s*(\d{0,2})\b",
+    "date": r"(ngày mai|hôm nay|hôm qua|ngày kia|\d{1,2}[/-]\d{1,2}(?:[/-]\d{2,4})?)",
+    "phone": r"\b(0\d{9}|0\d{3}[\s.-]?\d{3}[\s.-]?\d{3,4})\b",
+    "quantity": r"\b(\d+)\s*(vé|ghế|chỗ|người|suất)\b",
+    "seat_type": r"\b(ghế ngồi|giường nằm|limousine|vip|thường)\b",
+}
+
+NOISE_PATTERNS = [
+    r"^(ừ|uh|à|ờ|dạ|vâng|ok|được|rồi|nhé|nha)\s*$",
+    r"^(xin chào|chào|hello|hi|alo)\s*",
+    r"^(cảm ơn|thanks|thank you)\s*$",
+]
+
+INTENT_KEYWORDS = {
+    "book_ticket": ["đặt", "mua", "lấy", "book"],
+    "cancel": ["hủy", "cancel", "không đi nữa"],
+    "reschedule": ["đổi", "chuyển", "thay đổi", "dời"],
+    "inquiry": ["hỏi", "giá", "mấy giờ", "còn không", "bao nhiêu"],
+    "complaint": ["khiếu nại", "phàn nàn", "tệ", "chán"],
+    "confirm": ["xác nhận", "đồng ý", "ok", "được"],
+}
+
+
+class RegexExtractor(BaseExtractor):
+    """
+    Regex-based entity extractor
+    
+    Used as fallback when LLM is unavailable or fails.
+    Lower accuracy but zero latency and no API costs.
+    """
+    
+    async def extract(
+        self,
+        message: str,
+        context: Optional[str] = None
+    ) -> ExtractionResult:
+        """Extract entities using regex patterns"""
+        entities = {}
+        
+        # Extract locations
+        locations = re.findall(PATTERNS["location"], message, re.IGNORECASE)
+        if locations:
+            # First location = destination (simplified logic)
+            entities["destination"] = locations[0]
+            if len(locations) > 1:
+                entities["departure"] = locations[1]
+        
+        # Extract time
+        time_match = re.search(PATTERNS["time"], message, re.IGNORECASE)
+        if time_match:
+            hour = time_match.group(1)
+            minute = time_match.group(2) or "00"
+            # Simple AM/PM detection
+            if "chiều" in message or "tối" in message:
+                hour = str(int(hour) + 12) if int(hour) < 12 else hour
+            entities["time"] = f"{int(hour):02d}:{int(minute):02d}"
+        
+        # Extract date
+        date_match = re.search(PATTERNS["date"], message, re.IGNORECASE)
+        if date_match:
+            entities["date"] = date_match.group(1)
+        
+        # Extract phone
+        phone_match = re.search(PATTERNS["phone"], message)
+        if phone_match:
+            entities["customer_phone"] = phone_match.group(1).replace(" ", "").replace("-", "")
+        
+        # Extract quantity
+        qty_match = re.search(PATTERNS["quantity"], message)
+        if qty_match:
+            entities["quantity"] = int(qty_match.group(1))
+        
+        # Extract seat type
+        seat_match = re.search(PATTERNS["seat_type"], message, re.IGNORECASE)
+        if seat_match:
+            entities["seat_type"] = seat_match.group(1).lower()
+        
+        # Check if noise
+        is_noise = any(
+            re.match(pattern, message.strip(), re.IGNORECASE)
+            for pattern in NOISE_PATTERNS
+        )
+        
+        # Detect intent
+        intent = self._detect_intent(message)
+        
+        return ExtractionResult(
+            entities=entities,
+            intent=intent,
+            is_noise=is_noise,
+            is_change=False,  # Regex can't detect change-of-mind reliably
+            changed_fields=[],
+            confidence=0.7 if entities else 0.3,
+        )
+    
+    def _detect_intent(self, message: str) -> str:
+        """Simple keyword-based intent detection"""
+        message_lower = message.lower()
+        
+        for intent, keywords in INTENT_KEYWORDS.items():
+            if any(kw in message_lower for kw in keywords):
+                return intent
+        
+        return "unclear"

busbot_memory/memory/__init__.py

@@ -0,0 +1 @@
+"""Memory module - placeholder for Phase 2"""

busbot_memory/state/__init__.py

@@ -0,0 +1,5 @@
+"""State module exports"""
+
+from busbot_memory.state.manager import StateManager
+
+__all__ = ["StateManager"]

busbot_memory/state/manager.py

@@ -0,0 +1,90 @@
+"""State management for booking flow"""
+
+import logging
+from typing import Optional, Tuple, List
+
+from busbot_memory.core.models import BookingState, ExtractionResult
+
+logger = logging.getLogger(__name__)
+
+
+class StateManager:
+    """
+    Manages booking state updates
+    
+    Handles:
+    - Merging new entities into state
+    - Tracking changes (change-of-mind)
+    - Managing missing slots
+    """
+    
+    # Default slots to track for bus booking
+    DEFAULT_SLOTS = [
+        "departure",
+        "destination", 
+        "date",
+        "time",
+        "quantity",
+        "seat_type",
+        "customer_name",
+        "customer_phone",
+    ]
+    
+    def __init__(self, slot_types: Optional[List[str]] = None):
+        self.slot_types = slot_types or self.DEFAULT_SLOTS
+    
+    def update(
+        self,
+        current_state: BookingState,
+        extraction: ExtractionResult
+    ) -> Tuple[BookingState, List[str]]:
+        """
+        Update state with extracted entities
+        
+        Args:
+            current_state: Current booking state
+            extraction: Extraction result from LLM/regex
+            
+        Returns:
+            Tuple of (updated_state, list_of_changes)
+        """
+        # Update intent if detected
+        if extraction.intent and extraction.intent != "unclear":
+            current_state.intent = extraction.intent
+        
+        # Update slots
+        changes = current_state.update_slots(extraction.entities)
+        
+        # Track changes from LLM change-of-mind detection
+        if extraction.is_change and extraction.changed_fields:
+            for field in extraction.changed_fields:
+                if field not in [c.split(":")[0] for c in changes]:
+                    changes.append(f"{field}: changed")
+        
+        # Update missing slots
+        current_state.missing_slots = self._calculate_missing_slots(current_state)
+        
+        logger.debug(f"State updated: {len(changes)} changes, {len(current_state.missing_slots)} missing")
+        
+        return current_state, changes
+    
+    def _calculate_missing_slots(self, state: BookingState) -> List[str]:
+        """Calculate which slots are still missing"""
+        # For booking intent, we need certain slots
+        if state.intent == "book_ticket":
+            required = ["destination", "date", "time", "quantity", "customer_name", "customer_phone"]
+        elif state.intent == "reschedule":
+            required = ["date", "time"]
+        elif state.intent == "cancel":
+            required = ["customer_phone"]
+        else:
+            required = ["destination"]
+        
+        missing = [slot for slot in required if slot not in state.slots]
+        return missing
+    
+    def create_initial_state(self) -> BookingState:
+        """Create a fresh booking state"""
+        return BookingState(
+            missing_slots=self._calculate_missing_slots(BookingState())
+        )

busbot_memory/storage/__init__.py

@@ -0,0 +1 @@
+"""Storage module - placeholder for Phase 2"""

busbot_memory/utils/__init__.py

@@ -0,0 +1 @@
+"""Utils module - placeholder for Phase 2"""

busbot_memory/version.py

@@ -0,0 +1,2 @@
+"""Version information"""
+__version__ = "0.1.0"

busbot_memory-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+busbot_memory/__init__.py,sha256=dB6vdBKqfcsq3u_lmHND8eg7M9u1T2OtMPtzvxKVbXQ,436
+busbot_memory/version.py,sha256=FtxHurtf6YcDi4rEA3wEUJiwTKc8mZ9jDZQbq6lQxMg,48
+busbot_memory/core/__init__.py,sha256=feszx5rF9gi4eSP9dlgeN2a-xTfwgdS0ZM3tQNQ9KG8,381
+busbot_memory/core/config.py,sha256=Q-ffA9lM_7zVHep5qMIy8AfhjIGSWiyUW2wE0NGmPCM,1715
+busbot_memory/core/manager.py,sha256=djJJ3C-DbxZqDHiRL-vYnzGyM9xZvSdhfZ8_x1PhxQE,8094
+busbot_memory/core/models.py,sha256=8VM-xSBos839arFjp7vKRJsK3e-rMnZrjNU46nmwX7A,6211
+busbot_memory/domains/__init__.py,sha256=Z7zCVBmCcXi56N5CMnM3KCvYm7TjCvRnv1i0zOrhjlU,47
+busbot_memory/extractors/__init__.py,sha256=Z_lj6BkF9P-6PQPgijQayrkMR7m3jp3Emgx1Pf8L20I,264
+busbot_memory/extractors/base.py,sha256=iBKnOXRo9WW1R-2kqtKkjs2n_YFtD6paoar7mV_AJLM,671
+busbot_memory/extractors/llm.py,sha256=G-qkv6IuVZWfAzo4l6DR5o8fsuSd1UUw5auln-qltdU,6847
+busbot_memory/extractors/regex.py,sha256=AMTzQcrDlkJsYzOSJQNeM1P8Vma6dViRFrsapBgnz_U,4933
+busbot_memory/memory/__init__.py,sha256=Pirbd_SpJaBnt1l7tpXT86QHzrhQ--Qg2gJuP_jHnQU,46
+busbot_memory/state/__init__.py,sha256=O-f2tTE2NhyhFv-GT7Iytb1w_SpPARLbT894QqU0u0c,109
+busbot_memory/state/manager.py,sha256=E_KP3RNCTA4HneYTpuuk-M7DroDIFlJY-UtuEdsRaWM,2915
+busbot_memory/storage/__init__.py,sha256=_iMe3AwItiW2RoimbzphMsSwqccX6GyAZFAqh1UEeuo,47
+busbot_memory/utils/__init__.py,sha256=7wzd5GIIgAfEo9u9lRTpU6FdIKdQslbNHfc_4Cce_9Q,45
+busbot_memory-0.1.0.dist-info/METADATA,sha256=HavIxnEJ4BInBd6Di_uYlS7-lXnHVXKdma7viWLqgAU,3628
+busbot_memory-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+busbot_memory-0.1.0.dist-info/top_level.txt,sha256=s1GaBVqTS_djIs8JsgAg6-Z2vOIkCY4NRM-avkk-M04,14
+busbot_memory-0.1.0.dist-info/RECORD,,

busbot_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

busbot_memory-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+busbot_memory