hamtaa-texttools 1.1.21__py3-none-any.whl → 1.1.23__py3-none-any.whl

{hamtaa_texttools-1.1.21.dist-info → hamtaa_texttools-1.1.23.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.1.21
+Version: 1.1.23
 Summary: 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>, Zareshahi <a.zareshahi1377@gmail.com>
 License: MIT License
@@ -37,61 +37,53 @@ Dynamic: license-file
 
 ## 📌 Overview
 
-**TextTools** is a high-level **NLP toolkit** built on top of modern **LLMs**.  
+**TextTools** is a high-level **NLP toolkit** built on top of **LLMs**.  
 
 It provides both **sync (`TheTool`)** and **async (`AsyncTheTool`)** APIs for maximum flexibility.
 
 It provides ready-to-use utilities for **translation, question detection, keyword extraction, categorization, NER extraction, and more** - designed to help you integrate AI-powered text processing into your applications with minimal effort.
 
+**Note:** Most features of `texttools` are reliable when you use `google/gemma-3n-e4b-it` model.
+
 ---
 
 ## ✨ Features
 
 TextTools provides a rich collection of high-level NLP utilities,
-Each tool is designed to work with structured outputs (JSON / Pydantic).
+Each tool is designed to work with structured outputs.
 
 - **`categorize()`** - Classifies text into given categories
-- **`extract_keywords()`** - Extracts keywords from text
+- **`extract_keywords()`** - Extracts keywords from the text
 - **`extract_entities()`** - Named Entity Recognition (NER) system
-- **`is_question()`** - Binary detection of whether input is a question
+- **`is_question()`** - Binary question detection
 - **`text_to_question()`** - Generates questions from text
-- **`merge_questions()`** - Merges multiple questions with different modes
-- **`rewrite()`** - Rewrites text with different wording/meaning
+- **`merge_questions()`** - Merges multiple questions into one
+- **`rewrite()`** - Rewrites text in a diffrent way
 - **`subject_to_question()`** - Generates questions about a specific subject
 - **`summarize()`** - Text summarization
-- **`translate()`** - Text translation between languages
+- **`translate()`** - Text translation
 - **`propositionize()`** - Convert text to atomic independence meaningful sentences 
 - **`check_fact()`** - Check whether a statement is relevant to the source text
 - **`run_custom()`** - Allows users to define a custom tool with an arbitrary BaseModel
 
 ---
 
+## 🚀 Installation
+
+Install the latest release via PyPI:
+
+```bash
+pip install -U hamtaa-texttools
+```
+
+---
+
 ## 📊 Tool Quality Tiers
 
-| Status | Meaning | Use in Production? |
-|--------|---------|-------------------|
-| **✅ Production** | Evaluated, tested, stable. | **Yes** - ready for reliable use. |
-| **🧪 Experimental** | Added to the package but **not fully evaluated**. Functional, but quality may vary. | **Use with caution** - outputs not yet validated. |
-
-### Current Status
-**Production Tools:**
-- `categorize()` (list mode)
-- `extract_keywords()`
-- `extract_entities()`
-- `is_question()`
-- `text_to_question()`
-- `merge_questions()`
-- `rewrite()`
-- `subject_to_question()`
-- `summarize()`
-- `run_custom()` (fine in most cases)
-
-**Experimental Tools:**
-- `categorize()` (tree mode)
-- `translate()`
-- `propositionize()`
-- `check_fact()`
-- `run_custom()` (not evaluated in all scenarios)
+| Status | Meaning | Tools | Use in Production? |
+|--------|---------|----------|-------------------|
+| **✅ Production** | Evaluated, tested, stable. | `categorize()` (list mode), `extract_keywords()`, `extract_entities()`, `is_question()`, `text_to_question()`, `merge_questions()`, `rewrite()`, `subject_to_question()`, `summarize()`, `run_custom()` | **Yes** - ready for reliable use. |
+| **🧪 Experimental** | Added to the package but **not fully evaluated**. Functional, but quality may vary. | `categorize()` (tree mode), `translate()`, `propositionize()`, `check_fact()` | **Use with caution** - outputs not yet validated. |
 
 ---
 
@@ -100,49 +92,37 @@ Each tool is designed to work with structured outputs (JSON / Pydantic).
 TextTools provides several optional flags to customize LLM behavior:
 
 - **`with_analysis: bool`** → Adds a reasoning step before generating the final output.
-**Note:** This doubles token usage per call because it triggers an additional LLM request.
+**Note:** This doubles token usage per call.
 
 - **`logprobs: bool`** → Returns token-level probabilities for the generated output. You can also specify `top_logprobs=<N>` to get the top N alternative tokens and their probabilities.  
 **Note:** This feature works if it's supported by the model.
 
-- **`output_lang: str`** → Forces the model to respond in a specific language. The model will ignore other instructions about language and respond strictly in the requested language.
+- **`output_lang: str`** → Forces the model to respond in a specific language.
 
-- **`user_prompt: str`** → Allows you to inject a custom instruction or prompt into the model alongside the main template. This gives you fine-grained control over how the model interprets or modifies the input text.
+- **`user_prompt: str`** → Allows you to inject a custom instruction or into the model alongside the main template. This gives you fine-grained control over how the model interprets or modifies the input text.
 
 - **`temperature: float`** → Determines how creative the model should respond. Takes a float number from `0.0` to `2.0`.
 
-- **`validator: Callable (Experimental)`** → Forces TheTool to validate the output result based on your custom validator. Validator should return a bool (True if there were no problem, False if the validation fails.) If the validator fails, TheTool will retry to get another output by modifying `temperature`. You can specify `max_validation_retries=<N>` to change the number of retries.
+- **`validator: Callable (Experimental)`** → Forces TheTool to validate the output result based on your custom validator. Validator should return a boolean. If the validator fails, TheTool will retry to get another output by modifying `temperature`. You can also specify `max_validation_retries=<N>`.
 
-- **`priority: int (Experimental)`** → Task execution priority level. Higher values = higher priority. Affects processing order in queues.
+- **`priority: int (Experimental)`** → Task execution priority level. Affects processing order in queues.
 **Note:** This feature works if it's supported by the model and vLLM.
 
-**Note:** There might be some tools that don't support some of the parameters above.
-
 ---
 
 ## 🧩 ToolOutput
 
 Every tool of `TextTools` returns a `ToolOutput` object which is a BaseModel with attributes:
-- **`result: Any`** → The output of LLM
-- **`analysis: str`** → The reasoning step before generating the final output
-- **`logprobs: list`** → Token-level probabilities for the generated output
-- **`errors: list[str]`** → Any error that have occured during calling LLM
+- **`result: Any`**
+- **`analysis: str`**
+- **`logprobs: list`**
+- **`errors: list[str]`**
 - **`ToolOutputMetadata`** →
-    - **`tool_name: str`** → The tool name which processed the input
-    - **`processed_at: datetime`** → The process time
-    - **`execution_time: float`** → The execution time (seconds)
+    - **`tool_name: str`**
+    - **`processed_at: datetime`**
+    - **`execution_time: float`**
 
-**Note:** You can use `repr(ToolOutput)` to see details of your ToolOutput.
-
----
-
-## 🚀 Installation
-
-Install the latest release via PyPI:
-
-```bash
-pip install -U hamtaa-texttools
-```
+**Note:** You can use `repr(ToolOutput)` to print your output with all the details.
 
 ---
 
@@ -160,26 +140,13 @@ pip install -U hamtaa-texttools
 from openai import OpenAI
 from texttools import TheTool
 
-# Create your OpenAI client
 client = OpenAI(base_url = "your_url", API_KEY = "your_api_key")
+model = "model_name"
 
-# Specify the model
-model = "gpt-4o-mini"
-
-# Create an instance of TheTool
 the_tool = TheTool(client=client, model=model)
 
-# Example: Question Detection
-detection = the_tool.is_question("Is this project open source?", logprobs=True, top_logprobs=2)
-print(detection.result)
-print(detection.logprobs)
-# Output: True + logprobs
-
-# Example: Translation
-translation = the_tool.translate("سلام، حالت چطوره؟" target_language="English", with_analysis=True)
-print(translation.result)
-print(translation.analysis)
-# Output: "Hi! How are you?"  + analysis
+detection = the_tool.is_question("Is this project open source?")
+print(repr(detection))
 ```
 
 ---
@@ -192,22 +159,17 @@ from openai import AsyncOpenAI
 from texttools import AsyncTheTool
 
 async def main():
-    # Create your AsyncOpenAI client
     async_client = AsyncOpenAI(base_url="your_url", api_key="your_api_key")
+    model = "model_name"
 
-    # Specify the model
-    model = "gpt-4o-mini"
-
-    # Create an instance of AsyncTheTool
     async_the_tool = AsyncTheTool(client=async_client, model=model)
     
-    # Example: Async Translation and Keyword Extraction
     translation_task = async_the_tool.translate("سلام، حالت چطوره؟", target_language="English")
     keywords_task = async_the_tool.extract_keywords("Tomorrow, we will be dead by the car crash")
 
     (translation, keywords) = await asyncio.gather(translation_task, keywords_task)
-    print(translation.result)
-    print(keywords.result)
+    print(repr(translation))
+    print(repr(keywords))
 
 asyncio.run(main())
 ```
@@ -229,13 +191,12 @@ Use **TextTools** when you need to:
 
 Process large datasets efficiently using OpenAI's batch API.
 
-## ⚡ Quick Start (Batch)
+## ⚡ Quick Start (Batch Runner)
 
 ```python
 from pydantic import BaseModel
-from texttools import BatchJobRunner, BatchConfig
+from texttools import BatchRunner, BatchConfig
 
-# Configure your batch job
 config = BatchConfig(
     system_prompt="Extract entities from the text",
     job_name="entity_extraction",
@@ -244,12 +205,10 @@ config = BatchConfig(
     model="gpt-4o-mini"
 )
 
-# Define your output schema
 class Output(BaseModel):
     entities: list[str]
 
-# Run the batch job
-runner = BatchJobRunner(config, output_model=Output)
+runner = BatchRunner(config, output_model=Output)
 runner.run()
 ```
 

hamtaa_texttools-1.1.23.dist-info/RECORD

@@ -0,0 +1,32 @@
+hamtaa_texttools-1.1.23.dist-info/licenses/LICENSE,sha256=Hb2YOBKy2MJQLnyLrX37B4ZVuac8eaIcE71SvVIMOLg,1082
+texttools/__init__.py,sha256=fqGafzxcnGw0_ivi-vUyLfytWOkjLOumiaB0-I612iY,305
+texttools/batch/batch_config.py,sha256=TEUNC4YCEJDVmu-E1V2buglvQQvms8zw6lPRNsLTzDc,1050
+texttools/batch/batch_manager.py,sha256=Z7QiV-uL8QYbPmr7ifUEuOAeFHGNH_ybo8yyHK9Zca8,8730
+texttools/batch/batch_runner.py,sha256=szdvLS2oJtRwdLF29sefrfK7sHsi9WhqQ8xgSySymZA,9982
+texttools/internals/async_operator.py,sha256=kf2A3HBB7ebN5wg-LPVZwnDs8JoudJDeJbU_US408-I,6577
+texttools/internals/exceptions.py,sha256=6SDjUL1rmd3ngzD3ytF4LyTRj3bQMSFR9ECrLoqXXHw,395
+texttools/internals/models.py,sha256=9uoCAe2TLrSzyS9lMJja5orPAYaCvVL1zoCb6FNdkfs,4541
+texttools/internals/operator_utils.py,sha256=RDrNUNhN9QDgCOgw7JAc9IOqZ-gk1Jq-TrjiTlXEE9Q,2414
+texttools/internals/prompt_loader.py,sha256=cQnmeTLSp6MQb6hhv_FwiqzZI__opT7SU7XmPxS33d0,3143
+texttools/internals/sync_operator.py,sha256=Um3ud0DQ-murM8rkZy_Ud7qgfpDqhRqMzHWEkM13wt8,6482
+texttools/internals/text_to_chunks.py,sha256=vY3odhgCZK4E44k_SGlLoSiKkdN0ib6-lQAsPcplAHA,3843
+texttools/prompts/README.md,sha256=ztajRJcmFLhyrUF0_qmOXaCwGsTGCFabfMjch2LAJG0,1375
+texttools/prompts/categorize.yaml,sha256=42Rp3SgVHaDLKrJ27_uK788LiQud0pOXJthz4r0a40Y,1214
+texttools/prompts/check_fact.yaml,sha256=zWFQDRhEE1ij9wSeeenS9YSTM-bY5zzUaG390zUgmcs,714
+texttools/prompts/extract_entities.yaml,sha256=_zYKHNJDIzVDI_-TnwFCKyMs-XLM5igvmWhvSTc3INQ,637
+texttools/prompts/extract_keywords.yaml,sha256=1o4u3uwzapNtB1BUpNIRL5qtrwjW0Yhvyq0TZJiafdg,3272
+texttools/prompts/is_question.yaml,sha256=jnPARd2ZiulLzHW_r4WAsz3sOryfz6Gy5-yYXp-2hd0,496
+texttools/prompts/merge_questions.yaml,sha256=l9Q2OEjPp3SDkxbq3zZCj2ZmXacWSnmYMpUr3l6r5yE,1816
+texttools/prompts/propositionize.yaml,sha256=nbGAfbm1-2Hoc0JLtqZi-S7VHQfnMmuTKI7dZeBxQW0,1403
+texttools/prompts/rewrite.yaml,sha256=klEm8MqXK-Bo8RsS5R9KLMT0zlD-BKo_G6tz9lpAcEY,5420
+texttools/prompts/run_custom.yaml,sha256=IETY9H0wPGWIIzcnupfbwwKQblwZrbYAxB754W9MhgU,125
+texttools/prompts/subject_to_question.yaml,sha256=AK16pZW9HUppIF8JBSEenbUNOU3aqeVV781_WUXnLqk,1160
+texttools/prompts/summarize.yaml,sha256=rPh060Bx_yI1W2JNg-nr83LUk9itatYLKM8ciH2pOvg,486
+texttools/prompts/text_to_question.yaml,sha256=pUwPgK9l5f8S4E5fCht9JY7PFVK2aY1InPfASr7R5o4,1017
+texttools/prompts/translate.yaml,sha256=Dd5bs3O8SI-FlVSwHMYGeEjMmdOWeRlcfBHkhixCx7c,665
+texttools/tools/async_tools.py,sha256=0RjL7zJ565dIYYHJC7-QEZ4FoslB-yawg8rwcv3FBlE,43434
+texttools/tools/sync_tools.py,sha256=-2GGgnAKDfRFxxrCgFIA1h6wgoxehrrqEa-meay60r0,43227
+hamtaa_texttools-1.1.23.dist-info/METADATA,sha256=EsEgRolMNIv5dLunjtJTTSlYIaO6oE8JHRCsqP8uerk,8718
+hamtaa_texttools-1.1.23.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hamtaa_texttools-1.1.23.dist-info/top_level.txt,sha256=5Mh0jIxxZ5rOXHGJ6Mp-JPKviywwN0MYuH0xk5bEWqE,10
+hamtaa_texttools-1.1.23.dist-info/RECORD,,

texttools/__init__.py

@@ -1,7 +1,7 @@
-from .batch.batch_runner import BatchJobRunner
-from .batch.batch_config import BatchConfig
 from .tools.sync_tools import TheTool
 from .tools.async_tools import AsyncTheTool
 from .internals.models import CategoryTree
+from .batch.batch_runner import BatchRunner
+from .batch.batch_config import BatchConfig
 
-__all__ = ["TheTool", "AsyncTheTool", "BatchJobRunner", "BatchConfig", "CategoryTree"]
+__all__ = ["TheTool", "AsyncTheTool", "CategoryTree", "BatchRunner", "BatchConfig"]

texttools/batch/batch_config.py

@@ -1,3 +1,4 @@
+from typing import Any
 from dataclasses import dataclass
 from collections.abc import Callable
 
@@ -10,7 +11,7 @@ def export_data(data) -> list[dict[str, str]]:
     return data
 
 
-def import_data(data) -> object:
+def import_data(data) -> Any:
     """
     Takes the output and adds and aggregates it to the original structure.
     """

texttools/batch/batch_manager.py

@@ -1,7 +1,7 @@
 import json
 import uuid
 from pathlib import Path
-from typing import Type, TypeVar
+from typing import Type, TypeVar, Any
 import logging
 
 from pydantic import BaseModel
@@ -31,7 +31,7 @@ class BatchManager:
         prompt_template: str,
         state_dir: Path = Path(".batch_jobs"),
         custom_json_schema_obj_str: dict | None = None,
-        **client_kwargs: object,
+        **client_kwargs: Any,
     ):
         self._client = client
         self._model = model
@@ -51,7 +51,7 @@ class BatchManager:
     def _state_file(self, job_name: str) -> Path:
         return self._state_dir / f"{job_name}.json"
 
-    def _load_state(self, job_name: str) -> list[dict[str, object]]:
+    def _load_state(self, job_name: str) -> list[dict[str, Any]]:
         """
         Loads the state (job information) from the state file for the given job name.
         Returns an empty list if the state file does not exist.
@@ -62,7 +62,7 @@ class BatchManager:
                 return json.load(f)
         return []
 
-    def _save_state(self, job_name: str, jobs: list[dict[str, object]]) -> None:
+    def _save_state(self, job_name: str, jobs: list[dict[str, Any]]) -> None:
         """
         Saves the job state to the state file for the given job name.
         """
@@ -77,11 +77,11 @@ class BatchManager:
         if path.exists():
             path.unlink()
 
-    def _build_task(self, text: str, idx: str) -> dict[str, object]:
+    def _build_task(self, text: str, idx: str) -> dict[str, Any]:
         """
         Builds a single task dictionary for the batch job, including the prompt, model, and response format configuration.
         """
-        response_format_config: dict[str, object]
+        response_format_config: dict[str, Any]
 
         if self._custom_json_schema_obj_str:
             response_format_config = {

texttools/batch/batch_runner.py

@@ -2,7 +2,7 @@ import json
 import os
 import time
 from pathlib import Path
-from typing import Type, TypeVar
+from typing import Type, TypeVar, Any
 import logging
 
 from dotenv import load_dotenv
@@ -12,7 +12,7 @@ from pydantic import BaseModel
 from texttools.batch.batch_manager import BatchManager
 from texttools.batch.batch_config import BatchConfig
 from texttools.internals.models import Str
-from texttools.internals.exceptions import TextToolsError, ConfigurationError
+from texttools.internals.exceptions import TextToolsError
 
 # Base Model type for output models
 T = TypeVar("T", bound=BaseModel)
@@ -20,7 +20,7 @@ T = TypeVar("T", bound=BaseModel)
 logger = logging.getLogger("texttools.batch_runner")
 
 
-class BatchJobRunner:
+class BatchRunner:
     """
     Handles running batch jobs using a batch manager and configuration.
     """
@@ -38,7 +38,7 @@ class BatchJobRunner:
             self._output_model = output_model
             self._manager = self._init_manager()
             self._data = self._load_data()
-            self._parts: list[list[dict[str, object]]] = []
+            self._parts: list[list[dict[str, Any]]] = []
             # Map part index to job name
             self._part_idx_to_job_name: dict[int, str] = {}
             # Track retry attempts per part
@@ -47,7 +47,7 @@ class BatchJobRunner:
             Path(self._config.BASE_OUTPUT_DIR).mkdir(parents=True, exist_ok=True)
 
         except Exception as e:
-            raise ConfigurationError(f"Batch runner initialization failed: {e}")
+            raise TextToolsError(f"Batch runner initialization failed: {e}")
 
     def _init_manager(self) -> BatchManager:
         load_dotenv()
@@ -130,8 +130,8 @@ class BatchJobRunner:
 
     def _save_results(
         self,
-        output_data: list[dict[str, object]] | dict[str, object],
-        log: list[object],
+        output_data: list[dict[str, Any]] | dict[str, Any],
+        log: list[Any],
         part_idx: int,
     ):
         part_suffix = f"_part_{part_idx + 1}" if len(self._parts) > 1 else ""

texttools/internals/async_operator.py

@@ -1,4 +1,4 @@
-from typing import TypeVar, Type
+from typing import TypeVar, Type, Any
 from collections.abc import Callable
 
 from openai import AsyncOpenAI
@@ -27,17 +27,11 @@ class AsyncOperator:
         self._client = client
         self._model = model
 
-    async def _analyze_completion(self, analyze_prompt: str, temperature: float) -> str:
+    async def _analyze_completion(self, analyze_message: list[dict[str, str]]) -> str:
         try:
-            if not analyze_prompt:
-                raise PromptError("Analyze template is empty")
-
-            analyze_message = OperatorUtils.build_user_message(analyze_prompt)
-
             completion = await self._client.chat.completions.create(
                 model=self._model,
                 messages=analyze_message,
-                temperature=temperature,
             )
 
             if not completion.choices:
@@ -57,20 +51,18 @@ class AsyncOperator:
 
     async def _parse_completion(
         self,
-        main_prompt: str,
+        main_message: list[dict[str, str]],
         output_model: Type[T],
         temperature: float,
         logprobs: bool,
         top_logprobs: int,
-        priority: int,
-    ) -> tuple[T, object]:
+        priority: int | None,
+    ) -> tuple[T, Any]:
         """
         Parses a chat completion using OpenAI's structured output format.
-        Returns both the parsed object and the raw completion for logprobs.
+        Returns both the parsed Any and the raw completion for logprobs.
         """
         try:
-            main_message = OperatorUtils.build_user_message(main_prompt)
-
             request_kwargs = {
                 "model": self._model,
                 "messages": main_message,
@@ -82,7 +74,7 @@ class AsyncOperator:
                 request_kwargs["logprobs"] = True
                 request_kwargs["top_logprobs"] = top_logprobs
 
-            if priority:
+            if priority is not None:
                 request_kwargs["extra_body"] = {"priority": priority}
 
             completion = await self._client.beta.chat.completions.parse(
@@ -114,50 +106,48 @@ class AsyncOperator:
         temperature: float,
         logprobs: bool,
         top_logprobs: int,
-        validator: Callable[[object], bool] | None,
+        validator: Callable[[Any], bool] | None,
         max_validation_retries: int | None,
-        priority: int,
+        priority: int | None,
         # Internal parameters
-        prompt_file: str,
+        tool_name: str,
         output_model: Type[T],
         mode: str | None,
         **extra_kwargs,
     ) -> OperatorOutput:
         """
-        Execute the LLM pipeline with the given input text. (Sync)
+        Execute the LLM pipeline with the given input text.
         """
         try:
             prompt_loader = PromptLoader()
-
             prompt_configs = prompt_loader.load(
-                prompt_file=prompt_file,
+                prompt_file=tool_name + ".yaml",
                 text=text.strip(),
                 mode=mode,
                 **extra_kwargs,
             )
 
-            main_prompt = ""
-            analysis = ""
+            analysis: str | None = None
 
             if with_analysis:
-                analysis = await self._analyze_completion(
-                    prompt_configs["analyze_template"], temperature
+                analyze_message = OperatorUtils.build_message(
+                    prompt_configs["analyze_template"]
                 )
-                main_prompt += f"Based on this analysis:\n{analysis}\n"
-
-            if output_lang:
-                main_prompt += f"Respond only in the {output_lang} language.\n"
+                analysis = await self._analyze_completion(analyze_message)
 
-            if user_prompt:
-                main_prompt += f"Consider this instruction {user_prompt}\n"
-
-            main_prompt += prompt_configs["main_template"]
-
-            if logprobs and (not isinstance(top_logprobs, int) or top_logprobs < 2):
-                raise ValueError("top_logprobs should be an integer greater than 1")
+            main_message = OperatorUtils.build_message(
+                OperatorUtils.build_main_prompt(
+                    prompt_configs["main_template"], analysis, output_lang, user_prompt
+                )
+            )
 
             parsed, completion = await self._parse_completion(
-                main_prompt, output_model, temperature, logprobs, top_logprobs, priority
+                main_message,
+                output_model,
+                temperature,
+                logprobs,
+                top_logprobs,
+                priority,
             )
 
             # Retry logic if validation fails
@@ -166,9 +156,7 @@ class AsyncOperator:
                     not isinstance(max_validation_retries, int)
                     or max_validation_retries < 1
                 ):
-                    raise ValueError(
-                        "max_validation_retries should be a positive integer"
-                    )
+                    raise ValueError("max_validation_retries should be a positive int")
 
                 succeeded = False
                 for _ in range(max_validation_retries):
@@ -177,7 +165,7 @@ class AsyncOperator:
 
                     try:
                         parsed, completion = await self._parse_completion(
-                            main_prompt,
+                            main_message,
                             output_model,
                             retry_temperature,
                             logprobs,

texttools/internals/exceptions.py

@@ -20,9 +20,3 @@ class ValidationError(TextToolsError):
     """Errors from output validation."""
 
     pass
-
-
-class ConfigurationError(TextToolsError):
-    """Errors from misconfiguration."""
-
-    pass

texttools/internals/operator_utils.py

@@ -5,7 +5,29 @@ import random
 
 class OperatorUtils:
     @staticmethod
-    def build_user_message(prompt: str) -> list[dict[str, str]]:
+    def build_main_prompt(
+        main_template: str,
+        analysis: str | None,
+        output_lang: str | None,
+        user_prompt: str | None,
+    ) -> str:
+        main_prompt = ""
+
+        if analysis:
+            main_prompt += f"Based on this analysis:\n{analysis}\n"
+
+        if output_lang:
+            main_prompt += f"Respond only in the {output_lang} language.\n"
+
+        if user_prompt:
+            main_prompt += f"Consider this instruction {user_prompt}\n"
+
+        main_prompt += main_template
+
+        return main_prompt
+
+    @staticmethod
+    def build_message(prompt: str) -> list[dict[str, str]]:
         return [{"role": "user", "content": prompt}]
 
     @staticmethod
@@ -20,7 +42,7 @@ class OperatorUtils:
 
         for choice in completion.choices:
             if not getattr(choice, "logprobs", None):
-                return []
+                raise ValueError("Your model does not support logprobs")
 
             for logprob_item in choice.logprobs.content:
                 if ignore_pattern.match(logprob_item.token):
@@ -45,9 +67,6 @@ class OperatorUtils:
 
     @staticmethod
     def get_retry_temp(base_temp: float) -> float:
-        """
-        Calculate temperature for retry attempts.
-        """
         delta_temp = random.choice([-1, 1]) * random.uniform(0.1, 0.9)
         new_temp = base_temp + delta_temp
 

texttools/internals/prompt_loader.py

@@ -8,11 +8,6 @@ from texttools.internals.exceptions import PromptError
 class PromptLoader:
     """
     Utility for loading and formatting YAML prompt templates.
-
-    Responsibilities:
-    - Load and parse YAML prompt definitions.
-    - Select the right template (by mode, if applicable).
-    - Inject variables (`{text}`, plus any extra kwargs) into the templates.
     """
 
     MAIN_TEMPLATE = "main_template"