unique_toolkit 1.42.9__py3-none-any.whl → 1.43.0__py3-none-any.whl

unique_toolkit/_common/experimental/write_up_agent/__init__.py

@@ -0,0 +1,22 @@
+"""
+Write-Up Agent: Template-driven DataFrame summarization and report generation.
+"""
+
+from unique_toolkit._common.experimental.write_up_agent.agent import WriteUpAgent
+from unique_toolkit._common.experimental.write_up_agent.config import (
+    WriteUpAgentConfig,
+)
+from unique_toolkit._common.experimental.write_up_agent.schemas import (
+    GroupData,
+    ProcessedGroup,
+)
+
+__all__ = [
+    # Main agent
+    "WriteUpAgent",
+    # Configuration
+    "WriteUpAgentConfig",
+    # Data schemas
+    "GroupData",
+    "ProcessedGroup",
+]

unique_toolkit/_common/experimental/write_up_agent/agent.py

@@ -0,0 +1,170 @@
+"""
+Write-Up Agent - Main pipeline orchestrator.
+"""
+
+import logging
+
+import pandas as pd
+
+from unique_toolkit._common.experimental.write_up_agent.config import (
+    WriteUpAgentConfig,
+)
+from unique_toolkit._common.experimental.write_up_agent.schemas import GroupData
+from unique_toolkit._common.experimental.write_up_agent.services.dataframe_handler import (
+    DataFrameHandler,
+)
+from unique_toolkit._common.experimental.write_up_agent.services.dataframe_handler.exceptions import (
+    DataFrameGroupingError,
+    DataFrameHandlerError,
+    DataFrameProcessingError,
+    DataFrameValidationError,
+)
+from unique_toolkit._common.experimental.write_up_agent.services.generation_handler import (
+    GenerationHandler,
+    GenerationHandlerError,
+)
+from unique_toolkit._common.experimental.write_up_agent.services.template_handler import (
+    TemplateHandler,
+)
+from unique_toolkit._common.experimental.write_up_agent.services.template_handler.exceptions import (
+    ColumnExtractionError,
+    TemplateHandlerError,
+    TemplateParsingError,
+    TemplateRenderingError,
+    TemplateStructureError,
+)
+from unique_toolkit.language_model.service import LanguageModelService
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class WriteUpAgent:
+    """
+    Main pipeline orchestrator for DataFrame summarization.
+
+    Orchestrates the complete pipeline:
+    1. Extract template info (grouping + columns)
+    2. Validate DataFrame
+    3. Create groups
+    4. Render each group
+    5. Process with LLM
+    6. Return results
+    """
+
+    def __init__(self, config: WriteUpAgentConfig):
+        """
+        Initialize WriteUpAgent.
+
+        Args:
+            config: Configuration with template and settings
+        """
+        self._config = config
+        self._template_handler = TemplateHandler(config.template)
+        self._dataframe_handler = DataFrameHandler()
+
+        # Create generation handler with injected renderer
+        def renderer(group_data: GroupData) -> str:
+            return self._template_handler.render_group(group_data)
+
+        # TODO [UN-16142]: Find a better way to inject the renderer
+        self._generation_handler = GenerationHandler(
+            self._config.generation_handler_config, renderer
+        )
+
+    def process(self, df: pd.DataFrame, llm_service: LanguageModelService) -> str:
+        """
+        Execute complete pipeline and generate final report.
+
+        Args:
+            df: pandas DataFrame to process
+            llm_service: LanguageModelService to use for generating summaries
+
+        Returns:
+            Final markdown report as a single string with all groups processed
+
+        Raises:
+            Various handler exceptions if processing fails
+
+        Example:
+            >>> config = WriteUpAgentConfig(template="...", max_rows_per_group=10)
+            >>> agent = WriteUpAgent(config)
+            >>> report = agent.process(df)
+            >>> print(report)
+        """
+        # TODO [UN-16142]: Add error handling for each step separately
+        try:
+            # Step 1: Extract template structure
+            _LOGGER.info("Extracting template structure...")
+            grouping_column = self._template_handler.get_grouping_column()
+            selected_columns = self._template_handler.get_selected_columns()
+            _LOGGER.info(f"Detected grouping column: {grouping_column}")
+            _LOGGER.info(f"Detected data columns: {selected_columns}")
+
+            # Step 2: Validate DataFrame
+            _LOGGER.info("Validating DataFrame columns...")
+            self._dataframe_handler.validate_columns(
+                df, grouping_column, selected_columns
+            )
+
+            # Step 3: Create groups
+            _LOGGER.info("Creating groups from DataFrame...")
+            groups = self._dataframe_handler.create_groups(
+                df, grouping_column, selected_columns
+            )
+            _LOGGER.info(f"Created {len(groups)} groups")
+
+            # Step 4: Process groups with GenerationHandler
+            _LOGGER.info("Processing groups with GenerationHandler...")
+            processed_groups = self._generation_handler.process_groups(
+                groups, grouping_column, llm_service
+            )
+            _LOGGER.info(f"Generation complete for {len(processed_groups)} groups")
+
+            # Step 5: Render final report with LLM responses
+            _LOGGER.info("Rendering final report...")
+
+            final_report = self._template_handler.render_all_groups(processed_groups)
+
+            _LOGGER.info(f"Report generated ({len(final_report)} characters)")
+
+            return final_report
+
+        except TemplateParsingError as e:
+            _LOGGER.error(f"Template parsing failed: {e}")
+            raise
+
+        except TemplateStructureError as e:
+            _LOGGER.error(f"Template structure invalid: {e}")
+            raise
+
+        except ColumnExtractionError as e:
+            _LOGGER.error(f"Column extraction failed: {e}")
+            raise
+
+        except DataFrameValidationError as e:
+            _LOGGER.error(f"DataFrame validation failed: {e}")
+            raise
+
+        except DataFrameGroupingError as e:
+            _LOGGER.error(f"DataFrame grouping failed: {e}")
+            raise
+
+        except DataFrameProcessingError as e:
+            _LOGGER.error(f"DataFrame processing failed: {e}")
+            raise
+
+        except GenerationHandlerError as e:
+            _LOGGER.error(f"Generation failed: {e}")
+            raise
+
+        except TemplateRenderingError as e:
+            _LOGGER.error(f"Final rendering failed: {e}")
+            raise
+
+        except (TemplateHandlerError, DataFrameHandlerError) as e:
+            _LOGGER.error(f"Handler error: {e}")
+            raise
+
+        except Exception as e:
+            _LOGGER.error(f"Unexpected error: {e}", exc_info=True)
+            raise

unique_toolkit/_common/experimental/write_up_agent/config.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel, Field, field_validator
+
+from unique_toolkit._common.experimental.write_up_agent.services.generation_handler.config import (
+    GenerationHandlerConfig,
+)
+from unique_toolkit._common.experimental.write_up_agent.services.template_handler import (
+    default_jinja_template_loader,
+)
+from unique_toolkit._common.pydantic_helpers import get_configuration_dict
+
+
+class WriteUpAgentConfig(BaseModel):
+    """Configuration for the Write-Up Agent that generates summaries from DataFrame data.
+
+    The agent uses a Jinja template as the single source of truth for data structure.
+    The template is parsed to automatically detect grouping columns and data references.
+    """
+
+    model_config = get_configuration_dict()
+
+    # Template Configuration (single source of truth)
+    template: str = Field(
+        default_factory=default_jinja_template_loader,
+        description=(
+            "Jinja template string that defines the structure of the summary. "
+            "The template is parsed to automatically detect grouping columns and data references. "
+            "If not provided, loads the default Q&A template. "
+            "Example: '{% for g in groups %}## {{ g.section }}{% endfor %}'"
+        ),
+    )
+
+    generation_handler_config: GenerationHandlerConfig = Field(
+        default_factory=GenerationHandlerConfig,
+        description="Configuration for the generation handler.",
+    )
+
+    @field_validator("template")
+    @classmethod
+    def validate_template_not_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Template must not be empty")
+        return v

unique_toolkit/_common/experimental/write_up_agent/examples/data.csv

@@ -0,0 +1,13 @@
+section,question,answer
+Introduction,What is the Write-Up Agent?,The Write-Up Agent is a tool that automatically generates summaries from structured DataFrame data using LLM technology.
+Introduction,Who should use this tool?,Data scientists and analysts who need to convert tabular data into readable reports.
+Introduction,What are the key benefits?,Automated report generation with customizable templates and intelligent summarization.
+Methods,How does the agent process data?,The agent groups data by sections and generates summaries for each group using LLM calls with adaptive batching.
+Methods,What is adaptive batching?,A technique that splits large groups into smaller batches to fit within token limits while maintaining context.
+Methods,Can I customize the output format?,Yes! You can provide custom Jinja templates to control the structure and style of the generated report.
+Results,What level of accuracy can I expect?,The agent leverages state-of-the-art LLMs to produce accurate and contextually relevant summaries.
+Results,How fast is the processing?,Processing speed depends on the LLM provider and the size of your dataset. Batching helps optimize performance.
+Results,Can it handle large datasets?,Yes! The agent automatically batches large groups to handle datasets of any size efficiently.
+Conclusion,Is this production-ready?,Yes! The agent includes robust error handling and type-safe operations using Pydantic schemas.
+Conclusion,Where can I find more examples?,Check the examples directory for additional use cases and custom template examples.
+

unique_toolkit/_common/experimental/write_up_agent/examples/example_usage.py

@@ -0,0 +1,78 @@
+"""
+Example: Using the Write-Up Agent to generate summaries from DataFrame data.
+"""
+
+# TODO [UN-16142]: Add example usage in tutorial instead of here
+
+import logging
+from pathlib import Path
+
+import pandas as pd
+
+from unique_toolkit._common.experimental.write_up_agent import (
+    WriteUpAgent,
+    WriteUpAgentConfig,
+)
+from unique_toolkit._common.experimental.write_up_agent.services.generation_handler.config import (
+    GenerationHandlerConfig,
+)
+from unique_toolkit.app.unique_settings import UniqueSettings
+from unique_toolkit.language_model.service import LanguageModelService
+
+logging.basicConfig(level=logging.DEBUG)
+
+# Setup paths
+current_dir = Path(__file__).parent
+env_path = current_dir / "unique.env"
+data_path = current_dir / "data.csv"
+
+# Initialize SDK with your API keys
+_SETTINGS = UniqueSettings.from_env(env_file=env_path)
+_SETTINGS.init_sdk()
+
+# Configure the Write-Up Agent
+# Using default configuration which expects: section, question, answer columns
+write_up_agent_config = WriteUpAgentConfig(
+    generation_handler_config=GenerationHandlerConfig(
+        # Optional: Customize generation settings
+        # max_rows_per_batch=20,  # Max rows per batch (default: 20)
+        # max_tokens_per_batch=4000,  # Max tokens per batch (default: 4000)
+        # common_instruction="You are a technical writer...",  # Custom system prompt
+        # group_specific_instructions={
+        #     # IMPORTANT: Both column and value must be in snake_case
+        #     # DataFrame: Section="Introduction" → Key: "section:introduction"
+        #     "section:introduction": "Be welcoming and engaging",
+        #     "section:methods": "Be precise and technical"
+        # }
+    )
+)
+
+# Initialize the agent with LLM service
+write_up_agent = WriteUpAgent(
+    config=write_up_agent_config,
+)
+
+# Load your DataFrame
+# IMPORTANT: DataFrame must have columns: section, question, answer (otherwise adapt the template)
+df = pd.read_csv(data_path)
+
+print(f"Processing {len(df)} rows across {df['section'].nunique()} sections...")
+print(f"Columns in DataFrame: {list(df.columns)}")
+print()
+
+llm_service = LanguageModelService.from_settings(_SETTINGS)
+
+# Generate the report
+report = write_up_agent.process(df, llm_service=llm_service)
+
+# Display the result
+print("=" * 80)
+print("GENERATED REPORT")
+print("=" * 80)
+print(report)
+
+# Optional: Save to file
+output_path = current_dir / "report.md"
+output_path.write_text(report)
+print()
+print(f"Report saved to: {output_path}")

unique_toolkit/_common/experimental/write_up_agent/examples/report.md

@@ -0,0 +1,154 @@
+
+# Personal
+
+
+
+📌 **Core Information**  
+- **Name**: Purushottam Sharma  
+- **Prename(s)**: Purushottam  
+- **Date of Birth**: 03.04.1986  
+- **Place of Birth**: Mumbai, India  
+- **Verification**: All personal details are confirmed via a valid Indian passport (DS435645G04), issued on 05.10.2021 and expiring on 05.10.2031. The document verifies name, date of birth, nationality, and place of origin. No additional documentation is required.  
+
+📌 **Marital Status**  
+- **Status**: Unmarried  
+- **Verification**: No evidence of marriage (e.g., marriage certificate, joint tax filings, or public records) was found. No indirect indicators, such as cohabitation records or joint assets, suggest a marital relationship. The absence of evidence over time supports the conclusion of being unmarried.  
+
+📌 **Nationality**  
+- **Nationality**: Indian (IND)  
+- **Verification**: The Indian passport (DS435645G04) serves as the primary proof of nationality. No evidence of dual or additional citizenships was identified.  
+
+📌 **Political Exposure**  
+- No indications of managerial roles, political activity, or Politically Exposed Person (PEP) status were found in any category.  
+
+All personal details are verified, complete, and supported by official documentation.
+
+
+---
+
+
+# Employment
+
+
+
+Mr. Purushottam R. Sharma’s employment history and income have been thoroughly analyzed, confirming a credible and realistic career trajectory with appropriate compensation for his current role as Chief Investment Officer (CIO) at Al Noor Capital Investments in Dubai’s DIFC.
+
+### Career Trajectory and Compensation
+- **Career Progression**: Mr. Sharma advanced from Financial Analyst (2005–2010) to Portfolio Manager (2010–2020) at Morgan Stanley, followed by his current role as CIO (2025–present). His career reflects steady growth in responsibility and compensation.
+- **Current Compensation**: His annual gross income of AED 700,000 includes a basic salary (AED 540,000), housing allowance (AED 100,000), transport (AED 24,000), and other benefits (AED 36,000). This package aligns with DIFC market benchmarks for mid-tier CIO roles, which range from AED 650,000 to 1,000,000 annually.
+- **Inflation Adjustment**: The current salary is consistent with inflation-adjusted benchmarks for his career progression, reflecting a 110% increase from his estimated entry-level salary in 2005 and a slight increase from his mid-career earnings as a Portfolio Manager.
+
+### Contextual Factors Influencing Compensation
+1. **Company Size**: Al Noor Capital Investments is a mid-sized, boutique asset management firm, which typically offers lower compensation compared to larger, global institutions.
+2. **Tenure in Role**: Mr. Sharma’s appointment as CIO began in January 2025, and his salary likely reflects an entry-level package for the position, with potential for future increases based on performance.
+3. **Marital Status and Lifestyle**: As a single individual with no dependents, Mr. Sharma’s cost of living is lower, reducing the need for additional family-related benefits. His expense-to-income ratio is approximately 43%, allowing for a high savings rate of ~57%.
+4. **Employment Gap (2020–2025)**: A five-year gap in his career may have influenced his initial compensation upon re-entering the workforce, though no red flags or misconduct were identified during this period.
+
+### Cost of Living and Savings
+- **Living Costs**: Estimated annual expenses in Dubai range from AED 240,000 to 300,000, including housing, transportation, utilities, and leisure. Mr. Sharma’s housing and transport allowances adequately cover these costs.
+- **Savings Capacity**: With zero personal income tax in the UAE and a high savings rate, Mr. Sharma’s disposable income (~AED 400,000 annually) supports a comfortable lifestyle and significant financial security.
+
+### Verification and Credibility
+- **Income Verification**: Employment certificates, payslips, payroll summaries, and tax residency certificates have been provided and verified.
+- **Market Alignment**: The salary is within 15–20% of the median for similar roles in the DIFC, indicating alignment with market standards.
+- **No Red Flags**: No evidence of political exposure, financial stress, or discrepancies in documentation was found.
+
+### Conclusion
+Mr. Sharma’s income is realistic and justified based on his career progression, the size and market position of his current employer, and his personal circumstances. The compensation package is competitive within the DIFC market and supports a high standard of living with substantial savings potential. The five-year employment gap (2020–2025) may have influenced his initial salary, but no further adjustments or concerns are warranted.
+
+
+---
+
+
+# Inheritance And Gifts
+
+
+
+Mr. Purushottam R. Sharma received a single inheritance of USD 15,000,000 from his father, Mr. Rajendra V. Sharma, as the sole beneficiary under a Last Will and Testament dated March 12, 2003. The inheritance was distributed on June 30, 2005, following probate approval in Marin County, California (Case No. PR-2005-11876). The distribution was supported by primary legal documents, including the will, probate court order, executor’s certificate of distribution, and bank transfer records.
+
+### Composition of the Inheritance
+The inheritance, totaling USD 15,000,000, was derived from the following assets:
+- **Cash and Certificates of Deposit (CDs):** $6,200,000
+- **Marketable Securities:** $7,800,000 (liquidated prior to distribution)
+- **Net Proceeds from Real Property Sales:** $2,100,000
+- **Life Insurance Proceeds:** $450,000 (payable to the estate)
+
+After deducting debts, taxes, and administrative costs totaling $1,550,000, the net distributable estate amounted to $15,000,000.
+
+### Relationship and Reason for Inheritance
+The gifter, Mr. Rajendra V. Sharma, was the father of the beneficiary, Mr. Purushottam R. Sharma. This relationship is explicitly stated in the will and confirmed by probate documents. The inheritance was part of a planned familial wealth transfer, with no additional conditions or motives beyond standard estate planning.
+
+### Proof of Inheritance
+The inheritance is fully documented and legally validated through:
+- **Last Will and Testament (2003):** Declares Purushottam as the sole beneficiary.
+- **Probate Court Order (February 14, 2005):** Confirms the will’s validity and authorizes distribution.
+- **Executor’s Certificate of Distribution (June 30, 2005):** Confirms the transfer of $15,000,000.
+- **Bank Wire Records:** Document the transfer from Pacific Heritage Bank to Purushottam’s account.
+
+### Source of Wealth of the Gifter
+While the composition of Mr. Rajendra V. Sharma’s estate is detailed, the origin of his wealth (e.g., profession, business activities) is not documented. The estate’s composition suggests long-term wealth accumulation through investments, real estate, and insurance, typical of affluent individuals in California.
+
+### Summary
+- **Total Inherited Wealth:** USD 15,000,000
+- **Source:** Estate of Mr. Rajendra V. Sharma
+- **Legal Basis:** Court-supervised probate distribution
+- **Proof Level:** Comprehensive primary documentation
+No other gifts or inheritances are recorded for Mr. Purushottam R. Sharma. The inheritance process was legally robust, with all required documentation in place.
+
+
+---
+
+
+# Inheritance And Gifts/ General Wealth Analysis
+
+
+
+The analysis of Mr. Purushottam R. Sharma’s wealth trajectory confirms the plausibility of his reported net worth of approximately USD 100 million by 2025, based on a verified inheritance of USD 15 million in 2005, a 10% annual return, and the tax-free environment of Dubai. The following key factors contribute to this conclusion:
+
+### Wealth Growth Analysis
+1. **Initial Capital and Investment Returns**:
+   - Starting with a USD 15 million inheritance in 2005, the portfolio grew at an average annual return of 10%, compounded over 20 years.
+   - The tax-free environment in Dubai allowed for uninterrupted compounding, resulting in a projected portfolio value of ~USD 100.9 million by 2025.
+
+2. **Lifestyle and Expenditures**:
+   - Annual luxury lifestyle expenses are estimated at ~USD 700,000 (~AED 2.57 million), covering a high-end villa, private education, travel, staff, and other costs.
+   - Even with these withdrawals, the portfolio is projected to grow significantly, reaching ~USD 90–95 million after 20 years of spending.
+
+3. **Investment Strategy**:
+   - A diversified portfolio with allocations to global equities, ETFs, private equity, real estate, and cash has been assumed, yielding an average return of 10% annually.
+   - USD-denominated investments provide protection against inflation and currency fluctuations.
+
+### Key Factors Supporting Wealth Accumulation
+1. **Tax-Free Environment**:
+   - Dubai’s lack of income, capital gains, and wealth taxes ensures full compounding of returns without tax drag.
+2. **Disciplined Spending**:
+   - Annual withdrawals represent a small percentage of the portfolio, ensuring sustainable growth.
+3. **Professional Management**:
+   - Low fees and strategic reinvestment of returns contribute to long-term wealth preservation.
+4. **Favorable Economic Conditions**:
+   - Access to global markets, stable financial infrastructure, and a long-term residency in Dubai enhance wealth-building opportunities.
+
+### Wealth Composition (2025, Inflation-Adjusted)
+- **Global Equities & ETFs**: ~USD 60M
+- **Private Investments**: ~USD 20M
+- **Real Estate**: ~USD 12M
+- **Cash & Reserves**: ~USD 5M
+- **Luxury Assets (e.g., art, yachts)**: ~USD 3M
+- **Total Net Worth**: ~USD 100M
+
+### Strategic Recommendations
+1. **Maintain Tax Efficiency**:
+   - Continue leveraging Dubai’s tax-free environment to maximize compounding and preserve wealth.
+2. **Diversify Investments**:
+   - Ensure a balanced portfolio across asset classes to mitigate risks and sustain returns.
+3. **Monitor Lifestyle Spending**:
+   - Keep annual expenditures within sustainable limits to avoid unnecessary drawdowns.
+4. **Leverage Professional Management**:
+   - Engage experienced financial advisors to optimize returns and minimize fees.
+
+### Conclusion
+Mr. Sharma’s financial profile is credible and aligns with the wealth accumulation patterns of ultra-high-net-worth individuals in tax-efficient jurisdictions. His net worth of ~USD 100 million is realistic, supported by verified inheritance, disciplined investment strategies, and the favorable fiscal environment of Dubai. With continued prudent management, his wealth is sustainable for generations.
+
+
+---
+

unique_toolkit/_common/experimental/write_up_agent/schemas.py

@@ -0,0 +1,36 @@
+"""Data schemas for the Write-Up Agent."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class GroupData(BaseModel):
+    """
+    Represents a group of rows from a DataFrame.
+
+    This is the core data structure passed between handlers in the pipeline.
+    """
+
+    group_key: str = Field(
+        ...,
+        description="The value of the grouping column for this group (e.g., 'Introduction', 'Methods')",
+    )
+
+    rows: list[dict[str, Any]] = Field(
+        ...,
+        description="List of row dictionaries containing the selected columns for this group",
+    )
+
+
+class ProcessedGroup(GroupData):
+    """
+    Represents a group after LLM processing.
+
+    Extends GroupData with the LLM-generated response.
+    """
+
+    llm_response: str = Field(
+        ...,
+        description="The LLM-generated summary/output for this group",
+    )

unique_toolkit/_common/experimental/write_up_agent/services/__init__.py

@@ -0,0 +1,13 @@
+"""Services for the write-up agent pipeline."""
+
+from unique_toolkit._common.experimental.write_up_agent.services.dataframe_handler import (
+    DataFrameHandler,
+)
+from unique_toolkit._common.experimental.write_up_agent.services.template_handler import (
+    TemplateHandler,
+)
+
+__all__ = [
+    "DataFrameHandler",
+    "TemplateHandler",
+]

unique_toolkit/_common/experimental/write_up_agent/services/dataframe_handler/__init__.py

@@ -0,0 +1,19 @@
+"""DataFrame handler module."""
+
+from unique_toolkit._common.experimental.write_up_agent.services.dataframe_handler.exceptions import (
+    DataFrameGroupingError,
+    DataFrameHandlerError,
+    DataFrameProcessingError,
+    DataFrameValidationError,
+)
+from unique_toolkit._common.experimental.write_up_agent.services.dataframe_handler.service import (
+    DataFrameHandler,
+)
+
+__all__ = [
+    "DataFrameHandler",
+    "DataFrameHandlerError",
+    "DataFrameValidationError",
+    "DataFrameGroupingError",
+    "DataFrameProcessingError",
+]

unique_toolkit/_common/experimental/write_up_agent/services/dataframe_handler/exceptions.py

@@ -0,0 +1,29 @@
+"""Exceptions for DataFrame handler operations."""
+
+
+class DataFrameHandlerError(Exception):
+    """Base exception for all DataFrame handler errors."""
+
+    pass
+
+
+class DataFrameValidationError(DataFrameHandlerError):
+    """Raised when DataFrame validation fails (e.g., missing columns)."""
+
+    def __init__(self, message: str, missing_columns: list[str] | None = None):
+        super().__init__(message)
+        self.missing_columns = missing_columns or []
+
+
+class DataFrameGroupingError(DataFrameHandlerError):
+    """Raised when DataFrame grouping operation fails."""
+
+    def __init__(self, message: str, grouping_column: str | None = None):
+        super().__init__(message)
+        self.grouping_column = grouping_column
+
+
+class DataFrameProcessingError(DataFrameHandlerError):
+    """Raised when general DataFrame processing fails."""
+
+    pass