hamtaa-texttools 1.0.6__tar.gz → 1.0.7__tar.gz

{hamtaa_texttools-1.0.6/hamtaa_texttools.egg-info → hamtaa_texttools-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.0.6
+Version: 1.0.7
 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

{hamtaa_texttools-1.0.6 → hamtaa_texttools-1.0.7/hamtaa_texttools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.0.6
+Version: 1.0.7
 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

{hamtaa_texttools-1.0.6 → hamtaa_texttools-1.0.7}/hamtaa_texttools.egg-info/SOURCES.txt

@@ -15,20 +15,21 @@ texttools/formatters/base_formatter.py
 texttools/formatters/user_merge_formatter.py
 texttools/prompts/README.md
 texttools/prompts/categorizer.yaml
+texttools/prompts/extract_entities.yaml
+texttools/prompts/extract_keywords.yaml
 texttools/prompts/is_question.yaml
-texttools/prompts/keyword_extractor.yaml
-texttools/prompts/ner_extractor.yaml
-texttools/prompts/question_merger.yaml
-texttools/prompts/rewriter.yaml
+texttools/prompts/merge_questions.yaml
+texttools/prompts/rewrite.yaml
 texttools/prompts/run_custom.yaml
 texttools/prompts/subject_to_question.yaml
-texttools/prompts/summarizer.yaml
+texttools/prompts/summarize.yaml
 texttools/prompts/text_to_question.yaml
-texttools/prompts/translator.yaml
+texttools/prompts/translate.yaml
 texttools/tools/__init__.py
 texttools/tools/async_the_tool.py
 texttools/tools/the_tool.py
 texttools/tools/internals/async_operator.py
+texttools/tools/internals/base_operator.py
 texttools/tools/internals/operator.py
 texttools/tools/internals/output_models.py
 texttools/tools/internals/prompt_loader.py

{hamtaa_texttools-1.0.6 → hamtaa_texttools-1.0.7}/pyproject.toml

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

hamtaa_texttools-1.0.7/texttools/tools/async_the_tool.py

@@ -0,0 +1,338 @@
+from typing import Literal, Any
+
+from openai import AsyncOpenAI
+
+from texttools.tools.internals.async_operator import AsyncOperator
+import texttools.tools.internals.output_models as OutputModels
+
+
+class AsyncTheTool:
+    """
+    Async counterpart to TheTool.
+
+    Usage:
+        async_client = AsyncOpenAI(...)
+        tool = TheToolAsync(async_client, model="model-name")
+        result = await tool.categorize("text ...", with_analysis=True)
+    """
+
+    def __init__(
+        self,
+        client: AsyncOpenAI,
+        model: str,
+    ):
+        self.operator = AsyncOperator(client=client, model=model)
+
+    async def categorize(
+        self,
+        text: str,
+        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 | None = None,
+    ) -> dict[str, str]:
+        """
+        Categorize a text into a single Islamic studies domain category.
+
+        Args:
+            text: Input string to categorize.
+            with_analysis: If True, first runs an LLM "analysis" step and
+                           conditions the main prompt on that analysis.
+
+        Returns:
+            {"result": <category string>}
+            Example: {"result": "باورهای دینی"}
+        """
+        return await 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,
+            # Internal parameters
+            prompt_file="categorizer.yaml",
+            output_model=OutputModels.CategorizerOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    async def extract_keywords(
+        self,
+        text: str,
+        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 | None = None,
+    ) -> dict[str, list[str]]:
+        return await 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,
+            # Internal parameters
+            prompt_file="extract_keywords.yaml",
+            output_model=OutputModels.ListStrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    async def extract_entities(
+        self,
+        text: str,
+        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 | None = None,
+    ) -> dict[str, list[dict[str, str]]]:
+        return await 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,
+            # Internal parameters
+            prompt_file="extract_entities.yaml",
+            output_model=OutputModels.ListDictStrStrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    async def is_question(
+        self,
+        text: str,
+        with_analysis: bool = False,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
+        logprobs: bool = False,
+        top_logprobs: int | None = None,
+    ) -> dict[str, bool]:
+        return await self.operator.run(
+            # User parameters
+            text=text,
+            with_analysis=with_analysis,
+            user_prompt=user_prompt,
+            temperature=temperature,
+            logprobs=logprobs,
+            top_logprobs=top_logprobs,
+            # Internal parameters
+            prompt_file="is_question.yaml",
+            output_model=OutputModels.BoolOutput,
+            resp_format="parse",
+            mode=None,
+            output_lang=None,
+        )
+
+    async def text_to_question(
+        self,
+        text: str,
+        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 | None = None,
+    ) -> dict[str, str]:
+        return await 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,
+            # Internal parameters
+            prompt_file="text_to_question.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    async def merge_questions(
+        self,
+        text: list[str],
+        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 | None = None,
+        mode: Literal["default", "reason"] = "default",
+    ) -> dict[str, str]:
+        text = ", ".join(text)
+        return await 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,
+            # Internal parameters
+            prompt_file="merge_questions.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=mode,
+        )
+
+    async def rewrite(
+        self,
+        text: str,
+        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 | None = None,
+        mode: Literal["positive", "negative", "hard_negative"] = "positive",
+    ) -> dict[str, str]:
+        return await 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,
+            # Internal parameters
+            prompt_file="rewrite.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=mode,
+        )
+
+    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 | None = None,
+    ) -> dict[str, list[str]]:
+        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,
+            # Internal parameters
+            prompt_file="subject_to_question.yaml",
+            output_model=OutputModels.ReasonListStrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    async def summarize(
+        self,
+        text: str,
+        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 | None = None,
+    ) -> dict[str, str]:
+        return await 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,
+            # Internal parameters
+            prompt_file="summarize.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    async def translate(
+        self,
+        text: str,
+        target_language: str,
+        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 | None = None,
+    ) -> dict[str, str]:
+        return await self.operator.run(
+            # User parameters
+            text=text,
+            target_language=target_language,
+            with_analysis=with_analysis,
+            output_lang=output_lang,
+            user_prompt=user_prompt,
+            temperature=temperature,
+            logprobs=logprobs,
+            top_logprobs=top_logprobs,
+            # Internal parameters
+            prompt_file="translate.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=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!
+
+        Args:
+            prompt: Custom prompt.
+            output_model: Custom BaseModel output model.
+
+        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,
+            # Internal parameters
+            prompt_file="run_custom.yaml",
+            resp_format="parse",
+            user_prompt=None,
+            with_analysis=False,
+            mode=None,
+        )

hamtaa_texttools-1.0.7/texttools/tools/internals/async_operator.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, Type, Literal
+import logging
+
+from openai import AsyncOpenAI
+from pydantic import BaseModel
+
+from texttools.tools.internals.base_operator import BaseOperator
+from texttools.formatters.user_merge_formatter import (
+    UserMergeFormatter,
+)
+from texttools.tools.internals.prompt_loader import PromptLoader
+
+# Base Model type for output models
+T = TypeVar("T", bound=BaseModel)
+
+# Configure logger
+logger = logging.getLogger("async_operator")
+logger.setLevel(logging.INFO)
+
+
+class AsyncOperator(BaseOperator):
+    """
+    Core engine for running text-processing operations with an LLM (Async).
+
+    It wires together:
+    - `PromptLoader` → loads YAML prompt templates.
+    - `UserMergeFormatter` → applies formatting to messages (e.g., merging).
+    - AsyncOpenAI client → executes completions/parsed completions.
+    """
+
+    def __init__(self, client: AsyncOpenAI, model: str):
+        self.client: AsyncOpenAI = client
+        self.model = model
+
+    async def _analysis_completion(
+        self,
+        analyze_message: list[dict[str, str]],
+        temperature: float,
+    ) -> str:
+        completion = await self.client.chat.completions.create(
+            model=self.model,
+            messages=analyze_message,
+            temperature=temperature,
+        )
+        analysis = completion.choices[0].message.content.strip()
+        return analysis
+
+    async def _analyze(self, prompt_configs: dict[str, str], temperature: float) -> str:
+        analyze_prompt = prompt_configs["analyze_template"]
+        analyze_message = [self._build_user_message(analyze_prompt)]
+        analysis = await self._analysis_completion(analyze_message, temperature)
+        return analysis
+
+    async def _parse_completion(
+        self,
+        message: list[dict[str, str]],
+        output_model: Type[T],
+        temperature: float,
+        logprobs: bool = False,
+        top_logprobs: int = 3,
+    ) -> tuple[Type[T], Any]:
+        request_kwargs = {
+            "model": self.model,
+            "messages": message,
+            "response_format": output_model,
+            "temperature": temperature,
+        }
+
+        if logprobs:
+            request_kwargs["logprobs"] = True
+            request_kwargs["top_logprobs"] = top_logprobs
+
+        completion = await self.client.beta.chat.completions.parse(**request_kwargs)
+        parsed = completion.choices[0].message.parsed
+        return parsed, completion
+
+    async def _vllm_completion(
+        self,
+        message: list[dict[str, str]],
+        output_model: Type[T],
+        temperature: float,
+        logprobs: bool = False,
+        top_logprobs: int = 3,
+    ) -> tuple[Type[T], Any]:
+        json_schema = output_model.model_json_schema()
+
+        # Build kwargs dynamically
+        request_kwargs = {
+            "model": self.model,
+            "messages": message,
+            "extra_body": {"guided_json": json_schema},
+            "temperature": temperature,
+        }
+
+        if logprobs:
+            request_kwargs["logprobs"] = True
+            request_kwargs["top_logprobs"] = top_logprobs
+
+        completion = await self.client.chat.completions.create(**request_kwargs)
+        response = completion.choices[0].message.content
+
+        # Convert the string response to output model
+        parsed = self._convert_to_output_model(response, output_model)
+        return parsed, completion
+
+    async def run(
+        self,
+        # User parameters
+        text: str,
+        with_analysis: bool,
+        output_lang: str | None,
+        user_prompt: str | None,
+        temperature: float,
+        logprobs: bool,
+        top_logprobs: int | None,
+        # Internal parameters
+        prompt_file: str,
+        output_model: Type[T],
+        resp_format: Literal["vllm", "parse"],
+        mode: str | None,
+        **extra_kwargs,
+    ) -> dict[str, Any]:
+        """
+        Execute the async LLM pipeline with the given input text. (Async)
+        """
+        prompt_loader = PromptLoader()
+        formatter = UserMergeFormatter()
+
+        try:
+            cleaned_text = text.strip()
+
+            prompt_configs = prompt_loader.load(
+                prompt_file=prompt_file,
+                text=cleaned_text,
+                mode=mode,
+                **extra_kwargs,
+            )
+
+            messages: list[dict[str, str]] = []
+
+            if with_analysis:
+                analysis = await self._analyze(prompt_configs, temperature)
+                messages.append(
+                    self._build_user_message(f"Based on this analysis: {analysis}")
+                )
+
+            if output_lang:
+                messages.append(
+                    self._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}")
+                )
+
+            messages.append(self._build_user_message(prompt_configs["main_template"]))
+            messages = formatter.format(messages)
+
+            if resp_format == "vllm":
+                parsed, completion = await self._vllm_completion(
+                    messages, output_model, temperature, logprobs, top_logprobs
+                )
+            elif resp_format == "parse":
+                parsed, completion = await self._vllm_completion(
+                    messages, output_model, temperature, logprobs, top_logprobs
+                )
+
+            # Ensure output_model has a `result` field
+            if not hasattr(parsed, "result"):
+                logger.error(
+                    "The provided output_model must define a field named 'result'"
+                )
+
+            results = {"result": parsed.result}
+
+            if logprobs:
+                results["logprobs"] = self._extract_logprobs(completion)
+
+            if with_analysis:
+                results["analysis"] = analysis
+
+            return results
+
+        except Exception as e:
+            logger.error(f"Async TheTool failed: {e}")
+            return {"Error": str(e), "result": ""}

hamtaa_texttools-1.0.7/texttools/tools/internals/base_operator.py

@@ -0,0 +1,85 @@
+from typing import TypeVar, Type
+import json
+import re
+import math
+
+from pydantic import BaseModel
+from openai import OpenAI, AsyncOpenAI
+
+# Base Model type for output models
+T = TypeVar("T", bound=BaseModel)
+
+
+class BaseOperator:
+    def __init__(self, client: OpenAI | AsyncOpenAI, model: str):
+        self.client = client
+        self.model = model
+
+    def _build_user_message(self, prompt: str) -> dict[str, str]:
+        return {"role": "user", "content": prompt}
+
+    def _clean_json_response(self, response: str) -> str:
+        """
+        Clean JSON response by removing code block markers and whitespace.
+        Handles cases like:
+        - ```json{"result": "value"}```
+        """
+        stripped = response.strip()
+        cleaned = re.sub(r"^```(?:json)?\s*", "", stripped)
+        cleaned = re.sub(r"\s*```$", "", cleaned)
+
+        return cleaned.strip()
+
+    def _convert_to_output_model(
+        self, response_string: str, output_model: Type[T]
+    ) -> Type[T]:
+        """
+        Convert a JSON response string to output model.
+
+        Args:
+            response_string: The JSON string (may contain code block markers)
+            output_model: Your Pydantic output model class (e.g., StrOutput, ListStrOutput)
+
+        Returns:
+            Instance of your output model
+        """
+        # Clean the response string
+        cleaned_json = self._clean_json_response(response_string)
+
+        # Fix Python-style booleans
+        cleaned_json = cleaned_json.replace("False", "false").replace("True", "true")
+
+        # Convert string to Python dictionary
+        response_dict = json.loads(cleaned_json)
+
+        # Convert dictionary to output model
+        return output_model(**response_dict)
+
+    def _extract_logprobs(self, completion: dict):
+        logprobs_data = []
+        ignore_pattern = re.compile(r'^(result|[\s\[\]\{\}",:]+)$')
+
+        for choice in completion.choices:
+            if not getattr(choice, "logprobs", None):
+                continue
+
+            for logprob_item in choice.logprobs.content:
+                if ignore_pattern.match(logprob_item.token):
+                    continue
+                token_entry = {
+                    "token": logprob_item.token,
+                    "prob": round(math.exp(logprob_item.logprob), 8),
+                    "top_alternatives": [],
+                }
+                for alt in logprob_item.top_logprobs:
+                    if ignore_pattern.match(alt.token):
+                        continue
+                    token_entry["top_alternatives"].append(
+                        {
+                            "token": alt.token,
+                            "prob": round(math.exp(alt.logprob), 8),
+                        }
+                    )
+                logprobs_data.append(token_entry)
+
+        return logprobs_data