hamtaa-texttools 1.1.11__tar.gz → 1.1.12__tar.gz

{hamtaa_texttools-1.1.11/hamtaa_texttools.egg-info → hamtaa_texttools-1.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.1.11
+Version: 1.1.12
 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 → hamtaa_texttools-1.1.12/hamtaa_texttools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.1.11
+Version: 1.1.12
 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 → hamtaa_texttools-1.1.12}/hamtaa_texttools.egg-info/SOURCES.txt

@@ -31,8 +31,7 @@ texttools/prompts/translate.yaml
 texttools/tools/async_tools.py
 texttools/tools/sync_tools.py
 texttools/tools/internals/async_operator.py
-texttools/tools/internals/base_operator.py
-texttools/tools/internals/formatters.py
+texttools/tools/internals/operator_utils.py
 texttools/tools/internals/output_models.py
 texttools/tools/internals/prompt_loader.py
 texttools/tools/internals/sync_operator.py

{hamtaa_texttools-1.1.11 → hamtaa_texttools-1.1.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hamtaa-texttools"
-version = "1.1.11"
+version = "1.1.12"
 authors = [
   { name = "Tohidi", email = "the.mohammad.tohidi@gmail.com" },
   { name = "Montazer", email = "montazerh82@gmail.com" },

{hamtaa_texttools-1.1.11 → hamtaa_texttools-1.1.12}/tests/test_all_async_tools.py

@@ -28,9 +28,12 @@ async def main():
     merged_task = t.merge_questions(
         ["چرا ما موجوداتی اجتماعی هستیم؟", "چرا باید در کنار هم زندگی کنیم؟"],
         mode="default",
+        with_analysis=True,
     )
     rewritten_task = t.rewrite(
-        "چرا ما انسان ها، موجوداتی اجتماعی هستیم؟", mode="positive"
+        "چرا ما انسان ها، موجوداتی اجتماعی هستیم؟",
+        mode="positive",
+        user_prompt="Be carefull",
     )
     questions_task = t.subject_to_question("Friendship", 3)
     summary_task = t.summarize("Tomorrow, we will be dead by the car crash")

{hamtaa_texttools-1.1.11 → hamtaa_texttools-1.1.12}/tests/test_all_tools.py

@@ -49,6 +49,7 @@ print(repr(merged))
 rewritten = t.rewrite(
     "چرا ما انسان ها، موجوداتی اجتماعی هستیم؟",
     mode="positive",
+    with_analysis=True,
 )
 print(repr(rewritten))
 

{hamtaa_texttools-1.1.11 → hamtaa_texttools-1.1.12}/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,
         )

{hamtaa_texttools-1.1.11 → hamtaa_texttools-1.1.12}/texttools/tools/internals/async_operator.py

@@ -5,8 +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.formatters import Formatter
+from texttools.tools.internals.operator_utils import OperatorUtils
 from texttools.tools.internals.prompt_loader import PromptLoader
 
 # Base Model type for output models
@@ -15,7 +14,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 +25,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 +34,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 +53,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,
@@ -92,7 +92,6 @@ class AsyncOperator(BaseOperator):
         Execute the async LLM pipeline with the given input text. (Async)
         """
         prompt_loader = PromptLoader()
-        formatter = Formatter()
         output = ToolOutput()
 
         try:
@@ -109,35 +108,33 @@ 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 = formatter.user_merge_format(messages)
+            messages.append(
+                OperatorUtils.build_user_message(prompt_configs["main_template"])
+            )
 
             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 +145,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 +177,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

hamtaa_texttools-1.1.11/texttools/tools/internals/base_operator.py → hamtaa_texttools-1.1.12/texttools/tools/internals/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.
         """

{hamtaa_texttools-1.1.11 → hamtaa_texttools-1.1.12}/texttools/tools/internals/sync_operator.py

@@ -5,7 +5,7 @@ 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.prompt_loader import PromptLoader
 
 # Base Model type for output models
@@ -14,7 +14,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 +25,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 +34,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 +53,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,
@@ -107,35 +108,33 @@ 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"])
+            )
 
             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 +145,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 +177,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

{hamtaa_texttools-1.1.11 → hamtaa_texttools-1.1.12}/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,
         )

hamtaa_texttools-1.1.11/texttools/tools/internals/formatters.py

@@ -1,24 +0,0 @@
-class Formatter:
-    @staticmethod
-    def user_merge_format(messages: list[dict[str, str]]) -> list[dict[str, str]]:
-        """
-        Merges consecutive user messages into a single message, separated by newlines.
-
-        This is useful for condensing a multi-turn user input into a single
-        message for the LLM. Assistant and system messages are left unchanged and
-        act as separators between user message groups.
-        """
-        merged: list[dict[str, str]] = []
-
-        for message in messages:
-            role, content = message["role"], message["content"].strip()
-
-            # Merge with previous user turn
-            if merged and role == "user" and merged[-1]["role"] == "user":
-                merged[-1]["content"] += "\n" + content
-
-            # Otherwise, start a new turn
-            else:
-                merged.append({"role": role, "content": content})
-
-        return merged