django-unicom 25.2.31.dev0__tar.gz → 25.2.32.dev0__tar.gz

{django_unicom-25.2.31.dev0 → django_unicom-25.2.32.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-unicom
-Version: 25.2.31.dev0
+Version: 25.2.32.dev0
 Summary: Unified communication layer for Django (Telegram, WhatsApp, Email)
 Home-page: https://github.com/meena-erian/unicom
 Author: Meena (Menas) Erian
@@ -61,6 +61,9 @@ Dynamic: summary
   - [Telegram-Specific Features](#telegram-specific-features)
     - [Typing Indicators](#-typing-indicators)
     - [Interactive Buttons & Callbacks](#-interactive-messages-with-action-buttons)
+      - [Handling Button Clicks](#-handling-button-clicks)
+      - [Tool-Generated Buttons](#-tool-generated-buttons-advanced)
+      - [Button Routing Best Practices](#-button-routing-best-practices)
     - [Editing Messages](#-editing-telegram-messages)
     - [File Downloads and Voice Messages](#-file-downloads-and-voice-messages)
   - [LLM Integration](#llm-integration)
@@ -287,17 +290,19 @@ message = email_channel.send_message({
 })
 
 # 📱 Telegram only: Message with interactive buttons
-from unicom.services.telegram.create_inline_keyboard import create_simple_keyboard
+from unicom.services.telegram.create_inline_keyboard import create_callback_button, create_inline_keyboard
 
+# For initial messages, use legacy mode (no message parameter)
+# Buttons will work but won't be linked to CallbackExecution
 message = telegram_channel.send_message({
     'chat_id': 'user_chat_id',
     'text': 'Choose an option:',
-    'reply_markup': create_simple_keyboard(
-        "Confirm", "confirm_yes",
-        "Cancel", "confirm_no"
-    )
+    'reply_markup': create_inline_keyboard([
+        [create_callback_button("Confirm", {"action": "confirm"})],
+        [create_callback_button("Cancel", {"action": "cancel"})]
+    ])
 })
-# See "Interactive Buttons & Callbacks" section for handling button clicks
+# See "Interactive Buttons & Callbacks" section for full details
 ```
 
 ### Message Model
@@ -441,14 +446,14 @@ reply = message.reply_with({
 })
 
 # 📱 Telegram only: Reply with interactive buttons
-from unicom.services.telegram.create_inline_keyboard import create_simple_keyboard
+from unicom.services.telegram.create_inline_keyboard import create_inline_keyboard, create_callback_button
 
 reply = message.reply_with({
     'text': 'Would you like to continue?',
-    'reply_markup': create_simple_keyboard(
-        "Yes", "continue_yes",
-        "No", "continue_no"
-    )
+    'reply_markup': create_inline_keyboard([
+        [create_callback_button("Yes", {"action": "continue", "value": True}, message=message)],
+        [create_callback_button("No", {"action": "continue", "value": False}, message=message)]
+    ])
 })
 # See "Interactive Buttons & Callbacks" section for handling button clicks
 ```
@@ -660,39 +665,46 @@ message = telegram_channel.send_message({
 
 #### 📱 Interactive Messages with Action Buttons
 
-Telegram channels support inline keyboard buttons for interactive messages:
+Telegram channels support inline keyboard buttons. Pass any JSON-serializable `callback_data`:
 
 ```python
 from unicom.services.telegram.create_inline_keyboard import (
-    create_inline_keyboard, create_callback_button, create_url_button, create_simple_keyboard
+    create_inline_keyboard, create_callback_button, create_url_button
 )
 
-# Send message with custom inline keyboard
-reply_markup = create_inline_keyboard([
-    [create_callback_button("Yes", "yes_action"), create_callback_button("No", "no_action")],
-    [create_url_button("Visit Website", "https://example.com")]
-])
-
-message = telegram_channel.send_message({
-    'chat_id': 'telegram_chat_id',
+# When replying to existing messages, pass message and account for full features
+# This creates CallbackExecution records and enables security + tool integration
+incoming_message.reply_with({
     'text': 'Do you want to continue?',
-    'reply_markup': reply_markup
+    'reply_markup': create_inline_keyboard([
+        [create_callback_button("Yes", {"action": "confirm"}, message=incoming_message)],
+        [create_callback_button("No", {"action": "cancel"}, message=incoming_message)],
+        [create_url_button("Visit Website", "https://example.com")]
+    ])
 })
 
-# Quick helper for simple button layouts
-simple_keyboard = create_simple_keyboard("Option 1", "opt1", "Option 2", "opt2")
-message = telegram_channel.send_message({
-    'chat_id': 'telegram_chat_id',
-    'text': 'Choose an option:',
-    'reply_markup': simple_keyboard
+# Rich data structures with any JSON-serializable data
+incoming_message.reply_with({
+    'text': 'Choose a product:',
+    'reply_markup': create_inline_keyboard([
+        [create_callback_button("Product A", {"product_id": 123, "price": 29.99, "stock": 5}, message=incoming_message)],
+        [create_callback_button("Product B", {"product_id": 456, "price": 49.99, "stock": 12}, message=incoming_message)]
+    ])
 })
 
-# Works with all wrapper functions like reply_with
-reply = message.reply_with({
-    'text': 'Here are your options:',
+# Optional expiration for time-limited offers
+from django.utils import timezone
+from datetime import timedelta
+
+incoming_message.reply_with({
+    'text': 'Limited time offer!',
     'reply_markup': create_inline_keyboard([
-        [create_callback_button("Confirm", "confirm_action")],
-        [create_callback_button("Cancel", "cancel_action")]
+        [create_callback_button(
+            "Claim Offer",
+            {"offer_id": 789, "discount": 0.5},
+            message=incoming_message,
+            expires_at=timezone.now() + timedelta(hours=24)
+        )]
     ])
 })
 ```
@@ -706,62 +718,53 @@ from django.dispatch import receiver
 from unicom.signals import telegram_callback_received
 
 @receiver(telegram_callback_received)
-def handle_button_clicks(sender, callback_execution, **kwargs):
+def handle_button_clicks(sender, callback_execution, clicking_account, original_message, tool_call, **kwargs):
     """
-    Handle all button clicks with automatic security validation and idempotency.
-    Each callback is processed exactly once across all Django processes.
-
-    Available data in callback_execution:
-    - callback_data: The button's callback_data string
-    - authorized_user: The validated user (Account object)
-    - callback_message: Message object for sending responses
-    - original_message: The message that contained the buttons
-    """
-    # Get the button data and validated user
-    button_data = callback_execution.callback_data  # e.g., "confirm_action"
-    user = callback_execution.authorized_user       # Security-validated user
-    callback_msg = callback_execution.callback_message  # For replying
-    original_msg = callback_execution.original_message  # Original message with buttons
-
-    if button_data == 'confirm_action':
-        # Process confirmation
-        process_user_confirmation(user)
-        callback_msg.reply_with({'text': '✅ Confirmed!'})
-
-    elif button_data == 'cancel_action':
-        # Process cancellation
-        callback_msg.reply_with({'text': '❌ Cancelled'})
-
-    elif button_data.startswith('product_'):
-        # Handle dynamic data (e.g., "product_123")
-        product_id = button_data.split('_')[1]
-        product = get_product(product_id)
-
-        # Send response with new buttons
-        callback_msg.reply_with({
-            'text': f'Product: {product.name}\nPrice: ${product.price}',
-            'reply_markup': create_simple_keyboard(
-                'Buy Now', f'buy_{product_id}',
-                'Add to Cart', f'cart_{product_id}'
-            )
-        })
+    Handle button clicks.
 
-    elif button_data == 'show_menu':
-        # Update the original message (edit in place)
-        from unicom.services.telegram.create_inline_keyboard import create_inline_keyboard, create_callback_button
-        callback_msg.edit_original_message({
-            'text': '📋 Main Menu:',
-            'reply_markup': create_inline_keyboard([
-                [create_callback_button("Option 1", "opt1")],
-                [create_callback_button("Option 2", "opt2")]
-            ])
-        })
+    Args:
+        callback_execution: CallbackExecution instance with callback_data
+        clicking_account: The unicom.Account that clicked the button
+        original_message: The Message containing the buttons
+        tool_call: Optional ToolCall if button was from a tool (None otherwise)
 
-# Security is automatic:
-# - Only authorized users can click buttons (prevents group chat abuse)
-# - Each callback processes exactly once (prevents duplicate actions)
-# - Built-in protection against forwarded messages and replay attacks
-# - Loading indicators stop automatically (answerCallbackQuery)
+    Note: unicom.Account represents a platform user (e.g., Telegram user, email address).
+    To access Django auth.User: clicking_account.member.user (if member exists)
+    """
+    data = callback_execution.callback_data
+
+    # Handle dict callback_data
+    if isinstance(data, dict):
+        if data.get('action') == 'confirm':
+            process_confirmation(clicking_account)
+            original_message.reply_with({'text': '✅ Confirmed!'})
+
+        elif data.get('action') == 'buy_product':
+            product_id = data['product_id']
+            product = get_product(product_id)
+
+            # Create new buttons with callback_data
+            original_message.reply_with({
+                'text': f'Product: {product.name}\nPrice: ${product.price}',
+                'reply_markup': create_inline_keyboard([
+                    [create_callback_button('Confirm Purchase', {'action': 'confirm_purchase', 'product_id': product_id}, message=original_message, account=clicking_account)],
+                    [create_callback_button('Cancel', {'action': 'cancel'}, message=original_message, account=clicking_account)]
+                ])
+            })
+
+    # Handle string callback_data
+    elif data == 'cancel':
+        original_message.reply_with({'text': '❌ Cancelled'})
+
+    # Access Django User if needed
+    if clicking_account.member and clicking_account.member.user:
+        django_user = clicking_account.member.user
+        # Do something with django_user
+
+    # If button was from a tool, you can respond to the tool call
+    if tool_call and data.get('action') == 'confirm':
+        # Inform the LLM that the user confirmed
+        tool_call.respond({'confirmed': True, 'user_id': clicking_account.id})
 ```
 
 **Where to put your callback handler:**
@@ -781,24 +784,188 @@ class YourAppConfig(AppConfig):
 
 Make sure your app is in `INSTALLED_APPS` in settings.py.
 
-**Security Features (Automatic):**
+**Key Features:**
+
+- **Flexible Data**: Store any JSON-serializable data (dict, list, str, int, bool, None)
+- **Security**: Only the intended account can click the button
+- **Expiration**: Optional `expires_at` parameter for time-limited buttons
+- **Reusable**: Buttons can be clicked multiple times (developers control behavior)
+- **Efficient**: Callback data stored in DB, only ID sent to Telegram
+- **No Message Creation**: Button clicks don't create Message objects - they only trigger handlers
+- **Tool Integration**: When buttons are from tools, handlers can use `tool_call.respond()` to inform the LLM
+
+#### 📱 Tool-Generated Buttons (Advanced)
+
+When a tool sends buttons, you can link them to the ToolCall so handlers can respond to the LLM:
+
+```python
+# In your tool code (e.g., unibot Tool model)
+def my_interactive_tool(question: str) -> str:
+    """Ask user a question with buttons and wait for response."""
+
+    # tool_call is available in tool context - no need to query!
+    # Just use it directly
+
+    # Send message with buttons linked to this tool call
+    message.reply_with({
+        'text': f'Question: {question}',
+        'reply_markup': create_inline_keyboard([
+            [create_callback_button(
+                "Yes",
+                {"tool": "my_interactive_tool", "action": "answer", "value": "yes"},
+                message=message,
+                tool_call=tool_call  # Use the context variable
+            )],
+            [create_callback_button(
+                "No",
+                {"tool": "my_interactive_tool", "action": "answer", "value": "no"},
+                message=message,
+                tool_call=tool_call
+            )]
+        ])
+    })
+
+    # Return None to defer response - tool will respond when user clicks
+    return None
+
+# In your callback handler (callback_handlers.py)
+@receiver(telegram_callback_received)
+def handle_tool_buttons(sender, callback_execution, clicking_account, original_message, tool_call, **kwargs):
+    data = callback_execution.callback_data
+
+    # Route to correct handler based on tool name
+    if isinstance(data, dict) and data.get('tool') == 'my_interactive_tool':
+        if data.get('action') == 'answer':
+            # User clicked a button from the tool
+            answer = data['value']
+
+            # Respond to the tool call - this will notify the LLM
+            if tool_call:
+                tool_call.respond({
+                    'question_answered': True,
+                    'answer': answer,
+                    'user_id': clicking_account.id
+                })
+
+            # Also send confirmation to user
+            original_message.reply_with({
+                'text': f'✅ You answered: {answer}'
+            })
+```
+
+#### 📱 Button Routing Best Practices
+
+When building applications with multiple button types, use a consistent routing strategy:
+
+**Recommended Pattern: Use a "type" or "handler" field**
+
+```python
+# Define button types as constants for consistency
+BUTTON_TYPES = {
+    'PRODUCT': 'product_handler',
+    'NAVIGATION': 'nav_handler',
+    'SETTINGS': 'settings_handler',
+    'TOOL': 'tool_handler'
+}
+
+# Create buttons with type field
+create_callback_button(
+    "Buy Product A",
+    {
+        "type": "product_handler",  # Routes to product handler
+        "action": "buy",
+        "product_id": 123
+    },
+    message=message
+)
+
+create_callback_button(
+    "Settings",
+    {
+        "type": "settings_handler",  # Routes to settings handler
+        "action": "show_settings"
+    },
+    message=message
+)
+
+# In your callback handler - route based on type
+@receiver(telegram_callback_received)
+def handle_all_buttons(sender, callback_execution, clicking_account, original_message, tool_call, **kwargs):
+    data = callback_execution.callback_data
+
+    if not isinstance(data, dict):
+        return  # Skip non-dict data
+
+    # Route to appropriate handler based on type
+    handler_type = data.get('type')
+
+    if handler_type == 'product_handler':
+        handle_product_buttons(data, clicking_account, original_message)
+    elif handler_type == 'settings_handler':
+        handle_settings_buttons(data, clicking_account, original_message)
+    elif handler_type == 'tool_handler':
+        handle_tool_buttons(data, clicking_account, original_message, tool_call)
+    else:
+        # Unknown type - log or handle gracefully
+        print(f"Unknown button type: {handler_type}")
+
+def handle_product_buttons(data, account, message):
+    """Handle product-related button clicks"""
+    if data.get('action') == 'buy':
+        product_id = data['product_id']
+        # Process purchase...
+        message.reply_with({'text': f'Processing purchase for product {product_id}'})
+
+def handle_settings_buttons(data, account, message):
+    """Handle settings-related button clicks"""
+    if data.get('action') == 'show_settings':
+        # Show settings menu...
+        message.edit_original_message({'text': '⚙️ Settings Menu'})
+
+def handle_tool_buttons(data, account, message, tool_call):
+    """Handle tool-generated button clicks"""
+    if tool_call and data.get('action') == 'confirm':
+        tool_call.respond({'confirmed': True})
+        message.reply_with({'text': '✅ Confirmed'})
+```
+
+**Alternative Pattern: Multiple Signal Receivers**
 
-- **Authorization**: Only the intended recipient can click buttons
-  - In private chats: Only that user can click
-  - In group chats: Only the original message recipient can click
-  - Forwarded messages: Buttons are automatically disabled
+```python
+# Register separate handlers for different button types
+@receiver(telegram_callback_received)
+def handle_product_buttons(sender, callback_execution, **kwargs):
+    data = callback_execution.callback_data
+    # Only handle product buttons
+    if isinstance(data, dict) and data.get('type') == 'product':
+        # Handle product actions...
+        pass
 
-- **Idempotency**: Each button click processes exactly once
-  - Safe across multiple Django processes
-  - Database-backed coordination
-  - Prevents duplicate actions (e.g., double charges)
+@receiver(telegram_callback_received)
+def handle_navigation_buttons(sender, callback_execution, **kwargs):
+    data = callback_execution.callback_data
+    # Only handle navigation buttons
+    if isinstance(data, dict) and data.get('type') == 'nav':
+        # Handle navigation...
+        pass
+```
 
-- **User Experience**:
-  - Loading indicators stop immediately
-  - Fast response times
-  - Graceful network error handling
+**Scalable Data Structure Example:**
+
+```python
+# Well-structured callback data for complex applications
+callback_data = {
+    "type": "product_handler",      # Routes to correct handler
+    "action": "add_to_cart",        # Specific action
+    "entity_type": "product",       # Type of entity
+    "entity_id": 123,               # Entity identifier
+    "metadata": {                   # Additional context
+        "source": "search_results",
+        "page": 2
+    }
+}
+```
 
-**For more examples and best practices**, see the [detailed Telegram buttons guide](docs/telegram_buttons_guide.md).
 
 #### 📱 Editing Telegram Messages
 
@@ -818,24 +985,22 @@ edit_telegram_message(telegram_channel, message, {
 })
 
 # Edit messages with buttons (common in callback handlers)
-# Use the edit_original_message() method on callback messages
 from django.dispatch import receiver
 from unicom.signals import telegram_callback_received
 from unicom.services.telegram.create_inline_keyboard import create_inline_keyboard, create_callback_button
 
 @receiver(telegram_callback_received)
-def handle_navigation(sender, callback_execution, **kwargs):
+def handle_navigation(sender, callback_execution, clicking_account, original_message, tool_call, **kwargs):
     button_data = callback_execution.callback_data
-    callback_msg = callback_execution.callback_message
 
     if button_data == 'show_settings':
         # Edit the original message to show settings
-        callback_msg.edit_original_message({
+        original_message.edit_original_message({
             'text': '⚙️ Settings Menu',
             'reply_markup': create_inline_keyboard([
-                [create_callback_button("Account", "settings_account")],
-                [create_callback_button("Privacy", "settings_privacy")],
-                [create_callback_button("🔙 Back", "main_menu")]
+                [create_callback_button("Account", "settings_account", message=original_message, account=clicking_account)],
+                [create_callback_button("Privacy", "settings_privacy", message=original_message, account=clicking_account)],
+                [create_callback_button("🔙 Back", "main_menu", message=original_message, account=clicking_account)]
             ])
         })
 ```
@@ -929,35 +1094,78 @@ chat.log_tool_interaction(
 
 The LLM system supports delayed tool calls that can take hours or days to complete, perfect for reminders, monitoring, and long-running processes.
 
+**Tool Implementation - Return `None` to Defer Response:**
+
 ```python
-from unicom.models import Request, ToolCall
+# In your tool definition (e.g., unibot Tool model)
+def set_reminder(text: str, delay_hours: int) -> str:
+    """Schedule a reminder for later"""
+    from django.utils import timezone
+    from datetime import timedelta
+
+    # Schedule the reminder using the tool_call context variable
+    reminder_time = timezone.now() + timedelta(hours=delay_hours)
+
+    # Store tool_call.id for later response
+    # (e.g., in a database, Redis, or scheduler)
+    schedule_reminder(
+        tool_call_id=tool_call.call_id,
+        message=text,
+        scheduled_time=reminder_time
+    )
 
-# Submit multiple tool calls from a request (atomic operation)
-request = Request.objects.get(id='request_id')
-tool_calls = request.submit_tool_calls([
-    {
-        "name": "set_reminder",
-        "arguments": {"text": "Meeting tomorrow", "delay_hours": 24},
-        "id": "call_123"  # Optional, auto-generated if omitted
+    # Return None to defer the response
+    # System automatically marks tool_call as IN_PROGRESS
+    return None
+
+tool_definition = {
+    "name": "set_reminder",
+    "description": "Set a reminder for a specific time in the future",
+    "parameters": {
+        "text": {"type": "string", "description": "Reminder text"},
+        "delay_hours": {"type": "integer", "description": "Hours to wait"}
     },
-    {
-        "name": "monitor_system", 
-        "arguments": {"threshold": 90}
-    }
-])
+    "run": set_reminder
+}
+```
+
+**Responding Later from Any Process:**
+
+```python
+from unicom.models import ToolCall
+
+# Hours or days later, in a background job or scheduled task...
+tool_call = ToolCall.objects.get(call_id="call_123")
+
+# Respond to the tool call
+msg, child_request = tool_call.respond("Reminder: Meeting in 1 hour")
+# This creates a new child request for the LLM to process
+
+# The LLM receives the response and can continue the conversation
+```
+
+**For Periodic/Ongoing Tools (e.g., Monitoring):**
+
+```python
+def monitor_system(threshold: int) -> str:
+    """Monitor system continuously and report status"""
+
+    # Mark as ACTIVE for periodic responses
+    tool_call.mark_active()
+
+    # Start background monitoring
+    start_monitoring_task(tool_call_id=tool_call.call_id, threshold=threshold)
+
+    return None  # Or return initial status
+
+# Later, in your monitoring task...
+tool_call = ToolCall.objects.get(call_id="monitor_123", status='ACTIVE')
+
+# Send periodic updates without creating child requests
+tool_call.respond("CPU usage: 95%")  # Just logs, no child request
+tool_call.respond("CPU usage: 92%")  # Just logs, no child request
 
-# Days later... respond to tool calls
-reminder_call = ToolCall.objects.get(call_id="call_123")
-msg, child_request = reminder_call.respond("Reminder: Meeting in 1 hour")
-# Creates new child request for further processing
-
-# For periodic/ongoing tools, set status to ACTIVE
-monitor_call = tool_calls[1]  
-monitor_call.status = 'ACTIVE'
-monitor_call.save()
-# Now it can respond indefinitely without creating child requests
-monitor_call.respond("CPU usage: 95%")  # Just logs, no child request
-monitor_call.respond("CPU usage: 92%")  # Just logs, no child request
+# Tool call remains ACTIVE and can respond indefinitely
 ```
 
 #### 🤖 Request Hierarchy and Final Response Logic