✨ file to text tool

Author: Zhi-a

sdk/nexent/core/tools/analyze_text_file_tool.py

@@ -37,16 +37,16 @@ class AnalyzeTextFileTool(Tool):
     inputs = {
         "file_url_list": {
             "type": "array",
-            "description": "List of file URLs (S3, HTTP, or HTTPS). Supports s3://bucket/key, /bucket/key, http://, and https:// URLs. Can also accept a single file URL which will be treated as a list with one element."
+            "description": "List of file URLs (S3, HTTP, or HTTPS). Supports s3://bucket/key, /bucket/key, http://, and https:// URLs."
         },
         "query": {
             "type": "string",
             "description": "User's question to guide the analysis"
         }
     }
-    output_type = "string"
-    category = ToolCategory.FILE.value
-    tool_sign = ToolSign.FILE_OPERATION.value
+    output_type = "array"
+    category = ToolCategory.MULTIMODAL.value
+    tool_sign = ToolSign.MULTIMODAL_OPERATION.value
 
     def __init__(
         self,
@@ -76,30 +76,29 @@ def __init__(
         self.data_process_service_url = data_process_service_url
         self.mm = LoadSaveObjectManager(storage_client=self.storage_client)
 
-        self.running_prompt_zh = "正在分析文本文件..."
-        self.running_prompt_en = "Analyzing text file..."
+        self.running_prompt_zh = "正在分析文件..."
+        self.running_prompt_en = "Analyzing file..."
         # Dynamically apply the load_object decorator to forward method
         self.forward = self.mm.load_object(input_names=["file_url_list"])(self._forward_impl)
 
     def _forward_impl(
         self,
-        file_url_list: Union[bytes, List[bytes]],
+        file_url_list: List[bytes],
         query: str,
-    ) -> Union[str, List[str]]:
+    ) -> List[str]:
         """
         Analyze text file content using a large language model.
 
         Note: This method is wrapped by load_object decorator which downloads
         the image from S3 URL, HTTP URL, or HTTPS URL and passes bytes to this method.
 
         Args:
-            file_url_list: File bytes or a sequence of file bytes (converted from URLs by the decorator).
-                          The load_object decorator converts URLs to bytes before calling this method.
+            file_url_list: List of file bytes converted from URLs by the decorator.
+                           The load_object decorator converts URLs to bytes before calling this method.
             query: User's question to guide the analysis
 
         Returns:
-            Union[str, List[str]]: Single analysis string for one file or a list
-            of analysis strings that align with the order of the provided files.
+            List[str]: One analysis string per file that aligns with the order
         """
         # Send tool run message
         if self.observer:
@@ -109,19 +108,15 @@ def _forward_impl(
             self.observer.add_message("", ProcessType.CARD, json.dumps(card_content, ensure_ascii=False))
 
         if file_url_list is None:
-            raise ValueError("file_url_list must contain at least one file")
+            raise ValueError("file_url_list cannot be None")
 
-        if isinstance(file_url_list, (list, tuple)):
-            file_inputs: List[bytes] = list(file_url_list)
-        elif isinstance(file_url_list, bytes):
-            file_inputs = [file_url_list]
-        else:
-            raise ValueError("file_url_list must be bytes or a list/tuple of bytes")
+        if not isinstance(file_url_list, list):
+            raise ValueError("file_url_list must be a list of bytes")
 
         try:
             analysis_results: List[str] = []
 
-            for index, single_file in enumerate(file_inputs, start=1):
+            for index, single_file in enumerate(file_url_list, start=1):
                 logger.info(f"Extracting text content from file #{index}, query: {query}")
                 filename = f"file_{index}.txt"
 
@@ -143,8 +138,6 @@ def _forward_impl(
                     logger.error(f"Failed to analyze file #{index}: {analysis_error}")
                     analysis_results.append(str(analysis_error))
 
-            if len(analysis_results) == 1:
-                return analysis_results[0]
             return analysis_results
 
         except Exception as e:

sdk/nexent/core/utils/tools_common_message.py

@@ -11,6 +11,7 @@ class ToolSign(Enum):
     TAVILY_SEARCH = "d"  # Tavily search tool identifier
     FILE_OPERATION = "f"      # File operation tool identifier
     TERMINAL_OPERATION = "t"  # Terminal operation tool identifier
+    MULTIMODAL_OPERATION = "m"  # Multimodal operation tool identifier
 
 
 # Tool sign mapping for backward compatibility
@@ -21,6 +22,7 @@ class ToolSign(Enum):
     "exa_search": ToolSign.EXA_SEARCH.value,
     "file_operation": ToolSign.FILE_OPERATION.value,
     "terminal_operation": ToolSign.TERMINAL_OPERATION.value,
+    "multimodal_operation": ToolSign.MULTIMODAL_OPERATION.value,
 }
 
 # Reverse mapping for lookup
@@ -33,6 +35,7 @@ class ToolCategory(Enum):
     FILE = "file"
     EMAIL = "email"
     TERMINAL = "terminal"
+    MULTIMODAL = "multimodal"
 
 
 @dataclass

test/common/__init__.py

@@ -0,0 +1 @@
+"""Common utilities shared across backend tests."""

test/common/env_test_utils.py

@@ -0,0 +1,75 @@
+"""Shared helpers for image-service related tests."""
+
+from __future__ import annotations
+
+import sys
+import types
+from functools import lru_cache
+from pathlib import Path
+from typing import Dict, Any
+from unittest.mock import MagicMock
+
+
+def _ensure_path(path: Path) -> None:
+    if str(path) not in sys.path:
+        sys.path.insert(0, str(path))
+
+
+def _create_module(name: str, **attrs: Any) -> types.ModuleType:
+    module = types.ModuleType(name)
+    for attr_name, attr_value in attrs.items():
+        setattr(module, attr_name, attr_value)
+    sys.modules[name] = module
+    return module
+
+
+@lru_cache(maxsize=1)
+def bootstrap_env() -> Dict[str, Any]:
+    current_dir = Path(__file__).resolve().parent
+    project_root = current_dir.parents[1]
+    backend_dir = project_root / "backend"
+
+    _ensure_path(project_root)
+    _ensure_path(backend_dir)
+
+    mock_const = MagicMock()
+    consts_module = _create_module("consts", const=mock_const)
+    sys.modules["consts.const"] = mock_const
+
+    boto3_mock = MagicMock()
+    sys.modules.setdefault("boto3", boto3_mock)
+
+    client_module = _create_module(
+        "backend.database.client",
+        MinioClient=MagicMock(),
+        PostgresClient=MagicMock(),
+        db_client=MagicMock(),
+        get_db_session=MagicMock(),
+        as_dict=MagicMock(),
+        minio_client=MagicMock(),
+        postgres_client=MagicMock(),
+    )
+    sys.modules["database.client"] = client_module
+    if "database" not in sys.modules:
+        _create_module("database")
+
+    config_utils_module = _create_module(
+        "utils.config_utils",
+        tenant_config_manager=MagicMock(),
+        get_model_name_from_config=MagicMock(return_value=""),
+    )
+
+    nexent_module = _create_module("nexent", MessageObserver=MagicMock())
+    _create_module("nexent.core")
+    _create_module("nexent.core.models", OpenAIVLModel=MagicMock())
+
+    return {
+        "mock_const": mock_const,
+        "consts_module": consts_module,
+        "client_module": client_module,
+        "config_utils_module": config_utils_module,
+        "nexent_module": nexent_module,
+        "boto3_mock": boto3_mock,
+        "project_root": project_root,
+        "backend_dir": backend_dir,
+    }

test/sdk/core/agents/test_nexent_agent.py

@@ -491,6 +491,47 @@ def test_create_local_tool_success(nexent_agent_instance):
     assert result == mock_tool_instance
 
 
+def test_create_local_tool_analyze_text_file_tool(nexent_agent_instance):
+    """Test AnalyzeTextFileTool creation injects observer and metadata."""
+    mock_analyze_tool_class = MagicMock()
+    mock_analyze_tool_instance = MagicMock()
+    mock_analyze_tool_class.return_value = mock_analyze_tool_instance
+
+    tool_config = ToolConfig(
+        class_name="AnalyzeTextFileTool",
+        name="analyze_text_file",
+        description="desc",
+        inputs="{}",
+        output_type="array",
+        params={"prompt": "describe this"},
+        source="local",
+        metadata={
+            "llm_model": "llm_model_obj",
+            "storage_client": "storage_client_obj",
+        },
+    )
+
+    original_value = nexent_agent.__dict__.get("AnalyzeTextFileTool")
+    nexent_agent.__dict__["AnalyzeTextFileTool"] = mock_analyze_tool_class
+
+    try:
+        result = nexent_agent_instance.create_local_tool(tool_config)
+    finally:
+        if original_value is not None:
+            nexent_agent.__dict__["AnalyzeTextFileTool"] = original_value
+        elif "AnalyzeTextFileTool" in nexent_agent.__dict__:
+            del nexent_agent.__dict__["AnalyzeTextFileTool"]
+
+    mock_analyze_tool_class.assert_called_once_with(
+        observer=nexent_agent_instance.observer,
+        llm_model="llm_model_obj",
+        storage_client="storage_client_obj",
+        prompt="describe this",
+        data_process_service_url="https://example.com",
+    )
+    assert result == mock_analyze_tool_instance
+
+
 def test_create_local_tool_class_not_found(nexent_agent_instance):
     """Test create_local_tool raises ValueError when class is not found."""
     tool_config = ToolConfig(