hamtaa-texttools 1.1.17__py3-none-any.whl → 1.1.19__py3-none-any.whl

{hamtaa_texttools-1.1.17.dist-info → hamtaa_texttools-1.1.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamtaa-texttools
-Version: 1.1.17
+Version: 1.1.19
 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
@@ -61,10 +61,40 @@ Each tool is designed to work with structured outputs (JSON / Pydantic).
 - **`summarize()`** - Text summarization
 - **`translate()`** - Text translation between languages
 - **`propositionize()`** - Convert text to atomic independence meaningful sentences 
+- **`check_fact()`** - Check a statement is relevant to source text or not 
 - **`run_custom()`** - Allows users to define a custom tool with an arbitrary BaseModel
 
 ---
 
+## 📊 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)
+
+---
+
 ## ⚙️ `with_analysis`, `logprobs`, `output_lang`, `user_prompt`, `temperature`, `validator` and `priority` parameters
 
 TextTools provides several optional flags to customize LLM behavior:

hamtaa_texttools-1.1.19.dist-info/RECORD

@@ -0,0 +1,33 @@
+hamtaa_texttools-1.1.19.dist-info/licenses/LICENSE,sha256=Hb2YOBKy2MJQLnyLrX37B4ZVuac8eaIcE71SvVIMOLg,1082
+texttools/__init__.py,sha256=CmCS9dEvO6061GiJ8A7gD3UAhCWHTkaID9q3Krlyq_o,311
+texttools/batch/batch_config.py,sha256=m1UgILVKjNdWE6laNbfbG4vgi4o2fEegGZbeoam6pnY,749
+texttools/batch/batch_runner.py,sha256=Tz-jec27UZBSZAXc0sxitc5XycDfzvOYl47Yqzq6Myw,10031
+texttools/batch/internals/batch_manager.py,sha256=UoBe76vmFG72qrSaGKDZf4HzkykFBkkkbL9TLfV8TuQ,8730
+texttools/batch/internals/utils.py,sha256=F1_7YlVFKhjUROAFX4m0SaP8KiZVZyHRMIIB87VUGQc,373
+texttools/internals/async_operator.py,sha256=_RfYSm_66RJ6nppzorJ4r3BHdhr8xr404QjeVvsvX4Q,8485
+texttools/internals/exceptions.py,sha256=h_yp_5i_5IfmqTBQ4S6ZOISrrliJBQ3HTEAjwJXrplk,495
+texttools/internals/formatters.py,sha256=tACNLP6PeoqaRpNudVxBaHA25zyWqWYPZQuYysIu88g,941
+texttools/internals/models.py,sha256=zmgdFhMCNyfc-5dtSE4jwulhltVgxYzITZRMDJBUF0A,5977
+texttools/internals/operator_utils.py,sha256=w1k0RJ_W_CRbVc_J2w337VuL-opHpHiCxfhEOwtyuOo,1856
+texttools/internals/prompt_loader.py,sha256=i4OxcVJTjHFKPSoC-DWZUM3Vf8ye_vbD7b6t3N2qB08,3972
+texttools/internals/sync_operator.py,sha256=7SdsNoFQxgmMrSZbUUw7SJVqyO5Xhu8dui9lm64RKsk,8382
+texttools/prompts/README.md,sha256=-5YO93CN93QLifqZpUeUnCOCBbDiOTV-cFQeJ7Gg0I4,1377
+texttools/prompts/categorize.yaml,sha256=F7VezB25B_sT5yoC25ezODBddkuDD5lUHKetSpx9FKI,2743
+texttools/prompts/check_fact.yaml,sha256=5kpBjmfZxgp81Owc8-Pd0U8-cZowFGRdYlGTFQLYQ9o,702
+texttools/prompts/extract_entities.yaml,sha256=KiKjeDpHaeh3JVtZ6q1pa3k4DYucUIU9WnEcRTCA-SE,651
+texttools/prompts/extract_keywords.yaml,sha256=Vj4Tt3vT6LtpOo_iBZPo9oWI50oVdPGXe5i8yDR8ex4,3177
+texttools/prompts/is_question.yaml,sha256=d0-vKRbXWkxvO64ikvxRjEmpAXGpCYIPGhgexvPPjws,471
+texttools/prompts/merge_questions.yaml,sha256=0J85GvTirZB4ELwH3sk8ub_WcqqpYf6PrMKr3djlZeo,1792
+texttools/prompts/propositionize.yaml,sha256=kdj-UxPOYcLSTLF7cWARDxxTxSFB0qRBaRujdThPDxw,1380
+texttools/prompts/rewrite.yaml,sha256=LO7He_IA3MZKz8a-LxH9DHJpOjpYwaYN1pbjp1Y0tFo,5392
+texttools/prompts/run_custom.yaml,sha256=6oiMYOo_WctVbOmE01wZzI1ra7nFDMJzceTTtnGdmOA,126
+texttools/prompts/subject_to_question.yaml,sha256=C7x7rNNm6U_ZG9HOn6zuzYOtvJUZ2skuWbL1-aYdd3E,1147
+texttools/prompts/summarize.yaml,sha256=o6rxGPfWtZd61Duvm8NVvCJqfq73b-wAuMSKR6UYUqY,459
+texttools/prompts/text_to_question.yaml,sha256=UheKYpDn6iyKI8NxunHZtFpNyfCLZZe5cvkuXpurUJY,783
+texttools/prompts/translate.yaml,sha256=mGT2uBCei6uucWqVbs4silk-UV060v3G0jnt0P6sr50,634
+texttools/tools/async_tools.py,sha256=eNsKJqpTNL1AIM_enHvqUJYxov1Mb5ErnShZuX7oqRQ,49532
+texttools/tools/sync_tools.py,sha256=DbY7smzYnEgd1H0r-5sVW-NExJwhL23TtQ_n5ACqbBc,49344
+hamtaa_texttools-1.1.19.dist-info/METADATA,sha256=egHahU5ec3bSpRB0DK0CrT21kfmhbM6-xxJjoMp1eDU,10587
+hamtaa_texttools-1.1.19.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hamtaa_texttools-1.1.19.dist-info/top_level.txt,sha256=5Mh0jIxxZ5rOXHGJ6Mp-JPKviywwN0MYuH0xk5bEWqE,10
+hamtaa_texttools-1.1.19.dist-info/RECORD,,

texttools/__init__.py

@@ -2,6 +2,6 @@ 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 .tools.internals.models import CategoryTree
+from .internals.models import CategoryTree
 
 __all__ = ["TheTool", "AsyncTheTool", "BatchJobRunner", "BatchConfig", "CategoryTree"]

texttools/batch/batch_runner.py

@@ -11,7 +11,8 @@ from pydantic import BaseModel
 
 from texttools.batch.internals.batch_manager import BatchManager
 from texttools.batch.batch_config import BatchConfig
-from texttools.tools.internals.models import StrOutput
+from texttools.internals.models import StrOutput
+from texttools.internals.exceptions import TextToolsError, ConfigurationError
 
 # Base Model type for output models
 T = TypeVar("T", bound=BaseModel)
@@ -27,22 +28,26 @@ class BatchJobRunner:
     def __init__(
         self, config: BatchConfig = BatchConfig(), output_model: Type[T] = StrOutput
     ):
-        self._config = config
-        self._system_prompt = config.system_prompt
-        self._job_name = config.job_name
-        self._input_data_path = config.input_data_path
-        self._output_data_filename = config.output_data_filename
-        self._model = config.model
-        self._output_model = output_model
-        self._manager = self._init_manager()
-        self._data = self._load_data()
-        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
-        self._part_attempts: dict[int, int] = {}
-        self._partition_data()
-        Path(self._config.BASE_OUTPUT_DIR).mkdir(parents=True, exist_ok=True)
+        try:
+            self._config = config
+            self._system_prompt = config.system_prompt
+            self._job_name = config.job_name
+            self._input_data_path = config.input_data_path
+            self._output_data_filename = config.output_data_filename
+            self._model = config.model
+            self._output_model = output_model
+            self._manager = self._init_manager()
+            self._data = self._load_data()
+            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
+            self._part_attempts: dict[int, int] = {}
+            self._partition_data()
+            Path(self._config.BASE_OUTPUT_DIR).mkdir(parents=True, exist_ok=True)
+
+        except Exception as e:
+            raise ConfigurationError(f"Batch runner initialization failed: {e}")
 
     def _init_manager(self) -> BatchManager:
         load_dotenv()
@@ -162,56 +167,62 @@ class BatchJobRunner:
 
         Submits jobs, monitors progress, handles retries, and saves results.
         """
-        # Submit all jobs up-front for concurrent execution
-        self._submit_all_jobs()
-        pending_parts: set[int] = set(self._part_idx_to_job_name.keys())
-        logger.info(f"Pending parts: {sorted(pending_parts)}")
-        # Polling loop
-        while pending_parts:
-            finished_this_round: list[int] = []
-            for part_idx in list(pending_parts):
-                job_name = self._part_idx_to_job_name[part_idx]
-                status = self._manager.check_status(job_name=job_name)
-                logger.info(f"Status for {job_name}: {status}")
-                if status == "completed":
-                    logger.info(
-                        f"Job completed. Fetching results for part {part_idx + 1}..."
-                    )
-                    output_data, log = self._manager.fetch_results(
-                        job_name=job_name, remove_cache=False
-                    )
-                    output_data = self._config.import_function(output_data)
-                    self._save_results(output_data, log, part_idx)
-                    logger.info(f"Fetched and saved results for part {part_idx + 1}.")
-                    finished_this_round.append(part_idx)
-                elif status == "failed":
-                    attempt = self._part_attempts.get(part_idx, 0) + 1
-                    self._part_attempts[part_idx] = attempt
-                    if attempt <= self._config.max_retries:
+        try:
+            # Submit all jobs up-front for concurrent execution
+            self._submit_all_jobs()
+            pending_parts: set[int] = set(self._part_idx_to_job_name.keys())
+            logger.info(f"Pending parts: {sorted(pending_parts)}")
+            # Polling loop
+            while pending_parts:
+                finished_this_round: list[int] = []
+                for part_idx in list(pending_parts):
+                    job_name = self._part_idx_to_job_name[part_idx]
+                    status = self._manager.check_status(job_name=job_name)
+                    logger.info(f"Status for {job_name}: {status}")
+                    if status == "completed":
                         logger.info(
-                            f"Job {job_name} failed (attempt {attempt}). Retrying after short backoff..."
+                            f"Job completed. Fetching results for part {part_idx + 1}..."
                         )
-                        self._manager._clear_state(job_name)
-                        time.sleep(10)
-                        payload = self._to_manager_payload(self._parts[part_idx])
-                        new_job_name = (
-                            f"{self._job_name}_part_{part_idx + 1}_retry_{attempt}"
+                        output_data, log = self._manager.fetch_results(
+                            job_name=job_name, remove_cache=False
                         )
-                        self._manager.start(payload, job_name=new_job_name)
-                        self._part_idx_to_job_name[part_idx] = new_job_name
-                    else:
+                        output_data = self._config.import_function(output_data)
+                        self._save_results(output_data, log, part_idx)
                         logger.info(
-                            f"Job {job_name} failed after {attempt - 1} retries. Marking as failed."
+                            f"Fetched and saved results for part {part_idx + 1}."
                         )
                         finished_this_round.append(part_idx)
-                else:
-                    # Still running or queued
-                    continue
-            # Remove finished parts
-            for part_idx in finished_this_round:
-                pending_parts.discard(part_idx)
-            if pending_parts:
-                logger.info(
-                    f"Waiting {self._config.poll_interval_seconds}s before next status check for parts: {sorted(pending_parts)}"
-                )
-                time.sleep(self._config.poll_interval_seconds)
+                    elif status == "failed":
+                        attempt = self._part_attempts.get(part_idx, 0) + 1
+                        self._part_attempts[part_idx] = attempt
+                        if attempt <= self._config.max_retries:
+                            logger.info(
+                                f"Job {job_name} failed (attempt {attempt}). Retrying after short backoff..."
+                            )
+                            self._manager._clear_state(job_name)
+                            time.sleep(10)
+                            payload = self._to_manager_payload(self._parts[part_idx])
+                            new_job_name = (
+                                f"{self._job_name}_part_{part_idx + 1}_retry_{attempt}"
+                            )
+                            self._manager.start(payload, job_name=new_job_name)
+                            self._part_idx_to_job_name[part_idx] = new_job_name
+                        else:
+                            logger.info(
+                                f"Job {job_name} failed after {attempt - 1} retries. Marking as failed."
+                            )
+                            finished_this_round.append(part_idx)
+                    else:
+                        # Still running or queued
+                        continue
+                # Remove finished parts
+                for part_idx in finished_this_round:
+                    pending_parts.discard(part_idx)
+                if pending_parts:
+                    logger.info(
+                        f"Waiting {self._config.poll_interval_seconds}s before next status check for parts: {sorted(pending_parts)}"
+                    )
+                    time.sleep(self._config.poll_interval_seconds)
+
+        except Exception as e:
+            raise TextToolsError(f"Batch job execution failed: {e}")

texttools/{tools/internals → internals}/async_operator.py

@@ -5,10 +5,16 @@ import logging
 from openai import AsyncOpenAI
 from pydantic import BaseModel
 
-from texttools.tools.internals.models import ToolOutput
-from texttools.tools.internals.operator_utils import OperatorUtils
-from texttools.tools.internals.formatters import Formatter
-from texttools.tools.internals.prompt_loader import PromptLoader
+from texttools.internals.models import ToolOutput
+from texttools.internals.operator_utils import OperatorUtils
+from texttools.internals.formatters import Formatter
+from texttools.internals.prompt_loader import PromptLoader
+from texttools.internals.exceptions import (
+    TextToolsError,
+    LLMError,
+    ValidationError,
+    PromptError,
+)
 
 # Base Model type for output models
 T = TypeVar("T", bound=BaseModel)
@@ -35,15 +41,33 @@ class AsyncOperator:
         Calls OpenAI API for analysis using the configured prompt template.
         Returns the analyzed content as a string.
         """
-        analyze_prompt = prompt_configs["analyze_template"]
-        analyze_message = [OperatorUtils.build_user_message(analyze_prompt)]
-        completion = await self._client.chat.completions.create(
-            model=self._model,
-            messages=analyze_message,
-            temperature=temperature,
-        )
-        analysis = completion.choices[0].message.content.strip()
-        return analysis
+        try:
+            analyze_prompt = prompt_configs["analyze_template"]
+
+            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:
+                raise LLMError("No choices returned from LLM")
+
+            analysis = completion.choices[0].message.content.strip()
+
+            if not analysis:
+                raise LLMError("Empty analysis response")
+
+            return analysis.strip()
+
+        except Exception as e:
+            if isinstance(e, (PromptError, LLMError)):
+                raise
+            raise LLMError(f"Analysis failed: {e}")
 
     async def _parse_completion(
         self,
@@ -58,21 +82,37 @@ class AsyncOperator:
         Parses a chat completion using OpenAI's structured output format.
         Returns both the parsed object and the raw completion for logprobs.
         """
-        request_kwargs = {
-            "model": self._model,
-            "messages": message,
-            "response_format": output_model,
-            "temperature": temperature,
-        }
-
-        if logprobs:
-            request_kwargs["logprobs"] = True
-            request_kwargs["top_logprobs"] = top_logprobs
-        if priority:
-            request_kwargs["extra_body"] = {"priority": priority}
-        completion = await self._client.beta.chat.completions.parse(**request_kwargs)
-        parsed = completion.choices[0].message.parsed
-        return parsed, completion
+        try:
+            request_kwargs = {
+                "model": self._model,
+                "messages": message,
+                "response_format": output_model,
+                "temperature": temperature,
+            }
+
+            if logprobs:
+                request_kwargs["logprobs"] = True
+                request_kwargs["top_logprobs"] = top_logprobs
+            if priority:
+                request_kwargs["extra_body"] = {"priority": priority}
+            completion = await self._client.beta.chat.completions.parse(
+                **request_kwargs
+            )
+
+            if not completion.choices:
+                raise LLMError("No choices returned from LLM")
+
+            parsed = completion.choices[0].message.parsed
+
+            if not parsed:
+                raise LLMError("Failed to parse LLM response")
+
+            return parsed, completion
+
+        except Exception as e:
+            if isinstance(e, LLMError):
+                raise
+            raise LLMError(f"Completion failed: {e}")
 
     async def run(
         self,
@@ -94,13 +134,13 @@ class AsyncOperator:
         **extra_kwargs,
     ) -> ToolOutput:
         """
-        Execute the async LLM pipeline with the given input text. (Async)
+        Execute the LLM pipeline with the given input text. (Async)
         """
-        prompt_loader = PromptLoader()
-        formatter = Formatter()
-        output = ToolOutput()
-
         try:
+            prompt_loader = PromptLoader()
+            formatter = Formatter()
+            output = ToolOutput()
+
             # Prompt configs contain two keys: main_template and analyze template, both are string
             prompt_configs = prompt_loader.load(
                 prompt_file=prompt_file,
@@ -139,6 +179,9 @@ class AsyncOperator:
 
             messages = formatter.user_merge_format(messages)
 
+            if logprobs and (not isinstance(top_logprobs, int) or top_logprobs < 2):
+                raise ValueError("top_logprobs should be an integer greater than 1")
+
             parsed, completion = await self._parse_completion(
                 messages, output_model, temperature, logprobs, top_logprobs, priority
             )
@@ -147,6 +190,15 @@ class AsyncOperator:
 
             # Retry logic if validation fails
             if validator and not validator(output.result):
+                if (
+                    not isinstance(max_validation_retries, int)
+                    or max_validation_retries < 1
+                ):
+                    raise ValueError(
+                        "max_validation_retries should be a positive integer"
+                    )
+
+                succeeded = False
                 for attempt in range(max_validation_retries):
                     logger.warning(
                         f"Validation failed, retrying for the {attempt + 1} time."
@@ -154,6 +206,7 @@ class AsyncOperator:
 
                     # Generate new temperature for retry
                     retry_temperature = OperatorUtils.get_retry_temp(temperature)
+
                     try:
                         parsed, completion = await self._parse_completion(
                             messages,
@@ -161,28 +214,23 @@ class AsyncOperator:
                             retry_temperature,
                             logprobs,
                             top_logprobs,
+                            priority=priority,
                         )
 
                         output.result = parsed.result
 
                         # Check if retry was successful
                         if validator(output.result):
-                            logger.info(
-                                f"Validation passed on retry attempt {attempt + 1}"
-                            )
+                            succeeded = True
                             break
-                        else:
-                            logger.warning(
-                                f"Validation still failing after retry attempt {attempt + 1}"
-                            )
 
-                    except Exception as e:
+                    except LLMError as e:
                         logger.error(f"Retry attempt {attempt + 1} failed: {e}")
-                        # Continue to next retry attempt if this one fails
 
-            # Final check after all retries
-            if validator and not validator(output.result):
-                output.errors.append("Validation failed after all retry attempts")
+                if not succeeded:
+                    raise ValidationError(
+                        f"Validation failed after {max_validation_retries} retries"
+                    )
 
             if logprobs:
                 output.logprobs = OperatorUtils.extract_logprobs(completion)
@@ -194,7 +242,7 @@ class AsyncOperator:
 
             return output
 
+        except (PromptError, LLMError, ValidationError):
+            raise
         except Exception as e:
-            logger.error(f"AsyncTheTool failed: {e}")
-            output.errors.append(str(e))
-            return output
+            raise TextToolsError(f"Unexpected error in operator: {e}")

texttools/internals/exceptions.py

@@ -0,0 +1,28 @@
+class TextToolsError(Exception):
+    """Base exception for all TextTools errors."""
+
+    pass
+
+
+class PromptError(TextToolsError):
+    """Errors related to prompt loading and formatting."""
+
+    pass
+
+
+class LLMError(TextToolsError):
+    """Errors from LLM API calls."""
+
+    pass
+
+
+class ValidationError(TextToolsError):
+    """Errors from output validation."""
+
+    pass
+
+
+class ConfigurationError(TextToolsError):
+    """Errors from misconfiguration."""
+
+    pass

texttools/{tools/internals → internals}/models.py

@@ -8,9 +8,9 @@ class ToolOutput(BaseModel):
     result: Any = None
     logprobs: list[dict[str, Any]] = []
     analysis: str = ""
-    process: str = ""
+    process: str | None = None
     processed_at: datetime = datetime.now()
-    execution_time: float = -1.0
+    execution_time: float | None = None
     errors: list[str] = []
 
     def __repr__(self) -> str:

texttools/internals/prompt_loader.py

@@ -0,0 +1,108 @@
+from functools import lru_cache
+from pathlib import Path
+import yaml
+
+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 (`{input}`, plus any extra kwargs) into the templates.
+    """
+
+    MAIN_TEMPLATE = "main_template"
+    ANALYZE_TEMPLATE = "analyze_template"
+
+    @staticmethod
+    def _build_format_args(text: str, **extra_kwargs) -> dict[str, str]:
+        # Base formatting args
+        format_args = {"input": text}
+        # Merge extras
+        format_args.update(extra_kwargs)
+        return format_args
+
+    # Use lru_cache to load each file once
+    @lru_cache(maxsize=32)
+    def _load_templates(self, prompt_file: str, mode: str | None) -> dict[str, str]:
+        """
+        Loads prompt templates from YAML file with optional mode selection.
+        """
+        try:
+            base_dir = Path(__file__).parent.parent / Path("prompts")
+            prompt_path = base_dir / prompt_file
+
+            if not prompt_path.exists():
+                raise PromptError(f"Prompt file not found: {prompt_file}")
+
+            data = yaml.safe_load(prompt_path.read_text(encoding="utf-8"))
+
+            if self.MAIN_TEMPLATE not in data:
+                raise PromptError(f"Missing 'main_template' in {prompt_file}")
+
+            if self.ANALYZE_TEMPLATE not in data:
+                raise PromptError(f"Missing 'analyze_template' in {prompt_file}")
+
+            if mode and mode not in data.get(self.MAIN_TEMPLATE, {}):
+                raise PromptError(f"Mode '{mode}' not found in {prompt_file}")
+
+            # Extract templates based on mode
+            main_template = (
+                data[self.MAIN_TEMPLATE][mode]
+                if mode and isinstance(data[self.MAIN_TEMPLATE], dict)
+                else data[self.MAIN_TEMPLATE]
+            )
+
+            analyze_template = (
+                data[self.ANALYZE_TEMPLATE][mode]
+                if mode and isinstance(data[self.ANALYZE_TEMPLATE], dict)
+                else data[self.ANALYZE_TEMPLATE]
+            )
+
+            if not main_template or not main_template.strip():
+                raise PromptError(
+                    f"Empty main_template in {prompt_file}"
+                    + (f" for mode '{mode}'" if mode else "")
+                )
+
+            if (
+                not analyze_template
+                or not analyze_template.strip()
+                or analyze_template.strip() in ["{analyze_template}", "{}"]
+            ):
+                raise PromptError(
+                    "analyze_template cannot be empty"
+                    + (f" for mode '{mode}'" if mode else "")
+                )
+
+            return {
+                self.MAIN_TEMPLATE: main_template,
+                self.ANALYZE_TEMPLATE: analyze_template,
+            }
+
+        except yaml.YAMLError as e:
+            raise PromptError(f"Invalid YAML in {prompt_file}: {e}")
+        except Exception as e:
+            raise PromptError(f"Failed to load prompt {prompt_file}: {e}")
+
+    def load(
+        self, prompt_file: str, text: str, mode: str, **extra_kwargs
+    ) -> dict[str, str]:
+        try:
+            template_configs = self._load_templates(prompt_file, mode)
+            format_args = self._build_format_args(text, **extra_kwargs)
+
+            # Inject variables inside each template
+            for key in template_configs.keys():
+                template_configs[key] = template_configs[key].format(**format_args)
+
+            return template_configs
+
+        except KeyError as e:
+            raise PromptError(f"Missing template variable: {e}")
+        except Exception as e:
+            raise PromptError(f"Failed to format prompt: {e}")