hamtaa-texttools 1.1.11__py3-none-any.whl → 1.1.13__py3-none-any.whl

{hamtaa_texttools-1.1.11.dist-info → hamtaa_texttools-1.1.13.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.1.11
+Version: 1.1.13
 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

{hamtaa_texttools-1.1.11.dist-info → hamtaa_texttools-1.1.13.dist-info}/RECORD

@@ -1,4 +1,4 @@
-hamtaa_texttools-1.1.11.dist-info/licenses/LICENSE,sha256=Hb2YOBKy2MJQLnyLrX37B4ZVuac8eaIcE71SvVIMOLg,1082
+hamtaa_texttools-1.1.13.dist-info/licenses/LICENSE,sha256=Hb2YOBKy2MJQLnyLrX37B4ZVuac8eaIcE71SvVIMOLg,1082
 texttools/__init__.py,sha256=EZPPNPafVGvBaxjG9anP0piqH3gAC0DdjdAckQeAgNU,251
 texttools/batch/batch_config.py,sha256=FCDXy9TfH7xjd1PHvn_CtdwEQSq-YO5sktiaMZEId58,740
 texttools/batch/batch_runner.py,sha256=zzzVIXedmaq-8fqsFtGRR64F7CtYRLlhQeBu8uMwJQg,9385
@@ -16,15 +16,15 @@ texttools/prompts/subject_to_question.yaml,sha256=C7x7rNNm6U_ZG9HOn6zuzYOtvJUZ2s
 texttools/prompts/summarize.yaml,sha256=o6rxGPfWtZd61Duvm8NVvCJqfq73b-wAuMSKR6UYUqY,459
 texttools/prompts/text_to_question.yaml,sha256=UheKYpDn6iyKI8NxunHZtFpNyfCLZZe5cvkuXpurUJY,783
 texttools/prompts/translate.yaml,sha256=mGT2uBCei6uucWqVbs4silk-UV060v3G0jnt0P6sr50,634
-texttools/tools/async_tools.py,sha256=rLg2oU9isa_3UF9sKNzwIFjYK8pZNXcHR6P8QSKexYA,15933
-texttools/tools/sync_tools.py,sha256=eSNxPNmU1FY5u5LDJGshXSXpHb-CMrSL3Q-acacpuXU,15704
-texttools/tools/internals/async_operator.py,sha256=XawSPIylrOIN8EGXQn-X6jRXHSX-B6k-Af1lAnT2F4Y,7073
-texttools/tools/internals/base_operator.py,sha256=VgZISYaPwPaoTyoWLT_7wU17Oq4KGQ6XWDZpLwOyOm8,2179
+texttools/tools/async_tools.py,sha256=60VAAZyVRxI2rKVFFiCnbY--F4kNtVxYQticE0RyhOs,24677
+texttools/tools/sync_tools.py,sha256=F5TN3KQ_vlF7AC9J0vm2NzjIZC19Ox11tpc9K1SMRwQ,24448
+texttools/tools/internals/async_operator.py,sha256=9OzF5FFXYrXX1C6ZDbad1zw9A6BZsDQ65jQVrpqTlPw,6961
 texttools/tools/internals/formatters.py,sha256=tACNLP6PeoqaRpNudVxBaHA25zyWqWYPZQuYysIu88g,941
+texttools/tools/internals/operator_utils.py,sha256=w1k0RJ_W_CRbVc_J2w337VuL-opHpHiCxfhEOwtyuOo,1856
 texttools/tools/internals/output_models.py,sha256=ekpbyocmXj_dee7ieOT1zOkMo9cPHT7xcUFCZoUaXA0,1886
 texttools/tools/internals/prompt_loader.py,sha256=4g6-U8kqrGN7VpNaRcrBcnF-h03PXjUDBP0lL0_4EZY,1953
-texttools/tools/internals/sync_operator.py,sha256=UCzQatIeZ_o6sQr3lna1elYpUphHcO6EeJwMK8PymAk,6846
-hamtaa_texttools-1.1.11.dist-info/METADATA,sha256=nSiDrQTIQRX957pwvXAHsppGuwI5eU8HdAmgqyrTgew,9179
-hamtaa_texttools-1.1.11.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hamtaa_texttools-1.1.11.dist-info/top_level.txt,sha256=5Mh0jIxxZ5rOXHGJ6Mp-JPKviywwN0MYuH0xk5bEWqE,10
-hamtaa_texttools-1.1.11.dist-info/RECORD,,
+texttools/tools/internals/sync_operator.py,sha256=zbFLbFvaT9hAdIgpbDv17ljuqqu6ZeIOwCquM4gHTI8,6867
+hamtaa_texttools-1.1.13.dist-info/METADATA,sha256=4qkKZKb9DEb1vx2FMD-xRBDj_LCnDeytl-ea3zMVKdc,9179
+hamtaa_texttools-1.1.13.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hamtaa_texttools-1.1.13.dist-info/top_level.txt,sha256=5Mh0jIxxZ5rOXHGJ6Mp-JPKviywwN0MYuH0xk5bEWqE,10
+hamtaa_texttools-1.1.13.dist-info/RECORD,,

texttools/tools/async_tools.py

@@ -40,11 +40,22 @@ class AsyncTheTool:
         """
         Categorize a text into a single Islamic studies domain category.
 
+        Arguments:
+            text: The input text to categorize
+            with_analysis: Whether to include detailed reasoning analysis
+            user_prompt: Additional instructions for the categorization
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -78,11 +89,23 @@ class AsyncTheTool:
         """
         Extract salient keywords from text.
 
+        Arguments:
+            text: The input text to extract keywords from
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output response
+            user_prompt: Additional instructions for keyword extraction
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -116,11 +139,23 @@ class AsyncTheTool:
         """
         Perform Named Entity Recognition (NER) over the input text.
 
+        Arguments:
+            text: The input text to extract entities from
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output response
+            user_prompt: Additional instructions for entity extraction
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -153,11 +188,22 @@ class AsyncTheTool:
         """
         Detect if the input is phrased as a question.
 
+        Arguments:
+            text: The input text to analyze
+            with_analysis: Whether to include detailed reasoning analysis
+            user_prompt: Additional instructions for question detection
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -191,11 +237,23 @@ class AsyncTheTool:
         """
         Generate a single question from the given text.
 
+        Arguments:
+            text: The input text to generate a question from
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output question
+            user_prompt: Additional instructions for question generation
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -230,11 +288,24 @@ class AsyncTheTool:
         """
         Merge multiple questions into a single unified question.
 
+        Arguments:
+            text: List of questions to merge
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output merged question
+            user_prompt: Additional instructions for question merging
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            mode: Merging strategy - 'default' for direct merge, 'reason' for reasoned merge
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         text = ", ".join(text)
         return await self._operator.run(
@@ -270,11 +341,24 @@ class AsyncTheTool:
         """
         Rewrite a text with different modes.
 
+        Arguments:
+            text: The input text to rewrite
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output rewritten text
+            user_prompt: Additional instructions for rewriting
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            mode: Rewriting mode - 'positive', 'negative', or 'hard_negative'
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -309,11 +393,24 @@ class AsyncTheTool:
         """
         Generate a list of questions about a subject.
 
+        Arguments:
+            text: The subject text to generate questions about
+            number_of_questions: Number of questions to generate
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output questions
+            user_prompt: Additional instructions for question generation
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -348,11 +445,23 @@ class AsyncTheTool:
         """
         Summarize the given subject text.
 
+        Arguments:
+            text: The input text to summarize
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output summary
+            user_prompt: Additional instructions for summarization
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -386,11 +495,23 @@ class AsyncTheTool:
         """
         Translate text between languages.
 
+        Arguments:
+            text: The input text to translate
+            target_language: The target language for translation
+            with_analysis: Whether to include detailed reasoning analysis
+            user_prompt: Additional instructions for translation
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User parameters
@@ -418,13 +539,27 @@ class AsyncTheTool:
         temperature: float | None = None,
         logprobs: bool | None = None,
         top_logprobs: int | None = None,
+        validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         Custom tool that can do almost anything!
 
+        Arguments:
+            text: The user prompt
+            output_lang: Language for the output summary
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
-            ToolOutput: Object with fields:
-                - result (str): The output result
+            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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return await self._operator.run(
             # User paramaeters
@@ -435,10 +570,11 @@ class AsyncTheTool:
             temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
+            validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="run_custom.yaml",
             user_prompt=None,
             with_analysis=False,
             mode=None,
-            validator=None,
         )

texttools/tools/internals/async_operator.py

@@ -5,7 +5,7 @@ from openai import AsyncOpenAI
 from pydantic import BaseModel
 
 from texttools.tools.internals.output_models import ToolOutput
-from texttools.tools.internals.base_operator import BaseOperator
+from texttools.tools.internals.operator_utils import OperatorUtils
 from texttools.tools.internals.formatters import Formatter
 from texttools.tools.internals.prompt_loader import PromptLoader
 
@@ -15,7 +15,7 @@ T = TypeVar("T", bound=BaseModel)
 logger = logging.getLogger("texttools.async_operator")
 
 
-class AsyncOperator(BaseOperator):
+class AsyncOperator:
     """
     Core engine for running text-processing operations with an LLM (Async).
 
@@ -26,7 +26,8 @@ class AsyncOperator(BaseOperator):
     """
 
     def __init__(self, client: AsyncOpenAI, model: str):
-        super().__init__(client, model)
+        self._client = client
+        self._model = model
 
     async def _analyze(self, prompt_configs: dict[str, str], temperature: float) -> str:
         """
@@ -34,7 +35,7 @@ class AsyncOperator(BaseOperator):
         Returns the analyzed content as a string.
         """
         analyze_prompt = prompt_configs["analyze_template"]
-        analyze_message = [self._build_user_message(analyze_prompt)]
+        analyze_message = [OperatorUtils.build_user_message(analyze_prompt)]
         completion = await self._client.chat.completions.create(
             model=self._model,
             messages=analyze_message,
@@ -53,7 +54,7 @@ class AsyncOperator(BaseOperator):
     ) -> tuple[T, Any]:
         """
         Parses a chat completion using OpenAI's structured output format.
-        Returns both the parsed object and the raw completion for logging.
+        Returns both the parsed object and the raw completion for logprobs.
         """
         request_kwargs = {
             "model": self._model,
@@ -109,35 +110,35 @@ class AsyncOperator(BaseOperator):
             if with_analysis:
                 analysis = await self._analyze(prompt_configs, temperature)
                 messages.append(
-                    self._build_user_message(f"Based on this analysis: {analysis}")
+                    OperatorUtils.build_user_message(
+                        f"Based on this analysis: {analysis}"
+                    )
                 )
 
             if output_lang:
                 messages.append(
-                    self._build_user_message(
+                    OperatorUtils.build_user_message(
                         f"Respond only in the {output_lang} language."
                     )
                 )
 
             if user_prompt:
                 messages.append(
-                    self._build_user_message(f"Consider this instruction {user_prompt}")
+                    OperatorUtils.build_user_message(
+                        f"Consider this instruction {user_prompt}"
+                    )
                 )
 
-            messages.append(self._build_user_message(prompt_configs["main_template"]))
+            messages.append(
+                OperatorUtils.build_user_message(prompt_configs["main_template"])
+            )
+
             messages = formatter.user_merge_format(messages)
 
             parsed, completion = await self._parse_completion(
                 messages, output_model, temperature, logprobs, top_logprobs
             )
 
-            # Ensure output_model has a `result` field
-            if not hasattr(parsed, "result"):
-                error = "The provided output_model must define a field named 'result'"
-                logger.error(error)
-                output.errors.append(error)
-                return output
-
             output.result = parsed.result
 
             # Retry logic if validation fails
@@ -148,7 +149,7 @@ class AsyncOperator(BaseOperator):
                     )
 
                     # Generate new temperature for retry
-                    retry_temperature = self._get_retry_temp(temperature)
+                    retry_temperature = OperatorUtils.get_retry_temp(temperature)
                     try:
                         parsed, completion = await self._parse_completion(
                             messages,
@@ -180,7 +181,7 @@ class AsyncOperator(BaseOperator):
                 output.errors.append("Validation failed after all retry attempts")
 
             if logprobs:
-                output.logprobs = self._extract_logprobs(completion)
+                output.logprobs = OperatorUtils.extract_logprobs(completion)
 
             if with_analysis:
                 output.analysis = analysis

texttools/tools/internals/{base_operator.py → operator_utils.py}

@@ -1,26 +1,15 @@
-from typing import TypeVar, Any, Union
 import re
 import math
 import random
 
-from pydantic import BaseModel
-from openai import OpenAI, AsyncOpenAI
 
-# Base Model type for output models
-T = TypeVar("T", bound=BaseModel)
-
-ClientType = Union[OpenAI, AsyncOpenAI]
-
-
-class BaseOperator:
-    def __init__(self, client: ClientType, model: str):
-        self._client = client
-        self._model = model
-
-    def _build_user_message(self, prompt: str) -> dict[str, str]:
+class OperatorUtils:
+    @staticmethod
+    def build_user_message(prompt: str) -> dict[str, str]:
         return {"role": "user", "content": prompt}
 
-    def _extract_logprobs(self, completion: dict) -> list[dict[str, Any]]:
+    @staticmethod
+    def extract_logprobs(completion: dict) -> list[dict]:
         """
         Extracts and filters token probabilities from completion logprobs.
         Skips punctuation and structural tokens, returns cleaned probability data.
@@ -54,7 +43,8 @@ class BaseOperator:
 
         return logprobs_data
 
-    def _get_retry_temp(self, base_temp: float) -> float:
+    @staticmethod
+    def get_retry_temp(base_temp: float) -> float:
         """
         Calculate temperature for retry attempts.
         """

texttools/tools/internals/sync_operator.py

@@ -5,7 +5,8 @@ from openai import OpenAI
 from pydantic import BaseModel
 
 from texttools.tools.internals.output_models import ToolOutput
-from texttools.tools.internals.base_operator import BaseOperator
+from texttools.tools.internals.operator_utils import OperatorUtils
+from texttools.tools.internals.formatters import Formatter
 from texttools.tools.internals.prompt_loader import PromptLoader
 
 # Base Model type for output models
@@ -14,7 +15,7 @@ T = TypeVar("T", bound=BaseModel)
 logger = logging.getLogger("texttools.operator")
 
 
-class Operator(BaseOperator):
+class Operator:
     """
     Core engine for running text-processing operations with an LLM (Sync).
 
@@ -25,7 +26,8 @@ class Operator(BaseOperator):
     """
 
     def __init__(self, client: OpenAI, model: str):
-        super().__init__(client, model)
+        self._client = client
+        self._model = model
 
     def _analyze(self, prompt_configs: dict[str, str], temperature: float) -> str:
         """
@@ -33,7 +35,7 @@ class Operator(BaseOperator):
         Returns the analyzed content as a string.
         """
         analyze_prompt = prompt_configs["analyze_template"]
-        analyze_message = [self._build_user_message(analyze_prompt)]
+        analyze_message = [OperatorUtils.build_user_message(analyze_prompt)]
         completion = self._client.chat.completions.create(
             model=self._model,
             messages=analyze_message,
@@ -52,7 +54,7 @@ class Operator(BaseOperator):
     ) -> tuple[T, Any]:
         """
         Parses a chat completion using OpenAI's structured output format.
-        Returns both the parsed object and the raw completion for logging.
+        Returns both the parsed object and the raw completion for logprobs.
         """
         request_kwargs = {
             "model": self._model,
@@ -91,6 +93,7 @@ class Operator(BaseOperator):
         Execute the LLM pipeline with the given input text.
         """
         prompt_loader = PromptLoader()
+        formatter = Formatter()
         output = ToolOutput()
 
         try:
@@ -107,35 +110,35 @@ class Operator(BaseOperator):
             if with_analysis:
                 analysis = self._analyze(prompt_configs, temperature)
                 messages.append(
-                    self._build_user_message(f"Based on this analysis: {analysis}")
+                    OperatorUtils.build_user_message(
+                        f"Based on this analysis: {analysis}"
+                    )
                 )
 
             if output_lang:
                 messages.append(
-                    self._build_user_message(
+                    OperatorUtils.build_user_message(
                         f"Respond only in the {output_lang} language."
                     )
                 )
 
             if user_prompt:
                 messages.append(
-                    self._build_user_message(f"Consider this instruction {user_prompt}")
+                    OperatorUtils.build_user_message(
+                        f"Consider this instruction {user_prompt}"
+                    )
                 )
 
-            messages.append(self._build_user_message(prompt_configs["main_template"]))
-            messages
+            messages.append(
+                OperatorUtils.build_user_message(prompt_configs["main_template"])
+            )
+
+            messages = formatter.user_merge_format(messages)
 
             parsed, completion = self._parse_completion(
                 messages, output_model, temperature, logprobs, top_logprobs
             )
 
-            # Ensure output_model has a `result` field
-            if not hasattr(parsed, "result"):
-                error = "The provided output_model must define a field named 'result'"
-                logger.error(error)
-                output.errors.append(error)
-                return output
-
             output.result = parsed.result
 
             # Retry logic if validation fails
@@ -146,7 +149,7 @@ class Operator(BaseOperator):
                     )
 
                     # Generate new temperature for retry
-                    retry_temperature = self._get_retry_temp(temperature)
+                    retry_temperature = OperatorUtils.get_retry_temp(temperature)
                     try:
                         parsed, completion = self._parse_completion(
                             messages,
@@ -178,7 +181,7 @@ class Operator(BaseOperator):
                 output.errors.append("Validation failed after all retry attempts")
 
             if logprobs:
-                output.logprobs = self._extract_logprobs(completion)
+                output.logprobs = OperatorUtils.extract_logprobs(completion)
 
             if with_analysis:
                 output.analysis = analysis

texttools/tools/sync_tools.py

@@ -38,11 +38,22 @@ class TheTool:
         """
         Categorize a text into a single Islamic studies domain category.
 
+        Arguments:
+            text: The input text to categorize
+            with_analysis: Whether to include detailed reasoning analysis
+            user_prompt: Additional instructions for the categorization
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -76,11 +87,23 @@ class TheTool:
         """
         Extract salient keywords from text.
 
+        Arguments:
+            text: The input text to extract keywords from
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output response
+            user_prompt: Additional instructions for keyword extraction
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -114,11 +137,23 @@ class TheTool:
         """
         Perform Named Entity Recognition (NER) over the input text.
 
+        Arguments:
+            text: The input text to extract entities from
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output response
+            user_prompt: Additional instructions for entity extraction
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -151,11 +186,22 @@ class TheTool:
         """
         Detect if the input is phrased as a question.
 
+        Arguments:
+            text: The input text to analyze
+            with_analysis: Whether to include detailed reasoning analysis
+            user_prompt: Additional instructions for question detection
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -189,11 +235,23 @@ class TheTool:
         """
         Generate a single question from the given text.
 
+        Arguments:
+            text: The input text to generate a question from
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output question
+            user_prompt: Additional instructions for question generation
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -228,11 +286,24 @@ class TheTool:
         """
         Merge multiple questions into a single unified question.
 
+        Arguments:
+            text: List of questions to merge
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output merged question
+            user_prompt: Additional instructions for question merging
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            mode: Merging strategy - 'default' for direct merge, 'reason' for reasoned merge
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         text = ", ".join(text)
         return self._operator.run(
@@ -268,11 +339,24 @@ class TheTool:
         """
         Rewrite a text with different modes.
 
+        Arguments:
+            text: The input text to rewrite
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output rewritten text
+            user_prompt: Additional instructions for rewriting
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            mode: Rewriting mode - 'positive', 'negative', or 'hard_negative'
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -307,11 +391,24 @@ class TheTool:
         """
         Generate a list of questions about a subject.
 
+        Arguments:
+            text: The subject text to generate questions about
+            number_of_questions: Number of questions to generate
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output questions
+            user_prompt: Additional instructions for question generation
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -346,11 +443,23 @@ class TheTool:
         """
         Summarize the given subject text.
 
+        Arguments:
+            text: The input text to summarize
+            with_analysis: Whether to include detailed reasoning analysis
+            output_lang: Language for the output summary
+            user_prompt: Additional instructions for summarization
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -384,11 +493,23 @@ class TheTool:
         """
         Translate text between languages.
 
+        Arguments:
+            text: The input text to translate
+            target_language: The target language for translation
+            with_analysis: Whether to include detailed reasoning analysis
+            user_prompt: Additional instructions for translation
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
             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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User parameters
@@ -416,13 +537,27 @@ class TheTool:
         temperature: float | None = None,
         logprobs: bool | None = None,
         top_logprobs: int | None = None,
+        validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         Custom tool that can do almost anything!
 
+        Arguments:
+            text: The user prompt
+            output_lang: Language for the output summary
+            temperature: Controls randomness (0.0 = deterministic, 1.0 = creative)
+            logprobs: Whether to return token probability information
+            top_logprobs: Number of top token alternatives to return if logprobs enabled
+            validator: Custom validation function to validate the output
+            max_validation_retries: Maximum number of retry attempts if validation fails
+
         Returns:
-            ToolOutput: Object with fields:
-                - result (str): The output result
+            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
+                - errors (list(str) | None): Errors occured during tool call
         """
         return self._operator.run(
             # User paramaeters
@@ -433,10 +568,11 @@ class TheTool:
             temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
+            validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="run_custom.yaml",
             user_prompt=None,
             with_analysis=False,
             mode=None,
-            validator=None,
         )