hamtaa-texttools 1.1.0__tar.gz → 1.1.2__tar.gz

{hamtaa_texttools-1.1.0/hamtaa_texttools.egg-info → hamtaa_texttools-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.1.0
+Version: 1.1.2
 Summary: A high-level NLP toolkit built on top of modern LLMs.
 Author-email: Tohidi <the.mohammad.tohidi@gmail.com>, Montazer <montazerh82@gmail.com>, Givechi <mohamad.m.givechi@gmail.com>, MoosaviNejad <erfanmoosavi84@gmail.com>
 License: MIT License
@@ -29,7 +29,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: openai==1.97.1
-Requires-Dist: PyYAML>=6.0
+Requires-Dist: pyyaml>=6.0
 Dynamic: license-file
 
 # TextTools

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2/hamtaa_texttools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.1.0
+Version: 1.1.2
 Summary: A high-level NLP toolkit built on top of modern LLMs.
 Author-email: Tohidi <the.mohammad.tohidi@gmail.com>, Montazer <montazerh82@gmail.com>, Givechi <mohamad.m.givechi@gmail.com>, MoosaviNejad <erfanmoosavi84@gmail.com>
 License: MIT License
@@ -29,7 +29,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: openai==1.97.1
-Requires-Dist: PyYAML>=6.0
+Requires-Dist: pyyaml>=6.0
 Dynamic: license-file
 
 # TextTools

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/hamtaa_texttools.egg-info/requires.txt

@@ -1,2 +1,2 @@
 openai==1.97.1
-PyYAML>=6.0
+pyyaml>=6.0

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/pyproject.toml

@@ -1,32 +1,32 @@
-[build-system]
-requires = ["setuptools>=61.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "hamtaa-texttools"
-version = "1.1.0"
-authors = [
-  { name = "Tohidi", email = "the.mohammad.tohidi@gmail.com" },
-  { name = "Montazer", email = "montazerh82@gmail.com" },
-  { name = "Givechi", email = "mohamad.m.givechi@gmail.com" },
-  { name = "MoosaviNejad", email = "erfanmoosavi84@gmail.com" },
-]
-description = "A high-level NLP toolkit built on top of modern LLMs."
-readme = "README.md"
-license = {file = "LICENSE"}
-requires-python = ">=3.8"
-dependencies = [
-  "openai==1.97.1",
-  "PyYAML>=6.0",
-]
-keywords = ["nlp", "llm", "text-processing", "openai"]
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["texttools*"]
-
-[tool.setuptools]
-include-package-data = true
-
-[tool.setuptools.package-data]
-"texttools" = ["prompts/*.yaml", "prompts/*.yml"]
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hamtaa-texttools"
+version = "1.1.2"
+authors = [
+  { name = "Tohidi", email = "the.mohammad.tohidi@gmail.com" },
+  { name = "Montazer", email = "montazerh82@gmail.com" },
+  { name = "Givechi", email = "mohamad.m.givechi@gmail.com" },
+  { name = "MoosaviNejad", email = "erfanmoosavi84@gmail.com" },
+]
+description = "A high-level NLP toolkit built on top of modern LLMs."
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+dependencies = [
+  "openai==1.97.1",
+  "pyyaml>=6.0",
+]
+keywords = ["nlp", "llm", "text-processing", "openai"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["texttools*"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+"texttools" = ["prompts/*.yaml", "prompts/*.yml"]

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/texttools/batch/batch_manager.py

@@ -8,7 +8,6 @@ from pydantic import BaseModel
 from openai import OpenAI
 from openai.lib._pydantic import to_strict_json_schema
 
-# Configure logger
 logger = logging.getLogger("batch_runner")
 logger.setLevel(logging.INFO)
 

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/texttools/batch/batch_runner.py

@@ -12,7 +12,6 @@ from pydantic import BaseModel
 
 from texttools.batch import SimpleBatchManager
 
-# Configure logger
 logger = logging.getLogger("batch_runner")
 logger.setLevel(logging.INFO)
 

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/texttools/tools/async_the_tool.py

@@ -34,12 +34,15 @@ class AsyncTheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Categorize a text into a single Islamic studies domain category.
 
         Returns:
-            {"result": <category string>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The assigned Islamic studies category
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -66,12 +69,15 @@ class AsyncTheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, list[str]]:
+    ) -> OutputModels.ToolOutput:
         """
         Extract salient keywords from text.
 
         Returns:
-            {"result": [<keyword1>, <keyword2>, ...]} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (list[str]): List of extracted keywords
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -98,12 +104,15 @@ class AsyncTheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, list[dict[str, str]]]:
+    ) -> OutputModels.ToolOutput:
         """
         Perform Named Entity Recognition (NER) over the input text.
 
         Returns:
-            {"result": [{"text": <entity>, "type": <entity_type>}, ...]} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (list[dict]): List of entities with 'text' and 'type' keys
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -129,12 +138,15 @@ class AsyncTheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, bool]:
+    ) -> OutputModels.ToolOutput:
         """
         Detect if the input is phrased as a question.
 
         Returns:
-            {"result": True} or {"result": False} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (bool): True if text is a question, False otherwise
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -161,12 +173,15 @@ class AsyncTheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Generate a single question from the given text.
 
         Returns:
-            {"result": <generated_question>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The generated question
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -194,12 +209,15 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         mode: Literal["default", "reason"] = "default",
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Merge multiple questions into a single unified question.
 
         Returns:
-            {"result": <merged_question>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The merged question
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         text = ", ".join(text)
         return await self.operator.run(
@@ -228,12 +246,15 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         mode: Literal["positive", "negative", "hard_negative"] = "positive",
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Rewrite a text with different modes.
 
         Returns:
-            {"result": <rewritten_text>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The rewritten text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -261,12 +282,15 @@ class AsyncTheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, list[str]]:
+    ) -> OutputModels.ToolOutput:
         """
         Generate a list of questions about a subject.
 
         Returns:
-            {"result": [<question1>, <question2>, ...]} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (list[str]): List of generated questions
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -294,12 +318,15 @@ class AsyncTheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Summarize the given subject text.
 
         Returns:
-            {"result": <summary>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The summary text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -326,12 +353,15 @@ class AsyncTheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Translate text between languages.
 
         Returns:
-            {"result": <translated_text>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The translated text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return await self.operator.run(
             # User parameters
@@ -358,12 +388,13 @@ class AsyncTheTool:
         temperature: float | None = None,
         logprobs: bool | None = None,
         top_logprobs: int | None = None,
-    ) -> dict[str, Any]:
+    ) -> OutputModels.ToolOutput:
         """
         Custom tool that can do almost anything!
 
         Returns:
-            {"result": <Any>}
+            ToolOutput: Object with fields:
+                - result (str): The output result
         """
         return await self.operator.run(
             # User paramaeters

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/texttools/tools/internals/async_operator.py

@@ -12,7 +12,6 @@ from texttools.tools.internals.prompt_loader import PromptLoader
 # Base Model type for output models
 T = TypeVar("T", bound=BaseModel)
 
-# Configure logger
 logger = logging.getLogger("async_operator")
 logger.setLevel(logging.INFO)
 
@@ -32,6 +31,10 @@ class AsyncOperator(BaseOperator):
         self.model = model
 
     async def _analyze(self, prompt_configs: dict[str, str], temperature: float) -> str:
+        """
+        Calls OpenAI API for analysis using the configured prompt template.
+        Returns the analyzed content as a string.
+        """
         analyze_prompt = prompt_configs["analyze_template"]
         analyze_message = [self._build_user_message(analyze_prompt)]
         completion = await self.client.chat.completions.create(
@@ -50,6 +53,10 @@ class AsyncOperator(BaseOperator):
         logprobs: bool = False,
         top_logprobs: int = 3,
     ) -> tuple[Type[T], Any]:
+        """
+        Parses a chat completion using OpenAI's structured output format.
+        Returns both the parsed object and the raw completion for logging.
+        """
         request_kwargs = {
             "model": self.model,
             "messages": message,
@@ -73,6 +80,10 @@ class AsyncOperator(BaseOperator):
         logprobs: bool = False,
         top_logprobs: int = 3,
     ) -> tuple[Type[T], Any]:
+        """
+        Generates a completion using vLLM with JSON schema guidance.
+        Returns the parsed output model and raw completion.
+        """
         json_schema = output_model.model_json_schema()
 
         # Build kwargs dynamically
@@ -110,14 +121,16 @@ class AsyncOperator(BaseOperator):
         resp_format: Literal["vllm", "parse"],
         mode: str | None,
         **extra_kwargs,
-    ) -> dict[str, Any]:
+    ) -> ToolOutput:
         """
         Execute the async LLM pipeline with the given input text. (Async)
         """
         prompt_loader = PromptLoader()
         formatter = Formatter()
+        output = ToolOutput(result="", analysis="", logprobs=[], errors=[])
 
         try:
+            # Prompt configs contain two keys: main_template and analyze template, both are string
             prompt_configs = prompt_loader.load(
                 prompt_file=prompt_file,
                 text=text.strip(),
@@ -159,11 +172,10 @@ class AsyncOperator(BaseOperator):
 
             # Ensure output_model has a `result` field
             if not hasattr(parsed, "result"):
-                logger.error(
-                    "The provided output_model must define a field named 'result'"
-                )
-
-            output = ToolOutput(result="", analysis="", logprobs=[], errors=[])
+                error = "The provided output_model must define a field named 'result'"
+                logger.error(error)
+                output.errors.append(error)
+                return output
 
             output.result = parsed.result
 
@@ -174,6 +186,7 @@ class AsyncOperator(BaseOperator):
                 output.analysis = analysis
 
             return output
+
         except Exception as e:
             logger.error(f"AsyncTheTool failed: {e}")
-            return ToolOutput(result="", analysis="", logprobs=[], errors=[str(e)])
+            return output.errors.append(str(e))

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/texttools/tools/internals/base_operator.py

@@ -10,7 +10,6 @@ from openai import OpenAI, AsyncOpenAI
 # Base Model type for output models
 T = TypeVar("T", bound=BaseModel)
 
-# Configure logger
 logger = logging.getLogger("base_operator")
 logger.setLevel(logging.INFO)
 
@@ -40,13 +39,6 @@ class BaseOperator:
     ) -> Type[T]:
         """
         Convert a JSON response string to output model.
-
-        Args:
-            response_string: The JSON string (may contain code block markers)
-            output_model: Your Pydantic output model class (e.g., StrOutput, ListStrOutput)
-
-        Returns:
-            Instance of your output model
         """
         # Clean the response string
         cleaned_json = self._clean_json_response(response_string)
@@ -61,7 +53,12 @@ class BaseOperator:
         return output_model(**response_dict)
 
     def _extract_logprobs(self, completion: dict) -> list[dict[str, Any]]:
+        """
+        Extracts and filters token probabilities from completion logprobs.
+        Skips punctuation and structural tokens, returns cleaned probability data.
+        """
         logprobs_data = []
+
         ignore_pattern = re.compile(r'^(result|[\s\[\]\{\}",:]+)$')
 
         for choice in completion.choices:

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/texttools/tools/internals/operator.py

@@ -12,7 +12,6 @@ from texttools.tools.internals.prompt_loader import PromptLoader
 # Base Model type for output models
 T = TypeVar("T", bound=BaseModel)
 
-# Configure logger
 logger = logging.getLogger("operator")
 logger.setLevel(logging.INFO)
 
@@ -32,6 +31,10 @@ class Operator(BaseOperator):
         self.model = model
 
     def _analyze(self, prompt_configs: dict[str, str], temperature: float) -> str:
+        """
+        Calls OpenAI API for analysis using the configured prompt template.
+        Returns the analyzed content as a string.
+        """
         analyze_prompt = prompt_configs["analyze_template"]
         analyze_message = [self._build_user_message(analyze_prompt)]
         completion = self.client.chat.completions.create(
@@ -50,6 +53,10 @@ class Operator(BaseOperator):
         logprobs: bool = False,
         top_logprobs: int = 3,
     ) -> tuple[Type[T], Any]:
+        """
+        Parses a chat completion using OpenAI's structured output format.
+        Returns both the parsed object and the raw completion for logging.
+        """
         request_kwargs = {
             "model": self.model,
             "messages": message,
@@ -73,6 +80,10 @@ class Operator(BaseOperator):
         logprobs: bool = False,
         top_logprobs: int = 3,
     ) -> tuple[Type[T], Any]:
+        """
+        Generates a completion using vLLM with JSON schema guidance.
+        Returns the parsed output model and raw completion.
+        """
         json_schema = output_model.model_json_schema()
 
         # Build kwargs dynamically
@@ -110,14 +121,16 @@ class Operator(BaseOperator):
         resp_format: Literal["vllm", "parse"],
         mode: str | None,
         **extra_kwargs,
-    ) -> dict[str, Any]:
+    ) -> ToolOutput:
         """
         Execute the LLM pipeline with the given input text.
         """
         prompt_loader = PromptLoader()
         formatter = Formatter()
+        output = ToolOutput(result="", analysis="", logprobs=[], errors=[])
 
         try:
+            # Prompt configs contain two keys: main_template and analyze template, both are string
             prompt_configs = prompt_loader.load(
                 prompt_file=prompt_file,
                 text=text.strip(),
@@ -159,11 +172,10 @@ class Operator(BaseOperator):
 
             # Ensure output_model has a `result` field
             if not hasattr(parsed, "result"):
-                logger.error(
-                    "The provided output_model must define a field named 'result'"
-                )
-
-            output = ToolOutput(result="", analysis="", logprobs=[], errors=[])
+                error = "The provided output_model must define a field named 'result'"
+                logger.error(error)
+                output.errors.append(error)
+                return output
 
             output.result = parsed.result
 
@@ -174,6 +186,7 @@ class Operator(BaseOperator):
                 output.analysis = analysis
 
             return output
+
         except Exception as e:
-            logger.error(f"TheTool failed: {e}")
-            return ToolOutput(result="", analysis="", logprobs=[], errors=[str(e)])
+            logger.error(f"AsyncTheTool failed: {e}")
+            return output.errors.append(str(e))

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/texttools/tools/internals/prompt_loader.py

@@ -24,6 +24,9 @@ class PromptLoader:
     # Use lru_cache to load each file once
     @lru_cache(maxsize=32)
     def _load_templates(self, prompt_file: str, mode: str | None) -> dict[str, str]:
+        """
+        Loads prompt templates from YAML file with optional mode selection.
+        """
         base_dir = Path(__file__).parent.parent.parent / Path("prompts")
         prompt_path = base_dir / prompt_file
         data = yaml.safe_load(prompt_path.read_text(encoding="utf-8"))

{hamtaa_texttools-1.1.0 → hamtaa_texttools-1.1.2}/texttools/tools/the_tool.py

@@ -32,12 +32,15 @@ class TheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Categorize a text into a single Islamic studies domain category.
 
         Returns:
-            {"result": <category string>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The assigned Islamic studies category
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -64,12 +67,15 @@ class TheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, list[str]]:
+    ) -> OutputModels.ToolOutput:
         """
         Extract salient keywords from text.
 
         Returns:
-            {"result": [<keyword1>, <keyword2>, ...]} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (list[str]): List of extracted keywords
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -96,12 +102,15 @@ class TheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, list[dict[str, str]]]:
+    ) -> OutputModels.ToolOutput:
         """
         Perform Named Entity Recognition (NER) over the input text.
 
         Returns:
-            {"result": [{"text": <entity>, "type": <entity_type>}, ...]} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (list[dict]): List of entities with 'text' and 'type' keys
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -127,12 +136,15 @@ class TheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, bool]:
+    ) -> OutputModels.ToolOutput:
         """
         Detect if the input is phrased as a question.
 
         Returns:
-            {"result": True} or {"result": False} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (bool): True if text is a question, False otherwise
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -159,12 +171,15 @@ class TheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Generate a single question from the given text.
 
         Returns:
-            {"result": <generated_question>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The generated question
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -192,12 +207,15 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         mode: Literal["default", "reason"] = "default",
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Merge multiple questions into a single unified question.
 
         Returns:
-            {"result": <merged_question>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The merged question
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         text = ", ".join(text)
         return self.operator.run(
@@ -226,12 +244,15 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         mode: Literal["positive", "negative", "hard_negative"] = "positive",
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Rewrite a text with different modes.
 
         Returns:
-            {"result": <rewritten_text>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The rewritten text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -259,12 +280,15 @@ class TheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, list[str]]:
+    ) -> OutputModels.ToolOutput:
         """
         Generate a list of questions about a subject.
 
         Returns:
-            {"result": [<question1>, <question2>, ...]} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (list[str]): List of generated questions
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -292,12 +316,15 @@ class TheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Summarize the given subject text.
 
         Returns:
-            {"result": <summary>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The summary text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -324,12 +351,15 @@ class TheTool:
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int | None = None,
-    ) -> dict[str, str]:
+    ) -> OutputModels.ToolOutput:
         """
         Translate text between languages.
 
         Returns:
-            {"result": <translated_text>} + ("logprobs" and "analysis" if enabled)
+            ToolOutput: Object containing:
+                - result (str): The translated text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
         """
         return self.operator.run(
             # User parameters
@@ -356,12 +386,13 @@ class TheTool:
         temperature: float | None = None,
         logprobs: bool | None = None,
         top_logprobs: int | None = None,
-    ) -> dict[str, Any]:
+    ) -> OutputModels.ToolOutput:
         """
         Custom tool that can do almost anything!
 
         Returns:
-            {"result": <Any>}
+            ToolOutput: Object with fields:
+                - result (str): The output result
         """
         return self.operator.run(
             # User paramaeters