coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/formula_engine/novelty_codes.py

@@ -0,0 +1,206 @@
+# 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.
+"""Mapping of novelty codes to their calculation behavior.
+
+This module defines the mapping between novelty codes and their
+calculation behavior (perception/deduction, gravable, etc.).
+"""
+
+NOVELTY_CODES = {
+    "HORAS_EXTRA": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Horas extra trabajadas",
+    },
+    "HORAS_EXTRA_DOBLES": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Horas extra dobles (feriados/domingos)",
+    },
+    "AUSENCIA": {
+        "tipo": "deduccion",
+        "gravable": False,
+        "descripcion": "Ausencia no justificada",
+    },
+    "INCAPACIDAD": {
+        "tipo": "deduccion",
+        "gravable": False,
+        "descripcion": "Incapacidad médica",
+    },
+    "COMISION": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Comisiones por ventas",
+    },
+    "BONIFICACION": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Bonificación",
+    },
+    "VIATICO": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Viáticos",
+    },
+    "VACACIONES": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Pago de vacaciones",
+    },
+    "ADELANTO": {
+        "tipo": "deduccion",
+        "gravable": False,
+        "descripcion": "Adelanto de salario",
+    },
+    "PRESTAMO": {
+        "tipo": "deduccion",
+        "gravable": False,
+        "descripcion": "Cuota de préstamo",
+    },
+    # A. Compensación Base y Directa
+    "BONO_OBJETIVOS": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Bono por cumplimiento de objetivos",
+    },
+    "BONO_ANUAL": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Bono anual o trimestral",
+    },
+    "PLUS_PELIGROSIDAD": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Plus por peligrosidad o toxicidad",
+    },
+    "PLUS_NOCTURNO": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Plus por trabajo nocturno",
+    },
+    "PLUS_ANTIGUEDAD": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Plus por antigüedad",
+    },
+    # B. Compensaciones en Especie y Beneficios
+    "USO_VEHICULO": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Uso de vehículo de empresa",
+    },
+    "SEGURO_SALUD": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Seguro de salud privado",
+    },
+    "APORTE_PENSION": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Aporte patronal a pensión/retiro",
+    },
+    "STOCK_OPTIONS": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Opciones de compra de acciones",
+    },
+    "SUBSIDIO_ALIMENTACION": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Subsidio de alimentación",
+    },
+    "SUBSIDIO_TRANSPORTE": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Subsidio de transporte",
+    },
+    "SUBSIDIO_GUARDERIA": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Subsidio de guardería",
+    },
+    # C. Compensaciones por Tiempo y Bienestar
+    "PAGO_FESTIVOS": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Pago por días festivos trabajados",
+    },
+    "THIRTEENTH_SALARY": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Aguinaldo o gratificación anual",
+    },
+    "UTILIDADES": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Participación en utilidades",
+    },
+    "PERMISO_PAGADO": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Permisos pagados (enfermedad, maternidad, etc.)",
+    },
+    "FONDO_AHORRO_EMPRESA": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Aporte empresa a fondo de ahorro",
+    },
+    "FONDO_AHORRO_EMPLEADO": {
+        "tipo": "deduccion",
+        "gravable": False,
+        "descripcion": "Aporte empleado a fondo de ahorro",
+    },
+    # D. Reembolsos y Dietas
+    "GASTOS_REPRESENTACION": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Gastos de representación",
+    },
+    "REEMBOLSO_FORMACION": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Reembolso de gastos de formación",
+    },
+    "REEMBOLSO_MEDICO": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Reembolso de gastos médicos",
+    },
+    # E. Pagos por Eventos Específicos
+    "INDEMNIZACION": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Indemnización por despido",
+    },
+    "COMPENSACION_REUBICACION": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Compensación por reubicación",
+    },
+    "PREMIO_PUNTUALIDAD": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Premio por puntualidad/asistencia",
+    },
+    "PREMIO_INNOVACION": {
+        "tipo": "percepcion",
+        "gravable": True,
+        "descripcion": "Premio por ideas innovadoras",
+    },
+    "AYUDA_FALLECIMIENTO": {
+        "tipo": "percepcion",
+        "gravable": False,
+        "descripcion": "Ayuda por fallecimiento de familiar",
+    },
+}

coati_payroll/formula_engine/results/__init__.py

@@ -0,0 +1,20 @@
+# 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.
+"""Result DTOs for formula engine execution."""
+
+from .execution_result import ExecutionResult
+
+__all__ = [
+    "ExecutionResult",
+]

coati_payroll/formula_engine/results/execution_result.py

@@ -0,0 +1,59 @@
+# 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.
+"""Execution result DTO."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+
+class ExecutionResult:
+    """Result of formula execution."""
+
+    def __init__(
+        self,
+        variables: dict[str, Decimal],
+        step_results: dict[str, Any],
+        final_output: Decimal,
+    ):
+        """Initialize execution result.
+
+        Args:
+            variables: All variables after execution
+            step_results: Results from each step
+            final_output: Final output value
+        """
+        self.variables = variables
+        self.step_results = step_results
+        self.final_output = final_output
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert result to dictionary format.
+
+        Returns:
+            Dictionary representation of result
+        """
+        return {
+            "variables": {k: float(v) for k, v in self.variables.items()},
+            "results": {
+                k: (
+                    float(v)
+                    if isinstance(v, Decimal)
+                    else ({kk: float(vv) for kk, vv in v.items()} if isinstance(v, dict) else v)
+                )
+                for k, v in self.step_results.items()
+            },
+            "output": float(self.final_output),
+        }

coati_payroll/formula_engine/steps/__init__.py

@@ -0,0 +1,30 @@
+# 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.
+"""Step execution modules using Strategy pattern."""
+
+from .base_step import Step
+from .calculation_step import CalculationStep
+from .conditional_step import ConditionalStep
+from .tax_lookup_step import TaxLookupStep
+from .assignment_step import AssignmentStep
+from .step_factory import StepFactory
+
+__all__ = [
+    "Step",
+    "CalculationStep",
+    "ConditionalStep",
+    "TaxLookupStep",
+    "AssignmentStep",
+    "StepFactory",
+]

coati_payroll/formula_engine/steps/assignment_step.py

@@ -0,0 +1,71 @@
+# 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.
+"""Assignment step implementation."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+from ..ast.type_converter import to_decimal
+from .base_step import Step
+
+if TYPE_CHECKING:
+    from ..execution.execution_context import ExecutionContext
+
+
+class AssignmentStep(Step):
+    """Step for assigning values to variables."""
+
+    def execute(self, context: "ExecutionContext") -> Decimal:
+        """Execute assignment step.
+
+        Args:
+            context: Execution context
+
+        Returns:
+            Assigned value as Decimal
+        """
+        value = self.config.get("value")
+        result = self._resolve_value(value, context)
+        return result
+
+    def _resolve_value(self, value: Any, context: "ExecutionContext") -> Decimal:
+        """Resolve a value that might be a variable reference.
+
+        Args:
+            value: Value or variable name to resolve
+            context: Execution context
+
+        Returns:
+            Decimal value
+        """
+        if isinstance(value, str) and value in context.variables:
+            resolved = context.variables[value]
+            if context.trace_callback:
+                from coati_payroll.i18n import _
+
+                context.trace_callback(
+                    _("Resolviendo variable '%(name)s' => %(value)s") % {"name": value, "value": resolved}
+                )
+            return resolved
+
+        resolved_literal = to_decimal(value)
+        if context.trace_callback:
+            from coati_payroll.i18n import _
+
+            context.trace_callback(
+                _("Resolviendo valor literal '%(raw)s' => %(value)s") % {"raw": value, "value": resolved_literal}
+            )
+        return resolved_literal

coati_payroll/formula_engine/steps/base_step.py

@@ -0,0 +1,48 @@
+# 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.
+"""Base step interface for Strategy pattern."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..execution.execution_context import ExecutionContext
+
+
+class Step(ABC):
+    """Base interface for all step types."""
+
+    def __init__(self, name: str, config: dict[str, Any]):
+        """Initialize step.
+
+        Args:
+            name: Step name
+            config: Step configuration dictionary
+        """
+        self.name = name
+        self.config = config
+
+    @abstractmethod
+    def execute(self, context: "ExecutionContext") -> Any:
+        """Execute the step and return result.
+
+        Args:
+            context: Execution context with variables and tax tables
+
+        Returns:
+            Step execution result
+        """
+        pass

coati_payroll/formula_engine/steps/calculation_step.py

@@ -0,0 +1,42 @@
+# 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.
+"""Calculation step implementation."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from ..ast.expression_evaluator import ExpressionEvaluator
+from .base_step import Step
+
+if TYPE_CHECKING:
+    from ..execution.execution_context import ExecutionContext
+
+
+class CalculationStep(Step):
+    """Step for executing mathematical calculations."""
+
+    def execute(self, context: "ExecutionContext") -> Decimal:
+        """Execute calculation step.
+
+        Args:
+            context: Execution context
+
+        Returns:
+            Calculated result as Decimal
+        """
+        formula = self.config.get("formula", "")
+        evaluator = ExpressionEvaluator(variables=context.variables, trace_callback=context.trace_callback)
+        return evaluator.evaluate(formula)

coati_payroll/formula_engine/steps/conditional_step.py

@@ -0,0 +1,122 @@
+# 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.
+"""Conditional step implementation."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+from ..ast.expression_evaluator import ExpressionEvaluator
+from ..ast.safe_operators import COMPARISON_OPERATORS
+from ..ast.type_converter import to_decimal
+from ..exceptions import CalculationError
+from .base_step import Step
+
+if TYPE_CHECKING:
+    from ..execution.execution_context import ExecutionContext
+
+
+class ConditionalStep(Step):
+    """Step for conditional logic (if/else)."""
+
+    def execute(self, context: "ExecutionContext") -> Decimal:
+        """Execute conditional step.
+
+        Args:
+            context: Execution context
+
+        Returns:
+            Result of selected branch as Decimal
+        """
+        condition = self.config.get("condition", {})
+        if_true = self.config.get("if_true", "0")
+        if_false = self.config.get("if_false", "0")
+
+        # Evaluate condition
+        condition_result = self._evaluate_condition(condition, context)
+
+        # Select expression based on condition
+        selected_value = if_true if condition_result else if_false
+
+        # Evaluate selected expression
+        evaluator = ExpressionEvaluator(variables=context.variables, trace_callback=context.trace_callback)
+        return evaluator.evaluate(str(selected_value))
+
+    def _evaluate_condition(self, condition: dict[str, Any], context: "ExecutionContext") -> bool:
+        """Evaluate a conditional expression.
+
+        Args:
+            condition: Dictionary with 'left', 'operator', 'right' keys
+            context: Execution context
+
+        Returns:
+            Boolean result of the condition
+
+        Raises:
+            CalculationError: If condition is invalid
+        """
+        if not isinstance(condition, dict):
+            raise CalculationError("Condition must be a dictionary")
+
+        left = condition.get("left")
+        op = condition.get("operator")
+        right = condition.get("right")
+
+        if op not in COMPARISON_OPERATORS:
+            raise CalculationError(f"Invalid comparison operator: {op}")
+
+        # Resolve variable references
+        left_val = self._resolve_value(left, context)
+        right_val = self._resolve_value(right, context)
+        result = COMPARISON_OPERATORS[op](left_val, right_val)
+
+        if context.trace_callback:
+            from coati_payroll.i18n import _
+
+            context.trace_callback(
+                _("Condición evaluada: %(left)s %(op)s %(right)s -> %(res)s")
+                % {"left": left_val, "op": op, "right": right_val, "res": result}
+            )
+
+        return result
+
+    def _resolve_value(self, value: Any, context: "ExecutionContext") -> Decimal:
+        """Resolve a value that might be a variable reference.
+
+        Args:
+            value: Value or variable name to resolve
+            context: Execution context
+
+        Returns:
+            Decimal value
+        """
+        if isinstance(value, str) and value in context.variables:
+            resolved = context.variables[value]
+            if context.trace_callback:
+                from coati_payroll.i18n import _
+
+                context.trace_callback(
+                    _("Resolviendo variable '%(name)s' => %(value)s") % {"name": value, "value": resolved}
+                )
+            return resolved
+
+        resolved_literal = to_decimal(value)
+        if context.trace_callback:
+            from coati_payroll.i18n import _
+
+            context.trace_callback(
+                _("Resolviendo valor literal '%(raw)s' => %(value)s") % {"raw": value, "value": resolved_literal}
+            )
+        return resolved_literal

coati_payroll/formula_engine/steps/step_factory.py

@@ -0,0 +1,58 @@
+# 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.
+"""Factory for creating step instances."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from coati_payroll.enums import StepType
+
+from ..exceptions import CalculationError
+from .assignment_step import AssignmentStep
+from .base_step import Step
+from .calculation_step import CalculationStep
+from .conditional_step import ConditionalStep
+from .tax_lookup_step import TaxLookupStep
+
+
+class StepFactory:
+    """Factory for creating step instances."""
+
+    @staticmethod
+    def create_step(step_config: dict[str, Any]) -> Step:
+        """Create a step instance from configuration.
+
+        Args:
+            step_config: Step configuration dictionary
+
+        Returns:
+            Step instance
+
+        Raises:
+            CalculationError: If step type is unknown
+        """
+        step_type = step_config.get("type")
+        step_name = step_config.get("name", "unnamed_step")
+
+        if step_type == StepType.CALCULATION:
+            return CalculationStep(step_name, step_config)
+        elif step_type == StepType.CONDITIONAL:
+            return ConditionalStep(step_name, step_config)
+        elif step_type == StepType.TAX_LOOKUP:
+            return TaxLookupStep(step_name, step_config)
+        elif step_type == StepType.ASSIGNMENT:
+            return AssignmentStep(step_name, step_config)
+        else:
+            raise CalculationError(f"Unknown step type: {step_type}")