django-unicom 25.3.45.dev0__tar.gz → 25.3.45.dev2__tar.gz

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-unicom
-Version: 25.3.45.dev0
+Version: 25.3.45.dev2
 Summary: Unified communication layer for Django (Telegram, WhatsApp, Email)
 Home-page: https://github.com/meena-erian/unicom
 Author: Meena (Menas) Erian
@@ -539,7 +539,7 @@ reply = chat.send_message({
 
 ### Template System
 
-Create reusable message templates for consistent communication.
+Create reusable message templates for consistent communication, and optionally render Jinja-style template variables for richer personalization.
 
 #### Creating Templates Programmatically
 
@@ -595,6 +595,48 @@ message = channel.send_message({
 })
 ```
 
+#### Template Variables & Rendering
+
+There are two layers of templating:
+- **Unicom rendering (standalone messages):** Jinja2 rendering with a safe Unicom context. It is used automatically for ad-hoc/admin email compose and scheduled drafts. Context exposed to templates: `message` (subject/html/text/to/cc/bcc/attachments/chat_id/reply_to_message_id/timestamp), `channel` (id/name/platform), and `sender` (id/username/email when available). You can add more by passing `render_variables` (merged into `variables.*`) or `render_context` when calling `channel.send_message`.
+- **Unicrm rendering (mass-mail):** Jinja2 rendering with CRM data. Context exposed: `contact` (and nested `company`, `subscriptions`), `communication`, and `variables` (all active CRM TemplateVariables), plus `variables.unsubscribe_link` (HTML link) when a Communication is provided. This path is unchanged and remains tied to CRM mailings.
+
+Using variables in templates (applies to both renderers):
+```html
+<h1>Hello {{ variables.first_name }}</h1>
+<p>You’re receiving this on {{ now()|datetime("%Y-%m-%d") }}</p>
+```
+
+Creating CRM TemplateVariables (only available in CRM Communications):
+```python
+from unicrm.models import TemplateVariable
+
+TemplateVariable.objects.create(
+    key="contact_first_name",
+    label="Contact first name",
+    description="Returns the contact's first name",
+    code="""
+def compute(contact):
+    return (contact.first_name or '').strip() or 'there'
+""",
+    is_active=True,
+)
+```
+The callable must be `compute(contact)` and can access `contact`, `contact.company`, and helpers like `build_unsubscribe_link` (for unsubscribe variables). Values become available as `{{ variables.contact_first_name }}` in CRM emails.
+
+Opting into rendering for custom sends (programmatic):
+```python
+channel.send_message({
+    'to': ['a@example.com'],
+    'subject': 'Hello',
+    'html': '<p>Hello {{ variables.name }}</p>',
+    'render_template': True,                 # enable rendering (admin email compose & scheduled drafts set this for you)
+    'render_variables': {'name': 'Alice'},   # merged into variables.*
+    # Optionally pass a custom render_context if you want to add more fields
+})
+```
+If you omit `render_template`/context/variables, the HTML is sent as-is. The Django admin email composer and scheduled drafts already enable rendering by default; you only need to pass the flag when sending programmatically.
+
 ### Draft Messages & Scheduling
 
 Create draft messages and schedule them for later sending.

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/README.md

@@ -495,7 +495,7 @@ reply = chat.send_message({
 
 ### Template System
 
-Create reusable message templates for consistent communication.
+Create reusable message templates for consistent communication, and optionally render Jinja-style template variables for richer personalization.
 
 #### Creating Templates Programmatically
 
@@ -551,6 +551,48 @@ message = channel.send_message({
 })
 ```
 
+#### Template Variables & Rendering
+
+There are two layers of templating:
+- **Unicom rendering (standalone messages):** Jinja2 rendering with a safe Unicom context. It is used automatically for ad-hoc/admin email compose and scheduled drafts. Context exposed to templates: `message` (subject/html/text/to/cc/bcc/attachments/chat_id/reply_to_message_id/timestamp), `channel` (id/name/platform), and `sender` (id/username/email when available). You can add more by passing `render_variables` (merged into `variables.*`) or `render_context` when calling `channel.send_message`.
+- **Unicrm rendering (mass-mail):** Jinja2 rendering with CRM data. Context exposed: `contact` (and nested `company`, `subscriptions`), `communication`, and `variables` (all active CRM TemplateVariables), plus `variables.unsubscribe_link` (HTML link) when a Communication is provided. This path is unchanged and remains tied to CRM mailings.
+
+Using variables in templates (applies to both renderers):
+```html
+<h1>Hello {{ variables.first_name }}</h1>
+<p>You’re receiving this on {{ now()|datetime("%Y-%m-%d") }}</p>
+```
+
+Creating CRM TemplateVariables (only available in CRM Communications):
+```python
+from unicrm.models import TemplateVariable
+
+TemplateVariable.objects.create(
+    key="contact_first_name",
+    label="Contact first name",
+    description="Returns the contact's first name",
+    code="""
+def compute(contact):
+    return (contact.first_name or '').strip() or 'there'
+""",
+    is_active=True,
+)
+```
+The callable must be `compute(contact)` and can access `contact`, `contact.company`, and helpers like `build_unsubscribe_link` (for unsubscribe variables). Values become available as `{{ variables.contact_first_name }}` in CRM emails.
+
+Opting into rendering for custom sends (programmatic):
+```python
+channel.send_message({
+    'to': ['a@example.com'],
+    'subject': 'Hello',
+    'html': '<p>Hello {{ variables.name }}</p>',
+    'render_template': True,                 # enable rendering (admin email compose & scheduled drafts set this for you)
+    'render_variables': {'name': 'Alice'},   # merged into variables.*
+    # Optionally pass a custom render_context if you want to add more fields
+})
+```
+If you omit `render_template`/context/variables, the HTML is sent as-is. The Django admin email composer and scheduled drafts already enable rendering by default; you only need to pass the flag when sending programmatically.
+
 ### Draft Messages & Scheduling
 
 Create draft messages and schedule them for later sending.

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/django_unicom.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-unicom
-Version: 25.3.45.dev0
+Version: 25.3.45.dev2
 Summary: Unified communication layer for Django (Telegram, WhatsApp, Email)
 Home-page: https://github.com/meena-erian/unicom
 Author: Meena (Menas) Erian
@@ -539,7 +539,7 @@ reply = chat.send_message({
 
 ### Template System
 
-Create reusable message templates for consistent communication.
+Create reusable message templates for consistent communication, and optionally render Jinja-style template variables for richer personalization.
 
 #### Creating Templates Programmatically
 
@@ -595,6 +595,48 @@ message = channel.send_message({
 })
 ```
 
+#### Template Variables & Rendering
+
+There are two layers of templating:
+- **Unicom rendering (standalone messages):** Jinja2 rendering with a safe Unicom context. It is used automatically for ad-hoc/admin email compose and scheduled drafts. Context exposed to templates: `message` (subject/html/text/to/cc/bcc/attachments/chat_id/reply_to_message_id/timestamp), `channel` (id/name/platform), and `sender` (id/username/email when available). You can add more by passing `render_variables` (merged into `variables.*`) or `render_context` when calling `channel.send_message`.
+- **Unicrm rendering (mass-mail):** Jinja2 rendering with CRM data. Context exposed: `contact` (and nested `company`, `subscriptions`), `communication`, and `variables` (all active CRM TemplateVariables), plus `variables.unsubscribe_link` (HTML link) when a Communication is provided. This path is unchanged and remains tied to CRM mailings.
+
+Using variables in templates (applies to both renderers):
+```html
+<h1>Hello {{ variables.first_name }}</h1>
+<p>You’re receiving this on {{ now()|datetime("%Y-%m-%d") }}</p>
+```
+
+Creating CRM TemplateVariables (only available in CRM Communications):
+```python
+from unicrm.models import TemplateVariable
+
+TemplateVariable.objects.create(
+    key="contact_first_name",
+    label="Contact first name",
+    description="Returns the contact's first name",
+    code="""
+def compute(contact):
+    return (contact.first_name or '').strip() or 'there'
+""",
+    is_active=True,
+)
+```
+The callable must be `compute(contact)` and can access `contact`, `contact.company`, and helpers like `build_unsubscribe_link` (for unsubscribe variables). Values become available as `{{ variables.contact_first_name }}` in CRM emails.
+
+Opting into rendering for custom sends (programmatic):
+```python
+channel.send_message({
+    'to': ['a@example.com'],
+    'subject': 'Hello',
+    'html': '<p>Hello {{ variables.name }}</p>',
+    'render_template': True,                 # enable rendering (admin email compose & scheduled drafts set this for you)
+    'render_variables': {'name': 'Alice'},   # merged into variables.*
+    # Optionally pass a custom render_context if you want to add more fields
+})
+```
+If you omit `render_template`/context/variables, the HTML is sent as-is. The Django admin email composer and scheduled drafts already enable rendering by default; you only need to pass the flag when sending programmatically.
+
 ### Draft Messages & Scheduling
 
 Create draft messages and schedule them for later sending.

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/django_unicom.egg-info/SOURCES.txt

@@ -122,6 +122,7 @@ unicom/services/chat_summary.py
 unicom/services/decode_base64_image.py
 unicom/services/get_public_origin.py
 unicom/services/html_inline_images.py
+unicom/services/template_renderer.py
 unicom/services/crossplatform/__init__.py
 unicom/services/crossplatform/reply_to_message.py
 unicom/services/crossplatform/scheduler.py
@@ -197,6 +198,9 @@ unicom/templates/code_templates/category_processor.py
 unicom/templates/unicom/webchat_demo.html
 unicom/templatetags/__init__.py
 unicom/templatetags/unicom_tags.py
+unicom/tests/test_email_tracking_unsubscribe.py
+unicom/tests/test_template_renderer_context.py
+unicom/tests/test_template_renderer_unicom.py
 unicom/views/__init__.py
 unicom/views/chat_history_view.py
 unicom/views/compose_view.py
@@ -236,6 +240,7 @@ unicrm/urls.py
 unicrm/views.py
 unicrm/views_api.py
 unicrm/views_communication.py
+unicrm/views_lead_search.py
 unicrm/views_public.py
 unicrm/management/__init__.py
 unicrm/management/commands/__init__.py
@@ -262,6 +267,7 @@ unicrm/migrations/0017_unsubscribe_link_html_variable.py
 unicrm/migrations/0018_communication_mailing_list.py
 unicrm/migrations/0019_communication_follow_up_for_segment_for_followup.py
 unicrm/migrations/0020_communication_skip_antispam_guards.py
+unicrm/migrations/0021_fix_unsubscribe_counts.py
 unicrm/migrations/__init__.py
 unicrm/services/__init__.py
 unicrm/services/audience.py
@@ -271,7 +277,11 @@ unicrm/services/communication_enrollment.py
 unicrm/services/communication_runner.py
 unicrm/services/communication_scheduler.py
 unicrm/services/contact_interaction_cache.py
+unicrm/services/disk_usage_monitor.py
+unicrm/services/disk_usage_monitor_runner.py
 unicrm/services/getprospect_email_poller.py
+unicrm/services/lead_search.py
+unicrm/services/red_alerts.py
 unicrm/services/save_new_leads_callbacks.py
 unicrm/services/template_renderer.py
 unicrm/services/unsubscribe_links.py
@@ -283,6 +293,9 @@ unicrm/tests/test_communication_compose_view.py
 unicrm/tests/test_communication_dispatcher.py
 unicrm/tests/test_communication_scheduler.py
 unicrm/tests/test_contact_interactions.py
+unicrm/tests/test_disk_usage_monitor.py
+unicrm/tests/test_disk_usage_monitor_runner.py
+unicrm/tests/test_red_alerts.py
 unicrm/tests/test_retry_delivery_api.py
 unicrm/tests/test_template_renderer.py
 unicrm/tests/test_unsubscribe_view.py

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/unibot/models.py

@@ -441,6 +441,17 @@ class Bot(models.Model):
         Process a single Request object using this bot's code, updating status and error fields as needed.
         Passes the bot instance and its associated tools to the handler.
         """
+        # If this is a user interrupt immediately after a tool_call or tool_response (within 5 minutes), skip LLM processing. (The 
+        # LLM will respond through the request created when the tool response arrives and this is to avoid double processing.)
+        if req.message.is_outgoing is False and req.message.media_type not in ['tool_call', 'tool_response']:
+            prev_msg = req.message.chat.messages.filter(timestamp__lt=req.message.timestamp).order_by('-timestamp').first()
+            if prev_msg and prev_msg.media_type in ['tool_call', 'tool_response']:
+                delta = (req.message.timestamp - prev_msg.timestamp).total_seconds()
+                if delta < 300:
+                    req.status = 'COMPLETED'
+                    req.save(update_fields=['status'])
+                    return
+
         if hasattr(req, 'parent_request') and req.parent_request:
             print(f"[DEBUG] Processing child request {req.id} from parent {req.parent_request.id}")
         bot_code = self.code or Bot.get_default_code()

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/unibot/services/llm_handler.py

@@ -59,31 +59,56 @@ def build_openai_tools(tools_list: Optional[List[object]], bot=None, message=Non
 
         if auto_params:
             auto_params_map[name] = auto_params
-        props = {}
-        required = []
+        props: dict = {}
+        required: list = []
         for pname, pinfo in raw_params.items():
             ptype = pinfo.get('type', 'string')
-            if ptype in ('str', 'string'):
-                otype = 'string'
-            elif ptype in ('int', 'integer'):
-                otype = 'integer'
-            elif ptype in ('float', 'number'):
-                otype = 'number'
-            elif ptype in ('bool', 'boolean'):
-                otype = 'boolean'
+            # Preserve enum/items for the LLM; map common aliases for scalars.
+            if isinstance(ptype, str):
+                if ptype in ('str', 'string'):
+                    otype = 'string'
+                elif ptype in ('int', 'integer'):
+                    otype = 'integer'
+                elif ptype in ('float', 'number'):
+                    otype = 'number'
+                elif ptype in ('bool', 'boolean'):
+                    otype = 'boolean'
+                else:
+                    otype = ptype
             else:
-                otype = 'string'
+                # Allow JSON Schema style: list/union types
+                otype = ptype
+
             prop = {'type': otype}
-            if 'description' in pinfo:
-                prop['description'] = pinfo['description']
+            # Carry through common JSON Schema fields if present.
+            for key in (
+                'description',
+                'enum',
+                'items',
+                'properties',
+                'additionalProperties',
+                'format',
+                'minimum',
+                'maximum',
+                'minItems',
+                'maxItems',
+                'anyOf',
+                'oneOf',
+                'allOf',
+            ):
+                if key in pinfo:
+                    prop[key] = pinfo[key]
             if 'default' in pinfo:
                 prop['default'] = pinfo['default']
             else:
                 required.append(pname)
             props[pname] = prop
-        param_schema = { 'type': 'object',
-                            'properties': props,
-                            'additionalProperties': False }
+
+        param_schema = {
+            'type': 'object',
+            'properties': props,
+            'additionalProperties': False,
+        }
         if required:
             param_schema['required'] = required
         openai_tools.append({

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/unicom/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '25.3.45.dev0'
-__version_tuple__ = version_tuple = (25, 3, 45, 'dev0')
+__version__ = version = '25.3.45.dev2'
+__version_tuple__ = version_tuple = (25, 3, 45, 'dev2')
 
 __commit_id__ = commit_id = None

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/unicom/models/draft_message.py

@@ -180,6 +180,8 @@ class DraftMessage(models.Model):
                 msg_dict['chat_id'] = self.chat_id
             if self.skip_reacher_validation:
                 msg_dict['skip_reacher'] = True
+            # Enable template rendering with the built-in Unicom context.
+            msg_dict['render_template'] = True
         else:
             msg_dict['chat_id'] = self.chat_id
             msg_dict['text'] = self.text

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/unicom/models/message.py

@@ -445,6 +445,8 @@ class Message(models.Model):
                     break
                 chain.append(cur)
                 cur = cur.reply_to_message
+            # Sort chronologically to preserve call/response order
+            chain = sorted(chain, key=lambda m: m.timestamp)
             
             # Handle user interruption for tool response messages in thread mode
             if self.media_type == "tool_response":
@@ -465,14 +467,40 @@ class Message(models.Model):
                     ).exclude(
                         media_type__in=['tool_call', 'tool_response']
                     ).order_by('-timestamp').first()
+
+                    # Fallback: any user message in that window, even without reply_to
+                    if not user_interrupt:
+                        user_interrupt = self.chat.messages.filter(
+                            is_outgoing=False,
+                            timestamp__gt=latest_tool_call_time,
+                            timestamp__lt=self.timestamp
+                        ).exclude(
+                            media_type__in=['tool_call', 'tool_response']
+                        ).order_by('-timestamp').first()
                     
                     if user_interrupt:
-                        # Found user interrupt - get conversation from that user message
-                        return user_interrupt.as_llm_chat(depth=depth, mode=mode,
-                                                        system_instruction=system_instruction,
-                                                        multimodal=multimodal)
-            
-            for m in reversed(chain):
+                        if user_interrupt not in chain:
+                            chain.append(user_interrupt)
+                        chain = sorted(chain, key=lambda m: m.timestamp)
+            # Ensure tool_call and tool_response are adjacent
+            if self.media_type == "tool_response":
+                try:
+                    call_id = self.raw.get('tool_response', {}).get('call_id')
+                    if call_id:
+                        tc_idx = next((i for i, m in enumerate(chain)
+                                       if m.media_type == "tool_call"
+                                       and m.raw.get('tool_call', {}).get('id') == call_id), None)
+                        tr_idx = next((i for i, m in enumerate(chain)
+                                       if m.media_type == "tool_response"
+                                       and m.raw.get('tool_response', {}).get('call_id') == call_id), None)
+                        if tc_idx is not None and tr_idx is not None and tr_idx != tc_idx + 1:
+                            # Move tool_response directly after tool_call
+                            tr = chain.pop(tr_idx)
+                            chain.insert(tc_idx + 1, tr)
+                except Exception:
+                    pass
+
+            for m in chain:
                 messages.append(msg_to_dict(m))
         else:
             raise ValueError(f"Unknown mode: {mode}")

{django_unicom-25.3.45.dev0 → django_unicom-25.3.45.dev2}/unicom/services/email/send_email_message.py

@@ -17,6 +17,12 @@ import requests
 from urllib.parse import urljoin
 from django.utils import timezone
 from unicom.services.html_inline_images import html_shortlinks_to_base64_images, html_base64_images_to_shortlinks
+from unicom.services.template_renderer import (
+    render_template as render_unicom_template,
+    build_unicom_message_context,
+    extract_variable_keys,
+    compute_crm_variables,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -275,6 +281,46 @@ def send_email_message(channel: Channel, params: dict, user: User=None):
         html_content = convert_text_to_html(text_content)
         logger.debug("Converted plain text to HTML")
 
+    # Optionally render templates for non-CRM use-cases when explicitly requested.
+    render_context = params.get('render_context')
+    render_variables = params.get('render_variables') or {}
+    render_requested = params.get('render_template') or render_context or render_variables
+    if render_requested and html_content:
+        crm_variables: dict[str, object] = {}
+        requested_keys = extract_variable_keys(html_content)
+        if requested_keys:
+            # Use first To address (if any) to resolve contact for CRM variables.
+            primary_email = None
+            to_addrs_for_crm = params.get('to') or to_addrs
+            if to_addrs_for_crm:
+                primary_email = (to_addrs_for_crm[0] or '').strip()
+            crm_variables = compute_crm_variables(requested_keys, primary_email)
+
+        base_context = render_context or build_unicom_message_context(
+            params=params,
+            channel={
+                'id': channel.id,
+                'name': channel.name,
+                'platform': channel.platform,
+            },
+            user={
+                'id': getattr(user, 'id', None),
+                'username': getattr(user, 'username', None),
+                'email': getattr(user, 'email', None),
+            } if user else {},
+        )
+        merged_variables = {}
+        merged_variables.update(crm_variables)
+        merged_variables.update(render_variables)
+        render_result = render_unicom_template(
+            html_content,
+            base_context=base_context,
+            variables=merged_variables,
+        )
+        if render_result.errors:
+            logger.warning("Template rendering errors: %s", "; ".join(render_result.errors))
+        html_content = render_result.html
+
     # Add tracking
     if html_content:
         html_content = to_inline_png_img(html_content)  # Convert FontAwesome to inline images

django_unicom-25.3.45.dev2/unicom/services/template_renderer.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any, Dict, Mapping
+import re
+from urllib.parse import unquote
+
+from django.utils import timezone
+from jinja2 import StrictUndefined, TemplateError
+from jinja2.sandbox import SandboxedEnvironment
+
+
+# Matches TinyMCE-protected placeholders such as "{{ variables.x }}" that TinyMCE wraps.
+_PROTECTED_PLACEHOLDER_RE = re.compile(r'<!--\s*mce:protected\s+([^>]+?)-->')
+
+
+def _datetime_format(value, fmt: str = "%Y-%m-%d %H:%M %Z") -> str:
+    if not value:
+        return ""
+    if timezone.is_naive(value):  # pragma: no cover - defensive branch
+        value = timezone.make_aware(value)
+    return timezone.localtime(value).strftime(fmt)
+
+
+@lru_cache(maxsize=1)
+def get_jinja_environment() -> SandboxedEnvironment:
+    """
+    Returns a singleton sandboxed environment for rendering email templates.
+    Shared between Unicom and Unicrm to keep behavior consistent.
+    """
+    env = SandboxedEnvironment(
+        autoescape=True,
+        trim_blocks=True,
+        lstrip_blocks=True,
+        undefined=StrictUndefined,
+    )
+    env.filters['datetime'] = _datetime_format
+    env.globals.update({
+        'now': timezone.now,
+    })
+    return env
+
+
+def unprotect_tinymce_markup(content: str | None) -> str:
+    """
+    Restore TinyMCE protected placeholders ({{ ... }}) back to plain Jinja markup.
+    """
+    if not content:
+        return content or ''
+
+    def _restore(match: re.Match[str]) -> str:
+        encoded = match.group(1).strip()
+        try:
+            return unquote(encoded)
+        except Exception:  # pragma: no cover - defensive
+            return encoded
+
+    return _PROTECTED_PLACEHOLDER_RE.sub(_restore, content)
+
+
+@dataclass
+class RenderResult:
+    html: str
+    context: Dict[str, Any]
+    variables: Dict[str, Any]
+    errors: list[str]
+
+
+def render_template(
+    template_html: str,
+    *,
+    base_context: Mapping[str, Any] | None = None,
+    variables: Mapping[str, Any] | None = None,
+    extra_context: Mapping[str, Any] | None = None,
+) -> RenderResult:
+    """
+    Render arbitrary HTML with a sandboxed Jinja2 environment.
+
+    - Does nothing destructive to callers: on template error, returns original HTML and records the error.
+    - Callers can pass `variables` to expose as `variables.*` in templates; optional extra context merges in.
+    """
+    env = get_jinja_environment()
+    rendered_context: Dict[str, Any] = {}
+    if base_context:
+        rendered_context.update(base_context)
+    existing_vars = dict(rendered_context.get('variables') or {})
+    existing_vars.update(variables or {})
+    rendered_context['variables'] = existing_vars
+
+    if extra_context:
+        rendered_context.update(extra_context)
+
+    template_html = unprotect_tinymce_markup(template_html)
+    template = env.from_string(template_html)
+    errors: list[str] = []
+    try:
+        html = template.render(rendered_context)
+    except TemplateError as exc:
+        errors.append(str(exc))
+        html = template_html
+    return RenderResult(
+        html=html,
+        context=rendered_context,
+        variables=rendered_context['variables'],
+        errors=errors,
+    )
+
+
+def build_unicom_message_context(
+    *,
+    params: Mapping[str, Any],
+    channel: Mapping[str, Any] | None = None,
+    user: Mapping[str, Any] | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> Dict[str, Any]:
+    """
+    Construct a safe, serialisable context for Unicom standalone messages.
+    Intentionally excludes CRM-only data (contacts, unsubscribe links).
+    """
+    message_ctx = {
+        'subject': params.get('subject'),
+        'text': params.get('text'),
+        'html': params.get('html'),
+        'to': params.get('to'),
+        'cc': params.get('cc'),
+        'bcc': params.get('bcc'),
+        'attachments': params.get('attachments'),
+        'chat_id': params.get('chat_id'),
+        'reply_to_message_id': params.get('reply_to_message_id'),
+        'timestamp': timezone.now(),
+    }
+    ctx: Dict[str, Any] = {
+        'message': message_ctx,
+        'channel': channel or {},
+        'sender': user or {},
+    }
+    if extra:
+        ctx.update(extra)
+    return ctx
+
+
+_VARIABLE_PLACEHOLDER_RE = re.compile(r"\{\{\s*variables\.([^\s\}]+)\s*\}\}")
+
+
+def extract_variable_keys(template_html: str | None) -> set[str]:
+    """
+    Return the set of variable keys referenced as {{ variables.* }} in the template.
+    """
+    if not template_html:
+        return set()
+    unprotected = unprotect_tinymce_markup(template_html)
+    return {m.group(1) for m in _VARIABLE_PLACEHOLDER_RE.finditer(unprotected)}
+
+
+def _load_crm_models():
+    """
+    Dynamically load CRM models if unicrm is installed; otherwise return (None, None).
+    """
+    try:
+        from django.apps import apps
+        Contact = apps.get_model('unicrm', 'Contact')
+        TemplateVariable = apps.get_model('unicrm', 'TemplateVariable')
+        if Contact is None or TemplateVariable is None:
+            return None, None
+        return Contact, TemplateVariable
+    except Exception:
+        return None, None
+
+
+def compute_crm_variables(keys: set[str], contact_email: str | None) -> Dict[str, Any]:
+    """
+    Best-effort evaluation of CRM TemplateVariables for a contact resolved by email.
+    Safe to call when unicrm is not installed (returns {}).
+    """
+    if not keys or not contact_email:
+        return {}
+    Contact, TemplateVariable = _load_crm_models()
+    if Contact is None or TemplateVariable is None:
+        return {}
+    contact = Contact.objects.filter(email__iexact=contact_email).first()
+    if not contact:
+        return {}
+    results: Dict[str, Any] = {}
+    for variable in TemplateVariable.objects.filter(is_active=True, key__in=keys):
+        try:
+            results[variable.key] = variable.get_callable()(contact)
+        except Exception as exc:  # pragma: no cover - defensive
+            results[variable.key] = f"<error: {exc}>"
+    return results