hamtaa-texttools 0.1.43__py3-none-any.whl

texttools/tools/subject_to_question/gemma_question_generator.py

@@ -0,0 +1,224 @@
+from typing import Any, Optional
+
+from openai import OpenAI
+from pydantic import BaseModel
+
+from texttools.base.base_question_generator import BaseQuestionGeneratorFromSubject
+from texttools.formatter import Gemma3Formatter
+
+
+class QuestionGeneration(BaseModel):
+    """
+    we use this structue, the model will feel this class
+    """
+
+    reasoning_summary: str
+    questions: list
+
+
+class GemmaQuestionGeneratorFromSubject(BaseQuestionGeneratorFromSubject):
+    """
+    Question Generator for Gemma-style models with optional reasoning step.
+
+    Allows optional extra instructions via `prompt_template`.
+    """
+
+    def __init__(
+        self,
+        client: OpenAI,
+        *,
+        model: str,
+        chat_formatter: Optional[Any] = None,
+        use_reason: bool = False,
+        temperature: float = 0.0,
+        prompt_template: Optional[str] = None,
+        handlers: Optional[list[Any]] = None,
+        **client_kwargs: Any,
+    ):
+        super().__init__(handlers)
+        self.client = client
+        self.model = model
+        self.temperature = temperature
+        self.client_kwargs = client_kwargs
+
+        self.chat_formatter = chat_formatter or Gemma3Formatter()
+
+        self.use_reason = use_reason
+        self.prompt_template = prompt_template
+
+        # [DEPRECATED] we wont use unncessery structured outputs anymore
+        # Define the JSON schema for the generated question output
+        # self.json_schema = {"generated_question": "string"}
+
+    def _build_messages(
+        self,
+        subject: str,
+        reason: Optional[str] = None,
+        number_of_questions: int = 5,
+        language: str = "farsi/Persian",
+    ) -> list[dict[str, str]]:
+        """
+        Builds the message list for the LLM API call for question generation.
+        """
+        clean_subject = self.preprocess(subject)
+        messages: list[dict[str, str]] = []
+
+        if self.prompt_template:
+            messages.append({"role": "user", "content": self.prompt_template})
+
+        if reason:
+            messages.append(
+                {
+                    "role": "user",
+                    "content": f"Based on this analysis of the subject: {reason}",
+                }
+            )
+
+        messages.append(
+            {
+                "role": "user",
+                "content": f"""Given the following subject, generate a single,
+                appropriate question that this subject would directly respond to.
+                the generated subject should be independently meaningful,
+                and not mentioning any verbs like, this, that, he or she ... on the question.
+                **the generated question will be in this language {language}**
+
+                """,
+            }
+        )
+        messages.append(
+            {"role": "user", "content": f"here is the text: {clean_subject}"}
+        )
+
+        # Ensure the schema is dumped as a valid JSON string for the LLM
+        # schema_instr = f"Respond only in JSON format: {json.dumps(self.json_schema)}"
+        messages.append(
+            {
+                "role": "user",
+                "content": f"""
+        Respond only with the new generated question, without any additional information.
+        **the generated question will be in this language {language}**
+        generate {number_of_questions} number os question in the questions list.
+        
+        You must return ONLY a single JSON object that matches the schema.
+        Do NOT include any explanation before or after the JSON.
+        End the JSON with a closing brace }} and nothing else.
+        there is a `reasoning_summary` key, fill that up with a really summerized version
+        of your thoughts.
+        the `reasoning_summary` must be less than 20 words.
+                         """,
+            }
+        )
+
+        # messages.append(
+        #     {"role": "assistant", "content": "{\n"}
+        # )  # Hint to start JSON output
+        # in this new version we will use
+        # parse function of openai library
+
+        # this line will restructure the messages
+        # based on the formatter that we provided
+        # some models will require custom settings
+        restructured = self.chat_formatter.format(messages=messages)
+
+        return restructured
+
+    def _reason(self, subject: str, language: str) -> str:
+        """
+        Internal reasoning step to help the model understand the core information
+        and implications of the subject.
+        """
+        messages = [
+            {
+                "role": "user",
+                "content": """
+                    our goal is to generate questions, from the given subject that the user has provided
+                    the questions must be meaningfull, some of them should be specific and some should be general
+                    but first, in this step we want to analyze the inputted subject that the user asked us to generate questions
+                    for it
+
+                    what is the subject
+                    we need summerized analysis of the input subject
+                    what point of views can we see it and generate questoins from it
+
+                    questions that real users might have
+
+
+                    """,
+            },
+            {
+                "role": "user",
+                "content": f"""
+
+                    Here is the subject:
+
+                    {subject}
+
+                    respond only with this language {language}
+
+                    """,
+            },
+            # {
+            #     "role": "assistant",
+            #     "content": """
+            #         Sure, here is a summerized analysis
+            #     """,
+            # },
+        ]
+
+        restructured = self.chat_formatter.format(messages=messages)
+
+        resp = self.client.chat.completions.create(
+            model=self.model,
+            messages=restructured,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+
+        reason_summary = resp.choices[0].message.content.strip()
+        return reason_summary
+
+    def generate_question(
+        self, subject: str, number_of_questions: int, language: str
+    ) -> str:
+        """
+        Generates a question for the input `subject`.
+        Optionally uses an internal reasoning step for better accuracy.
+
+        language: the language of the question
+
+        """
+        reason_summary = None
+        if self.use_reason:
+            reason_summary = self._reason(subject, language)
+
+        messages = self._build_messages(
+            subject, reason_summary, number_of_questions, language
+        )
+
+        completion = self.client.beta.chat.completions.parse(
+            model=self.model,
+            messages=messages,
+            response_format=QuestionGeneration,
+            temperature=self.temperature,
+            extra_body=dict(
+                guided_decoding_backend="auto",
+            ),
+            **self.client_kwargs,
+        )
+        message = completion.choices[0].message
+        if message.parsed:
+            result = message.parsed.questions
+        else:
+            raise ValueError(
+                f"Failed to parse the response. Raw content: {message.content}"
+            )
+
+        # dispatch and return
+        self._dispatch(
+            {
+                "original_subject": subject,
+                "generated_question": result,
+            }
+        )
+        return result

texttools/tools/summarizer/__init__.py

@@ -0,0 +1,2 @@
+from texttools.tools.summarizer.llm_summerizer import LLMSummarizer
+from texttools.tools.summarizer.gemma_summarizer import GemmaSummarizer

texttools/tools/summarizer/gemma_summarizer.py

@@ -0,0 +1,140 @@
+import json
+from typing import Any, Optional
+
+from openai import OpenAI
+
+from texttools.base.base_summarizer import BaseSummarizer
+from texttools.handlers import ResultHandler
+
+
+class GemmaSummarizer(BaseSummarizer):
+    """
+    Summarizer for Gemma-style models with optional reasoning step.
+    Outputs JSON with a single string field: {"summary": "..."}.
+
+    Allows optional extra instructions via `prompt_template`.
+    """
+
+    def __init__(
+        self,
+        client: OpenAI,
+        *,
+        model: str,
+        use_reason: bool = False,
+        temperature: float = 0.0,
+        prompt_template: Optional[str] = None,
+        handlers: Optional[list[ResultHandler]] = None,
+        **client_kwargs: Any,
+    ):
+        super().__init__(handlers)
+        self.client = client
+        self.model = model
+        self.temperature = temperature
+        self.client_kwargs = client_kwargs
+
+        self.use_reason = use_reason
+        self.prompt_template = prompt_template
+
+        # Define the JSON schema for the summary output
+        self.json_schema = {"summary": "string"}
+
+    def _build_messages(
+        self, text: str, reason: Optional[str] = None
+    ) -> list[dict[str, str]]:
+        """
+        Builds the message list for the LLM API call.
+        """
+        clean_text = self.preprocess(text)
+        # Ensure the schema is dumped as a valid JSON string
+
+        messages: list[dict[str, str]] = []
+
+        if self.prompt_template:
+            messages.append({"role": "user", "content": self.prompt_template})
+
+        if reason:  # Include the reason if available
+            messages.append(
+                {"role": "user", "content": f"Based on this analysis: {reason}"}
+            )
+
+        messages.append(
+            {
+                "role": "user",
+                "content": "Please provide a concise summary of the following text.",
+            }
+        )
+        messages.append({"role": "user", "content": clean_text})
+
+        schema_instr = f"Respond only in JSON format: {json.dumps(self.json_schema)}"
+        messages.append({"role": "user", "content": schema_instr})
+
+        messages.append(
+            {"role": "assistant", "content": "{"}
+        )  # Start with '{' to hint JSON
+        return messages
+
+    def _reason(self, text: str) -> str:
+        """
+        Internal reasoning step to help the model better understand the text for summarization.
+        """
+        messages = [
+            {
+                "role": "user",
+                "content": """
+                    Read the following text and identify its main points, key arguments, and overall purpose.
+                    Provide a brief, summarized analysis that will help in generating an accurate and concise summary.
+                    """,
+            },
+            {
+                "role": "user",
+                "content": f"""
+                    {text}
+                    """,
+            },
+        ]
+
+        resp = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+
+        reason_summary = resp.choices[0].message.content.strip()
+        return reason_summary
+
+    def summarize(self, text: str) -> str:
+        """
+        Generates a summary for `text`.
+        Optionally uses an internal reasoning step for better quality.
+        """
+        reason_summary = None
+        if self.use_reason:
+            reason_summary = self._reason(text)
+
+        messages = self._build_messages(text, reason_summary)
+        resp = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+        raw = resp.choices[0].message.content.strip()
+
+        if not raw.startswith("{"):
+            raw = "{" + raw
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Failed to parse JSON: {e}\nRaw output: {raw}")
+
+        result = parsed.get("summary")
+        # Validate that the result is a string
+        if not isinstance(result, str):
+            raise ValueError(
+                f"Invalid response schema, expected a string for 'summary', got: {parsed}"
+            )
+
+        # dispatch and return, passing original_text
+        self._dispatch(summary=result, original_text=text)
+        return result

texttools/tools/summarizer/llm_summerizer.py

@@ -0,0 +1,108 @@
+from typing import Any, Optional
+
+from openai import OpenAI
+from pydantic import BaseModel, create_model
+
+from texttools.base.base_summarizer import BaseSummarizer
+
+
+class LLMSummarizer(BaseSummarizer):
+    """
+    LLM-based text summarizer that wraps OpenAI's structured output parsing.
+
+    Usage:
+        ```python
+        from openai import OpenAI
+        from texttools import LLMSummarizer
+
+        client = OpenAI()
+        summarizer = LLMSummarizer(
+            client=client,
+            model="gpt-4o-2024-08-06",
+            temperature=0.7,
+            prompt_template=(
+                "You are a helpful assistant that produces concise summaries of the provided text."
+            ),
+            handlers=[my_handler],  # optional callbacks on each summarization
+            max_tokens=150,         # any other OpenAIClient kwargs
+        )
+
+        summary = summarizer.summarize("Long article text...")
+        print(summary)
+        ```
+
+    Parameters:
+        client (OpenAI):
+            Instantiated OpenAI client. Ensure your API key is configured.
+        model (str):
+            Model name to use (e.g., "gpt-4").
+        temperature (float, default=0.7):
+            Sampling temperature.
+        prompt_template (str, optional):
+            System-level instructions guiding the summarization.
+        handlers (list[callable], optional):
+            List of callables that receive {"summary": str, "original_text": str}.
+        client_kwargs (Any):
+            Additional parameters passed directly to OpenAI (e.g., max_tokens, top_p).
+    """
+
+    def __init__(
+        self,
+        client: OpenAI,
+        *,
+        model: str,
+        temperature: float = 0.7,
+        prompt_template: Optional[str] = None,
+        handlers: Optional[list[Any]] = None,
+        **client_kwargs: Any,
+    ):
+        super().__init__(handlers)
+        self.client = client
+        self.model = model
+        self.temperature = temperature
+        self.client_kwargs = client_kwargs
+
+        self.prompt_template = (
+            prompt_template
+            if prompt_template is not None
+            else (
+                """
+                You are a helpful assistant that produces concise and accurate summaries of the provided text.
+                do not explain anything, onlu provide the summarized version.
+                """
+            )
+        )
+
+        self._OutputModel = create_model(
+            "SummarizationOutput",
+            summary=(str, ...),
+        )
+
+    def _build_messages(self, text: str) -> list[dict[str, str]]:
+        preprocessed = self.preprocess(text)
+        return [
+            {"role": "system", "content": self.prompt_template},
+            {"role": "user", "content": preprocessed},
+        ]
+
+    def summarize(self, text: str) -> str:
+        """
+        Generate a summary for the input text.
+
+        :param text: The text to summarize.
+        :return: A summary string.
+        """
+        messages = self._build_messages(text)
+        resp = self.client.responses.parse(
+            model=self.model,
+            input=messages,
+            text_format=self._OutputModel,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+        output: BaseModel = resp.output_parsed
+        summary_text: str = output.summary
+
+        self._dispatch(summary=summary_text, original_text=text)
+
+        return summary_text

texttools/tools/translator/__init__.py

@@ -0,0 +1 @@
+from texttools.tools.translator.gemma_translator import GemmaTranslator

texttools/tools/translator/gemma_translator.py

@@ -0,0 +1,202 @@
+import json
+import re
+from typing import Any, Optional
+
+from openai import OpenAI
+from pydantic import BaseModel
+
+from texttools.base.base_translator import BaseTranslator
+from texttools.formatter.gemma3_formatter import Gemma3Formatter
+
+
+# Pydantic BaseModel to specify the output format of preprocessor
+# Preprocessor's job is to extract proper names
+class PreprocessorOutput(BaseModel):
+    text: str
+    text_type: str
+
+
+class GemmaTranslator(BaseTranslator):
+    """
+    Translator for Gemma-style models with optional reasoning step.
+    Outputs only the translated text, without any additional structure.
+    """
+
+    def __init__(
+        self,
+        client: OpenAI,
+        *,
+        model: str,
+        chat_formatter: Optional[Any] = None,
+        use_reason: bool = False,
+        temperature: float = 0.0,
+        prompt_template: str = None,
+        handlers: list[Any] = None,
+        **client_kwargs: Any,
+    ):
+        super().__init__(handlers)
+        self.client = client
+        self.model = model
+        self.temperature = temperature
+        self.client_kwargs = client_kwargs
+        self.chat_formatter = chat_formatter or Gemma3Formatter()
+        self.use_reason = use_reason
+        self.prompt_template = prompt_template
+
+    def _build_messages(
+        self,
+        text: str,
+        target_language: str,
+        source_language: Optional[str] = None,
+        reason: Optional[str] = None,
+        proper_names: Optional[list[str]] = None,
+    ) -> list[dict[str, str]]:
+        messages: list[dict[str, str]] = []
+
+        # This prompt gives initial information about translation like languages and proper names
+        enforce_prompt = f"""
+        You are a {source_language}-to-{target_language} translator.
+        Important Rule: The following are proper names and must NOT be translated.
+        They must be only transliterated into {target_language}.
+        That means preserving their phonetic form without changing their meaning.
+        Apply the rule for **ALL** of following proper names.
+        Proper names (do not translate **** of them):
+        {proper_names if proper_names else "None"}
+        If any proper name is found in the text, you MUST only transliterate it.
+        Output only the translated text. No comments, no explanations, no markdown.
+        """
+        messages.append({"role": "user", "content": enforce_prompt})
+
+        clean_text = text.strip()
+        if reason:
+            reason_prompt = f"""
+            Based on the analysis conducted, translate the following text {"from" + source_language if source_language else ""} to {target_language}.
+            The text to be translated is: "{clean_text}"
+            The analysis conducted: {reason}
+            """
+            messages.append({"role": "user", "content": reason_prompt})
+        else:
+            regular_prompt = f"""Translate the following text from {source_language or "original"} to {target_language}: 
+            {clean_text}"""
+            messages.append({"role": "user", "content": regular_prompt})
+
+        # Optional additional template
+        if self.prompt_template:
+            messages.append({"role": "user", "content": self.prompt_template})
+
+        restructured = self.chat_formatter.format(messages=messages)
+
+        return restructured
+
+    def _reason(self, text: str, target_language: str) -> str:
+        """
+        Internal reasoning step to help the model with translation.
+        """
+
+        reason_step_prompt = f"""
+        Analyze the following text and identify important linguistic considerations for translation.
+        Do not translate the text. Point out any idioms, cultural references, or complex structures that need special attention.
+        Also, list all proper nouns that should not be translated. Write your analysis in the {target_language}.
+        """
+        messages = [
+            {"role": "user", "content": reason_step_prompt},
+            {"role": "user", "content": text},
+        ]
+
+        restructured = self.chat_formatter.format(messages=messages)
+        completion = self.client.chat.completions.create(
+            model=self.model,
+            messages=restructured,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+
+        return completion.choices[0].message.content.strip()
+
+    def preprocess(self, text: str) -> list:
+        """
+        Preprocessor that finds proper names of Islamic figures. The extractions will be given to the
+        LLm in order to know that it shouldn't translate them, but transliterate them.
+        """
+
+        messages: list[dict[str, str]] = []
+
+        main_prompt = """
+        You must detect proper names of people.
+        Your task is to extract a JSON list of entities from the given input. For each entity, include:
+        text: The exact matched string from the original.
+        type: Only include "Proper Name" for actual names of real people. 
+        If there is no proper name in the following text, return empty json.
+        """
+        messages.append({"role": "user", "content": main_prompt})
+
+        text_prompt = f"""The text to be extracted is:{text}"""
+        messages.append({"role": "user", "content": text_prompt})
+
+        restructured = self.chat_formatter.format(messages=messages)
+        completion = self.client.chat.completions.create(
+            model=self.model,
+            messages=restructured,
+            response_format={
+                "type": "json_schema",
+                "json_schema": {
+                    "name": "NER",
+                    "schema": PreprocessorOutput.model_json_schema(),
+                },
+            },
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+        response = completion.choices[0].message.content
+
+        # Remove Markdown-style triple backticks and any optional language tag like "json"
+        if response.startswith("```"):
+            response = re.sub(r"^```(?:json)?\s*|```$", "", response.strip())
+
+        entities = json.loads(response)
+
+        return entities
+
+    def translate(
+        self, text: str, target_language: str, source_language: Optional[str] = None
+    ) -> str:
+        """
+        Translates text and returns only the translated string.
+        """
+
+        # Extract proper names to tell the LLM what names not to translate, but to transliterate
+        extracted = self.preprocess(text)
+        proper_names = [e["text"] for e in extracted]
+
+        reason_summary = None
+        if self.use_reason:
+            reason_summary = self._reason(text, target_language, source_language)
+
+        messages = self._build_messages(
+            text, target_language, source_language, reason_summary, proper_names
+        )
+        print(f"Original: {text}")
+        print(
+            f"Translating to {target_language} from {source_language or 'original'}..."
+        )
+        print(
+            f"Reasoning: {reason_summary}" if reason_summary else "Reasoning not used."
+        )
+
+        completion = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+        response = completion.choices[0].message.content.strip()
+
+        self._dispatch(
+            {
+                "original_text": text,
+                "source_language": source_language,
+                "target_language": target_language,
+                "translated_text": response,
+            }
+        )
+        return response