hamtaa-texttools 1.0.6__py3-none-any.whl → 1.0.8__py3-none-any.whl

{hamtaa_texttools-1.0.6.dist-info → hamtaa_texttools-1.0.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.0.6
+Version: 1.0.8
 Summary: TextTools is 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
@@ -42,8 +42,6 @@ It provides both **sync (`TheTool`)** and **async (`AsyncTheTool`)** APIs for ma
 
 It provides ready-to-use utilities for **translation, question detection, keyword extraction, categorization, NER extractor, and more** — designed to help you integrate AI-powered text processing into your applications with minimal effort.
 
-**Thread Safety:** All methods in AsyncTheTool are thread-safe, allowing concurrent usage across multiple threads without conflicts.
-
 ---
 
 ## ✨ Features
@@ -78,7 +76,11 @@ Note: This doubles token usage per call because it triggers an additional LLM re
 
 - **`user_prompt="..."`** → Allows you to inject a custom instruction or prompt into the model alongside the main template. This gives you fine-grained control over how the model interprets or modifies the input text.
 
-All these flags can be used individually or together to tailor the behavior of any tool in **TextTools**.
+- **`temperature=0.0`** → Determines how creative the model should respond. Takes a float number from `0.0` to `1.0`.
+
+All these parameters can be used individually or together to tailor the behavior of any tool in **TextTools**.
+
+**Note:** There might be some tools that don't support some of the parameters above.
 
 ---
 
@@ -104,7 +106,6 @@ pip install -U hamtaa-texttools
 
 ```python
 from openai import OpenAI
-from pydantic import BaseModel
 from texttools import TheTool
 
 # Create your OpenAI client
@@ -114,29 +115,19 @@ client = OpenAI(base_url = "your_url", API_KEY = "your_api_key")
 model = "gpt-4o-mini"
 
 # Create an instance of TheTool
-# Note: You can give parameters to TheTool so that you don't need to give them to each tool
-the_tool = TheTool(client=client, model=model, with_analysis=True, output_lang="English")
+the_tool = TheTool(client=client, model=model)
 
 # Example: Question Detection
 detection = the_tool.is_question("Is this project open source?", logprobs=True, top_logprobs=2)
 print(detection["result"])
 print(detection["logprobs"])
-# Output: True
+# Output: True \n --logprobs
 
 # Example: Translation
-# Note: You can overwrite with_analysis if defined at TheTool
-print(the_tool.translate("سلام، حالت چطوره؟", target_language="English", with_analysis=False)["result"])
-# Output: "Hi! How are you?"
-
-# Example: Custom Tool
-# Note: Output model should only contain result key
-# Everything else will be ignored
-class Custom(BaseModel):
-  result: list[list[dict[str, int]]]
-
-custom_prompt = "Something"
-custom_result = the_tool.run_custom(custom_prompt, Custom)
-print(custom_result)
+translation = the_tool.translate("سلام، حالت چطوره؟" target_language="English", with_analysis=True)
+print(translation["result"])
+print(translation["analysis"])
+# Output: "Hi! How are you?" \n --analysis
 ```
 
 ---
@@ -149,7 +140,7 @@ from openai import AsyncOpenAI
 from texttools import AsyncTheTool
 
 async def main():
-    # Create your async OpenAI client
+    # Create your AsyncOpenAI client
     async_client = AsyncOpenAI(base_url="your_url", api_key="your_api_key")
 
     # Specify the model

hamtaa_texttools-1.0.8.dist-info/RECORD

@@ -0,0 +1,30 @@
+hamtaa_texttools-1.0.8.dist-info/licenses/LICENSE,sha256=Hb2YOBKy2MJQLnyLrX37B4ZVuac8eaIcE71SvVIMOLg,1082
+texttools/__init__.py,sha256=v3tQCH_Cjj47fCpuhK6sKSVAqEjNkc-cZbY4OJa4IZw,202
+texttools/batch/__init__.py,sha256=q50JsQsmQGp_8RW0KNasYeYWVV0R4FUNZ-ujXwEJemY,143
+texttools/batch/batch_manager.py,sha256=leVIFkR-3HpDkQi_MK3TgFNnHYsCN-wbS4mTWoPmO3c,8828
+texttools/batch/batch_runner.py,sha256=cgiCYLIBQQC0dBWM8_lVP9c5QLJoAmS2ijMtp0p3U2o,10313
+texttools/prompts/README.md,sha256=rclMaCV1N8gT1KcpZu0-ka0dKGNg2f1CEcRMdQkgQOc,1379
+texttools/prompts/categorizer.yaml,sha256=GMqIIzQFhgnlpkgU1qi3FAD3mD4A2jiWD5TilQ2XnnE,1204
+texttools/prompts/extract_entities.yaml,sha256=KiKjeDpHaeh3JVtZ6q1pa3k4DYucUIU9WnEcRTCA-SE,651
+texttools/prompts/extract_keywords.yaml,sha256=0O7ypL_OsEOxtvlQ2CZjnsv9637DJwAKprZsf9Vo2_s,769
+texttools/prompts/is_question.yaml,sha256=d0-vKRbXWkxvO64ikvxRjEmpAXGpCYIPGhgexvPPjws,471
+texttools/prompts/merge_questions.yaml,sha256=0J85GvTirZB4ELwH3sk8ub_WcqqpYf6PrMKr3djlZeo,1792
+texttools/prompts/rewrite.yaml,sha256=LO7He_IA3MZKz8a-LxH9DHJpOjpYwaYN1pbjp1Y0tFo,5392
+texttools/prompts/run_custom.yaml,sha256=38OkCoVITbuuS9c08UZSP1jZW4WjSmRIi8fR0RAiPu4,108
+texttools/prompts/subject_to_question.yaml,sha256=C7x7rNNm6U_ZG9HOn6zuzYOtvJUZ2skuWbL1-aYdd3E,1147
+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/__init__.py,sha256=hG1I28Q7BJ1Dbs95x6QMKXdsAlC5Eh_tqC-EbAibwiU,114
+texttools/tools/async_the_tool.py,sha256=9VY6ym7SvQqlokt0mwAwnytmu1CUIehDmnAvx74Z78o,12480
+texttools/tools/the_tool.py,sha256=JtQolr6i_6xogtuhX6IhyudFyAsitQy5NfSxUJAS-iA,12246
+texttools/tools/internals/async_operator.py,sha256=GPTHsjldQlmNYXkGCyypc9ENIxjeHUIHWWJ_ltUyNfs,6006
+texttools/tools/internals/base_operator.py,sha256=5tZy6QEGWJI9fnVIYwOecqv8teOFBIpWFOxQav11VRM,2941
+texttools/tools/internals/formatters.py,sha256=tACNLP6PeoqaRpNudVxBaHA25zyWqWYPZQuYysIu88g,941
+texttools/tools/internals/operator.py,sha256=gl_vzcLueYi6cbxjIHhOCBtyhM6UXwJJ9Mstj8bA-Mg,5896
+texttools/tools/internals/output_models.py,sha256=Rf2x-UuGlmQHrvYIqnD11YuzMH_mPuir62HoMJQa2uk,1528
+texttools/tools/internals/prompt_loader.py,sha256=rbitJD3e8vAdcooP1Yx6KnSI83g28ho-FegfZ1cJ4j4,1979
+hamtaa_texttools-1.0.8.dist-info/METADATA,sha256=9yLqF7h34BREgmpbVxrEH2sXfglyJSNiddewvoeSy1c,7148
+hamtaa_texttools-1.0.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hamtaa_texttools-1.0.8.dist-info/top_level.txt,sha256=5Mh0jIxxZ5rOXHGJ6Mp-JPKviywwN0MYuH0xk5bEWqE,10
+hamtaa_texttools-1.0.8.dist-info/RECORD,,

texttools/tools/async_the_tool.py

@@ -1,277 +1,383 @@
-from typing import Literal
+from typing import Literal, Any
 
 from openai import AsyncOpenAI
 
-import texttools.tools.internals.output_models as OutputModels
 from texttools.tools.internals.async_operator import AsyncOperator
+import texttools.tools.internals.output_models as OutputModels
 
 
 class AsyncTheTool:
     """
     Async counterpart to TheTool.
 
+    Each method configures the async operator with a specific YAML prompt,
+    output schema, and flags, then delegates execution to `operator.run()`.
+
     Usage:
         async_client = AsyncOpenAI(...)
-        tool = TheToolAsync(async_client, model="gemma-3")
-        result = await tool.categorize("متن ...", with_analysis=True)
+        tool = TheToolAsync(async_client, model="model-name")
+        result = await tool.categorize("text ...", with_analysis=True)
     """
 
     def __init__(
         self,
         client: AsyncOpenAI,
-        *,
         model: str,
-        temperature: float = 0.0,
     ):
-        self.operator = AsyncOperator(
-            client=client,
-            model=model,
-            temperature=temperature,
-        )
+        self.operator = AsyncOperator(client=client, model=model)
 
     async def categorize(
         self,
         text: str,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 8,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
     ) -> dict[str, str]:
-        results = await self.operator.run(
-            text,
-            prompt_file="categorizer.yaml",
-            output_model=OutputModels.CategorizerOutput,
+        """
+        Categorize a text into a single Islamic studies domain category.
+
+        Returns:
+            {"result": <category string>} + ("logprobs" and "analysis" if enabled)
+        """
+        return await self.operator.run(
+            # User parameters
+            text=text,
             with_analysis=with_analysis,
-            resp_format="parse",
             user_prompt=user_prompt,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="categorizer.yaml",
+            output_model=OutputModels.CategorizerOutput,
+            resp_format="parse",
+            mode=None,
+            output_lang=None,
         )
-        return results
 
     async def extract_keywords(
         self,
         text: str,
-        output_lang: str | None = None,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        output_lang: str | None = None,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 3,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
     ) -> dict[str, list[str]]:
-        results = await self.operator.run(
-            text,
-            prompt_file="keyword_extractor.yaml",
-            output_model=OutputModels.ListStrOutput,
+        """
+        Extract salient keywords from text.
+
+        Returns:
+            {"result": [<keyword1>, <keyword2>, ...]} + ("logprobs" and "analysis" if enabled)
+        """
+        return await self.operator.run(
+            # User parameters
+            text=text,
             with_analysis=with_analysis,
-            resp_format="parse",
-            user_prompt=user_prompt,
             output_lang=output_lang,
+            user_prompt=user_prompt,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="extract_keywords.yaml",
+            output_model=OutputModels.ListStrOutput,
+            resp_format="parse",
+            mode=None,
         )
-        return results
 
     async def extract_entities(
         self,
         text: str,
-        output_lang: str | None = None,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        output_lang: str | None = None,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 3,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
     ) -> dict[str, list[dict[str, str]]]:
-        results = await self.operator.run(
-            text,
-            prompt_file="ner_extractor.yaml",
-            output_model=OutputModels.ListDictStrStrOutput,
+        """
+        Perform Named Entity Recognition (NER) over the input text.
+
+        Returns:
+            {"result": [{"text": <entity>, "type": <entity_type>}, ...]} + ("logprobs" and "analysis" if enabled)
+        """
+        return await self.operator.run(
+            # User parameters
+            text=text,
             with_analysis=with_analysis,
-            resp_format="parse",
-            user_prompt=user_prompt,
             output_lang=output_lang,
+            user_prompt=user_prompt,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="extract_entities.yaml",
+            output_model=OutputModels.ListDictStrStrOutput,
+            resp_format="parse",
+            mode=None,
         )
-        return results
 
     async def is_question(
         self,
-        question: str,
-        output_lang: str | None = None,
+        text: str,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 2,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
     ) -> dict[str, bool]:
-        results = await self.operator.run(
-            question,
-            prompt_file="is_question.yaml",
-            output_model=OutputModels.BoolOutput,
+        """
+        Detect if the input is phrased as a question.
+
+        Returns:
+            {"result": True} or {"result": False} + ("logprobs" and "analysis" if enabled)
+        """
+        return await self.operator.run(
+            # User parameters
+            text=text,
             with_analysis=with_analysis,
-            resp_format="parse",
             user_prompt=user_prompt,
-            output_lang=output_lang,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="is_question.yaml",
+            output_model=OutputModels.BoolOutput,
+            resp_format="parse",
+            mode=None,
+            output_lang=None,
         )
-        return results
 
     async def text_to_question(
         self,
         text: str,
-        output_lang: str | None = None,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        output_lang: str | None = None,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 3,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
     ) -> dict[str, str]:
-        results = await self.operator.run(
-            text,
-            prompt_file="text_to_question.yaml",
-            output_model=OutputModels.StrOutput,
+        """
+        Generate a single question from the given text.
+
+        Returns:
+            {"result": <generated_question>} + ("logprobs" and "analysis" if enabled)
+        """
+        return await self.operator.run(
+            # User parameters
+            text=text,
             with_analysis=with_analysis,
-            resp_format="parse",
-            user_prompt=user_prompt,
             output_lang=output_lang,
+            user_prompt=user_prompt,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="text_to_question.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=None,
         )
-        return results
 
     async def merge_questions(
         self,
-        questions: list[str],
-        output_lang: str | None = None,
-        mode: Literal["default", "reason"] = "default",
+        text: list[str],
         with_analysis: bool = False,
-        user_prompt: str = "",
+        output_lang: str | None = None,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 3,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
+        mode: Literal["default", "reason"] = "default",
     ) -> dict[str, str]:
-        question_str = ", ".join(questions)
-        results = await self.operator.run(
-            question_str,
-            prompt_file="question_merger.yaml",
-            output_model=OutputModels.StrOutput,
+        """
+        Merge multiple questions into a single unified question.
+
+        Returns:
+            {"result": <merged_question>} + ("logprobs" and "analysis" if enabled)
+        """
+        text = ", ".join(text)
+        return await self.operator.run(
+            # User parameters
+            text=text,
             with_analysis=with_analysis,
-            use_modes=True,
-            mode=mode,
-            resp_format="parse",
-            user_prompt=user_prompt,
             output_lang=output_lang,
+            user_prompt=user_prompt,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="merge_questions.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=mode,
         )
-        return results
 
     async def rewrite(
         self,
-        question: str,
-        output_lang: str | None = None,
-        mode: Literal["positive", "negative", "hard_negative"] = "positive",
+        text: str,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        output_lang: str | None = None,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 3,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
+        mode: Literal["positive", "negative", "hard_negative"] = "positive",
     ) -> dict[str, str]:
-        results = await self.operator.run(
-            question,
-            prompt_file="rewriter.yaml",
-            output_model=OutputModels.StrOutput,
+        """
+        Rewrite a text with different modes.
+
+        Returns:
+            {"result": <rewritten_text>} + ("logprobs" and "analysis" if enabled)
+        """
+        return await self.operator.run(
+            # User parameters
+            text=text,
             with_analysis=with_analysis,
-            use_modes=True,
-            mode=mode,
-            resp_format="parse",
-            user_prompt=user_prompt,
             output_lang=output_lang,
+            user_prompt=user_prompt,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="rewrite.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=mode,
         )
-        return results
 
     async def subject_to_question(
         self,
-        subject: str,
+        text: str,
         number_of_questions: int,
-        output_lang: str | None = None,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        output_lang: str | None = None,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 3,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
     ) -> dict[str, list[str]]:
-        results = await self.operator.run(
-            subject,
-            prompt_file="subject_to_question.yaml",
-            output_model=OutputModels.ReasonListStrOutput,
-            with_analysis=with_analysis,
-            resp_format="parse",
-            user_prompt=user_prompt,
+        """
+        Generate a list of questions about a subject.
+
+        Returns:
+            {"result": [<question1>, <question2>, ...]} + ("logprobs" and "analysis" if enabled)
+        """
+        return await 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,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="subject_to_question.yaml",
+            output_model=OutputModels.ReasonListStrOutput,
+            resp_format="parse",
+            mode=None,
         )
-        return results
 
     async def summarize(
         self,
         text: str,
-        output_lang: str | None = None,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        output_lang: str | None = None,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 3,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
     ) -> dict[str, str]:
-        results = await self.operator.run(
-            text,
-            prompt_file="summarizer.yaml",
-            output_model=OutputModels.StrOutput,
+        """
+        Summarize the given subject text.
+
+        Returns:
+            {"result": <summary>} + ("logprobs" and "analysis" if enabled)
+        """
+        return await self.operator.run(
+            # User parameters
+            text=text,
             with_analysis=with_analysis,
-            resp_format="parse",
-            user_prompt=user_prompt,
             output_lang=output_lang,
+            user_prompt=user_prompt,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="summarize.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=None,
         )
-        return results
 
     async def translate(
         self,
         text: str,
         target_language: str,
         with_analysis: bool = False,
-        user_prompt: str = "",
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
         logprobs: bool = False,
-        top_logprobs: int = 3,
-        max_tokens: int | None = None,
+        top_logprobs: int | None = None,
     ) -> dict[str, str]:
-        results = await self.operator.run(
-            text,
-            prompt_file="translator.yaml",
-            output_model=OutputModels.StrOutput,
+        """
+        Translate text between languages.
+
+        Returns:
+            {"result": <translated_text>} + ("logprobs" and "analysis" if enabled)
+        """
+        return await self.operator.run(
+            # User parameters
+            text=text,
+            target_language=target_language,
             with_analysis=with_analysis,
-            resp_format="parse",
             user_prompt=user_prompt,
-            target_language=target_language,
+            temperature=temperature,
+            logprobs=logprobs,
+            top_logprobs=top_logprobs,
+            # Internal parameters
+            prompt_file="translate.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=None,
+            output_lang=None,
+        )
+
+    async def run_custom(
+        self,
+        prompt: str,
+        output_model: Any,
+        output_lang: str | None = None,
+        temperature: float | None = None,
+        logprobs: bool | None = None,
+        top_logprobs: int | None = None,
+    ) -> dict[str, Any]:
+        """
+        Custom tool that can do almost anything!
+
+        Returns:
+            {"result": <Any>}
+        """
+        return await self.operator.run(
+            # User paramaeters
+            text=prompt,
+            output_model=output_model,
+            output_model_str=output_model.model_json_schema(),
+            output_lang=output_lang,
+            temperature=temperature,
             logprobs=logprobs,
             top_logprobs=top_logprobs,
-            max_tokens=max_tokens,
+            # Internal parameters
+            prompt_file="run_custom.yaml",
+            resp_format="parse",
+            user_prompt=None,
+            with_analysis=False,
+            mode=None,
         )
-        return results