coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/formula_engine/steps/tax_lookup_step.py

@@ -0,0 +1,45 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tax lookup step implementation."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from ..tables.table_lookup import TableLookup
+from .base_step import Step
+
+if TYPE_CHECKING:
+    from ..execution.execution_context import ExecutionContext
+
+
+class TaxLookupStep(Step):
+    """Step for looking up values in tax tables."""
+
+    def execute(self, context: "ExecutionContext") -> dict[str, Decimal]:
+        """Execute tax lookup step.
+
+        Args:
+            context: Execution context
+
+        Returns:
+            Dictionary with tax calculation results
+        """
+        table_name = self.config.get("table", "")
+        input_var = self.config.get("input", "")
+        input_value = context.variables.get(input_var, Decimal("0"))
+
+        table_lookup = TableLookup(context.tax_tables, context.trace_callback)
+        return table_lookup.lookup(table_name, input_value)

coati_payroll/formula_engine/tables/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tax table and bracket calculation modules."""
+
+from .tax_table import TaxTable
+from .bracket_calculator import BracketCalculator
+from .table_lookup import TableLookup
+
+__all__ = [
+    "TaxTable",
+    "BracketCalculator",
+    "TableLookup",
+]

coati_payroll/formula_engine/tables/bracket_calculator.py

@@ -0,0 +1,51 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Bracket tax calculation."""
+
+from __future__ import annotations
+
+from decimal import Decimal, ROUND_HALF_UP
+from typing import Any
+
+from ..ast.type_converter import to_decimal
+
+
+class BracketCalculator:
+    """Calculates tax for a specific bracket."""
+
+    @staticmethod
+    def calculate(bracket: dict[str, Any], input_value: Decimal) -> dict[str, Decimal]:
+        """Calculate tax for a specific bracket.
+
+        Args:
+            bracket: Tax bracket definition
+            input_value: Value being taxed
+
+        Returns:
+            Dictionary with calculated tax components
+        """
+        rate = to_decimal(bracket.get("rate", 0))
+        fixed = to_decimal(bracket.get("fixed", 0))
+        over = to_decimal(bracket.get("over", 0))
+
+        # Calculate tax: fixed + (input_value - over) * rate
+        excess = max(input_value - over, Decimal("0"))
+        tax = fixed + (excess * rate)
+
+        return {
+            "tax": tax.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP),
+            "rate": rate,
+            "fixed": fixed,
+            "over": over,
+        }

coati_payroll/formula_engine/tables/table_lookup.py

@@ -0,0 +1,161 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Table lookup implementation."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, Callable
+
+from coati_payroll.i18n import _
+
+from ..ast.type_converter import to_decimal
+from ..exceptions import CalculationError
+from .bracket_calculator import BracketCalculator
+
+
+class TableLookup:
+    """Handles lookups in tax tables."""
+
+    def __init__(self, tax_tables: dict[str, Any], trace_callback: Callable[[str], None] | None = None):
+        """Initialize table lookup.
+
+        Args:
+            tax_tables: Dictionary of tax table names to table definitions
+            trace_callback: Optional callback for trace logging
+        """
+        self.tax_tables = tax_tables
+        self.trace_callback = trace_callback or (lambda _: None)
+
+    def lookup(self, table_name: str, input_value: Decimal) -> dict[str, Decimal]:
+        """Look up tax bracket in a tax table.
+
+        Args:
+            table_name: Name of the tax table
+            input_value: Value to look up
+
+        Returns:
+            Dictionary with 'tax', 'rate', 'fixed', 'over' values
+
+        Raises:
+            CalculationError: If table not found or lookup fails
+        """
+        if table_name not in self.tax_tables:
+            raise CalculationError(f"Tax table '{table_name}' not found")
+
+        table = self.tax_tables[table_name]
+        if not isinstance(table, list):
+            raise CalculationError(f"Tax table '{table_name}' must be a list")
+
+        if not table:
+            # Defensive: empty table
+            self.trace_callback(
+                _("Advertencia: tabla de impuestos '%(table)s' está vacía, devolviendo ceros") % {"table": table_name}
+            )
+            return {
+                "tax": Decimal("0"),
+                "rate": Decimal("0"),
+                "fixed": Decimal("0"),
+                "over": Decimal("0"),
+            }
+
+        self.trace_callback(
+            _("Buscando tabla de impuestos '%(table)s' con valor %(value)s; brackets=%(count)s")
+            % {"table": table_name, "value": input_value, "count": len(table)}
+        )
+
+        # Defensive: Sort brackets by min value if not already sorted
+        try:
+            sorted_table = sorted(table, key=lambda b: to_decimal(b.get("min", 0)))
+            if sorted_table != table:
+                self.trace_callback(
+                    _("Advertencia: tabla '%(table)s' no estaba ordenada, ordenando automáticamente")
+                    % {"table": table_name}
+                )
+                table = sorted_table
+        except Exception as e:
+            self.trace_callback(
+                _("Advertencia: no se pudo ordenar la tabla '%(table)s': %(error)s")
+                % {"table": table_name, "error": str(e)}
+            )
+
+        # Find the applicable bracket
+        matched_brackets = []
+        for i, bracket in enumerate(table):
+            try:
+                min_val = to_decimal(bracket.get("min", 0))
+                max_val = bracket.get("max")
+
+                if max_val is None:
+                    # Open-ended bracket (highest tier)
+                    if input_value >= min_val:
+                        matched_brackets.append((i, bracket, min_val, None))
+                else:
+                    max_val = to_decimal(max_val)
+                    # Defensive: validate bracket range
+                    if max_val < min_val:
+                        msg = _("Advertencia: tramo %(index)s de tabla '%(table)s' tiene max < min, omitiendo")
+                        self.trace_callback(msg % {"index": i, "table": table_name})
+                        continue
+
+                    if min_val <= input_value <= max_val:
+                        matched_brackets.append((i, bracket, min_val, max_val))
+            except Exception as e:
+                # Defensive: skip invalid brackets
+                self.trace_callback(
+                    _("Advertencia: error procesando tramo %(index)s de tabla '%(table)s': %(error)s")
+                    % {"index": i, "table": table_name, "error": str(e)}
+                )
+                continue
+
+        # Handle multiple matches (overlaps) - use the first valid match
+        if matched_brackets:
+            if len(matched_brackets) > 1:
+                # Multiple brackets match - this indicates an overlap
+                self.trace_callback(
+                    _(
+                        "ADVERTENCIA CRÍTICA: múltiples tramos coinciden para valor %(value)s en tabla '%(table)s'. "
+                        "Esto indica solapamiento. Usando el primer tramo encontrado."
+                    )
+                    % {"value": input_value, "table": table_name}
+                )
+
+            i, bracket, min_val, max_val = matched_brackets[0]
+            result = BracketCalculator.calculate(bracket, input_value)
+            if max_val is None:
+                self.trace_callback(
+                    _("Aplicando tramo abierto desde %(min)s para valor %(value)s -> %(result)s")
+                    % {"min": min_val, "value": input_value, "result": result}
+                )
+            else:
+                self.trace_callback(
+                    _("Aplicando tramo %(min)s - %(max)s para valor %(value)s -> %(result)s")
+                    % {"min": min_val, "max": max_val, "value": input_value, "result": result}
+                )
+            return result
+
+        # If no bracket found, return zeros
+        self.trace_callback(
+            _(
+                "No se encontró tramo para valor %(value)s en tabla '%(table)s', devolviendo ceros. "
+                "Esto puede indicar un gap en la configuración de la tabla."
+            )
+            % {"value": input_value, "table": table_name}
+        )
+        return {
+            "tax": Decimal("0"),
+            "rate": Decimal("0"),
+            "fixed": Decimal("0"),
+            "over": Decimal("0"),
+        }

coati_payroll/formula_engine/tables/tax_table.py

@@ -0,0 +1,32 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tax table data structure."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TaxTable:
+    """Represents a tax table with brackets."""
+
+    def __init__(self, name: str, brackets: list[dict[str, Any]]):
+        """Initialize tax table.
+
+        Args:
+            name: Table name
+            brackets: List of bracket dictionaries
+        """
+        self.name = name
+        self.brackets = brackets

coati_payroll/formula_engine/validation/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Validation modules for formula engine."""
+
+from .schema_validator import SchemaValidator
+from .tax_table_validator import TaxTableValidator
+from .security_validator import SecurityValidator
+
+__all__ = [
+    "SchemaValidator",
+    "TaxTableValidator",
+    "SecurityValidator",
+]

coati_payroll/formula_engine/validation/schema_validator.py

@@ -0,0 +1,37 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Schema validation for formula engine."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from coati_payroll.schema_validator import validate_schema
+
+from ..exceptions import ValidationError
+
+
+class SchemaValidator:
+    """Validates formula engine schemas."""
+
+    def validate(self, schema: dict[str, Any]) -> None:
+        """Validate a calculation schema.
+
+        Args:
+            schema: JSON schema to validate
+
+        Raises:
+            ValidationError: If schema is invalid
+        """
+        validate_schema(schema, error_class=ValidationError)

coati_payroll/formula_engine/validation/security_validator.py

@@ -0,0 +1,52 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Security validation for AST nodes."""
+
+from __future__ import annotations
+
+import ast
+
+from ..ast.safe_operators import ALLOWED_AST_TYPES, SAFE_FUNCTIONS
+from ..exceptions import CalculationError
+
+
+class SecurityValidator:
+    """Validates AST security for expression evaluation."""
+
+    @staticmethod
+    def validate_ast_security(node: ast.AST) -> None:
+        """Validate that an AST node only contains safe operations.
+
+        Args:
+            node: AST node to validate
+
+        Raises:
+            CalculationError: If unsafe operations are detected
+        """
+        # Validate all nodes in the tree in a single pass
+        for child in ast.walk(node):
+            if not isinstance(child, ALLOWED_AST_TYPES):
+                raise CalculationError(
+                    f"Unsafe operation detected: {child.__class__.__name__}. "
+                    "Only basic arithmetic and safe functions are allowed."
+                )
+            # Validate function calls
+            if isinstance(child, ast.Call):
+                if not isinstance(child.func, ast.Name):
+                    raise CalculationError("Only named functions are allowed")
+                if child.func.id not in SAFE_FUNCTIONS:
+                    raise CalculationError(
+                        f"Function '{child.func.id}' is not allowed. "
+                        f"Allowed functions: {', '.join(SAFE_FUNCTIONS.keys())}"
+                    )

coati_payroll/formula_engine/validation/tax_table_validator.py

@@ -0,0 +1,205 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tax table validation for formula engine."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+from ..ast.type_converter import to_decimal
+from ..exceptions import ValidationError
+
+
+class TaxTableValidator:
+    """Validates tax tables for integrity."""
+
+    def __init__(self, strict_mode: bool = False):
+        """Initialize validator.
+
+        Args:
+            strict_mode: If True, warnings are treated as errors
+        """
+        self.strict_mode = strict_mode
+
+    def validate_table(self, table_name: str, table: list[dict[str, Any]]) -> tuple[list[str], list[str]]:
+        """Validate a tax table for critical integrity issues.
+
+        Args:
+            table_name: Name of the tax table being validated
+            table: List of tax bracket dictionaries
+
+        Returns:
+            Tuple of (errors, warnings) lists
+
+        Raises:
+            ValidationError: If table has critical errors
+        """
+        errors: list[str] = []
+        warnings: list[str] = []
+
+        if not table:
+            raise ValidationError(
+                f"La tabla de impuestos '{table_name}' está vacía. " "Debe contener al menos un tramo."
+            )
+
+        # Validate each bracket structure
+        for i, bracket in enumerate(table):
+            if not isinstance(bracket, dict):
+                raise ValidationError(f"El tramo {i} de la tabla '{table_name}' debe ser un diccionario")
+
+            min_val = bracket.get("min")
+            max_val = bracket.get("max")
+
+            if min_val is None:
+                raise ValidationError(f"El tramo {i} de la tabla '{table_name}' debe tener un valor 'min'")
+
+            try:
+                min_decimal = to_decimal(min_val)
+            except ValidationError as e:
+                raise ValidationError(
+                    f"El valor 'min' del tramo {i} de la tabla '{table_name}' es inválido: {e}"
+                ) from e
+
+            if max_val is not None:
+                try:
+                    max_decimal = to_decimal(max_val)
+                    if max_decimal < min_decimal:
+                        raise ValidationError(
+                            f"El tramo {i} de la tabla '{table_name}' tiene 'max' ({max_val}) "
+                            f"menor que 'min' ({min_val}). El límite superior debe ser mayor o igual al inferior."
+                        )
+                except ValidationError as e:
+                    raise ValidationError(
+                        f"El valor 'max' del tramo {i} de la tabla '{table_name}' es inválido: {e}"
+                    ) from e
+
+            # Validate fixed and over values
+            fixed = bracket.get("fixed", 0)
+            over = bracket.get("over", 0)
+
+            try:
+                fixed_decimal = to_decimal(fixed)
+                over_decimal = to_decimal(over)
+
+                if fixed_decimal < 0:
+                    errors.append(
+                        f"El tramo {i} de la tabla '{table_name}' tiene 'fixed' negativo ({fixed}). "
+                        "El valor 'fixed' no puede ser negativo."
+                    )
+
+                if over_decimal < 0:
+                    errors.append(
+                        f"El tramo {i} de la tabla '{table_name}' tiene 'over' negativo ({over}). "
+                        "El valor 'over' no puede ser negativo."
+                    )
+
+                if over_decimal > min_decimal:
+                    errors.append(
+                        f"El tramo {i} de la tabla '{table_name}' tiene 'over' ({over}) mayor que 'min' ({min_val}). "
+                        "El valor 'over' debe ser menor o igual a 'min'."
+                    )
+            except ValidationError as e:
+                errors.append(f"Valores inválidos en tramo {i} de tabla '{table_name}': {e}")
+
+        # Validate ordering and overlaps
+        for i in range(len(table) - 1):
+            current = table[i]
+            next_bracket = table[i + 1]
+
+            current_min = to_decimal(current.get("min", 0))
+            current_max = current.get("max")
+            next_min = to_decimal(next_bracket.get("min", 0))
+
+            # Check ordering: next bracket's min should be >= current bracket's min
+            if next_min < current_min:
+                raise ValidationError(
+                    f"La tabla de impuestos '{table_name}' no está ordenada. "
+                    f"El tramo {i + 1} tiene 'min'={next_min} que es menor que el 'min'={current_min} "
+                    f"del tramo {i}. Los tramos deben estar ordenados de menor a mayor."
+                )
+
+            # Check for overlaps and gaps
+            if current_max is not None:
+                current_max_decimal = to_decimal(current_max)
+
+                # Check for overlap or gap
+                if current_max_decimal > next_min:
+                    # Overlap detected
+                    overlap_start = next_min
+                    overlap_end = current_max_decimal
+                    raise ValidationError(
+                        f"La tabla de impuestos '{table_name}' tiene tramos solapados. "
+                        f"Los tramos {i} y {i + 1} se solapan en el rango [{overlap_start}, {overlap_end}]. "
+                        f"El tramo {i} termina en {current_max_decimal} y el tramo {i + 1} comienza en {next_min}. "
+                        "Los tramos no deben solaparse."
+                    )
+                elif current_max_decimal < next_min:
+                    # Check for significant gap
+                    gap_size = next_min - current_max_decimal
+                    tolerance = Decimal("0.01")  # Allow 1 cent gap for rounding
+
+                    if gap_size > tolerance:
+                        warnings.append(
+                            f"La tabla de impuestos '{table_name}' tiene un gap significativo entre "
+                            f"los tramos {i} y {i + 1}. "
+                            f"El tramo {i} termina en {current_max_decimal} y el tramo {i + 1} comienza en {next_min}. "
+                            f"Hay un gap de {gap_size} que no está cubierto por ningún tramo."
+                        )
+            else:
+                # Current bracket is open-ended, but there's a next bracket - this is an error
+                raise ValidationError(
+                    f"La tabla de impuestos '{table_name}' tiene un tramo abierto (sin 'max') en la posición {i}, "
+                    f"pero hay tramos adicionales después. El tramo abierto debe ser el último de la tabla."
+                )
+
+        # Validate that only the last bracket can be open-ended
+        for i in range(len(table) - 1):
+            if table[i].get("max") is None:
+                raise ValidationError(
+                    f"La tabla de impuestos '{table_name}' tiene un tramo abierto (sin 'max') en la posición {i}, "
+                    "pero no es el último tramo. Solo el último tramo puede ser abierto."
+                )
+
+        # Raise errors if any critical errors found
+        if errors:
+            raise ValidationError(f"Errores críticos en la tabla de impuestos '{table_name}': {'; '.join(errors)}")
+
+        return errors, warnings
+
+    def validate_all(self, tax_tables: dict[str, Any]) -> list[str]:
+        """Validate all tax tables in the schema.
+
+        Args:
+            tax_tables: Dictionary of tax table names to table definitions
+
+        Returns:
+            List of warning messages (non-critical issues)
+
+        Raises:
+            ValidationError: If any tax table has critical validation errors
+        """
+        if not isinstance(tax_tables, dict):
+            raise ValidationError("'tax_tables' debe ser un diccionario")
+
+        all_warnings: list[str] = []
+
+        for table_name, table in tax_tables.items():
+            if not isinstance(table, list):
+                raise ValidationError(f"La tabla de impuestos '{table_name}' debe ser una lista de tramos")
+
+            errors, warnings = self.validate_table(table_name, table)
+            all_warnings.extend(warnings)
+
+        return all_warnings