iatoolkit 0.91.1__py3-none-any.whl → 1.7.0__py3-none-any.whl

iatoolkit/core.py

@@ -9,20 +9,26 @@ from flask_injector import FlaskInjector
 from flask_bcrypt import Bcrypt
 from flask_cors import CORS
 from iatoolkit.common.exceptions import IAToolkitException
-from typing import Optional, Dict, Any
 from iatoolkit.repositories.database_manager import DatabaseManager
+from iatoolkit.common.interfaces.asset_storage import AssetRepository
+from iatoolkit.company_registry import get_registered_companies
 from werkzeug.middleware.proxy_fix import ProxyFix
 from injector import Binder, Injector, singleton
+from typing import Optional, Dict, Any
 from urllib.parse import urlparse
 import redis
 import logging
 import os
 
 from iatoolkit import __version__ as IATOOLKIT_VERSION
+from iatoolkit.services.configuration_service import ConfigurationService
 
 # global variable for the unique instance of IAToolkit
 _iatoolkit_instance: Optional['IAToolkit'] = None
 
+def is_bound(injector: Injector, cls) -> bool:
+    return cls in injector.binder._bindings
+
 class IAToolkit:
     """
     IAToolkit main class
@@ -49,8 +55,8 @@ class IAToolkit:
         self.config = config or {}
         self.app = None
         self.db_manager = None
-        self._injector = None
-        self.version = IATOOLKIT_VERSION    # default version
+        self._injector = Injector()         # init empty injector
+        self.version = IATOOLKIT_VERSION
         self.license = "Community Edition"
 
     @classmethod
@@ -61,7 +67,7 @@ class IAToolkit:
             _iatoolkit_instance = cls()
         return _iatoolkit_instance
 
-    def create_iatoolkit(self):
+    def create_iatoolkit(self, start: bool = True):
         """
             Creates, configures, and returns the Flask application instance.
             this is the main entry point for the application factory.
@@ -77,8 +83,8 @@ class IAToolkit:
         # Step 2: Set up the core components that DI depends on
         self._setup_database()
 
-        # Step 3: Create the Injector and configure all dependencies in one place
-        self._injector = Injector(self._configure_core_dependencies)
+        # Step 3: Configure dependencies using the existing injector
+        self._configure_core_dependencies(self._injector)
 
         # Step 4: Register routes using the fully configured injector
         self._register_routes()
@@ -98,6 +104,7 @@ class IAToolkit:
 
         # Step 8: Finalize setup within the application context
         self._setup_redis_sessions()
+
         self._setup_cors()
         self._setup_additional_services()
         self._setup_cli_commands()
@@ -107,11 +114,21 @@ class IAToolkit:
         # Step 9: define the download_dir
         self._setup_download_dir()
 
+        # register data source
+        if start:
+            self.register_data_sources()
+
         logging.info(f"🎉 IAToolkit {self.license} version {self.version} correctly initialized.")
         self._initialized = True
 
         return self.app
 
+    def register_data_sources(self):
+        # load the company configurations
+        configuration_service = self._injector.get(ConfigurationService)
+        for company in get_registered_companies():
+            configuration_service.register_data_sources(company)
+
     def _get_config_value(self, key: str, default=None):
         # get a value from the config dict or the environment variable
         return self.config.get(key, os.getenv(key, default))
@@ -181,11 +198,11 @@ class IAToolkit:
             os.environ["TOKENIZERS_PARALLELISM"] = "false"
 
     def _setup_database(self):
-        database_uri = self._get_config_value('DATABASE_URI')
+        database_uri = self._get_config_value('DATABASE_URI') or self._get_config_value('DATABASE_URL')
         if not database_uri:
             raise IAToolkitException(
                 IAToolkitException.ErrorType.CONFIG_ERROR,
-                "DATABASE_URI is requires (config dict or env. variable)"
+                "DATABASE_URI is required (config dict or env. variable)"
             )
 
         self.db_manager = DatabaseManager(database_url=database_uri, schema='iatoolkit')
@@ -240,8 +257,9 @@ class IAToolkit:
         extra_origins = []
         all_company_instances = get_company_registry().get_all_company_instances()
         for company_name, company_instance in all_company_instances.items():
-            cors_origin = company_instance.company.parameters.get('cors_origin', [])
-            extra_origins += cors_origin
+            if company_instance.company:
+                cors_origin = company_instance.company.parameters.get('cors_origin', [])
+                extra_origins += cors_origin
 
         all_origins = default_origins + extra_origins
 
@@ -256,8 +274,11 @@ class IAToolkit:
 
         logging.info(f"✅ CORS configured for: {all_origins}")
 
-    def _configure_core_dependencies(self, binder: Binder):
+    def _configure_core_dependencies(self, injector: Injector):
         """⚙️ Configures all system dependencies."""
+
+        # get the binder from injector
+        binder = injector.binder
         try:
             # Core dependencies
             binder.bind(Flask, to=self.app)
@@ -282,17 +303,19 @@ class IAToolkit:
         from iatoolkit.repositories.profile_repo import ProfileRepo
         from iatoolkit.repositories.llm_query_repo import LLMQueryRepo
         from iatoolkit.repositories.vs_repo import VSRepo
-        from iatoolkit.repositories.tasks_repo import TaskRepo
+        from iatoolkit.repositories.filesystem_asset_repository import FileSystemAssetRepository
 
         binder.bind(DocumentRepo, to=DocumentRepo)
         binder.bind(ProfileRepo, to=ProfileRepo)
         binder.bind(LLMQueryRepo, to=LLMQueryRepo)
         binder.bind(VSRepo, to=VSRepo)
-        binder.bind(TaskRepo, to=TaskRepo)
+
+        # this class can be setup befor by iatoolkit enterprise
+        if not is_bound(self._injector, AssetRepository):
+            binder.bind(AssetRepository, to=FileSystemAssetRepository)
 
     def _bind_services(self, binder: Binder):
         from iatoolkit.services.query_service import QueryService
-        from iatoolkit.services.tasks_service import TaskService
         from iatoolkit.services.benchmark_service import BenchmarkService
         from iatoolkit.services.document_service import DocumentService
         from iatoolkit.services.prompt_service import PromptService
@@ -309,9 +332,12 @@ class IAToolkit:
         from iatoolkit.services.embedding_service import EmbeddingService
         from iatoolkit.services.history_manager_service import HistoryManagerService
         from iatoolkit.services.tool_service import ToolService
+        from iatoolkit.services.llm_client_service import llmClient
+        from iatoolkit.services.auth_service import AuthService
+        from iatoolkit.services.sql_service import SqlService
+        from iatoolkit.services.knowledge_base_service import KnowledgeBaseService
 
         binder.bind(QueryService, to=QueryService)
-        binder.bind(TaskService, to=TaskService)
         binder.bind(BenchmarkService, to=BenchmarkService)
         binder.bind(DocumentService, to=DocumentService)
         binder.bind(PromptService, to=PromptService)
@@ -328,21 +354,23 @@ class IAToolkit:
         binder.bind(EmbeddingService, to=EmbeddingService)
         binder.bind(HistoryManagerService, to=HistoryManagerService)
         binder.bind(ToolService, to=ToolService)
+        binder.bind(llmClient, to=llmClient)
+        binder.bind(AuthService, to=AuthService)
+        binder.bind(SqlService, to=SqlService)
+        binder.bind(KnowledgeBaseService, to=KnowledgeBaseService)
 
     def _bind_infrastructure(self, binder: Binder):
-        from iatoolkit.infra.llm_client import llmClient
         from iatoolkit.infra.llm_proxy import LLMProxy
         from iatoolkit.infra.google_chat_app import GoogleChatApp
         from iatoolkit.infra.brevo_mail_app import BrevoMailApp
-        from iatoolkit.services.auth_service import AuthService
         from iatoolkit.common.util import Utility
+        from iatoolkit.common.model_registry import ModelRegistry
 
         binder.bind(LLMProxy, to=LLMProxy)
-        binder.bind(llmClient, to=llmClient)
         binder.bind(GoogleChatApp, to=GoogleChatApp)
         binder.bind(BrevoMailApp, to=BrevoMailApp)
-        binder.bind(AuthService, to=AuthService)
         binder.bind(Utility, to=Utility)
+        binder.bind(ModelRegistry, to=ModelRegistry)
 
     def _setup_additional_services(self):
         Bcrypt(self.app)
@@ -406,11 +434,13 @@ class IAToolkit:
                 'app_name': 'IAToolkit',
                 'user_identifier': SessionManager.get('user_identifier'),
                 'company_short_name': SessionManager.get('company_short_name'),
+                'user_role': user_profile.get('user_role'),
                 'user_is_local': user_profile.get('user_is_local'),
                 'user_email': user_profile.get('user_email'),
                 'iatoolkit_base_url': request.url_root,
                 'flashed_messages': get_flashed_messages(with_categories=True),
-                't': translate_for_template
+                't': translate_for_template,
+                'google_analytics_id': self._get_config_value('GOOGLE_ANALYTICS_ID', ''),
             }
 
     def _get_default_static_folder(self) -> str:
@@ -474,6 +504,7 @@ class IAToolkit:
         logging.info(f"✅ download dir created in: {download_dir}")
 
 
+
 def current_iatoolkit() -> IAToolkit:
     return IAToolkit.get_instance()
 

iatoolkit/infra/connectors/file_connector_factory.py

@@ -40,6 +40,7 @@ class FileConnectorFactory:
             return S3Connector(
                 bucket=config['bucket'],
                 prefix=config.get('prefix', ''),
+                folder=config.get('folder', ''),
                 auth=auth
             )
 

iatoolkit/infra/connectors/s3_connector.py

@@ -9,14 +9,16 @@ from typing import List
 
 
 class S3Connector(FileConnector):
-    def __init__(self, bucket: str, prefix: str, auth: dict):
+    def __init__(self, bucket: str, prefix: str, folder: str, auth: dict):
         self.bucket = bucket
         self.prefix = prefix
+        self.folder = folder
         self.s3 = boto3.client('s3', **auth)
 
     def list_files(self) -> List[dict]:
         # list all the files as dictionaries, with keys:  'path', 'name' y 'metadata'.
-        response = self.s3.list_objects_v2(Bucket=self.bucket, Prefix=self.prefix)
+        prefix = f'{self.prefix}/{self.folder}/'
+        response = self.s3.list_objects_v2(Bucket=self.bucket, Prefix=prefix)
         files = response.get('Contents', [])
 
         return [

iatoolkit/infra/llm_providers/deepseek_adapter.py

@@ -0,0 +1,278 @@
+# deepseek_adapter.py
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+import logging
+from typing import Dict, List, Optional, Any
+
+from iatoolkit.infra.llm_response import LLMResponse, ToolCall, Usage
+from iatoolkit.common.exceptions import IAToolkitException
+import json
+
+class DeepseekAdapter:
+    """
+    Adapter for DeepSeek using the OpenAI-compatible Chat Completions API.
+    It translates IAToolkit's common request/response format into
+    DeepSeek chat.completions calls.
+    """
+
+    def __init__(self, deepseek_client):
+        # deepseek_client is an OpenAI client configured with base_url="https://api.deepseek.com"
+        self.client = deepseek_client
+
+    # ------------------------------------------------------------------
+    # Public entry point
+    # ------------------------------------------------------------------
+
+    def create_response(self, model: str, input: List[Dict], **kwargs) -> LLMResponse:
+        """
+        Entry point called by LLMProxy.
+
+        :param model: DeepSeek model name (e.g. "deepseek-chat").
+        :param input: Common IAToolkit input list. It may contain:
+                      - normal messages: {"role": "...", "content": "..."}
+                      - function outputs: {"type": "function_call_output",
+                                           "call_id": "...", "output": "..."}
+        :param kwargs: extra options (tools, tool_choice, context_history, etc.).
+        """
+        tools = kwargs.get("tools") or []
+        tool_choice = kwargs.get("tool_choice", "auto")
+        context_history = kwargs.get("context_history") or []
+
+        try:
+            # 1) Build messages from history (if any)
+            messages: List[Dict[str, Any]] = []
+            if context_history:
+                history_messages = self._build_messages_from_input(context_history)
+                messages.extend(history_messages)
+
+            # 2) Append current turn messages
+            current_messages = self._build_messages_from_input(input)
+            messages.extend(current_messages)
+
+            # Detect if this input already contains function_call_output items.
+            # That means we are in the "second phase" after executing tools.
+            has_function_outputs = any(
+                item.get("type") == "function_call_output" for item in input
+            )
+
+            # 3) Build the tools payload
+            tools_payload = self._build_tools_payload(tools)
+
+            # If we already have function_call_output messages and the caller did not force
+            # a specific tool_choice (e.g. "required" for SQL retry), we disable tools and
+            # tool_choice to avoid infinite tool-calling loops (especially with iat_sql_query).
+            if has_function_outputs and tool_choice == "auto":
+                logging.debug(
+                    "[DeepseekAdapter] Detected function_call_output in input; "
+                    "disabling tools and tool_choice to avoid tool loop."
+                )
+                tools_payload = None
+                tool_choice = None
+
+            logging.debug(f"[DeepseekAdapter] messages={messages}")
+            logging.debug(f"[DeepseekAdapter] tools={tools_payload}, tool_choice={tool_choice}")
+
+            # Build kwargs for API call, skipping empty parameters
+            call_kwargs: Dict[str, Any] = {
+                "model": model,
+                "messages": messages,
+            }
+            if tools_payload:
+                call_kwargs["tools"] = tools_payload
+            if tool_choice:
+                call_kwargs["tool_choice"] = tool_choice
+
+            logging.debug(f"[DeepseekAdapter] Calling DeepSeek chat.completions API...: {json.dumps(messages, indent=2)}")
+            response = self.client.chat.completions.create(**call_kwargs)
+
+            return self._map_deepseek_chat_response(response)
+
+        except IAToolkitException:
+            # Re-raise IAToolkit exceptions as is
+            raise
+        except Exception as ex:
+            logging.exception("Unexpected error calling DeepSeek")
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.LLM_ERROR,
+                f"DeepSeek error: {ex}"
+            ) from ex
+
+    # ------------------------------------------------------------------
+    # Helpers to build the request
+    # ------------------------------------------------------------------
+
+    def _build_messages_from_input(self, input_items: List[Dict]) -> List[Dict]:
+        """
+        Transform IAToolkit 'input' items into ChatCompletion 'messages'.
+
+        We handle:
+        - Standard messages with 'role' and 'content'.
+        - function_call_output items by converting them into assistant messages
+          containing the tool result, so the model can use them to answer.
+        """
+        messages: List[Dict[str, Any]] = []
+
+        for item in input_items:
+            # Tool call outputs are mapped to assistant messages with the tool result.
+            if item.get("type") == "function_call_output":
+                output = item.get("output", "")
+                if not output:
+                    logging.warning(
+                        "[DeepseekAdapter] function_call_output item without 'output': %s",
+                        item
+                    )
+                    continue
+
+                messages.append(
+                    {
+                        "role": "user",
+                        "content": f"Tool result:\n{output}",
+                    }
+                )
+                continue
+
+            role = item.get("role")
+            content = item.get("content")
+
+            # Skip tool-role messages completely for DeepSeek
+            if role == "tool":
+                logging.warning(f"[DeepseekAdapter] Skipping tool-role message: {item}")
+                continue
+
+            if not role:
+                logging.warning(f"[DeepseekAdapter] Skipping message without role: {item}")
+                continue
+
+            messages.append({"role": role, "content": content})
+
+        return messages
+
+    def _build_tools_payload(self, tools: List[Dict]) -> Optional[List[Dict]]:
+        """
+        Transform IAToolkit tool definitions into DeepSeek/OpenAI chat tools format.
+
+        Expected internal tool format:
+        {
+            "type": "function",
+            "name": ...,
+            "description": ...,
+            "parameters": {...},
+            "strict": True/False
+        }
+        Or already in OpenAI tools format with "function" key.
+        """
+        if not tools:
+            return None
+
+        tools_payload: List[Dict[str, Any]] = []
+
+        for tool in tools:
+            # If it's already in OpenAI 'function' format, reuse it
+            if "function" in tool:
+                func_def = tool["function"]
+            else:
+                # Build function definition from flattened structure
+                func_def = {
+                    "name": tool.get("name"),
+                    "description": tool.get("description", ""),
+                    "parameters": tool.get("parameters", {}) or {},
+                }
+
+            # Ensure parameters is a dict
+            if "parameters" in func_def and not isinstance(func_def["parameters"], dict):
+                logging.warning(
+                    "Tool parameters must be a dict; got %s",
+                    type(func_def["parameters"])
+                )
+                func_def["parameters"] = {}
+
+            ds_tool: Dict[str, Any] = {
+                "type": tool.get("type", "function"),
+                "function": func_def,
+            }
+
+            if tool.get("strict") is True:
+                ds_tool["strict"] = True
+
+            tools_payload.append(ds_tool)
+
+        return tools_payload or None
+
+    # ------------------------------------------------------------------
+    # Mapping DeepSeek response -> LLMResponse
+    # ------------------------------------------------------------------
+
+    def _map_deepseek_chat_response(self, response: Any) -> LLMResponse:
+        """
+        Map DeepSeek Chat Completion response to our common LLMResponse.
+        Handles both plain assistant messages and tool_calls.
+        """
+        # We only look at the first choice
+        if not response.choices:
+            raise IAToolkitException(
+                IAToolkitException.ErrorType.LLM_ERROR,
+                "DeepSeek response has no choices."
+            )
+
+        choice = response.choices[0]
+        message = choice.message
+
+        # Usage mapping
+        usage = Usage(
+            input_tokens=getattr(getattr(response, "usage", None), "prompt_tokens", 0) or 0,
+            output_tokens=getattr(getattr(response, "usage", None), "completion_tokens", 0) or 0,
+            total_tokens=getattr(getattr(response, "usage", None), "total_tokens", 0) or 0,
+        )
+
+        # Capture reasoning content (specific to deepseek-reasoner)
+        reasoning_content = getattr(message, "reasoning_content", "") or ""
+
+        # If the model produced tool calls, fills this list
+        tool_calls_out: List[ToolCall] = []
+
+        tool_calls = getattr(message, "tool_calls", None) or []
+        if not tool_calls:
+            # No tool calls: standard assistant message
+            output_text = getattr(message, "content", "") or ""
+            status = "completed"
+
+        else:
+            logging.debug(f"[DeepSeek] RAW tool_calls: {tool_calls}")
+
+            for tc in tool_calls:
+                func = getattr(tc, "function", None)
+                if not func:
+                    continue
+
+                name = getattr(func, "name", "")
+                arguments = getattr(func, "arguments", "") or "{}"
+
+                # DeepSeek/OpenAI return arguments as JSON string
+                logging.debug(
+                    f"[DeepSeek] ToolCall generated -> id={getattr(tc, 'id', '')} "
+                    f"name={name} arguments_raw={arguments}"
+                )
+                tool_calls_out.append(
+                    ToolCall(
+                        call_id=getattr(tc, "id", ""),
+                        type="function_call",
+                        name=name,
+                        arguments=arguments,
+                    )
+                )
+
+            status = "tool_calls"
+            output_text = ""  # caller will inspect tool_calls in .output
+
+        return LLMResponse(
+            id=getattr(response, "id", "deepseek-unknown"),
+            model=getattr(response, "model", "deepseek-unknown"),
+            status=status,
+            output_text=output_text,
+            output=tool_calls_out,
+            usage=usage,
+            reasoning_content=reasoning_content
+        )

iatoolkit/infra/{gemini_adapter.py → llm_providers/gemini_adapter.py}

@@ -13,13 +13,11 @@ import json
 import uuid
 
 class GeminiAdapter:
-    """Adaptador para la API de Gemini"""
 
     def __init__(self, gemini_client):
-        """Inicializar con cliente Gemini ya configurado"""
         self.client = gemini_client
 
-        # Configuración de seguridad - permitir contenido que podría ser bloqueado por defecto
+        # security configuration - allow content that might be blocked by default
         self.safety_settings = {
             HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_NONE,
             HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_NONE,
@@ -37,38 +35,36 @@ class GeminiAdapter:
                         reasoning: Optional[Dict] = None,
                         tool_choice: str = "auto",
                         ) -> LLMResponse:
-        """Llamada a la API de Gemini y mapeo a estructura común"""
         try:
-            # Inicializar el modelo de Gemini usando el cliente configurado
+            # init the model with the configured client
             gemini_model = self.client.GenerativeModel(
                 model_name=self._map_model_name(model),
                 safety_settings=self.safety_settings
             )
 
-            # Preparar el contenido para Gemini
+            # prepare the content for gemini
             if context_history:
-                # Concatenar el historial de conversación con el input actual
+                # concat the history with the current input
                 contents = self._prepare_gemini_contents(context_history + input)
             else:
-                # Usar solo el input actual si no hay historial
                 contents = self._prepare_gemini_contents(input)
 
-            # Preparar herramientas si están disponibles
+            # prepare tools
             gemini_tools = self._prepare_gemini_tools(tools) if tools else None
 
-            # Configurar generación
+            # config generation
             generation_config = self._prepare_generation_config(text, tool_choice)
 
-            # Llamar a Gemini
+            # call gemini
             if gemini_tools:
-                # Con herramientas
+                # with tools
                 response = gemini_model.generate_content(
                     contents,
                     tools=gemini_tools,
                     generation_config=generation_config
                 )
             else:
-                # Sin herramientas
+                # without tools
                 response = gemini_model.generate_content(
                     contents,
                     generation_config=generation_config
@@ -102,9 +98,7 @@ class GeminiAdapter:
 
             raise IAToolkitException(IAToolkitException.ErrorType.LLM_ERROR, error_message)
 
-    # ... rest of the methods keep the same ...
     def _map_model_name(self, model: str) -> str:
-        """Mapear nombre del modelo a formato de Gemini"""
         model_mapping = {
             "gemini-pro": "gemini-2.5-pro",
             "gemini": "gemini-2.5-pro",
@@ -115,7 +109,7 @@ class GeminiAdapter:
         return model_mapping.get(model.lower(), model)
 
     def _prepare_gemini_contents(self, input: List[Dict]) -> List[Dict]:
-        """Convertir mensajes de formato OpenAI a formato Gemini"""
+        # convert input messages to Gemini format
         gemini_contents = []
 
         for message in input:
@@ -143,7 +137,7 @@ class GeminiAdapter:
         return gemini_contents
 
     def _prepare_gemini_tools(self, tools: List[Dict]) -> List[Dict]:
-        """Convertir herramientas de formato OpenAI a formato Gemini"""
+        # convert tools to Gemini format
         if not tools:
             return None
 

iatoolkit/infra/{openai_adapter.py → llm_providers/openai_adapter.py}

@@ -7,7 +7,8 @@ import logging
 from typing import Dict, List, Optional
 from iatoolkit.infra.llm_response import LLMResponse, ToolCall, Usage
 from iatoolkit.common.exceptions import IAToolkitException
-
+import html
+from typing import List
 
 class OpenAIAdapter:
     """Adaptador para la API de OpenAI"""
@@ -53,10 +54,6 @@ class OpenAIAdapter:
             error_message = f"Error calling OpenAI API: {str(e)}"
             logging.error(error_message)
 
-            # En caso de error de contexto
-            if "context_length_exceeded" in str(e):
-                error_message = 'Tu consulta supera el limite de contexto. Reinicia el contexto con el boton de la barra superior.'
-
             raise IAToolkitException(IAToolkitException.ErrorType.LLM_ERROR, error_message)
 
     def _map_openai_response(self, openai_response) -> LLMResponse:
@@ -80,11 +77,48 @@ class OpenAIAdapter:
             total_tokens=openai_response.usage.total_tokens if openai_response.usage else 0
         )
 
+        # Reasoning content extracted from Responses output items (type="reasoning")
+        reasoning_list = self._extract_reasoning_content(openai_response)
+        reasoning_str = "\n".join(reasoning_list)
+
         return LLMResponse(
             id=openai_response.id,
             model=openai_response.model,
             status=openai_response.status,
             output_text=getattr(openai_response, 'output_text', ''),
             output=tool_calls,
-            usage=usage
-        )
+            usage=usage,
+            reasoning_content=reasoning_str
+        )
+
+    def _extract_reasoning_content(self, openai_response) -> List[str]:
+        """
+        Extract reasoning summaries (preferred) or reasoning content fragments from Responses API output.
+
+        Format required by caller:
+          1. reason is ...
+          2. reason is ...
+        """
+        reasons: List[str] = []
+
+        output_items = getattr(openai_response, "output", None) or []
+        for item in output_items:
+            if getattr(item, "type", None) != "reasoning":
+                continue
+
+            # 1) Preferred: reasoning summaries (requires reasoning={"summary":"auto"} or similar)
+            summary = getattr(item, "summary", None) or []
+            for s in summary:
+                text = getattr(s, "text", None)
+                if text:
+                    reasons.append(str(text).strip())
+
+            # 2) Fallback: some responses may carry reasoning content in "content"
+            # (e.g., content parts like {"type":"reasoning_text","text":"..."}).
+            content = getattr(item, "content", None) or []
+            for c in content:
+                text = getattr(c, "text", None)
+                if text:
+                    reasons.append(str(text).strip())
+
+        return reasons