iatoolkit 2.12.2__tar.gz → 2.14.0__tar.gz

{iatoolkit-2.12.2/src/iatoolkit.egg-info → iatoolkit-2.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iatoolkit
-Version: 2.12.2
+Version: 2.14.0
 Summary: IAToolkit
 Author: Fernando Libedinsky
 License-Expression: MIT

{iatoolkit-2.12.2 → iatoolkit-2.14.0}/src/iatoolkit/__init__.py

@@ -3,7 +3,7 @@
 #
 # IAToolkit is open source software.
 
-__version__ = "2.12.2"
+__version__ = "2.14.0"
 
 # Expose main classes and functions at the top level of the package
 

{iatoolkit-2.12.2 → iatoolkit-2.14.0}/src/iatoolkit/locales/en.yaml

@@ -408,9 +408,28 @@ ui:
     tab_settings: "Settings"
     tab_audience: "Audience"
     tab_executions: "Executions"
+    whatsapp_templates_title: "WhatsApp Templates"
+    whatsapp_templates_empty: "No WhatsApp templates have been synced yet."
+    whatsapp_templates_subtitle: "Templates available in Kapso for WhatsApp campaigns."
+    sync_templates: "Sync templates"
+    sync_templates_success: "Templates synced."
+    sync_templates_error: "Could not sync templates."
     template_label: "Initial message"
     template_help: "This template is rendered per contact when the campaign is activated. You can use variables such as {{ full_name }}, {{ company_name }}, or {{ source.product }}."
     template_placeholder: "You can use variables like {{ full_name }}, {{ email }}, {{ phone_number }}, {{ government_id }}, {{ external_contact_key }}, {{ company_name }}, {{ company_short_name }}, {{ metadata.* }}, and {{ source.* }}"
+    initial_message_mode_label: "Start mode"
+    whatsapp_template_label: "WhatsApp template"
+    select_whatsapp_template: "Select a WhatsApp template"
+    whatsapp_template_preview_title: "Template preview"
+    whatsapp_template_variables_title: "Template variables"
+    whatsapp_template_variables_help: "Map each template variable using contact fields, metadata, source, or company values."
+    whatsapp_template_variable_mapping_placeholder: "Example: full_name or source.product"
+    whatsapp_template_variable_example: "Provider example: {value}"
+    whatsapp_template_no_preview: "Select a template to preview it and map its variables."
+    whatsapp_template_status: "Status"
+    whatsapp_template_language: "Language"
+    whatsapp_template_category: "Category"
+    whatsapp_template_last_synced: "Last sync"
     audience_title: "Audience"
     audience_help: "Upload a CSV, map the core columns, and turn those rows into contacts ready to activate over WhatsApp."
     audience_empty: "No audience has been imported yet."
@@ -421,6 +440,8 @@ ui:
     audience_col_email: "Email"
     audience_col_status: "Status"
     audience_col_delivery: "Activation"
+    audience_col_client: "Client"
+    audience_col_last_activity: "Last activity"
     audience_col_error: "Error"
     audience_col_actions: "Actions"
     audience_total_label: "{count} contacts"
@@ -428,11 +449,21 @@ ui:
     summary_ready: "Ready"
     summary_pending: "Pending"
     summary_activated: "Activated"
+    summary_not_replied: "No reply"
+    summary_replied: "Replied"
+    summary_agent_engaged: "Conversing"
     summary_failed: "Failed"
     summary_skipped: "Skipped"
     executions_title: "Execution status"
     executions_empty: "This campaign has not been launched yet."
     executions_last_launch: "Last launch: {date}"
+    executions_summary_snapshot: "{replied} replied · {engaged} in conversation"
+    executions_load_error: "Could not load campaign executions."
+    executions_attempted: "Attempted"
+    executions_processed: "Processed"
+    executions_summary_status: "{status} · {date} · {progress}% progress"
+    executions_row_counts: "{processed}/{attempted} processed · {activated} activated · {failed} failed · {skipped} skipped"
+    executions_row_progress: "{progress}% progress"
     select_campaign: "Select a campaign"
     workspace_placeholder: "Create or select a campaign to edit its template, settings, and audience."
     import_csv: "Import CSV"
@@ -463,7 +494,7 @@ ui:
     mapping_ignore: "Ignore"
     mapping_preview_first: "Load a preview first"
     launch_campaign: "Launch campaign"
-    launch_success: "Campaign launched."
+    launch_success: "Campaign launch queued."
     launch_error: "Could not launch the campaign."
     select_campaign_first: "Select a campaign first."
     add_to_campaign: "Add to campaign"
@@ -489,6 +520,9 @@ ui:
       completed: "Completed"
       failed: "Failed"
       paused: "Paused"
+    initial_message_mode:
+      free_text: "Free text"
+      whatsapp_template: "WhatsApp template"
     audience_status:
       ready: "Ready"
       invalid: "Invalid"
@@ -498,6 +532,27 @@ ui:
       activated: "Activated"
       failed: "Failed"
       skipped: "Skipped"
+    execution_status:
+      pending: "Queued"
+      running: "Running"
+      completed: "Completed"
+      failed: "Failed"
+      cancelled: "Cancelled"
+    engagement_status:
+      not_replied: "No reply"
+      replied: "Replied"
+      agent_engaged: "Conversing"
+    last_message_direction:
+      inbound: "Client"
+      outbound: "Agent"
+    reply_latency_label: "First reply in {value}"
+    reply_latency_seconds: "{count}s"
+    reply_latency_minutes: "{count}m"
+    reply_latency_hours: "{count}h"
+    reply_latency_days: "{count}d"
+    message_count_label: "Messages: {inbound} inbound / {outbound} outbound"
+    last_message_label: "Last message: {value}"
+    first_reply_label: "First reply: {value}"
 
   admin:
     workspace: "Workspace"

{iatoolkit-2.12.2 → iatoolkit-2.14.0}/src/iatoolkit/locales/es.yaml

@@ -409,9 +409,28 @@ ui:
     tab_settings: "Settings"
     tab_audience: "Audience"
     tab_executions: "Ejecuciones"
+    whatsapp_templates_title: "WhatsApp Templates"
+    whatsapp_templates_empty: "Todavía no hay templates de WhatsApp sincronizados."
+    whatsapp_templates_subtitle: "Templates disponibles en Kapso para campañas de WhatsApp."
+    sync_templates: "Sync templates"
+    sync_templates_success: "Templates sincronizados."
+    sync_templates_error: "No se pudieron sincronizar los templates."
     template_label: "Mensaje inicial"
     template_help: "Este template se renderiza por contacto al activar la campaña. Puedes usar variables como {{ full_name }}, {{ company_name }} o {{ source.producto }}."
     template_placeholder: "Puedes usar variables como {{ full_name }}, {{ email }}, {{ phone_number }}, {{ government_id }}, {{ external_contact_key }}, {{ company_name }}, {{ company_short_name }}, {{ metadata.* }} y {{ source.* }}"
+    initial_message_mode_label: "Modo de inicio"
+    whatsapp_template_label: "WhatsApp template"
+    select_whatsapp_template: "Selecciona un WhatsApp template"
+    whatsapp_template_preview_title: "Preview del template"
+    whatsapp_template_variables_title: "Variables del template"
+    whatsapp_template_variables_help: "Mapea cada variable del template usando campos del contacto, metadata, source o company."
+    whatsapp_template_variable_mapping_placeholder: "Ejemplo: full_name o source.producto"
+    whatsapp_template_variable_example: "Ejemplo provider: {value}"
+    whatsapp_template_no_preview: "Selecciona un template para ver su preview y mapear variables."
+    whatsapp_template_status: "Status"
+    whatsapp_template_language: "Idioma"
+    whatsapp_template_category: "Categoría"
+    whatsapp_template_last_synced: "Última sync"
     audience_title: "Audiencia"
     audience_help: "Carga un CSV, mapea columnas básicas y convierte las filas en contactos listos para activar por WhatsApp."
     audience_empty: "Todavía no hay audiencia cargada."
@@ -422,6 +441,8 @@ ui:
     audience_col_email: "Email"
     audience_col_status: "Estado"
     audience_col_delivery: "Activación"
+    audience_col_client: "Cliente"
+    audience_col_last_activity: "Última actividad"
     audience_col_error: "Error"
     audience_col_actions: "Acciones"
     audience_total_label: "{count} contactos"
@@ -429,11 +450,21 @@ ui:
     summary_ready: "Listos"
     summary_pending: "Pendientes"
     summary_activated: "Activados"
+    summary_not_replied: "Sin respuesta"
+    summary_replied: "Respondieron"
+    summary_agent_engaged: "Conversando"
     summary_failed: "Fallidos"
     summary_skipped: "Omitidos"
     executions_title: "Estado de ejecución"
     executions_empty: "Esta campaña todavía no se ha lanzado."
     executions_last_launch: "Último lanzamiento: {date}"
+    executions_summary_snapshot: "{replied} respondieron · {engaged} conversando"
+    executions_load_error: "No se pudieron cargar las ejecuciones de la campaña."
+    executions_attempted: "Intentados"
+    executions_processed: "Procesados"
+    executions_summary_status: "{status} · {date} · {progress}% de progreso"
+    executions_row_counts: "{processed}/{attempted} procesados · {activated} activados · {failed} fallidos · {skipped} omitidos"
+    executions_row_progress: "{progress}% de progreso"
     select_campaign: "Selecciona una campaña"
     workspace_placeholder: "Crea o selecciona una campaña para editar su template, settings y audiencia."
     import_csv: "Importar CSV"
@@ -464,7 +495,7 @@ ui:
     mapping_ignore: "Ignorar"
     mapping_preview_first: "Primero carga una previsualización"
     launch_campaign: "Lanzar campaña"
-    launch_success: "Campaña lanzada."
+    launch_success: "Lanzamiento de campaña encolado."
     launch_error: "No se pudo lanzar la campaña."
     select_campaign_first: "Primero selecciona una campaña."
     add_to_campaign: "Agregar a campaña"
@@ -490,6 +521,9 @@ ui:
       completed: "Completada"
       failed: "Fallida"
       paused: "Pausada"
+    initial_message_mode:
+      free_text: "Texto libre"
+      whatsapp_template: "WhatsApp template"
     audience_status:
       ready: "Lista"
       invalid: "Inválida"
@@ -499,6 +533,27 @@ ui:
       activated: "Activada"
       failed: "Fallida"
       skipped: "Omitida"
+    execution_status:
+      pending: "En cola"
+      running: "En ejecución"
+      completed: "Completada"
+      failed: "Fallida"
+      cancelled: "Cancelada"
+    engagement_status:
+      not_replied: "Sin respuesta"
+      replied: "Respondió"
+      agent_engaged: "Conversando"
+    last_message_direction:
+      inbound: "Cliente"
+      outbound: "Agente"
+    reply_latency_label: "Primera respuesta en {value}"
+    reply_latency_seconds: "{count}s"
+    reply_latency_minutes: "{count}m"
+    reply_latency_hours: "{count}h"
+    reply_latency_days: "{count}d"
+    message_count_label: "Mensajes: {inbound} inbound / {outbound} outbound"
+    last_message_label: "Último mensaje: {value}"
+    first_reply_label: "Primera respuesta: {value}"
 
   admin:
     workspace: "Recursos"

{iatoolkit-2.12.2 → iatoolkit-2.14.0}/src/iatoolkit/services/context_builder_service.py

@@ -333,13 +333,17 @@ class ContextBuilderService:
                 collection_names=rag_collections,
             )
 
+        company_context_blocks = self.company_context_service.get_company_context_blocks(company_short_name)
+
         final_system_context = self._join_context_sections(
             rendered_sections.get("identity"),
+            company_context_blocks.get("markdown_context"),
             rendered_sections.get("conversation_rules"),
             rendered_sections.get("retrieval_guidance"),
             collection_context,
             rendered_sections.get("data_access_rules"),
             sql_context,
+            company_context_blocks.get("yaml_context"),
             rendered_sections.get("output_contract"),
         )
 

{iatoolkit-2.12.2 → iatoolkit-2.14.0}/src/iatoolkit/services/llm_client_service.py

@@ -27,6 +27,10 @@ from iatoolkit.services.structured_output_service import StructuredOutputService
 from iatoolkit.services.telemetry_service import NoopTelemetryService
 
 CONTEXT_ERROR_MESSAGE = 'Tu consulta supera el límite de contexto, utiliza el boton de recarga de contexto.'
+TELEMETRY_MAX_STRING_LENGTH = 1000
+TELEMETRY_MAX_COLLECTION_ITEMS = 20
+TELEMETRY_MAX_DEPTH = 4
+TELEMETRY_REDACTED_VALUE = "[REDACTED]"
 
 class llmClient:
     _llm_clients_cache = {}      # class attribute, for the clients cache
@@ -121,6 +125,7 @@ class llmClient:
         text_payload = request_params["text"]
         reasoning_payload = request_params["reasoning"]
         telemetry_execution = self.telemetry_service.start_execution(telemetry_request)
+        request_source = str((execution_metadata or {}).get("request_source") or "").strip().lower()
 
         try:
             start_time = time.time()
@@ -209,58 +214,105 @@ class llmClient:
                         raise
                     logging.debug(f"[Dispatcher] Parsed args = {args}")
 
+                    tool_call_id = str(getattr(tool_call, "call_id", "") or "").strip()
+                    tool_span = None
+                    tool_status = None
+                    tool_result_for_telemetry = None
+                    tool_error_message = None
+                    tool_output_type = None
+                    tool_attachments_count = 0
+                    tool_elapsed_seconds = 0.0
+
                     try:
                         call_kwargs = dict(args)
                         if images:
                             call_kwargs["request_images"] = images
 
-                        result = self.dispatcher.dispatch(
-                            company_short_name=company.short_name,
-                            function_name=function_name,
-                            user_identifier=user_identifier,
-                            **call_kwargs
+                        tool_span = telemetry_execution.start_child_span(
+                            name=f"tool.{function_name}",
+                            span_type="tool",
+                            event=self._build_tool_telemetry_start_event(
+                                company_short_name=company.short_name,
+                                function_name=function_name,
+                                call_id=tool_call_id,
+                                args=call_kwargs,
+                                request_source=request_source,
+                            ),
                         )
-                        force_tool_name = None
-                    except IAToolkitException as e:
-                        if (e.error_type == IAToolkitException.ErrorType.DATABASE_ERROR and
-                            sql_retry_count < self.MAX_SQL_RETRIES):
-                            sql_retry_count += 1
-                            sql_query_with_error = args.get('query', 'No se pudo extraer la consulta.')
-                            original_db_error = str(e.__cause__) if e.__cause__ else str(e)
-
-                            logging.warning(
-                                    f"Error de SQL capturado, intentando corregir con el LLM (Intento {sql_retry_count}/{self.MAX_SQL_RETRIES}).")
-                            result = self._create_sql_retry_prompt(function_name, sql_query_with_error, original_db_error)
-
-                            # force the next call to be this function
-                            force_tool_name = function_name
-                        else:
-                            error_message = f"**LLM_DISPATCHER** error en dispatch para tool: '{function_name}': {str(e)}"
+
+                        try:
+                            result = self.dispatcher.dispatch(
+                                company_short_name=company.short_name,
+                                function_name=function_name,
+                                user_identifier=user_identifier,
+                                **call_kwargs
+                            )
+                            force_tool_name = None
+                            tool_status = "completed"
+                        except IAToolkitException as e:
+                            if (e.error_type == IAToolkitException.ErrorType.DATABASE_ERROR and
+                                sql_retry_count < self.MAX_SQL_RETRIES):
+                                sql_retry_count += 1
+                                sql_query_with_error = args.get('query', 'No se pudo extraer la consulta.')
+                                original_db_error = str(e.__cause__) if e.__cause__ else str(e)
+
+                                logging.warning(
+                                        f"Error de SQL capturado, intentando corregir con el LLM (Intento {sql_retry_count}/{self.MAX_SQL_RETRIES}).")
+                                result = self._create_sql_retry_prompt(function_name, sql_query_with_error, original_db_error)
+
+                                # force the next call to be this function
+                                force_tool_name = function_name
+                                tool_status = "retry_generated"
+                            else:
+                                error_message = f"**LLM_DISPATCHER** error en dispatch para tool: '{function_name}': {str(e)}"
+                                tool_status = "error"
+                                tool_error_message = error_message
+                                raise IAToolkitException(IAToolkitException.ErrorType.CALL_ERROR, error_message)
+                        except Exception as e:
+                            error_message = f"Dispatch error en tool {function_name} con args {args} -******- {str(e)}"
+                            tool_status = "error"
+                            tool_error_message = error_message
                             raise IAToolkitException(IAToolkitException.ErrorType.CALL_ERROR, error_message)
-                    except Exception as e:
-                        error_message = f"Dispatch error en tool {function_name} con args {args} -******- {str(e)}"
-                        raise IAToolkitException(IAToolkitException.ErrorType.CALL_ERROR, error_message)
-
-                    result, tool_native_attachments = self._split_tool_result_and_native_attachments(result)
-                    active_attachments = self._merge_native_attachments(active_attachments, tool_native_attachments)
-
-                    # add the return value into the list of messages
-                    input_messages.append({
-                        "type": "function_call_output",
-                        "call_id": tool_call.call_id,
-                        "status": "completed",
-                        "output": self._serialize_tool_output(result)
-                    })
-                    history_messages.append({
-                        "type": "function_call_output",
-                        "call_id": tool_call.call_id,
-                        "status": "completed",
-                        "output": self._serialize_tool_output(result),
-                    })
-                    function_calls = True
+
+                        result, tool_native_attachments = self._split_tool_result_and_native_attachments(result)
+                        active_attachments = self._merge_native_attachments(active_attachments, tool_native_attachments)
+                        tool_result_for_telemetry = result
+                        tool_output_type = type(result).__name__
+                        tool_attachments_count = len(tool_native_attachments or [])
+
+                        # add the return value into the list of messages
+                        input_messages.append({
+                            "type": "function_call_output",
+                            "call_id": tool_call.call_id,
+                            "status": "completed",
+                            "output": self._serialize_tool_output(result)
+                        })
+                        history_messages.append({
+                            "type": "function_call_output",
+                            "call_id": tool_call.call_id,
+                            "status": "completed",
+                            "output": self._serialize_tool_output(result),
+                        })
+                        function_calls = True
+                    finally:
+                        tool_elapsed_seconds = time.time() - fcall_time
+                        telemetry_execution.log_child_span(
+                            tool_span,
+                            self._build_tool_telemetry_finish_event(
+                                function_name=function_name,
+                                call_id=tool_call_id,
+                                status=tool_status,
+                                elapsed_seconds=tool_elapsed_seconds,
+                                result=tool_result_for_telemetry,
+                                error_message=tool_error_message,
+                                output_type=tool_output_type,
+                                attachments_count=tool_attachments_count,
+                            ),
+                        )
+                        telemetry_execution.end_child_span(tool_span)
 
                     # log the function call parameters and execution time in secs
-                    elapsed = time.time() - fcall_time
+                    elapsed = tool_elapsed_seconds
                     f_call_identity = {function_name:args, 'time': f'{elapsed:.1f}' }
                     f_calls.append(f_call_identity)
                     f_call_time += elapsed
@@ -305,6 +357,8 @@ class llmClient:
             stats['model'] = model
 
             combined_stats = self.add_stats(stats, stats_fcall)
+            combined_stats["tool_call_count"] = len(f_calls)
+            combined_stats["tool_time_ms_total"] = int(round(f_call_time * 1000))
             if isinstance(execution_metadata, dict):
                 combined_stats = dict(combined_stats or {})
                 request_source = str(execution_metadata.get("request_source") or "").strip().lower()
@@ -344,6 +398,8 @@ class llmClient:
                     "total_tokens": combined_stats.get("total_tokens"),
                     "response_time": combined_stats.get("response_time"),
                     "sql_retry_count": combined_stats.get("sql_retry_count"),
+                    "tool_call_count": combined_stats.get("tool_call_count"),
+                    "tool_time_ms_total": combined_stats.get("tool_time_ms_total"),
                 },
             )
             telemetry_stats = telemetry_execution.build_stats()
@@ -479,6 +535,156 @@ class llmClient:
 
         return merged
 
+    @staticmethod
+    def _build_tool_telemetry_start_event(
+        company_short_name: str,
+        function_name: str,
+        call_id: str,
+        args: dict[str, Any],
+        request_source: str = "",
+    ) -> dict[str, Any]:
+        metadata = {
+            "company": company_short_name,
+            "tool_name": function_name,
+        }
+        if call_id:
+            metadata["call_id"] = call_id
+        if request_source:
+            metadata["request_source"] = request_source
+
+        return {
+            "metadata": metadata,
+            "input": {
+                "arguments": llmClient._sanitize_tool_payload_for_telemetry(args),
+            },
+        }
+
+    @staticmethod
+    def _build_tool_telemetry_finish_event(
+        function_name: str,
+        call_id: str,
+        status: Optional[str],
+        elapsed_seconds: float,
+        result: Any = None,
+        error_message: Optional[str] = None,
+        output_type: Optional[str] = None,
+        attachments_count: int = 0,
+    ) -> dict[str, Any]:
+        metadata: dict[str, Any] = {
+            "tool_name": function_name,
+            "status": status or "unknown",
+            "elapsed_ms": int(round(max(elapsed_seconds, 0.0) * 1000)),
+        }
+        if call_id:
+            metadata["call_id"] = call_id
+        if output_type:
+            metadata["output_type"] = output_type
+        if attachments_count:
+            metadata["attachments_count"] = attachments_count
+        if error_message:
+            metadata["error_message"] = llmClient._truncate_telemetry_string(str(error_message))
+
+        event: dict[str, Any] = {"metadata": metadata}
+        if result is not None:
+            event["output"] = {
+                "preview": llmClient._sanitize_tool_payload_for_telemetry(result, parent_key="output"),
+            }
+        return event
+
+    @staticmethod
+    def _sanitize_tool_payload_for_telemetry(
+        value: Any,
+        *,
+        parent_key: str = "",
+        depth: int = 0,
+    ) -> Any:
+        if depth >= TELEMETRY_MAX_DEPTH:
+            return "[TRUNCATED_DEPTH]"
+
+        if isinstance(value, dict):
+            sanitized: dict[str, Any] = {}
+            items = list(value.items())
+            for index, (key, item) in enumerate(items):
+                if index >= TELEMETRY_MAX_COLLECTION_ITEMS:
+                    sanitized["__truncated_items__"] = len(items) - TELEMETRY_MAX_COLLECTION_ITEMS
+                    break
+
+                key_str = str(key)
+                key_name = key_str.strip().lower()
+                if llmClient._is_sensitive_telemetry_key(key_name):
+                    sanitized[key_str] = TELEMETRY_REDACTED_VALUE
+                    continue
+
+                if key_name in {"request_images", "images"} and isinstance(item, list):
+                    sanitized[key_str] = {"count": len(item), "content": "[OMITTED_IMAGES]"}
+                    continue
+
+                if key_name in {"attachments", "native_attachments", "request_attachments"} and isinstance(item, list):
+                    sanitized[key_str] = {"count": len(item), "content": "[OMITTED_ATTACHMENTS]"}
+                    continue
+
+                sanitized[key_str] = llmClient._sanitize_tool_payload_for_telemetry(
+                    item,
+                    parent_key=key_name,
+                    depth=depth + 1,
+                )
+            return sanitized
+
+        if isinstance(value, (list, tuple, set)):
+            items = list(value)
+            sanitized_items = [
+                llmClient._sanitize_tool_payload_for_telemetry(item, parent_key=parent_key, depth=depth + 1)
+                for item in items[:TELEMETRY_MAX_COLLECTION_ITEMS]
+            ]
+            if len(items) > TELEMETRY_MAX_COLLECTION_ITEMS:
+                sanitized_items.append(f"[TRUNCATED_ITEMS:{len(items) - TELEMETRY_MAX_COLLECTION_ITEMS}]")
+            return sanitized_items
+
+        if isinstance(value, (bytes, bytearray)):
+            return f"[BINARY:{len(value)} bytes]"
+
+        if isinstance(value, str):
+            if llmClient._looks_like_base64(value) or parent_key in {"base64", "data"}:
+                return "[REDACTED_BINARY_TEXT]"
+            return llmClient._truncate_telemetry_string(value)
+
+        if isinstance(value, (int, float, bool)) or value is None:
+            return value
+
+        return llmClient._truncate_telemetry_string(str(value))
+
+    @staticmethod
+    def _is_sensitive_telemetry_key(key_name: str) -> bool:
+        if not key_name:
+            return False
+
+        return any(
+            marker in key_name
+            for marker in (
+                "api_key",
+                "apikey",
+                "secret",
+                "password",
+                "token",
+                "authorization",
+                "credential",
+            )
+        )
+
+    @staticmethod
+    def _looks_like_base64(value: str) -> bool:
+        candidate = str(value or "").strip()
+        if len(candidate) < 256 or len(candidate) % 4 != 0:
+            return False
+        return bool(re.fullmatch(r"[A-Za-z0-9+/=\s]+", candidate))
+
+    @staticmethod
+    def _truncate_telemetry_string(value: str, max_length: int = TELEMETRY_MAX_STRING_LENGTH) -> str:
+        text = str(value or "")
+        if len(text) <= max_length:
+            return text
+        return f"{text[:max_length]}...[truncated]"
+
     @staticmethod
     def _build_history_messages_from_response(response) -> list[dict]:
         if response is None: