hamtaa-texttools 1.1.10__py3-none-any.whl → 1.1.12__py3-none-any.whl

{hamtaa_texttools-1.1.10.dist-info → hamtaa_texttools-1.1.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.1.10
+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
@@ -79,7 +79,7 @@ TextTools provides several optional flags to customize LLM behavior:
 
 - **`temperature (float)`** → Determines how creative the model should respond. Takes a float number from `0.0` to `2.0`.
 
-- **`validator (Callable)`** → Forces TheTool to validate the output result based on your custom validator. Validator should return bool (True if there were no problem, False if the validation failed.) If validator failed, TheTool will retry to get another output by modifying `temperature`.
+- **`validator (Callable)`** → Forces TheTool to validate the output result based on your custom validator. Validator should return bool (True if there were no problem, False if the validation failed.) If validator failed, TheTool will retry to get another output by modifying `temperature`. You can specify `max_validation_retries=<N>` to change the number of retries.
 
 All these parameters can be used individually or together to tailor the behavior of any tool in **TextTools**.
 

{hamtaa_texttools-1.1.10.dist-info → hamtaa_texttools-1.1.12.dist-info}/RECORD

@@ -1,4 +1,4 @@
-hamtaa_texttools-1.1.10.dist-info/licenses/LICENSE,sha256=Hb2YOBKy2MJQLnyLrX37B4ZVuac8eaIcE71SvVIMOLg,1082
+hamtaa_texttools-1.1.12.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,14 @@ 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=yEj4dM2bdW_12hxvimhxPOGfGhl1PqFsHM3Z4toCTaM,14813
-texttools/tools/sync_tools.py,sha256=wHY0O8R9HipUz0P268zk1w3SlFxEIffm5EjX4tcWxNM,14579
-texttools/tools/internals/async_operator.py,sha256=5sVc5K5-Vuulsxly0IfrLmzd8W7ySI4cY09myyOGL0I,7022
-texttools/tools/internals/base_operator.py,sha256=l2Mg59MGIf396yPx1CAgcplKclOptQWeTR0UIz9VTdk,2255
-texttools/tools/internals/formatters.py,sha256=tACNLP6PeoqaRpNudVxBaHA25zyWqWYPZQuYysIu88g,941
-texttools/tools/internals/operator.py,sha256=W0DxTGB3cbtDfzLqwMCM8x5xiVWgN0vZWX8PzJwAQKE,6795
+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=aHXhCweEhyl8uP4qTeccAQOmAxVrThFOmdtgtlChQWs,6804
+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
-hamtaa_texttools-1.1.10.dist-info/METADATA,sha256=6X7Qd8nOAIn7reZ5l-66CyK5fczMADtlIfdIbypJIUE,9101
-hamtaa_texttools-1.1.10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hamtaa_texttools-1.1.10.dist-info/top_level.txt,sha256=5Mh0jIxxZ5rOXHGJ6Mp-JPKviywwN0MYuH0xk5bEWqE,10
-hamtaa_texttools-1.1.10.dist-info/RECORD,,
+texttools/tools/internals/sync_operator.py,sha256=ar1o5apJgDtQEPLCiGBghS_Y3IXfJMEbXOG9EeS7a9Q,6710
+hamtaa_texttools-1.1.12.dist-info/METADATA,sha256=iPj8bakwOVrpkdHe0n2sn36ZjphP1gREP7Ud5Z0uNxU,9179
+hamtaa_texttools-1.1.12.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hamtaa_texttools-1.1.12.dist-info/top_level.txt,sha256=5Mh0jIxxZ5rOXHGJ6Mp-JPKviywwN0MYuH0xk5bEWqE,10
+hamtaa_texttools-1.1.12.dist-info/RECORD,,

texttools/tools/async_tools.py

@@ -35,15 +35,27 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -54,6 +66,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="categorizer.yaml",
             output_model=OM.CategorizerOutput,
@@ -71,15 +84,28 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -91,6 +117,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="extract_keywords.yaml",
             output_model=OM.ListStrOutput,
@@ -107,15 +134,28 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -127,6 +167,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="extract_entities.yaml",
             output_model=OM.ListDictStrStrOutput,
@@ -142,15 +183,27 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -161,6 +214,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="is_question.yaml",
             output_model=OM.BoolOutput,
@@ -178,15 +232,28 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -198,6 +265,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="text_to_question.yaml",
             output_model=OM.StrOutput,
@@ -215,15 +283,29 @@ class AsyncTheTool:
         top_logprobs: int | None = None,
         mode: Literal["default", "reason"] = "default",
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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(
@@ -236,6 +318,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="merge_questions.yaml",
             output_model=OM.StrOutput,
@@ -253,15 +336,29 @@ class AsyncTheTool:
         top_logprobs: int | None = None,
         mode: Literal["positive", "negative", "hard_negative"] = "positive",
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -273,6 +370,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="rewrite.yaml",
             output_model=OM.StrOutput,
@@ -290,15 +388,29 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -311,6 +423,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="subject_to_question.yaml",
             output_model=OM.ReasonListStrOutput,
@@ -327,15 +440,28 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -347,6 +473,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="summarize.yaml",
             output_model=OM.StrOutput,
@@ -363,15 +490,28 @@ class AsyncTheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -383,6 +523,7 @@ class AsyncTheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="translate.yaml",
             output_model=OM.StrOutput,
@@ -398,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
@@ -415,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,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,
@@ -81,6 +81,7 @@ class AsyncOperator(BaseOperator):
         logprobs: bool,
         top_logprobs: int | None,
         validator: Callable[[Any], bool] | None,
+        max_validation_retries: int | None,
         # Internal parameters
         prompt_file: str,
         output_model: Type[T],
@@ -91,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:
@@ -108,46 +108,44 @@ 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
             if validator and not validator(output.result):
-                for attempt in range(self.MAX_RETRIES):
+                for attempt in range(max_validation_retries):
                     logger.warning(
                         f"Validation failed, retrying for the {attempt + 1} time."
                     )
 
                     # 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,
@@ -179,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

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

@@ -1,29 +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:
-    # Max retry in case of failed output validation
-    MAX_RETRIES = 3
-
-    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.
@@ -57,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/{operator.py → 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,
@@ -80,6 +81,7 @@ class Operator(BaseOperator):
         logprobs: bool,
         top_logprobs: int | None,
         validator: Callable[[Any], bool] | None,
+        max_validation_retries: int | None,
         # Internal parameters
         prompt_file: str,
         output_model: Type[T],
@@ -106,46 +108,44 @@ 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
             if validator and not validator(output.result):
-                for attempt in range(self.MAX_RETRIES):
+                for attempt in range(max_validation_retries):
                     logger.warning(
                         f"Validation failed, retrying for the {attempt + 1} time."
                     )
 
                     # 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,
@@ -177,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

texttools/tools/sync_tools.py

@@ -2,7 +2,7 @@ from typing import Literal, Any, Callable
 
 from openai import OpenAI
 
-from texttools.tools.internals.operator import Operator
+from texttools.tools.internals.sync_operator import Operator
 import texttools.tools.internals.output_models as OM
 
 
@@ -33,15 +33,27 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -52,6 +64,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="categorizer.yaml",
             output_model=OM.CategorizerOutput,
@@ -69,15 +82,28 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -89,6 +115,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="extract_keywords.yaml",
             output_model=OM.ListStrOutput,
@@ -105,15 +132,28 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -125,6 +165,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="extract_entities.yaml",
             output_model=OM.ListDictStrStrOutput,
@@ -140,15 +181,27 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -159,6 +212,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="is_question.yaml",
             output_model=OM.BoolOutput,
@@ -176,15 +230,28 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -196,6 +263,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="text_to_question.yaml",
             output_model=OM.StrOutput,
@@ -213,15 +281,29 @@ class TheTool:
         top_logprobs: int | None = None,
         mode: Literal["default", "reason"] = "default",
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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(
@@ -234,6 +316,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="merge_questions.yaml",
             output_model=OM.StrOutput,
@@ -251,15 +334,29 @@ class TheTool:
         top_logprobs: int | None = None,
         mode: Literal["positive", "negative", "hard_negative"] = "positive",
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -271,6 +368,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="rewrite.yaml",
             output_model=OM.StrOutput,
@@ -288,15 +386,29 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -309,6 +421,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="subject_to_question.yaml",
             output_model=OM.ReasonListStrOutput,
@@ -325,15 +438,28 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -345,6 +471,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="summarize.yaml",
             output_model=OM.StrOutput,
@@ -361,15 +488,28 @@ class TheTool:
         logprobs: bool = False,
         top_logprobs: int | None = None,
         validator: Callable[[Any], bool] | None = None,
+        max_validation_retries: int | None = None,
     ) -> OM.ToolOutput:
         """
         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
@@ -381,6 +521,7 @@ class TheTool:
             logprobs=logprobs,
             top_logprobs=top_logprobs,
             validator=validator,
+            max_validation_retries=max_validation_retries,
             # Internal parameters
             prompt_file="translate.yaml",
             output_model=OM.StrOutput,
@@ -396,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
@@ -413,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,
         )

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