hamtaa-texttools 1.3.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

texttools/tools/sync_tools.py

@@ -1,10 +1,10 @@
+import logging
 from collections.abc import Callable
 from time import perf_counter
 from typing import Any, Literal
 
 from openai import OpenAI
 
-from ..core.engine import text_to_chunks
 from ..core.exceptions import LLMError, PromptError, TextToolsError, ValidationError
 from ..core.internal_models import (
     Bool,
@@ -15,21 +15,20 @@ from ..core.internal_models import (
     create_dynamic_model,
 )
 from ..core.operators.sync_operator import Operator
+from ..core.utils import TheToolUtils
 from ..models import CategoryTree, ToolOutput, ToolOutputMetadata
 
 
 class TheTool:
-    """
-    Each method configures the operator with a specific YAML prompt,
-    output schema, and flags, then delegates execution to `operator.run()`.
-    """
-
     def __init__(
         self,
         client: OpenAI,
         model: str,
+        raise_on_error: bool = True,
     ):
         self._operator = Operator(client=client, model=model)
+        self.logger = logging.getLogger(self.__class__.__name__)
+        self.raise_on_error = raise_on_error
 
     def categorize(
         self,
@@ -45,16 +44,14 @@ class TheTool:
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Categorize a text into a category / category tree.
-
-        Important Note: category_tree mode is EXPERIMENTAL, you can use it but it isn't reliable.
+        Classify text into given categories
 
         Arguments:
             text: The input text
             categories: The category list / category tree
-            with_analysis: Whether to include detailed reasoning analysis
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -157,6 +154,11 @@ class TheTool:
                 )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -167,27 +169,29 @@ class TheTool:
     def extract_keywords(
         self,
         text: str,
+        mode: Literal["auto", "threshold", "count"],
+        number_of_keywords: int | None = None,
         with_analysis: bool = False,
         output_lang: str | None = None,
         user_prompt: str | None = None,
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int = 3,
-        mode: Literal["auto", "threshold", "count"] = "auto",
-        number_of_keywords: int | None = None,
         validator: Callable[[Any], bool] | None = None,
         max_validation_retries: int | None = None,
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Extract salient keywords from text.
+        Extract keywords from the text
 
         Arguments:
             text: The input text
-            with_analysis: Whether to include detailed reasoning analysis
-            output_lang: Language for the output
+            mode: auto -> decide n of keywords automatically, threshold -> decide n of keywords by a threshold, count -> takes number of keywords as the parameter
+            number_of_keywords: Must be set only when using "count" mode
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
+            output_lang: Forces the model to respond in a specific language
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -204,20 +208,20 @@ class TheTool:
             operator_output = self._operator.run(
                 # User parameters
                 text=text,
+                number_of_keywords=number_of_keywords,
+                mode=mode,
                 with_analysis=with_analysis,
                 output_lang=output_lang,
                 user_prompt=user_prompt,
                 temperature=temperature,
                 logprobs=logprobs,
                 top_logprobs=top_logprobs,
-                number_of_keywords=number_of_keywords,
                 validator=validator,
                 max_validation_retries=max_validation_retries,
                 priority=priority,
                 # Internal parameters
                 tool_name=tool_name,
                 output_model=ListStr,
-                mode=mode,
             )
 
             metadata = ToolOutputMetadata(
@@ -231,6 +235,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -241,7 +250,7 @@ class TheTool:
     def extract_entities(
         self,
         text: str,
-        entities: list[str] | None = None,
+        entities: list[str] = ["all named entities"],
         with_analysis: bool = False,
         output_lang: str | None = None,
         user_prompt: str | None = None,
@@ -253,15 +262,15 @@ class TheTool:
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Perform Named Entity Recognition (NER) over the input text.
+        Perform Named Entity Recognition (NER)
 
         Arguments:
             text: The input text
-            entities: List of entities provided by user
-            with_analysis: Whether to include detailed reasoning analysis
-            output_lang: Language for the output
+            entities: List of entities
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
+            output_lang: Forces the model to respond in a specific language
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -278,8 +287,7 @@ class TheTool:
             operator_output = self._operator.run(
                 # User parameters
                 text=text,
-                entities=entities
-                or "all named entities (e.g., PER, ORG, LOC, DAT, etc.)",
+                entities=entities,
                 with_analysis=with_analysis,
                 output_lang=output_lang,
                 user_prompt=user_prompt,
@@ -306,6 +314,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -330,9 +343,9 @@ class TheTool:
 
         Arguments:
             text: The input text
-            with_analysis: Whether to include detailed reasoning analysis
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -375,6 +388,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -382,10 +400,11 @@ class TheTool:
 
         return tool_output
 
-    def text_to_question(
+    def to_question(
         self,
         text: str,
         number_of_questions: int,
+        mode: Literal["from_text", "from_subject"],
         with_analysis: bool = False,
         output_lang: str | None = None,
         user_prompt: str | None = None,
@@ -397,15 +416,16 @@ class TheTool:
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Generate a single question from the given text.
+        Generate questions from the given text / subject
 
         Arguments:
             text: The input text
+            mode: from_text -> generate questions from an answer, from_subject -> generate questions from a subject
             number_of_questions: Number of questions to generate
-            with_analysis: Whether to include detailed reasoning analysis
-            output_lang: Language for the output
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
+            output_lang: Forces the model to respond in a specific language
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -415,7 +435,7 @@ class TheTool:
         Returns:
             ToolOutput
         """
-        tool_name = "text_to_question"
+        tool_name = "to_question"
         start = perf_counter()
 
         try:
@@ -423,6 +443,7 @@ class TheTool:
                 # User parameters
                 text=text,
                 number_of_questions=number_of_questions,
+                mode=mode,
                 with_analysis=with_analysis,
                 output_lang=output_lang,
                 user_prompt=user_prompt,
@@ -435,7 +456,6 @@ class TheTool:
                 # Internal parameters
                 tool_name=tool_name,
                 output_model=ReasonListStr,
-                mode=None,
             )
 
             metadata = ToolOutputMetadata(
@@ -449,6 +469,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -459,26 +484,27 @@ class TheTool:
     def merge_questions(
         self,
         text: list[str],
+        mode: Literal["simple", "stepwise"],
         with_analysis: bool = False,
         output_lang: str | None = None,
         user_prompt: str | None = None,
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int = 3,
-        mode: Literal["default", "reason"] = "default",
         validator: Callable[[Any], bool] | None = None,
         max_validation_retries: int | None = None,
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Merge multiple questions into a single unified question.
+        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
+            mode: simple -> regular question merging, stepwise -> merge questions in two steps
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
+            output_lang: Forces the model to respond in a specific language
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -496,6 +522,7 @@ class TheTool:
             operator_output = self._operator.run(
                 # User parameters
                 text=text,
+                mode=mode,
                 with_analysis=with_analysis,
                 output_lang=output_lang,
                 user_prompt=user_prompt,
@@ -508,7 +535,6 @@ class TheTool:
                 # Internal parameters
                 tool_name=tool_name,
                 output_model=Str,
-                mode=mode,
             )
 
             metadata = ToolOutputMetadata(
@@ -522,6 +548,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -529,29 +560,30 @@ class TheTool:
 
         return tool_output
 
-    def rewrite(
+    def augment(
         self,
         text: str,
+        mode: Literal["positive", "negative", "hard_negative"],
         with_analysis: bool = False,
         output_lang: str | None = None,
         user_prompt: str | None = None,
         temperature: float | None = 0.0,
         logprobs: bool = False,
         top_logprobs: int = 3,
-        mode: Literal["positive", "negative", "hard_negative"] = "positive",
         validator: Callable[[Any], bool] | None = None,
         max_validation_retries: int | None = None,
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Rewrite a text with different modes.
+        Rewrite text in different augmentations
 
         Arguments:
             text: The input text
-            with_analysis: Whether to include detailed reasoning analysis
-            output_lang: Language for the output
+            mode: positive -> positive augmentation, negative -> negative augmentation, hard_negative -> hard negative augmentation
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
+            output_lang: Forces the model to respond in a specific language
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -561,13 +593,14 @@ class TheTool:
         Returns:
             ToolOutput
         """
-        tool_name = "rewrite"
+        tool_name = "augment"
         start = perf_counter()
 
         try:
             operator_output = self._operator.run(
                 # User parameters
                 text=text,
+                mode=mode,
                 with_analysis=with_analysis,
                 output_lang=output_lang,
                 user_prompt=user_prompt,
@@ -580,7 +613,6 @@ class TheTool:
                 # Internal parameters
                 tool_name=tool_name,
                 output_model=Str,
-                mode=mode,
             )
 
             metadata = ToolOutputMetadata(
@@ -594,80 +626,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
-            metadata = ToolOutputMetadata(tool_name=tool_name)
-            tool_output = ToolOutput(
-                errors=[f"{type(e).__name__}: {e}"], metadata=metadata
-            )
+            self.logger.error(str(e))
 
-        return tool_output
+            if self.raise_on_error:
+                raise
 
-    def subject_to_question(
-        self,
-        text: str,
-        number_of_questions: int,
-        with_analysis: bool = False,
-        output_lang: str | None = None,
-        user_prompt: str | None = None,
-        temperature: float | None = 0.0,
-        logprobs: bool = False,
-        top_logprobs: int = 3,
-        validator: Callable[[Any], bool] | None = None,
-        max_validation_retries: int | None = None,
-        priority: int | None = None,
-    ) -> 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
-            user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
-            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
-            priority: Task execution priority (if enabled by vLLM and the model)
-
-        Returns:
-            ToolOutput
-        """
-        tool_name = "subject_to_question"
-        start = perf_counter()
-
-        try:
-            operator_output = self._operator.run(
-                # User parameters
-                text=text,
-                number_of_questions=number_of_questions,
-                with_analysis=with_analysis,
-                output_lang=output_lang,
-                user_prompt=user_prompt,
-                temperature=temperature,
-                logprobs=logprobs,
-                top_logprobs=top_logprobs,
-                validator=validator,
-                max_validation_retries=max_validation_retries,
-                priority=priority,
-                # Internal parameters
-                tool_name=tool_name,
-                output_model=ReasonListStr,
-                mode=None,
-            )
-
-            metadata = ToolOutputMetadata(
-                tool_name=tool_name, execution_time=perf_counter() - start
-            )
-            tool_output = ToolOutput(
-                result=operator_output.result,
-                logprobs=operator_output.logprobs,
-                analysis=operator_output.analysis,
-                metadata=metadata,
-            )
-
-        except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -689,14 +652,14 @@ class TheTool:
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Summarize the given subject text.
+        Summarize the given text
 
         Arguments:
             text: The input text
-            with_analysis: Whether to include detailed reasoning analysis
-            output_lang: Language for the output
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
+            output_lang: Forces the model to respond in a specific language
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -739,6 +702,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -749,7 +717,7 @@ class TheTool:
     def translate(
         self,
         text: str,
-        target_language: str,
+        target_lang: str,
         use_chunker: bool = True,
         with_analysis: bool = False,
         user_prompt: str | None = None,
@@ -761,17 +729,17 @@ class TheTool:
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Translate text between languages.
+        Translate text between languages
 
         Important Note: This tool is EXPERIMENTAL, you can use it but it isn't reliable.
 
         Arguments:
             text: The input text
-            target_language: The target language for translation
-            use_chunker: Whether to use text chunker for text length bigger than 1500
-            with_analysis: Whether to include detailed reasoning analysis
+            target_lang: The target language for translation
+            use_chunker: Whether to use text chunker for large texts
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -786,7 +754,7 @@ class TheTool:
 
         try:
             if len(text.split(" ")) > 1500 and use_chunker:
-                chunks = text_to_chunks(text, 1200, 0)
+                chunks = TheToolUtils.to_chunks(text, 1200, 0)
                 translation = ""
                 analysis = ""
                 logprobs_list = []
@@ -795,7 +763,7 @@ class TheTool:
                     chunk_operator_output = self._operator.run(
                         # User parameters
                         text=chunk,
-                        target_language=target_language,
+                        target_lang=target_lang,
                         with_analysis=with_analysis,
                         user_prompt=user_prompt,
                         temperature=temperature,
@@ -832,7 +800,7 @@ class TheTool:
                 operator_output = self._operator.run(
                     # User parameters
                     text=text,
-                    target_language=target_language,
+                    target_lang=target_lang,
                     with_analysis=with_analysis,
                     user_prompt=user_prompt,
                     temperature=temperature,
@@ -859,6 +827,11 @@ class TheTool:
                 )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -880,16 +853,16 @@ class TheTool:
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Proposition input text to meaningful sentences.
+        Convert a text into atomic, independent, meaningful sentences
 
         Important Note: This tool is EXPERIMENTAL, you can use it but it isn't reliable.
 
         Arguments:
             text: The input text
-            with_analysis: Whether to include detailed reasoning analysis
-            output_lang: Language for the output
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
+            output_lang: Forces the model to respond in a specific language
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -932,6 +905,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -939,7 +917,7 @@ class TheTool:
 
         return tool_output
 
-    def check_fact(
+    def is_fact(
         self,
         text: str,
         source_text: str,
@@ -954,17 +932,17 @@ class TheTool:
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Checks wheather a statement is relevant to the source text or not.
+        Check whether a statement is a fact based on the source text
 
         Important Note: This tool is EXPERIMENTAL, you can use it but it isn't reliable.
 
         Arguments:
             text: The input text
-            source_text: The source text that we want to check relation of text to it
-            with_analysis: Whether to include detailed reasoning analysis
-            output_lang: Language for the output
+            source_text: The source text
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
+            output_lang: Forces the model to respond in a specific language
             user_prompt: Additional instructions
-            temperature: Controls randomness (0.0 - 2.0)
+            temperature: Controls randomness
             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
@@ -974,7 +952,7 @@ class TheTool:
         Returns:
             ToolOutput
         """
-        tool_name = "check_fact"
+        tool_name = "is_fact"
         start = perf_counter()
 
         try:
@@ -1008,6 +986,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata
@@ -1030,15 +1013,15 @@ class TheTool:
         priority: int | None = None,
     ) -> ToolOutput:
         """
-        Custom tool that can do almost anything!
+        Custom tool that can do almost anything
 
         Arguments:
             prompt: The user prompt
             output_model: Pydantic BaseModel used for structured output
-            with_analysis: Whether to include detailed reasoning analysis
+            with_analysis: Adds a reasoning step before generating the final output. Note: This doubles token usage per call
             analyze_template: The analyze template used for reasoning analysis
-            output_lang: Language for the output
-            temperature: Controls randomness (0.0 - 2.0)
+            output_lang: Forces the model to respond in a specific language
+            temperature: Controls randomness
             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
@@ -1083,6 +1066,11 @@ class TheTool:
             )
 
         except (PromptError, LLMError, ValidationError, TextToolsError, Exception) as e:
+            self.logger.error(str(e))
+
+            if self.raise_on_error:
+                raise
+
             metadata = ToolOutputMetadata(tool_name=tool_name)
             tool_output = ToolOutput(
                 errors=[f"{type(e).__name__}: {e}"], metadata=metadata