hamtaa-texttools 1.0.1__py3-none-any.whl → 1.1.7__py3-none-any.whl

texttools/tools/the_tool.py

@@ -1,291 +1,433 @@
-from typing import Literal, Any
-
-from openai import OpenAI
-
-from texttools.tools.operator import Operator
-import texttools.tools.output_models as OutputModels
-
-
-class TheTool:
-    """
-    High-level interface exposing specialized text tools for.
-
-    Each method configures the operator with a specific YAML prompt,
-    output schema, and flags, then delegates execution to `operator.run()`.
-
-    Supported capabilities:
-    - categorize: assign a text to one of several Islamic categories.
-    - extract_keywords: produce a keyword list from text.
-    - extract_entities: simple NER (name/type pairs).
-    - detect_question: binary check whether input is a question.
-    - generate_question_from_text: produce a new question from a text.
-    - merge_questions: combine multiple questions (default/reason modes).
-    - rewrite_question: rephrase questions (same meaning/different wording, or vice versa).
-    - generate_questions_from_subject: generate multiple questions given a subject.
-    - summarize: produce a concise summary of a subject.
-    - translate: translate text between languages.
-
-    Usage pattern:
-        client = OpenAI(...)
-        tool = TheTool(client, model="gemma-3")
-        result = tool.categorize("متن ورودی ...", with_analysis=True)
-    """
-
-    def __init__(
-        self,
-        client: OpenAI,
-        *,
-        model: str,
-        temperature: float = 0.0,
-        **client_kwargs: Any,
-    ):
-        self.operator = Operator(
-            client=client,
-            model=model,
-            temperature=temperature,
-            **client_kwargs,
-        )
-
-    def categorize(self, text: str, with_analysis: bool = False) -> 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": "باورهای دینی"}
-        """
-        self.operator.PROMPT_FILE = "categorizer.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.CategorizerOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = False
-
-        results = self.operator.run(text)
-        return results
-
-    def extract_keywords(
-        self, text: str, with_analysis: bool = False
-    ) -> dict[str, list[str]]:
-        """
-        Extract salient keywords from text.
-
-        Args:
-            text: Input string to analyze.
-            with_analysis: Whether to run an extra LLM reasoning step.
-
-        Returns:
-            {"result": [<keyword1>, <keyword2>, ...]}
-        """
-        self.operator.PROMPT_FILE = "keyword_extractor.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.ListStrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = False
-
-        results = self.operator.run(text)
-        return results
-
-    def extract_entities(
-        self, text: str, with_analysis: bool = False
-    ) -> dict[str, list[dict[str, str]]]:
-        """
-        Perform Named Entity Recognition (NER) over the input text.
-
-        Args:
-            text: Input string.
-            with_analysis: Whether to run an extra LLM reasoning step.
-
-        Returns:
-            {"result": [{"text": <entity>, "type": <entity_type>}, ...]}
-        """
-        self.operator.PROMPT_FILE = "ner_extractor.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.ListDictStrStrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = False
-
-        results = self.operator.run(text)
-        return results
-
-    def detect_question(
-        self, question: str, with_analysis: bool = False
-    ) -> dict[str, str]:
-        """
-        Detect if the input is phrased as a question.
-
-        Args:
-            question: Input string to evaluate.
-            with_analysis: Whether to include an analysis step.
-
-        Returns:
-            {"result": "true"} or {"result": "false"}
-        """
-        self.operator.PROMPT_FILE = "question_detector.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.StrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = False
-
-        results = self.operator.run(question)
-        return results
-
-    def generate_question_from_text(
-        self, text: str, with_analysis: bool = False
-    ) -> dict[str, str]:
-        """
-        Generate a single question from the given text.
-
-        Args:
-            text: Source text to derive a question from.
-            with_analysis: Whether to use analysis before generation.
-
-        Returns:
-            {"result": <generated_question>}
-        """
-        self.operator.PROMPT_FILE = "question_generator.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.StrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = False
-
-        results = self.operator.run(text)
-        return results
-
-    def merge_questions(
-        self,
-        questions: list[str],
-        mode: Literal["default_mode", "reason_mode"] = "default_mode",
-        with_analysis: bool = False,
-    ) -> dict[str, str]:
-        """
-        Merge multiple questions into a single unified question.
-
-        Args:
-            questions: List of question strings.
-            mode: Merge strategy:
-                - "default_mode": simple merging.
-                - "reason_mode": merging with reasoning explanation.
-            with_analysis: Whether to use an analysis step.
-
-        Returns:
-            {"result": <merged_question>}
-        """
-        question_str = ", ".join(questions)
-
-        self.operator.PROMPT_FILE = "question_merger.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.StrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = True
-        self.operator.MODE = mode
-
-        results = self.operator.run(question_str)
-        return results
-
-    def rewrite_question(
-        self,
-        question: str,
-        mode: Literal[
-            "same_meaning_different_wording_mode",
-            "different_meaning_similar_wording_mode",
-        ] = "same_meaning_different_wording_mode",
-        with_analysis: bool = False,
-    ) -> dict[str, str]:
-        """
-        Rewrite a question with different wording or meaning.
-
-        Args:
-            question: Input question to rewrite.
-            mode: Rewrite strategy:
-                - "same_meaning_different_wording_mode": keep meaning, change words.
-                - "different_meaning_similar_wording_mode": alter meaning, preserve wording style.
-            with_analysis: Whether to include an analysis step.
-
-        Returns:
-            {"result": <rewritten_question>}
-        """
-        self.operator.PROMPT_FILE = "question_rewriter.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.StrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = True
-        self.operator.MODE = mode
-
-        results = self.operator.run(question)
-        return results
-
-    def generate_questions_from_subject(
-        self,
-        subject: str,
-        number_of_questions: int,
-        language: str = "English",
-        with_analysis: bool = False,
-    ) -> dict[str, list[str]]:
-        """
-        Generate a list of questions about a subject.
-
-        Args:
-            subject: Topic of interest.
-            number_of_questions: Number of questions to produce.
-            language: Target language for generated questions.
-            with_analysis: Whether to include an analysis step.
-
-        Returns:
-            {"result": [<question1>, <question2>, ...]}
-        """
-        self.operator.PROMPT_FILE = "subject_question_generator.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.ReasonListStrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = False
-
-        results = self.operator.run(
-            subject,
-            number_of_questions=number_of_questions,
-            language=language,
-        )
-        return results
-
-    def summarize(self, subject: str, with_analysis: bool = False) -> dict[str, str]:
-        """
-        Summarize the given subject text.
-
-        Args:
-            subject: Input text to summarize.
-            with_analysis: Whether to include an analysis step.
-
-        Returns:
-            {"result": <summary>}
-        """
-        self.operator.PROMPT_FILE = "summarizer.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.StrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = False
-
-        results = self.operator.run(subject)
-        return results
-
-    def translate(
-        self,
-        text: str,
-        target_language: str,
-        with_analysis: bool = False,
-    ) -> dict[str, str]:
-        """
-        Translate text between languages.
-
-        Args:
-            text: Input string to translate.
-            target_language: Language code or name to translate into.
-            with_analysis: Whether to include an analysis step.
-
-        Returns:
-            {"result": <translated_text>}
-        """
-        self.operator.PROMPT_FILE = "translator.yaml"
-        self.operator.OUTPUT_MODEL = OutputModels.StrOutput
-        self.operator.WITH_ANALYSIS = with_analysis
-        self.operator.USE_MODES = False
-
-        results = self.operator.run(
-            text,
-            target_language=target_language,
-        )
-        return results
+from typing import Literal, Any, Callable
+
+from openai import OpenAI
+
+from texttools.tools.internals.operator import Operator
+import texttools.tools.internals.output_models as OutputModels
+
+
+class TheTool:
+    """
+    Each method configures the operator with a specific YAML prompt,
+    output schema, and flags, then delegates execution to `operator.run()`.
+
+    Usage:
+        client = OpenAI(...)
+        tool = TheTool(client, model="model-name")
+        result = tool.categorize("text ...", with_analysis=True)
+    """
+
+    def __init__(
+        self,
+        client: OpenAI,
+        model: str,
+    ):
+        self.operator = Operator(client=client, model=model)
+
+    def categorize(
+        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,
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Categorize a text into a single Islamic studies domain category.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (str): The assigned Islamic studies category
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return self.operator.run(
+            # User parameters
+            text=text,
+            with_analysis=with_analysis,
+            user_prompt=user_prompt,
+            temperature=temperature,
+            logprobs=logprobs,
+            top_logprobs=top_logprobs,
+            validator=validator,
+            # Internal parameters
+            prompt_file="categorizer.yaml",
+            output_model=OutputModels.CategorizerOutput,
+            resp_format="parse",
+            mode=None,
+            output_lang=None,
+        )
+
+    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,
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Extract salient keywords from text.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (list[str]): List of extracted keywords
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return 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,
+            # Internal parameters
+            prompt_file="extract_keywords.yaml",
+            output_model=OutputModels.ListStrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    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,
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Perform Named Entity Recognition (NER) over the input text.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (list[dict]): List of entities with 'text' and 'type' keys
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return 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,
+            # Internal parameters
+            prompt_file="extract_entities.yaml",
+            output_model=OutputModels.ListDictStrStrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    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,
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Detect if the input is phrased as a question.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (bool): True if text is a question, False otherwise
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return self.operator.run(
+            # User parameters
+            text=text,
+            with_analysis=with_analysis,
+            user_prompt=user_prompt,
+            temperature=temperature,
+            logprobs=logprobs,
+            top_logprobs=top_logprobs,
+            validator=validator,
+            # Internal parameters
+            prompt_file="is_question.yaml",
+            output_model=OutputModels.BoolOutput,
+            resp_format="parse",
+            mode=None,
+            output_lang=None,
+        )
+
+    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,
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Generate a single question from the given text.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (str): The generated question
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return 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,
+            # Internal parameters
+            prompt_file="text_to_question.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    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",
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Merge multiple questions into a single unified question.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (str): The merged question
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        text = ", ".join(text)
+        return 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,
+            # Internal parameters
+            prompt_file="merge_questions.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=mode,
+        )
+
+    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",
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Rewrite a text with different modes.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (str): The rewritten text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return 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,
+            # Internal parameters
+            prompt_file="rewrite.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=mode,
+        )
+
+    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,
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Generate a list of questions about a subject.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (list[str]): List of generated questions
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return 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,
+            # Internal parameters
+            prompt_file="subject_to_question.yaml",
+            output_model=OutputModels.ReasonListStrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    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,
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Summarize the given subject text.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (str): The summary text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return 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,
+            # Internal parameters
+            prompt_file="summarize.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=None,
+        )
+
+    def translate(
+        self,
+        text: str,
+        target_language: str,
+        with_analysis: bool = False,
+        user_prompt: str | None = None,
+        temperature: float | None = 0.0,
+        logprobs: bool = False,
+        top_logprobs: int | None = None,
+        validator: Callable[[Any], bool] | None = None,
+    ) -> OutputModels.ToolOutput:
+        """
+        Translate text between languages.
+
+        Returns:
+            ToolOutput: Object containing:
+                - result (str): The translated text
+                - logprobs (list | None): Probability data if logprobs enabled
+                - analysis (str | None): Detailed reasoning if with_analysis enabled
+        """
+        return self.operator.run(
+            # User parameters
+            text=text,
+            target_language=target_language,
+            with_analysis=with_analysis,
+            user_prompt=user_prompt,
+            temperature=temperature,
+            logprobs=logprobs,
+            top_logprobs=top_logprobs,
+            validator=validator,
+            # Internal parameters
+            prompt_file="translate.yaml",
+            output_model=OutputModels.StrOutput,
+            resp_format="parse",
+            mode=None,
+            output_lang=None,
+        )
+
+    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,
+    ) -> OutputModels.ToolOutput:
+        """
+        Custom tool that can do almost anything!
+
+        Returns:
+            ToolOutput: Object with fields:
+                - result (str): The output result
+        """
+        return 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,
+            validator=None,
+        )