hamtaa-texttools 0.1.43__py3-none-any.whl

texttools/tools/reranker/sorter.py

@@ -0,0 +1,278 @@
+import json
+import logging
+from typing import Any, Optional
+
+from openai import OpenAI
+
+from texttools.base.base_task_performer import BaseTaskPerformer
+
+
+class GemmaSorter(BaseTaskPerformer):
+    """
+    A sorter component utilizing Gemma-style LLMs to order a list of
+    pre-scored results based on a query, handling ties semantically.
+    """
+
+    def __init__(
+        self,
+        client: OpenAI,
+        *,
+        model: str,
+        temperature: float = 0.0,
+        prompt_template: Optional[str] = None,
+        use_reason: bool = False,
+        handlers: Optional[list[Any]] = None,
+        **client_kwargs: Any,
+    ):
+        """
+        Initializes the GemmaSorter.
+
+        :param client: An initialized OpenAI client (or compatible).
+        :param model: The name of the LLM model to use for sorting (e.g., "gemma-7b-it").
+        :param temperature: The sampling temperature for LLM generation (0.0 for deterministic).
+        :param prompt_template: An optional initial system-level prompt for the LLM.
+        :param use_reason: If True, the sorter will perform an internal reasoning step
+                           and include it in the sorting prompt.
+        :param handlers: Optional list of handlers for dispatching sorting results.
+        :param client_kwargs: Additional keyword arguments for the OpenAI client.
+        """
+        super().__init__(handlers)
+        self.client = client
+        self.model = model
+        self.temperature = temperature
+        self.client_kwargs = client_kwargs
+        self.prompt_template = prompt_template
+        self.use_reason = use_reason
+
+        # Defines the expected JSON schema for the LLM's ordered IDs output.
+        self.sort_schema = {"ordered_ids": ["string"]}
+
+    def _build_sorting_messages(
+        self,
+        query: str,
+        scored_results: list[dict[str, Any]],
+        reason: Optional[str] = None,
+    ) -> list[dict[str, str]]:
+        """
+        Constructs the messages payload for the LLM API call to sort results.
+
+        :param query: The original search query.
+        :param scored_results: A list of dictionaries, where each dict has '_internal_id', 'text', and 'score'.
+        :param reason: An optional reasoning summary to provide context to the LLM.
+        :return: A list of message dictionaries formatted for the LLM API.
+        """
+        clean_query = self._preprocess(query)
+        messages: list[dict[str, str]] = []
+
+        if self.prompt_template:
+            messages.append({"role": "user", "content": self.prompt_template})
+
+        if self.use_reason and reason:
+            messages.append(
+                {
+                    "role": "user",
+                    "content": f"Based on this analysis: {reason}",
+                }
+            )
+
+        messages.append({"role": "user", "content": f"Original Query: {clean_query}"})
+
+        # Format the scored results for the LLM.
+        scored_results_presentation = []
+        for res_dict in scored_results:
+            scored_results_presentation.append(
+                f"ID: {res_dict['_internal_id']}\nScore: {res_dict.get('score', 'N/A')}\nText: {res_dict.get('text', 'N/A')}"
+            )
+        messages.append(
+            {
+                "role": "user",
+                "content": "Here are the results with their assigned scores:\n"
+                + "\n---\n".join(scored_results_presentation),
+            }
+        )
+
+        sorting_instruction = (
+            "Based on the provided scores, sort the result 'id's into an ordered list from most relevant to least relevant. "
+            "If multiple results have the same score, use semantic similarity to the original query as a tie-breaker. "
+            "Return only a JSON list of the 'id's in the final sorted order."
+        )
+        messages.append({"role": "user", "content": sorting_instruction})
+
+        schema_instr = f"Respond only in JSON format: {json.dumps(self.sort_schema)}"
+        messages.append({"role": "user", "content": schema_instr})
+        messages.append({"role": "assistant", "content": "{"})
+        return messages
+
+    def _reason(self, query: str, results: list[dict[str, Any]]) -> str:
+        """
+        Generates an internal reasoning summary to help the LLM with sorting,
+        especially for tie-breaking. This summary is based on the query and initial results.
+
+        :param query: The original search query.
+        :param results: A list of results, potentially including scores and IDs.
+        :return: A string containing the reasoning summary.
+        """
+        clean_query = self._preprocess(query)
+
+        # Truncate results for reasoning prompt to avoid exceeding token limits
+        results_for_reasoning_display = []
+        for res in results:
+            text_snippet = res.get("text", "")
+            if len(text_snippet) > 100:
+                text_snippet = text_snippet[:100] + "..."
+            results_for_reasoning_display.append(text_snippet)
+
+        reason_prompt = f"""
+            Analyze the original query: "{clean_query}"
+            And consider these initial result snippets (with their scores if available): {results_for_reasoning_display}
+
+            Formulate a brief analysis focusing on how to best order these results, especially considering tie-breaking rules based on semantic similarity to the query.
+            """
+
+        messages = [
+            {"role": "user", "content": reason_prompt},
+        ]
+
+        resp = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+        return resp.choices[0].message.content.strip()
+
+    def perform(
+        self, query: str, scored_results: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """
+        Sorts a list of results (each with an assigned score and an '_internal_id')
+        based on the query using the configured LLM. This is the main public method for the sorter.
+
+        :param query: The original search query string.
+        :param scored_results: A list of dictionaries, where each dict has at least
+                               '_internal_id', 'text', and 'score' keys.
+        :return: A list of result dictionaries representing the final sorted order.
+                 Each dictionary will have the '_internal_id' removed.
+        :raises ValueError: If scored_results is empty, LLM output is malformed, or IDs are invalid.
+        """
+        if not scored_results:
+            logging.info("Received empty list of scored results for sorting.")
+            self._dispatch(
+                {"query": query, "scored_results": scored_results, "ordered_ids": []}
+            )
+            return []
+
+        # Prepare a map for quick lookup of full result objects by their internal ID
+        id_to_full_result_map: dict[str, dict[str, Any]] = {}
+        for i, res in enumerate(scored_results):
+            if "_internal_id" not in res:
+                # Assign a temporary internal ID if missing, important for LLM interaction
+                res["_internal_id"] = res.get("id", f"gen_id_{i}")
+            if "score" not in res:
+                logging.warning(
+                    f"Result ID '{res['_internal_id']}' missing score for sorting. Defaulting to 0."
+                )
+                res["score"] = 0
+            id_to_full_result_map[res["_internal_id"]] = res.copy()  # Store a copy
+
+        reason_summary = None
+        if self.use_reason:
+            reason_summary = self._reason(query, list(id_to_full_result_map.values()))
+
+        messages_sort = self._build_sorting_messages(
+            query, list(id_to_full_result_map.values()), reason_summary
+        )
+
+        resp_sort = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages_sort,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+        raw_sort_output = resp_sort.choices[0].message.content.strip()
+
+        # Robustly extract JSON if LLM adds preamble
+        if not raw_sort_output.startswith("{"):
+            raw_sort_output = "{" + raw_sort_output
+
+        try:
+            parsed_sort = json.loads(raw_sort_output)
+        except json.JSONDecodeError as e:
+            logging.error(
+                f"Failed to parse JSON for sorting step: {e}\nRaw output: {raw_sort_output}"
+            )
+            self._dispatch(
+                {
+                    "query": query,
+                    "scored_results": scored_results,
+                    "ordered_ids_from_llm": [],
+                    "final_sorted_results": [],
+                    "error": f"JSON parsing failed: {e}",
+                }
+            )
+            raise ValueError(
+                f"LLM output is not valid JSON for sorting: {raw_sort_output}"
+            ) from e
+
+        llm_ordered_ids = parsed_sort.get("ordered_ids")
+        if not isinstance(llm_ordered_ids, list) or not all(
+            isinstance(item, str) for item in llm_ordered_ids
+        ):
+            logging.warning(
+                f"LLM returned invalid sort schema. Expected 'ordered_ids' as a list of strings, got: {parsed_sort}"
+            )
+            self._dispatch(
+                {
+                    "query": query,
+                    "scored_results": scored_results,
+                    "ordered_ids_from_llm": llm_ordered_ids,
+                    "final_sorted_results": [],
+                    "warning": "Invalid sort format",
+                }
+            )
+            raise ValueError(
+                f"LLM returned invalid 'ordered_ids' format: {llm_ordered_ids}"
+            )
+
+        final_sorted_results: list[dict[str, Any]] = []
+        ids_placed_by_llm_set = set()
+
+        for internal_id in llm_ordered_ids:
+            if (
+                internal_id in id_to_full_result_map
+                and internal_id not in ids_placed_by_llm_set
+            ):
+                result_to_add = id_to_full_result_map[internal_id].copy()
+                result_to_add.pop("_internal_id", None)
+                final_sorted_results.append(result_to_add)
+                ids_placed_by_llm_set.add(internal_id)
+            elif internal_id not in id_to_full_result_map:
+                logging.warning(
+                    f"LLM ordered ID '{internal_id}' not found in original results. Skipping."
+                )
+
+        unranked_results = []
+        for res in scored_results:
+            if res["_internal_id"] not in ids_placed_by_llm_set:
+                result_to_add = res.copy()
+                result_to_add.pop("_internal_id", None)
+                unranked_results.append(result_to_add)
+
+        if unranked_results:  # Add warning here
+            logging.warning(
+                f"The LLM did not explicitly rank {len(unranked_results)} result(s). "
+                "These will be appended to the end of the sorted list, ordered by their original score."
+            )
+
+        unranked_results.sort(key=lambda x: x.get("score", -1), reverse=True)
+        final_sorted_results.extend(unranked_results)
+
+        self._dispatch(
+            {
+                "query": query,
+                "original_scored_results": scored_results,
+                "llm_ordered_ids": llm_ordered_ids,
+                "final_sorted_results": final_sorted_results,
+            }
+        )
+        return final_sorted_results

texttools/tools/rewriter/__init__.py

@@ -0,0 +1,2 @@
+from .gemma_question_rewriter import GemmaQuestionRewriter
+from texttools.base.base_question_rewriter import RewriteMode

texttools/tools/rewriter/gemma_question_rewriter.py

@@ -0,0 +1,213 @@
+from typing import Any, Optional
+
+from openai import OpenAI
+
+from texttools.base.base_question_rewriter import BaseQuestionRewriter, RewriteMode
+from texttools.formatter import Gemma3Formatter
+
+# class QuestionGeneration(BaseModel):
+#     generated_question: str
+
+
+class GemmaQuestionRewriter(BaseQuestionRewriter):
+    """
+    Question Rewriter for Gemma-style models with two modes:
+    1. Rewrite with same meaning, different wording.
+    2. Rewrite with different meaning, similar wording.
+    Outputs JSON with a single string field: {"rewritten_question": "..."}.
+
+    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.reason_summary = None
+        self.prompt_template = prompt_template
+
+        self.json_schema = {"rewritten_question": "string"}
+
+    def _build_messages(
+        self,
+        question: str,
+        mode: RewriteMode,
+    ) -> list[dict[str, str]]:
+        """
+        Builds the message list for the LLM API call for question rewriting,
+        adapting the prompt based on the chosen mode.
+        """
+        clean_question = self.preprocess(question)
+        messages: list[dict[str, str]] = []
+
+        if self.prompt_template:
+            messages.append({"role": "user", "content": self.prompt_template})
+
+        if self.reason_summary:
+            messages.append(
+                {
+                    "role": "user",
+                    "content": f"Based on this analysis: {self.reason_summary}",
+                }
+            )
+
+        if mode == RewriteMode.SAME_MEANING_DIFFERENT_WORDING:
+            instruction = (
+                "Rewrite the following question using completely different wording and phrasing, "
+                "ensuring its original meaning is perfectly preserved. The rewritten question "
+                "should be distinct from the original but convey the exact same inquiry."
+                "**respond in the language of the question**"
+            )
+        elif mode == RewriteMode.DIFFERENT_MEANING_SIMILAR_WORDING:
+            instruction = (
+                "Rewrite the following question using *very similar wording and phrasing* "
+                "to the original, but ensure the rewritten question has a *completely different meaning*. "
+                "Focus on subtle changes that drastically alter the intent or subject of the question."
+                "**respond in the language of the question**"
+            )
+        else:
+            raise ValueError(f"Unsupported rewrite mode: {mode}")
+
+        messages.append({"role": "user", "content": instruction})
+        messages.append(
+            {"role": "user", "content": f"here is the question: {clean_question}"}
+        )
+
+        # schema_instr = f"Respond only in JSON format: {json.dumps(self.json_schema)}"
+        messages.append(
+            {
+                "role": "user",
+                "content": """
+        Respond only with the new generated question, without any additional information.
+        **the generated question will be in the language of the users input**
+                         """,
+            }
+        )
+
+        # messages.append({"role": "assistant", "content": "{"})
+        # deprecated method for structured output
+
+        # 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, question: str, mode: RewriteMode) -> str:
+        """
+        Internal reasoning step to help the model understand the core meaning
+        or structure of the question depending on the mode.
+        """
+        if mode == RewriteMode.SAME_MEANING_DIFFERENT_WORDING:
+            reason_prompt = """
+                Analyze the following question to identify its core intent, key concepts, 
+                and the specific information it is seeking.
+                Provide a brief, summarized understanding of the question's meaning that
+                will help in rephrasing it accurately without changing its intent.
+                
+                **respond in the language of the question**
+                
+                """
+        elif mode == RewriteMode.DIFFERENT_MEANING_SIMILAR_WORDING:
+            reason_prompt = """
+                Analyze the following question to identify its exact wording, phrasing,
+                and the literal meaning it conveys.
+                Provide a brief, summarized analysis of its linguistic structure and current meaning,
+                which will then be used to create a new question with similar words but a different meaning.
+                
+                **respond in the language of the question**
+                """
+        else:
+            raise ValueError(f"Unsupported rewrite mode for reason: {mode}")
+
+        messages = [
+            {"role": "user", "content": reason_prompt},
+            {"role": "user", "content": f"here is the question: {question}"},
+        ]
+
+        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()
+        self.reason_summary = reason_summary
+
+    def rewrite_question(
+        self,
+        question: str,
+        mode: RewriteMode = RewriteMode.SAME_MEANING_DIFFERENT_WORDING,
+        reason_summary: str = None,
+    ) -> str:
+        """
+        Rewrites the input `question` based on the specified `mode`.
+        Optionally uses an internal reasoning step for better accuracy.
+        """
+
+        if self.use_reason and not reason_summary:
+            self._reason(question, mode)
+        elif reason_summary:
+            self.reason_summary = reason_summary
+
+        messages = self._build_messages(question, mode)
+
+        # for structured output formatting
+        # but now i want to try somthing else
+        # i want to see if i could get the results without structured output
+        # completion = self.client.beta.chat.completions.parse(
+        #     model=self.model,
+        #     messages=messages,
+        #     response_format=QuestionGeneration,
+        #     temperature=self.temperature,
+        #     extra_body=dict(guided_decoding_backend="outlines"),
+        #     **self.client_kwargs,
+        # )
+        # message = completion.choices[0].message
+        # if message.parsed:
+        #     result = message.parsed.generated_question
+        # else:
+        #     raise ValueError(f"Failed to parse the response. Raw content: {message.content}")
+
+        resp = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+
+        result = resp.choices[0].message.content.strip()
+
+        # dispatch and return
+        self._dispatch(
+            {
+                "original_question": question,
+                "rewritten_question": result,
+                "mode": mode.value,
+            }
+        )
+        return result
+
+    def get_reason(self):
+        return self.reason_summary

texttools/tools/router/gemma_router.py

@@ -0,0 +1,169 @@
+from typing import Any, Literal, Optional
+
+from openai import OpenAI
+from pydantic import BaseModel
+
+from texttools.base.base_categorizer import BaseCategorizer
+from texttools.formatter import Gemma3Formatter
+from texttools.handlers import ResultHandler
+
+
+class Output(BaseModel):
+    reason: str
+    main_tag: Literal[
+        "باورهای دینی",
+        "اخلاق اسلامی",
+        "احکام و فقه",
+        "تاریخ اسلام و شخصیت ها",
+        "منابع دینی",
+        "دین و جامعه/سیاست",
+        "عرفان و معنویت",
+        "هیچکدام",
+    ] = None
+
+
+class GemmaCategorizer(BaseCategorizer):
+    """
+    Categorizer for Gemma-style models. It requires a predefined Enum of categories
+    to choose from and returns an Enum member.
+    Outputs JSON with a single string field: {"category": "..."}.
+
+    Allows optional extra instructions via `prompt_template`.
+    """
+
+    def __init__(
+        self,
+        client: OpenAI,
+        *,
+        model: str,
+        output_structure: BaseModel = Output,
+        chat_formatter: Optional[Any] = None,
+        use_reason: bool = False,
+        temperature: float = 0.0,
+        prompt_template: Optional[str] = None,
+        handlers: Optional[list[ResultHandler]] = None,
+        **client_kwargs: Any,
+    ):
+        super().__init__(handlers=handlers)
+        self.client = client
+        self.model = model
+        self.temperature = temperature
+        self.client_kwargs = client_kwargs
+        self.output_structure = output_structure
+        self.chat_formatter = chat_formatter or Gemma3Formatter()
+
+        self.use_reason = use_reason
+        self.prompt_template = prompt_template
+
+    def _build_messages(
+        self, text: str, reason: Optional[str] = None
+    ) -> list[dict[str, str]]:
+        """
+        Builds the message list for the LLM API call for categorization.
+        """
+        clean_text = self.preprocess(text)
+
+        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: {reason}"}
+            )
+
+        messages.append(
+            {
+                "role": "user",
+                "content": """
+                تو یک متخصص علوم دینی هستی
+                من به عنوان کاربر یک متن به تو میدم و از تو میخوام که
+                اون متن رو در یکی از دسته بندی های زیر طبقه بندی کنی
+                
+        "باورهای دینی",
+        "اخلاق اسلامی",
+        "احکام و فقه",
+        "تاریخ اسلام و شخصیت ها",
+        "منابع دینی",
+        "دین و جامعه/سیاست",
+        "عرفان و معنویت",
+        "هیچکدام",
+
+                
+                در خروجی که از تو خواسته شده بخشی با عنوان reason وجود دارد
+                در اون بخش، دلیل انتخاب دسته بندی رو به صورت خلاصه بیاور
+
+
+                متنی که باید طبقه بندی کنی:
+                
+                
+                
+                """,
+            }
+        )
+        messages.append({"role": "user", "content": clean_text})
+        restructured = self.chat_formatter.format(messages=messages)
+
+        return restructured
+
+    def _reason(self, text: str) -> str:
+        """
+        Internal reasoning step to help the model analyze the text for categorization.
+        """
+        messages = [
+            {
+                "role": "user",
+                "content": """
+                هدف ما طبقه بندی متن هست
+                متن رو بخون و ایده اصلی و آنالیزی کوتاه از اون رو ارائه بده
+                
+                بسیار خلاصه باشه خروجی تو
+                نهایتا 20 کلمه
+                    """,
+            },
+            {
+                "role": "user",
+                "content": f"""
+                    {text}
+                    """,
+            },
+        ]
+
+        restrucruted = self.chat_formatter.format(messages=messages)
+
+        resp = self.client.chat.completions.create(
+            model=self.model,
+            messages=restrucruted,
+            temperature=self.temperature,
+            **self.client_kwargs,
+        )
+
+        reason_summary = resp.choices[0].message.content.strip()
+        return reason_summary
+
+    def categorize(self, text: str):
+        """
+        Categorizes `text` by selecting an appropriate member from the predefined Enum.
+        Optionally uses an internal reasoning step for better accuracy.
+        """
+        reason_summary = None
+        if self.use_reason:
+            reason_summary = self._reason(text)
+
+        messages = self._build_messages(text, reason_summary)
+        completion = self.client.beta.chat.completions.parse(
+            model=self.model,
+            messages=messages,
+            response_format=Output,
+            temperature=self.temperature,
+            extra_body=dict(guided_decoding_backend="auto"),
+            **self.client_kwargs,
+        )
+        message = completion.choices[0].message
+
+        category_name = message.parsed.main_tag
+
+        # dispatch and return - Note: _dispatch expects dict
+        self._dispatch(results={"main_tag": category_name})
+        return {"main_tag": category_name}

texttools/tools/subject_to_question/__init__.py

@@ -0,0 +1 @@
+from .gemma_question_generator import GemmaQuestionGeneratorFromSubject