hamtaa-texttools 0.1.44__tar.gz → 1.0.0__tar.gz

hamtaa_texttools-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hamtaa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hamtaa_texttools-1.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: hamtaa-texttools
+Version: 1.0.0
+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
+        
+        Copyright (c) 2025 Hamtaa
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Keywords: nlp,llm,text-processing,openai
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai==1.97.1
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# TextTools
+
+## 📌 Overview
+
+**TextTools** is a high-level **NLP toolkit** built on top of modern **LLMs**.  
+It provides ready-to-use utilities for **translation, question detection, keyword extraction, categorization, NER extractor, and more** — designed to help you integrate AI-powered text processing into your applications with minimal effort.
+
+---
+
+## ✨ Features
+
+TextTools provides a rich collection of high-level NLP utilities built on top of LLMs.  
+Each tool is designed to work out-of-the-box with structured outputs (JSON / Pydantic).
+
+- **Categorizer** → Zero-finetuning text categorization for fast, scalable classification.  
+- **Keyword Extractor** → Identify the most important keywords in a text.  
+- **Question Merger** → Merge the provided questions, preserving all the main points 
+- **NER (Named Entity Recognition) Extractor** → Extract people, places, organizations, and other entities.  
+- **Question Detector** → Determine whether a text is a question or not.  
+- **Question Generator From Text** → Generate high-quality, context-relevant questions from provided text.
+- **Question Generator From Subject** → Generate high-quality, context-relevant questions from a subject.
+- **Rewriter** → Rewrite text while preserving meaning or without it.
+- **Summarizer** → Condense long passages into clear, structured summaries. 
+- **Translator** → Translate text across multiple languages, with support for custom rules.
+
+---
+
+## 🔍 `with_analysis` Mode
+
+The `with_analysis=True` flag enhances the tool's output by providing a detailed reasoning chain behind its result. This is valuable for debugging, improving prompts, or understanding model behavior.
+
+**Please be aware:** This feature works by making an additional LLM API call for each tool invocation, which will **effectively double your token usage** for that operation.
+
+---
+
+## 🚀 Installation
+
+Install the latest release via PyPI:
+
+```bash
+pip install -U hamta-texttools
+```
+
+---
+
+## ⚡ Quick Start
+
+```python
+from openai import OpenAI
+
+from texttools import TheTool
+
+# Create your OpenAI client
+client = OpenAI(base_url = "your_url", API_KEY = "your_api_key")
+
+# Specify the model
+model = "gpt-4o-mini"
+
+# Create an instance of TheTool
+# ⚠️ Note: Enabling `with_analysis=True` provides deeper insights but incurs additional LLM calls and token usage.
+the_tool = TheTool(client = client, model = model, with_analysis = True)
+
+# Example: Question Detection
+print(the_tool.detect_question("Is this project open source?")["result"])
+# Output: True
+
+# Example: Translation
+print(the_tool.translate("سلام، حالت چطوره؟")["result"])
+# Output: "Hi! How are you?"
+```
+
+---
+
+## 📚 Use Cases
+
+Use **TextTools** when you need to:
+
+- 🔍 **Classify** large datasets quickly without model training  
+- 🌍 **Translate** and process multilingual corpora with ease  
+- 🧩 **Integrate** LLMs into production pipelines (structured outputs)  
+- 📊 **Analyze** large text collections using embeddings and categorization  
+- ⚙️ **Automate** common text-processing tasks without reinventing the wheel  
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome!  
+Feel free to **open issues, suggest new features, or submit pull requests**.  
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hamtaa_texttools-1.0.0/README.md

@@ -0,0 +1,95 @@
+# TextTools
+
+## 📌 Overview
+
+**TextTools** is a high-level **NLP toolkit** built on top of modern **LLMs**.  
+It provides ready-to-use utilities for **translation, question detection, keyword extraction, categorization, NER extractor, and more** — designed to help you integrate AI-powered text processing into your applications with minimal effort.
+
+---
+
+## ✨ Features
+
+TextTools provides a rich collection of high-level NLP utilities built on top of LLMs.  
+Each tool is designed to work out-of-the-box with structured outputs (JSON / Pydantic).
+
+- **Categorizer** → Zero-finetuning text categorization for fast, scalable classification.  
+- **Keyword Extractor** → Identify the most important keywords in a text.  
+- **Question Merger** → Merge the provided questions, preserving all the main points 
+- **NER (Named Entity Recognition) Extractor** → Extract people, places, organizations, and other entities.  
+- **Question Detector** → Determine whether a text is a question or not.  
+- **Question Generator From Text** → Generate high-quality, context-relevant questions from provided text.
+- **Question Generator From Subject** → Generate high-quality, context-relevant questions from a subject.
+- **Rewriter** → Rewrite text while preserving meaning or without it.
+- **Summarizer** → Condense long passages into clear, structured summaries. 
+- **Translator** → Translate text across multiple languages, with support for custom rules.
+
+---
+
+## 🔍 `with_analysis` Mode
+
+The `with_analysis=True` flag enhances the tool's output by providing a detailed reasoning chain behind its result. This is valuable for debugging, improving prompts, or understanding model behavior.
+
+**Please be aware:** This feature works by making an additional LLM API call for each tool invocation, which will **effectively double your token usage** for that operation.
+
+---
+
+## 🚀 Installation
+
+Install the latest release via PyPI:
+
+```bash
+pip install -U hamta-texttools
+```
+
+---
+
+## ⚡ Quick Start
+
+```python
+from openai import OpenAI
+
+from texttools import TheTool
+
+# Create your OpenAI client
+client = OpenAI(base_url = "your_url", API_KEY = "your_api_key")
+
+# Specify the model
+model = "gpt-4o-mini"
+
+# Create an instance of TheTool
+# ⚠️ Note: Enabling `with_analysis=True` provides deeper insights but incurs additional LLM calls and token usage.
+the_tool = TheTool(client = client, model = model, with_analysis = True)
+
+# Example: Question Detection
+print(the_tool.detect_question("Is this project open source?")["result"])
+# Output: True
+
+# Example: Translation
+print(the_tool.translate("سلام، حالت چطوره؟")["result"])
+# Output: "Hi! How are you?"
+```
+
+---
+
+## 📚 Use Cases
+
+Use **TextTools** when you need to:
+
+- 🔍 **Classify** large datasets quickly without model training  
+- 🌍 **Translate** and process multilingual corpora with ease  
+- 🧩 **Integrate** LLMs into production pipelines (structured outputs)  
+- 📊 **Analyze** large text collections using embeddings and categorization  
+- ⚙️ **Automate** common text-processing tasks without reinventing the wheel  
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome!  
+Feel free to **open issues, suggest new features, or submit pull requests**.  
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hamtaa_texttools-1.0.0/hamtaa_texttools.egg-info/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: hamtaa-texttools
+Version: 1.0.0
+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
+        
+        Copyright (c) 2025 Hamtaa
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Keywords: nlp,llm,text-processing,openai
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai==1.97.1
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# TextTools
+
+## 📌 Overview
+
+**TextTools** is a high-level **NLP toolkit** built on top of modern **LLMs**.  
+It provides ready-to-use utilities for **translation, question detection, keyword extraction, categorization, NER extractor, and more** — designed to help you integrate AI-powered text processing into your applications with minimal effort.
+
+---
+
+## ✨ Features
+
+TextTools provides a rich collection of high-level NLP utilities built on top of LLMs.  
+Each tool is designed to work out-of-the-box with structured outputs (JSON / Pydantic).
+
+- **Categorizer** → Zero-finetuning text categorization for fast, scalable classification.  
+- **Keyword Extractor** → Identify the most important keywords in a text.  
+- **Question Merger** → Merge the provided questions, preserving all the main points 
+- **NER (Named Entity Recognition) Extractor** → Extract people, places, organizations, and other entities.  
+- **Question Detector** → Determine whether a text is a question or not.  
+- **Question Generator From Text** → Generate high-quality, context-relevant questions from provided text.
+- **Question Generator From Subject** → Generate high-quality, context-relevant questions from a subject.
+- **Rewriter** → Rewrite text while preserving meaning or without it.
+- **Summarizer** → Condense long passages into clear, structured summaries. 
+- **Translator** → Translate text across multiple languages, with support for custom rules.
+
+---
+
+## 🔍 `with_analysis` Mode
+
+The `with_analysis=True` flag enhances the tool's output by providing a detailed reasoning chain behind its result. This is valuable for debugging, improving prompts, or understanding model behavior.
+
+**Please be aware:** This feature works by making an additional LLM API call for each tool invocation, which will **effectively double your token usage** for that operation.
+
+---
+
+## 🚀 Installation
+
+Install the latest release via PyPI:
+
+```bash
+pip install -U hamta-texttools
+```
+
+---
+
+## ⚡ Quick Start
+
+```python
+from openai import OpenAI
+
+from texttools import TheTool
+
+# Create your OpenAI client
+client = OpenAI(base_url = "your_url", API_KEY = "your_api_key")
+
+# Specify the model
+model = "gpt-4o-mini"
+
+# Create an instance of TheTool
+# ⚠️ Note: Enabling `with_analysis=True` provides deeper insights but incurs additional LLM calls and token usage.
+the_tool = TheTool(client = client, model = model, with_analysis = True)
+
+# Example: Question Detection
+print(the_tool.detect_question("Is this project open source?")["result"])
+# Output: True
+
+# Example: Translation
+print(the_tool.translate("سلام، حالت چطوره؟")["result"])
+# Output: "Hi! How are you?"
+```
+
+---
+
+## 📚 Use Cases
+
+Use **TextTools** when you need to:
+
+- 🔍 **Classify** large datasets quickly without model training  
+- 🌍 **Translate** and process multilingual corpora with ease  
+- 🧩 **Integrate** LLMs into production pipelines (structured outputs)  
+- 📊 **Analyze** large text collections using embeddings and categorization  
+- ⚙️ **Automate** common text-processing tasks without reinventing the wheel  
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome!  
+Feel free to **open issues, suggest new features, or submit pull requests**.  
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hamtaa_texttools-1.0.0/hamtaa_texttools.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+hamtaa_texttools.egg-info/PKG-INFO
+hamtaa_texttools.egg-info/SOURCES.txt
+hamtaa_texttools.egg-info/dependency_links.txt
+hamtaa_texttools.egg-info/requires.txt
+hamtaa_texttools.egg-info/top_level.txt
+tests/test_tools.py
+texttools/__init__.py
+texttools/formatters/base_formatter.py
+texttools/formatters/user_merge_formatter/user_merge_formatter.py
+texttools/tools/__init__.py
+texttools/tools/operator.py
+texttools/tools/output_models.py
+texttools/tools/prompt_loader.py
+texttools/tools/the_tool.py
+texttools/utils/__init__.py
+texttools/utils/batch_manager/__init__.py
+texttools/utils/batch_manager/batch_manager.py
+texttools/utils/batch_manager/batch_runner.py

hamtaa_texttools-1.0.0/hamtaa_texttools.egg-info/requires.txt

@@ -0,0 +1,2 @@
+openai==1.97.1
+PyYAML>=6.0

hamtaa_texttools-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hamtaa-texttools"
+version = "1.0.0"
+authors = [
+  { name = "Tohidi", email = "the.mohammad.tohidi@gmail.com" },
+  { name = "Montazer", email = "montazerh82@gmail.com" },
+  { name = "Givechi", email = "mohamad.m.givechi@gmail.com" },
+  { name = "MoosaviNejad", email = "erfanmoosavi84@gmail.com" },
+]
+description = "TextTools is a high-level NLP toolkit built on top of modern LLMs."
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+dependencies = [
+  "openai==1.97.1",
+  "PyYAML>=6.0"
+]
+keywords = ["nlp", "llm", "text-processing", "openai"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["texttools*"]

hamtaa_texttools-1.0.0/tests/test_tools.py

@@ -0,0 +1,65 @@
+import os
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+from texttools import TheTool
+
+# Load environment variables from .env
+load_dotenv()
+
+# Load API key from environment variable
+API_KEY = os.getenv("OPENAI_API_KEY")
+model = "google/gemma-3n-e4b-it"
+
+# Create OpenAI client
+client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=API_KEY)
+
+# Create an instance of TheTool
+t = TheTool(client=client, model=model)
+
+# Categorizer
+category = t.categorize("سلام حالت چطوره؟")
+print(category)
+
+# Keyword Extractor
+keywords = t.extract_keywords("Tomorrow, we will be dead by the car crash")
+print(keywords)
+
+# NER Extractor
+entities = t.extract_entities("We will be dead by the car crash")
+print(entities)
+
+# Question Detector
+detection = t.detect_question("We will be dead by the car crash")
+print(detection)
+
+# Question from Answer Generator
+question = t.generate_question_from_text("We will be dead by the car crash")
+print(question)
+
+# Question Merger
+question = t.merge_questions(
+    ["چرا ما انسان ها، موجوداتی اجتماعی هستیم؟", "چرا ما باید در کنار هم زندگی کنیم؟"],
+    mode="default_mode",
+)
+print(question)
+
+# Question Rewriter
+question = t.rewrite_question(
+    "چرا ما انسان ها، موجوداتی اجتماعی هستیم؟",
+    mode="same_meaning_different_wording_mode",
+)
+print(question)
+
+# Question Generator from Subject
+questions = t.generate_questions_from_subject("Friendship", 3)
+print(questions)
+
+# Summarizer
+summary = t.summarize("Tomorrow, we will be dead by the car crash")
+print(summary)
+
+# Translator
+translation = t.translate("سلام حالت چطوره؟", target_language="English")
+print(translation)

hamtaa_texttools-1.0.0/texttools/__init__.py

@@ -0,0 +1,9 @@
+from .tools.the_tool import TheTool
+from .utils.batch_manager.batch_manager import SimpleBatchManager
+from .utils.batch_manager.batch_runner import BatchJobRunner
+
+__all__ = [
+    "TheTool",
+    "SimpleBatchManager",
+    "BatchJobRunner",
+]

hamtaa_texttools-1.0.0/texttools/formatters/base_formatter.py

@@ -0,0 +1,33 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseFormatter(ABC):
+    """
+    Adapter to convert a conversation into a specific LLM API's input format.
+
+    Concrete implementations transform standardized messages (e.g., list[dict]) into the
+    exact payload required by a provider (e.g., OpenAI's message list, a single string, etc.).
+    """
+
+    @abstractmethod
+    def format(
+        self,
+        messages: Any,
+    ) -> Any:
+        """
+        Transform the input messages into a provider-specific payload.
+
+        Args:
+            messages: The input conversation. While often a list of dicts with
+                      'role' and 'content' keys, the exact type and structure may vary
+                      by implementation.
+
+        Returns:
+            A payload in the format expected by the target LLM API. This could be:
+            - A list of role-content dictionaries (e.g., for OpenAI)
+            - A single formatted string (e.g., for completion-style APIs)
+            - A complex dictionary with additional parameters
+            - Any other provider-specific data structure
+        """
+        pass

hamtaa_texttools-1.0.0/texttools/formatters/user_merge_formatter/user_merge_formatter.py

@@ -0,0 +1,47 @@
+from texttools.formatters.base_formatter import BaseFormatter
+
+
+class UserMergeFormatter(BaseFormatter):
+    """
+    Merges consecutive user messages into a single message, separated by newlines.
+
+    This is useful for condensing a multi-turn user input into a single coherent
+    message for the LLM. Assistant and system messages are left unchanged and
+    act as separators between user message groups.
+
+    Raises:
+        ValueError: If the input messages have invalid structure or roles.
+    """
+
+    def _validate_input(self, messages: list[dict[str, str]]):
+        valid_keys = {"role", "content"}
+        valid_roles = {"user", "assistant"}
+
+        for message in messages:
+            # Validate keys
+            if set(message.keys()) != valid_keys:
+                raise ValueError(
+                    f"Message dict keys must be exactly {valid_keys}, got {set(message.keys())}"
+                )
+            # Validate roles
+            role = message["role"]
+            if role != "system" and role not in valid_roles:
+                raise ValueError(f"Unexpected role: {role}")
+
+    def format(self, messages: list[dict[str, str]]) -> list[dict[str, str]]:
+        self._validate_input(messages)
+
+        merged: list[dict[str, str]] = []
+
+        for message in messages:
+            role, content = message["role"], message["content"].strip()
+
+            # Merge with previous user turn
+            if merged and role == "user" and merged[-1]["role"] == "user":
+                merged[-1]["content"] += "\n" + content
+
+            # Otherwise, start a new turn
+            else:
+                merged.append({"role": role, "content": content})
+
+        return merged

hamtaa_texttools-1.0.0/texttools/tools/__init__.py

@@ -0,0 +1,3 @@
+from .the_tool import TheTool
+
+__all__ = ["TheTool"]