hamtaa-texttools 1.3.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

texttools/tools/async_tools.py

@@ -4,7 +4,6 @@ from typing import Any, Literal
 
 from openai import AsyncOpenAI
 
-from ..core.engine import text_to_chunks, run_with_timeout
 from ..core.exceptions import LLMError, PromptError, TextToolsError, ValidationError
 from ..core.internal_models import (
     Bool,
@@ -15,15 +14,11 @@ from ..core.internal_models import (
     create_dynamic_model,
 )
 from ..core.operators.async_operator import AsyncOperator
+from ..core.utils import TheToolUtils
 from ..models import CategoryTree, ToolOutput, ToolOutputMetadata
 
 
 class AsyncTheTool:
-    """
-    Each method configures the operator with a specific YAML prompt,
-    output schema, and flags, then delegates execution to `operator.run()`.
-    """
-
     def __init__(
         self,
         client: AsyncOpenAI,
@@ -46,16 +41,16 @@ class AsyncTheTool:
         timeout: float | None = None,
     ) -> ToolOutput:
         """
-        Categorize a text into a category / category tree.
+        Classify text into given categories
 
         Important Note: category_tree mode is EXPERIMENTAL, you can use it but it isn't reliable.
 
         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
@@ -72,7 +67,7 @@ class AsyncTheTool:
 
         try:
             if isinstance(categories, list):
-                operator_output = await run_with_timeout(
+                operator_output = await TheToolUtils.run_with_timeout(
                     self._operator.run(
                         # User parameters
                         text=text,
@@ -121,7 +116,7 @@ class AsyncTheTool:
                     ]
                     category_names = list(parent_node.children.keys())
 
-                    level_operator_output = await run_with_timeout(
+                    level_operator_output = await TheToolUtils.run_with_timeout(
                         self._operator.run(
                             # User parameters
                             text=text,
@@ -175,28 +170,30 @@ class AsyncTheTool:
     async 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,
         timeout: float | 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
@@ -211,24 +208,24 @@ class AsyncTheTool:
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User parameters
                     text=text,
                     with_analysis=with_analysis,
+                    number_of_keywords=number_of_keywords,
+                    mode=mode,
                     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,
                 ),
                 timeout=timeout,
             )
@@ -254,7 +251,7 @@ class AsyncTheTool:
     async 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,
@@ -267,15 +264,15 @@ class AsyncTheTool:
         timeout: float | 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 (Optional)
-            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
@@ -290,12 +287,11 @@ class AsyncTheTool:
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 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,
@@ -349,9 +345,9 @@ class AsyncTheTool:
 
         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
@@ -366,7 +362,7 @@ class AsyncTheTool:
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User parameters
                     text=text,
@@ -405,10 +401,11 @@ class AsyncTheTool:
 
         return tool_output
 
-    async def text_to_question(
+    async 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,
@@ -421,15 +418,16 @@ class AsyncTheTool:
         timeout: float | 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
@@ -440,15 +438,16 @@ class AsyncTheTool:
         Returns:
             ToolOutput
         """
-        tool_name = "text_to_question"
+        tool_name = "to_question"
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User parameters
                     text=text,
                     number_of_questions=number_of_questions,
+                    mode=mode,
                     with_analysis=with_analysis,
                     output_lang=output_lang,
                     user_prompt=user_prompt,
@@ -461,7 +460,6 @@ class AsyncTheTool:
                     # Internal parameters
                     tool_name=tool_name,
                     output_model=ReasonListStr,
-                    mode=None,
                 ),
                 timeout=timeout,
             )
@@ -487,27 +485,28 @@ class AsyncTheTool:
     async 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,
         timeout: float | 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
@@ -523,10 +522,11 @@ class AsyncTheTool:
 
         try:
             text = ", ".join(text)
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User parameters
                     text=text,
+                    mode=mode,
                     with_analysis=with_analysis,
                     output_lang=output_lang,
                     user_prompt=user_prompt,
@@ -539,7 +539,6 @@ class AsyncTheTool:
                     # Internal parameters
                     tool_name=tool_name,
                     output_model=Str,
-                    mode=mode,
                 ),
                 timeout=timeout,
             )
@@ -562,30 +561,31 @@ class AsyncTheTool:
 
         return tool_output
 
-    async def rewrite(
+    async 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,
         timeout: float | 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
@@ -596,93 +596,15 @@ class AsyncTheTool:
         Returns:
             ToolOutput
         """
-        tool_name = "rewrite"
+        tool_name = "augment"
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User parameters
                     text=text,
-                    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=Str,
                     mode=mode,
-                ),
-                timeout=timeout,
-            )
-
-            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
-            )
-
-        return tool_output
-
-    async 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,
-        timeout: float | 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)
-            timeout: Maximum time in seconds to wait for the response before raising a timeout error
-
-        Returns:
-            ToolOutput
-        """
-        tool_name = "subject_to_question"
-        start = perf_counter()
-
-        try:
-            operator_output = await run_with_timeout(
-                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,
@@ -694,8 +616,7 @@ class AsyncTheTool:
                     priority=priority,
                     # Internal parameters
                     tool_name=tool_name,
-                    output_model=ReasonListStr,
-                    mode=None,
+                    output_model=Str,
                 ),
                 timeout=timeout,
             )
@@ -733,14 +654,14 @@ class AsyncTheTool:
         timeout: float | 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
@@ -755,7 +676,7 @@ class AsyncTheTool:
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User parameters
                     text=text,
@@ -797,7 +718,7 @@ class AsyncTheTool:
     async def translate(
         self,
         text: str,
-        target_language: str,
+        target_lang: str,
         use_chunker: bool = True,
         with_analysis: bool = False,
         user_prompt: str | None = None,
@@ -810,17 +731,17 @@ class AsyncTheTool:
         timeout: float | 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
@@ -836,17 +757,17 @@ class AsyncTheTool:
 
         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 = []
 
                 for chunk in chunks:
-                    chunk_operator_output = await run_with_timeout(
+                    chunk_operator_output = await TheToolUtils.run_with_timeout(
                         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,
@@ -882,11 +803,11 @@ class AsyncTheTool:
                 )
 
             else:
-                operator_output = await run_with_timeout(
+                operator_output = await TheToolUtils.run_with_timeout(
                     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,
@@ -937,16 +858,16 @@ class AsyncTheTool:
         timeout: float | 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
@@ -961,7 +882,7 @@ class AsyncTheTool:
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User parameters
                     text=text,
@@ -1000,7 +921,7 @@ class AsyncTheTool:
 
         return tool_output
 
-    async def check_fact(
+    async def is_fact(
         self,
         text: str,
         source_text: str,
@@ -1016,17 +937,17 @@ class AsyncTheTool:
         timeout: float | 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
@@ -1037,11 +958,11 @@ class AsyncTheTool:
         Returns:
             ToolOutput
         """
-        tool_name = "check_fact"
+        tool_name = "is_fact"
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User parameters
                     text=text,
@@ -1097,15 +1018,15 @@ class AsyncTheTool:
         timeout: float | 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
@@ -1120,7 +1041,7 @@ class AsyncTheTool:
         start = perf_counter()
 
         try:
-            operator_output = await run_with_timeout(
+            operator_output = await TheToolUtils.run_with_timeout(
                 self._operator.run(
                     # User paramaeters
                     text=prompt,