turnstack 0.1.0__py3-none-any.whl

turnstack/reply.py

@@ -0,0 +1,67 @@
+from dataclasses import dataclass, field
+from typing import Optional, List, Literal, Dict, Any
+
+
+@dataclass
+class ReplyOption:
+    """
+    A single option hint returned alongside a menu/confirm reply.
+
+    The developer's WhatsApp adapter uses these to build interactive
+    button or list payloads.  The engine always populates this on
+    menu and confirm nodes so the adapter never has to re-parse the tree.
+    """
+    label: str
+    value: str          # the node key / Option.value — what gets sent back as interactive_id
+    description: str = ""
+
+
+@dataclass
+class Reply:
+    """
+    The engine's response object.
+
+    ``BotEngine.process()`` always returns one of these.
+    The developer's adapter pattern-matches on ``type`` to decide
+    how to send it via their WhatsApp provider.
+
+    Fields
+    ------
+    type:             "text" | "media" | "end" | "error"
+    body:             Text body to send. For media, this is the caption.
+    phone:            Recipient phone number.
+    file_bytes:       Raw file bytes (populated when type="media").
+    filename:         Filename for media (e.g. "report_june.pdf").
+    mime_type:        MIME type for media (e.g. "application/pdf").
+    options:          Option hints for menu/confirm nodes.
+                      Use these to build interactive buttons/lists without
+                      re-reading the tree yourself.
+    node_type:        The type of the current node ("menu", "input", etc.).
+                      Lets the adapter decide whether to send interactive or plain text.
+    current_node:     Current node key — useful for debugging.
+    session_state:    "new" | "active" | "expired"
+    suggested_replies: Simple string list for quick-reply chips (subset of options.label).
+    meta:             Arbitrary metadata dictionary for the adapter.
+                      For example, set ``meta={"button_label": "Select Property"}``
+                      to override the default "Options" button text in interactive lists.
+    """
+    type: Literal["text", "media", "end", "error"]
+    body: str
+    phone: str
+
+    # media fields
+    file_bytes: Optional[bytes] = None
+    filename: Optional[str] = None
+    mime_type: Optional[str] = None
+
+    # interactive hints — populated for menu/confirm nodes
+    options: List[ReplyOption] = field(default_factory=list)
+    node_type: Optional[str] = None           # "menu" | "confirm" | "input" | etc.
+
+    # convenience
+    suggested_replies: List[str] = field(default_factory=list)
+
+    # debug / meta
+    current_node: Optional[str] = None
+    session_state: Optional[str] = None
+    meta: Dict[str, Any] = field(default_factory=dict)

turnstack/session.py

@@ -0,0 +1,130 @@
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional, List
+from datetime import datetime
+from abc import ABC, abstractmethod
+
+
+@dataclass
+class Session:
+    """
+    A single user's conversation state.
+
+    The engine reads and writes this object on every message.
+    Developers can read ``session.collected``,
+    and ``session.context`` inside action and router functions.
+
+    Fields
+    ------
+    phone:           Session key — the user's phone number.
+    lifecycle_state: "new" | "active" | "expired"
+    current_node:    Key of the node the user is currently on.
+    nav_stack:       Back-navigation history.  The engine pushes before
+                     every forward transition and pops on "go back".
+                     Developers should not modify this directly.
+    collected:       Data gathered via Input nodes.
+                     Cleared when the session returns to the entry node.
+    pagination:      Internal state for ListNode pagination.
+    context:         Arbitrary dict for cross-node data.
+                     Use this in router ``before`` functions to load a user
+                     profile, store an invitation, etc.
+    last_active:     UTC timestamp of the last message processed.
+    """
+    user_id: str
+    lifecycle_state: str = "new"
+    current_node: str = "entry"
+    nav_stack: List[str] = field(default_factory=list)
+    collected: Dict[str, Any] = field(default_factory=dict)
+    pagination: Dict[str, Any] = field(default_factory=dict)
+    context: Dict[str, Any] = field(default_factory=dict)
+    last_active: Optional[datetime] = None
+
+    def __post_init__(self):
+        if self.last_active is None:
+            self.last_active = datetime.utcnow()
+
+    # ── lifecycle ──────────────────────────────────────────────────────────
+
+    def touch(self) -> None:
+        """Update last_active and activate a new/expired session."""
+        self.last_active = datetime.utcnow()
+        if self.lifecycle_state in ("new", "expired"):
+            self.lifecycle_state = "active"
+
+    def is_expired(self, timeout_seconds: int) -> bool:
+        if self.lifecycle_state == "expired":
+            return True
+        if self.lifecycle_state == "active" and self.last_active:
+            delta = datetime.utcnow() - self.last_active
+            return delta.total_seconds() > timeout_seconds
+        return False
+
+    def expire(self) -> None:
+        self.lifecycle_state = "expired"
+
+    def reset(self, entry_node: str) -> None:
+        """Reset all flow state, keep phone."""
+        self.current_node = entry_node
+        self.nav_stack = []
+        self.collected = {}
+        self.pagination = {}
+        self.context = {}
+        self.lifecycle_state = "active"
+        self.touch()
+
+    # ── navigation helpers (used by the engine, available to developers) ──
+
+    def go_back(self) -> Optional[str]:
+        """
+        Pop and return the previous node from the nav stack.
+        Returns None if already at the root.
+        """
+        if self.nav_stack:
+            return self.nav_stack.pop()
+        return None
+
+    def go_home(self, entry_node: str) -> None:
+        """Clear the nav stack and return to the entry node."""
+        self.nav_stack.clear()
+        self.current_node = entry_node
+        self.collected = {}
+
+
+class SessionStore(ABC):
+    """
+    Abstract base class for session persistence.
+
+    Implement this for your storage backend (Redis, Postgres, SQLite, etc.).
+    TurnStack ships with :class:`~turnstack.stores.memory.InMemorySessionStore`
+    for development and testing.
+
+    Example Redis implementation outline::
+
+        class RedisSessionStore(SessionStore):
+            def __init__(self, redis_client):
+                self.r = redis_client
+
+            async def get(self, phone):
+                data = await self.r.get(f"session:{phone}")
+                return pickle.loads(data) if data else None
+
+            async def save(self, session):
+                await self.r.setex(f"session:{session.phone}", 3600, pickle.dumps(session))
+
+            async def delete(self, phone):
+                await self.r.delete(f"session:{phone}")
+    """
+
+    @abstractmethod
+    async def get(self, phone: str) -> Optional[Session]:
+        """Load session by phone number. Return None if not found."""
+        ...
+
+    @abstractmethod
+    async def save(self, session: Session) -> None:
+        """Persist session."""
+        ...
+
+    @abstractmethod
+    async def delete(self, phone: str) -> None:
+        """Delete session."""
+        ...

turnstack/stores/__init__.py

@@ -0,0 +1,3 @@
+from .memory import InMemorySessionStore
+
+__all__ = ["InMemorySessionStore"]

turnstack/stores/memory.py

@@ -0,0 +1,60 @@
+import time
+from typing import Dict, Optional
+from ..session import Session, SessionStore
+
+
+class InMemorySessionStore(SessionStore):
+    """
+    In-memory session store with automatic eviction of expired sessions.
+
+    - Sessions are removed when they exceed `session_timeout` seconds since last activity.
+    - Optional `max_sessions` prevents unbounded memory growth.
+    - Cleanup runs automatically on every `get()` and `save()` (with a periodic full sweep).
+
+    For production with high concurrency, consider a persistent store (Redis, SQLite).
+    """
+
+    def __init__(self, session_timeout: int = 1800, max_sessions: int = 10000):
+        self._sessions: Dict[str, Session] = {}
+        self.session_timeout = session_timeout
+        self.max_sessions = max_sessions
+        self._last_cleanup = time.time()
+        self._cleanup_interval = 60  # seconds
+
+    async def get(self, user_id: str) -> Optional[Session]:
+        """Return session if exists and not expired, otherwise None."""
+        self._maybe_cleanup()
+        session = self._sessions.get(user_id)
+        if session and session.is_expired(self.session_timeout):
+            await self.delete(user_id)
+            return None
+        return session
+
+    async def save(self, session: Session) -> None:
+        """Store session, evicting oldest if max_sessions exceeded."""
+        self._maybe_cleanup()
+        # Enforce session limit (only when adding a new session)
+        if len(self._sessions) >= self.max_sessions and session.user_id not in self._sessions:
+            # Remove the session with the oldest last_active
+            oldest_uid = min(self._sessions.items(), key=lambda x: x[1].last_active or 0)[0]
+            await self.delete(oldest_uid)
+        self._sessions[session.user_id] = session
+
+    async def delete(self, user_id: str) -> None:
+        self._sessions.pop(user_id, None)
+
+    def all(self) -> Dict[str, Session]:
+        """Return copy of all sessions (debug only)."""
+        return dict(self._sessions)
+
+    def _maybe_cleanup(self):
+        """Periodically remove all expired sessions."""
+        now = time.time()
+        if now - self._last_cleanup >= self._cleanup_interval:
+            expired = [
+                uid for uid, sess in self._sessions.items()
+                if sess.is_expired(self.session_timeout)
+            ]
+            for uid in expired:
+                del self._sessions[uid]
+            self._last_cleanup = now

turnstack/tree.py

@@ -0,0 +1,151 @@
+"""
+turnstack.tree
+==============
+FlowTree — the single source of truth for a bot's conversation flow.
+
+Developers define their entire flow here using node classes from
+:mod:`turnstack.nodes`.  The tree is validated at engine startup so broken
+flows fail loudly, not silently at runtime.
+"""
+
+from __future__ import annotations
+from typing import Dict, Any, List, Optional, Union
+from .exceptions import FlowValidationError
+from .nodes import BaseNode, NodeDict
+
+# ── node type constants ───────────────────────────────────────────────────────
+NODE_MENU        = "menu"
+NODE_INPUT       = "input"
+NODE_CONFIRM     = "confirm"
+NODE_ACTION      = "action"
+NODE_ROUTER      = "router"
+NODE_LIST        = "list"
+NODE_MEDIA       = "media"
+NODE_INPUT = "input"
+
+# All types that have a single "next" key
+_SINGLE_NEXT = {NODE_INPUT, NODE_ACTION, NODE_MEDIA, NODE_INPUT}
+# All types that have options with individual "next" keys
+_OPTION_NEXT = {NODE_MENU, NODE_CONFIRM}
+
+
+class FlowTree:
+    """
+    Container for all flow nodes.
+
+    Usage::
+
+        from turnstack import FlowTree
+        from turnstack.nodes import Menu, Option, Input, Action, Router, Route
+
+        tree = FlowTree(entry="entry")
+
+        tree.add("entry", Router(
+            routes=[Route(when=lambda s: s.context.get("user"), next="home")],
+            default="welcome",
+        ))
+
+        tree.add("welcome", Menu(
+            text="Welcome! What would you like to do?",
+            options=[
+                Option("Register", next="register_name"),
+                Option("Learn More", next="learn_more"),
+            ]
+        ))
+
+    Nodes can be added as node class instances *or* raw dicts (for backwards
+    compatibility with existing code).
+    """
+
+    def __init__(self, entry: str = "welcome"):
+        self._nodes: Dict[str, NodeDict] = {}
+        self.entry = entry
+
+    # ── public API ────────────────────────────────────────────────────────
+
+    def add(self, name: str, node: Union[BaseNode, NodeDict]) -> "FlowTree":
+        """
+        Register a node under ``name``.
+
+        Accepts either a node class instance (recommended) or a raw dict
+        (legacy / advanced use).
+
+        Returns self so calls can be chained::
+
+            tree.add("a", ...).add("b", ...).add("c", ...)
+        """
+        self._nodes[name] = node.to_dict() if isinstance(node, BaseNode) else node
+        return self
+
+    def get(self, name: str) -> Optional[NodeDict]:
+        """Return the raw node dict for ``name``, or None if not found."""
+        return self._nodes.get(name)
+
+    def all_nodes(self) -> Dict[str, NodeDict]:
+        """Return a copy of all nodes (read-only view for tooling)."""
+        return dict(self._nodes)
+
+    # ── validation ────────────────────────────────────────────────────────
+
+    def validate(self) -> None:
+        """
+        Walk the entire tree and raise :class:`FlowValidationError` on the
+        first broken reference.
+
+        Called automatically by ``BotEngine.__init__``.
+        Developers can also call it manually after building the tree.
+
+        Checks:
+        - Entry node exists
+        - Every ``next`` key points to a real node (or ``"__end__"``)
+        - Every option ``next`` key in menu/confirm nodes points to a real node
+        - Every router ``default`` points to a real node
+        - Every router route ``next`` points to a real node
+        - Every list ``on_select`` points to a real node
+        - No action node references itself as ``next``
+        """
+        errors: List[str] = []
+
+        if self.entry not in self._nodes:
+            errors.append(f"Entry node '{self.entry}' is not defined in the tree.")
+
+        for node_name, node in self._nodes.items():
+            t = node.get("type", "")
+
+            # Existing checks
+            if t in _SINGLE_NEXT:
+                self._check_ref(node_name, node.get("next"), errors)
+
+            elif t in _OPTION_NEXT:
+                options = node.get("options", [])
+                if t == NODE_CONFIRM and len(options) > 3:
+                    errors.append(
+                        f"Confirm node '{node_name}' has {len(options)} options. "
+                        "WhatsApp interactive buttons support at most 3."
+                    )
+                for opt in options:
+                    target = opt.get("next") if isinstance(opt, dict) else None
+                    self._check_ref(f"{node_name} option '{opt.get('label', '?')}'", target, errors)
+
+            elif t == NODE_ROUTER:
+                self._check_ref(f"{node_name} default", node.get("default"), errors)
+                for route in node.get("routes", []):
+                    self._check_ref(f"{node_name} route", route.get("next"), errors)
+
+            elif t == NODE_LIST:
+                self._check_ref(f"{node_name} on_select", node.get("on_select"), errors)
+                extra_opts = node.get("extra_options", [])
+                if len(extra_opts) > 3:
+                    errors.append(
+                        f"ListNode '{node_name}' has {len(extra_opts)} extra_options, "
+                        "but interactive lists support at most 3 static actions."
+                    )
+
+        if errors:
+            raise FlowValidationError(
+                "Flow tree validation failed:\n" + "\n".join(f"  • {e}" for e in errors)
+            )
+
+    def _check_ref(self, context: str, key: Optional[str], errors: List[str]) -> None:
+        if key and key != "__end__" and key not in self._nodes:
+            errors.append(f"{context} → references missing node '{key}'")