A lightweight, Python-native tax calculation library for Brazilian fiscal rules (ICMS, IPI, PIS/COFINS, FCP, DIFAL, ICMS ST and more).

This repository provides calculators and a facade to reproduce common fiscal calculation flows used by Brazilian electronic invoices (NF-e, NFC-e, CT-e) and related documents.

• Calculators for ICMS, ICMS ST, IPI, PIS, COFINS, FCP, DIFAL, IBPT and CBS/IBS flows
• A Facade (FacadeCalculadoraTributacao) that composes calculators into a single, test-friendly API
• Auditable execution traces via debug_execution for troubleshooting and tests
• Designed for deterministic unit testing and integration with decision tables (DMN)

A simplified diagram showing how data and decisions flow through the package.

flowchart LR
  In(("Tributavel (data model)")) --> Facade["FacadeCalculadoraTributacao"]
  Facade --> Calculators["Tax Calculators (taxes/)"]
  Calculators -->|uses rules| Rules["DMN rules (rules/)"]
  Rules -->|decision logic| Calculators
  Facade --> Audit["AuditManager / ExecutionReport"]
  Audit --> Pretty["Human-readable report"]
  Audit --> JSON["JSON report"]
  Facade --> API["Public API (calcula_icms, calcula_tributacao)"]

  subgraph Repo
    R1["rules/ (DMN-backed)"]
    R2["taxes/ (calculators)"]
    R3["audit.py (reporting)"]
    R4["scripts/ (helpers)"]
  end

  R1 --> Rules
  R2 --> Calculators
  R3 --> Audit
  R4 --> Facade

• Tributavel is the single data holder for item/document values and percentages.
• FacadeCalculadoraTributacao orchestrates the calculators and consults DMN-backed rule tables when necessary.
• rules/ contains DMN-style rule definitions consulted via bkflow-dmn.
• taxes/ implements numeric calculations; audit.py captures evaluation traces and produces both human-readable and JSON reports.
• scripts/ contains utilities used to generate embedded documentation and debug examples.

The Tributavel dataclass is the central data structure that holds all information needed for tax calculations. All fields have sensible defaults and use Decimal for monetary values.

from decimal import Decimal
from motor_tributario_py.models import Tributavel

# Simple product with ICMS
produto = Tributavel(
    valor_produto=Decimal('100.00'),
    quantidade_produto=Decimal('2'),
    percentual_icms=Decimal('18'),
)

# Product with freight, insurance and discount
produto_completo = Tributavel(
    valor_produto=Decimal('500.00'),
    frete=Decimal('50.00'),
    seguro=Decimal('10.00'),
    desconto=Decimal('25.00'),
    tipo_desconto="Incondicional",
    percentual_icms=Decimal('12'),
    percentual_ipi=Decimal('5'),
    percentual_pis=Decimal('1.65'),
    percentual_cofins=Decimal('7.6'),
)

from decimal import Decimal
from motor_tributario_py.models import Tributavel
from motor_tributario_py.facade import FacadeCalculadoraTributacao

# Create a Tributavel instance with product data
produto = Tributavel(
    valor_produto=Decimal('100.00'),
    quantidade_produto=Decimal('1'),
    percentual_icms=Decimal('18.0'),
    percentual_pis=Decimal('1.65'),
    percentual_cofins=Decimal('7.6'),
)

# Use the facade to calculate taxes
facade = FacadeCalculadoraTributacao(produto)

# Calculate ICMS
res_icms = facade.calcula_icms()
print('ICMS Base:', res_icms.base_calculo)  # 100.00
print('ICMS Valor:', res_icms.valor)        # 18.00

# Calculate all taxes at once
resultado = facade.calcula_tributacao()
print('Valor PIS:', resultado.valor_pis)       # 1.65
print('Valor COFINS:', resultado.valor_cofins) # 7.60

# Debug execution with detailed trace
report = facade.debug_execution('calcula_icms')
print(report.format_pretty())

================================================================================
EXECUTION REPORT: calcula_icms
================================================================================

INPUTS:
  args: ()
  kwargs: {}

  Tributavel:
    valor_produto: 100.00
    quantidade_produto: 1
    tipo_desconto: Incondicional
    percentual_icms: 18.0
    percentual_pis: 1.65
    percentual_cofins: 7.6

DECISION TRACE:

  [1] Full ICMS Calculation Rules
      Total Rules: 4
      Matched: [3]

      ━━━ Rule #4 ━━━
      Input Conditions:
        • is_ativo: false
        • tipo_desconto: "Incondicional"
      Output Calculations:
        • base_calculo = ( ( ( ( (valor_produto * quantidade_produto) + frete) + seguro) + outras_despesas) - desconto ) * (decimal(1) - (percentual_reducao / decimal(100)))
          Evaluated: ( ( ( ( (100.00 * 1) + 0) + 0) + 0) - 0 ) * (decimal(1) - (0 / decimal(100)))
          → Result: 100.00
        • valor_final = ( ( ( ( ( ( (valor_produto * quantidade_produto) + frete) + seguro) + outras_despesas) - desconto ) * (decimal(1) - (percentual_reducao / decimal(100))) ) * percentual_icms) / decimal(100)
          Evaluated: ( ( ( ( ( ( (100.00 * 1) + 0) + 0) + 0) - 0 ) * (decimal(1) - (0 / decimal(100))) ) * 18.0) / decimal(100)
          → Result: 18.000

FINAL RESULT:
  base_calculo: 100.00
  valor: 18.000
  percentual_icms: 18.0
  percentual_reducao: 0
  percentual_icms_st: 0
  percentual_mva: 0
  base_calculo_st: None
  valor_icms_st: None
  percentual_reducao_st: 0.00
  percentual_diferimento: 0.00
  valor_icms_diferido: None
  valor_icms_operacao: None
  valor_bc_st_retido: 100.00
  base_calculo_icms_efetivo: None
  valor_icms_efetivo: None
  modalidade_determinacao_bc_icms: ValorOperacao
  modalidade_determinacao_bc_icms_st: None

================================================================================

{
  "method_name": "calcula_icms",
  "inputs": {
    "tributavel": {
      "valor_produto": 100.0,
      "frete": 0.0,
      "seguro": 0.0,
      "outras_despesas": 0.0,
      "desconto": 0.0,
      "valor_ipi": 0.0,
      "quantidade_produto": 1.0,
      "is_servico": false,
      "is_ativo_imobilizado_ou_uso_consumo": false,
      "tipo_desconto": "Incondicional",
      "cst": "",
      "tipo_calculo_icms_desonerado": "",
      "crt": "",
      "tipo_operacao": "",
      "tipo_pessoa": "",
      "percentual_icms": 18.0,
      "percentual_reducao": 0.0,
      "percentual_ipi": 0.0,
      "percentual_pis": 1.65,
      "percentual_reducao_pis": 0.0,
      "percentual_cofins": 7.6,
      "percentual_reducao_cofins": 0.0,
      "percentual_icms_st": 0.0,
      "percentual_mva": 0.0,
      "percentual_reducao_st": 0.0,
      "percentual_fcp": 0.0,
      "percentual_fcp_st": 0.0,
      "percentual_credito": 0.0,
      "csosn": 0,
      "percentual_fcp_st_retido": 0.0,
      "valor_ultima_base_calculo_icms_st_retido": 0.0,
      "percentual_difal_interna": 0.0,
      "percentual_difal_interestadual": 0.0,
      "percentual_issqn": 0.0,
      "percentual_ret_pis": 0.0,
      "percentual_ret_cofins": 0.0,
      "percentual_ret_csll": 0.0,
      "percentual_ret_irrf": 0.0,
      "percentual_ret_inss": 0.0,
      "percentual_federal": 0.0,
      "percentual_estadual": 0.0,
      "percentual_municipal": 0.0,
      "percentual_federal_importados": 0.0,
      "percentual_ibs_uf": 0.0,
      "percentual_ibs_municipal": 0.0,
      "percentual_cbs": 0.0,
      "percentual_reducao_ibs_uf": 0.0,
      "percentual_reducao_ibs_municipal": 0.0,
      "percentual_reducao_cbs": 0.0,
      "documento": "",
      "percentual_icms_efetivo": 0.0,
      "percentual_reducao_icms_efetivo": 0.0,
      "quantidade_base_calculo_icms_monofasico": 0.0,
      "aliquota_ad_rem_icms": 0.0,
      "percentual_reducao_aliquota_ad_rem_icms": 0.0,
      "percentual_biodiesel": 0.0,
      "percentual_originario_uf": 0.0,
      "quantidade_base_calculo_icms_monofasico_retido_anteriormente": 0.0,
      "aliquota_ad_rem_icms_retido_anteriormente": 0.0,
      "somar_pis_na_base_ibs_cbs": false,
      "somar_cofins_na_base_ibs_cbs": false,
      "somar_icms_na_base_ibs_cbs": false,
      "somar_issqn_na_base_ibs_cbs": false,
      "percentual_diferimento": 0.0,
      "deduz_icms_da_base_de_pis_cofins": false
    },
    "args": [],
    "kwargs": {}
  },
  "result": {
    "base_calculo": 100.0,
    "valor": 18.0,
    "percentual_icms": 18.0,
    "percentual_reducao": 0.0,
    "percentual_icms_st": 0.0,
    "percentual_mva": 0.0,
    "base_calculo_st": null,
    "valor_icms_st": null,
    "percentual_reducao_st": 0.0,
    "percentual_diferimento": 0.0,
    "valor_icms_diferido": null,
    "valor_icms_operacao": null,
    "valor_bc_st_retido": 100.0,
    "base_calculo_icms_efetivo": null,
    "valor_icms_efetivo": null,
    "modalidade_determinacao_bc_icms": "ValorOperacao",
    "modalidade_determinacao_bc_icms_st": null
  },
  "audit_trail": {
    "traces": [
      {
        "table_title": "Full ICMS Calculation Rules",
        "facts": {
          "valor_produto": 100.0,
          "quantidade_produto": 1.0,
          "frete": 0.0,
          "seguro": 0.0,
          "outras_despesas": 0.0,
          "valor_ipi": 0.0,
          "is_ativo": false,
          "tipo_desconto": "Incondicional",
          "desconto": 0.0,
          "percentual_reducao": 0.0,
          "percentual_icms": 18.0
        },
        "matched_rules": [
          3
        ],
        "rule_count": 4,
        "final_result": [
          {
            "base_calculo": 100.0,
            "valor_final": 18.0
          }
        ],
        "matched_rule_details": [
          {
            "rule_number": 4,
            "input_conditions": {
              "is_ativo": "false",
              "tipo_desconto": "\"Incondicional\""
            },
            "output_calculations": {
              "base_calculo": {
                "expression": "( ( ( ( (valor_produto * quantidade_produto) + frete) + seguro) + outras_despesas) - desconto ) * (decimal(1) - (percentual_reducao / decimal(100)))",
                "evaluated": "( ( ( ( (100.00 * 1) + 0) + 0) + 0) - 0 ) * (decimal(1) - (0 / decimal(100)))",
                "result": 100.0
              },
              "valor_final": {
                "expression": "( ( ( ( ( ( (valor_produto * quantidade_produto) + frete) + seguro) + outras_despesas) - desconto ) * (decimal(1) - (percentual_reducao / decimal(100))) ) * percentual_icms) / decimal(100)",
                "evaluated": "( ( ( ( ( ( (100.00 * 1) + 0) + 0) + 0) - 0 ) * (decimal(1) - (0 / decimal(100))) ) * 18.0) / decimal(100)",
                "result": 18.0
              }
            }
          }
        ]
      }
    ]
  }
}

Notes:

• The FacadeCalculadoraTributacao accepts keyword overrides to Tributavel properties at construction time (handy for tests).
• Some flows rely on decision tables (DMN) to determine behaviour for specific CST/CSON rules. The package integrates with bkflow-dmn for that purpose.

• motor_tributario_py/ - package sources
  • facade.py - high-level orchestration API
  • models.py - Tributavel data model used across calculators
  • rules/ - DMN-backed rule dispatchers and helpers
  • taxes/ - individual tax calculators (icms, pis, cofins, ipi, difal, etc.)
  • utils/, audit.py - helpers and auditing utilities

Diagrama simplificado mostrando o fluxo de dados e decisões dentro do pacote.

flowchart LR
  In(("Tributavel\n(data model)")) --> Facade["FacadeCalculadoraTributacao"]
  Facade --> Calculators["Tax Calculators\n(taxes/)" ]
  Calculators -->|uses rules| Rules["DMN rules\n(rules/)"]
  Rules -->|decision logic| Calculators
  Facade --> Audit["AuditManager / ExecutionReport"]
  Audit --> Pretty["Human-readable report"]
  Audit --> JSON["JSON report"]
  Facade --> API["Public API\n(calcula_icms, calcula_tributacao)"]

  subgraph Repo
    R1["rules/ (DMN-backed)"]
    R2["taxes/ (calculators)"]
    R3["audit.py (reporting)"]
    R4["scripts/ (helpers)"]
  end

  R1 --> Rules
  R2 --> Calculators
  R3 --> Audit
  R4 --> Facade

• Tributavel é o objeto de dados com valores e percentuais do item/documento.
• FacadeCalculadoraTributacao orquestra as chamadas aos calculadores e consulta tabelas de decisão quando necessário.
• rules/ contém definições de regras estilo DMN consultadas via bkflow-dmn.
• taxes/ implementa os cálculos numéricos; audit.py gera traços para depuração e relatórios em texto/JSON.
• scripts/ contém utilitários usados para gerar a documentação embutida e exemplos de depuração.

Unit tests and fixtures live under tests/. Run them with pytest:

pytest -q

Contributions are welcome. Open a PR with a clear description and tests for new calculations or bug fixes. Keep changes small and focused.

Please refer to the repository LICENSE file for licensing information.

Summary: Credito ICMS Preprocessing; Credito ICMS Calculation

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/credito_icms_rules.py

Rule: Credito ICMS Preprocessing Hit policy: Unique

Rule: Credito ICMS Calculation Hit policy: Unique

Summary: CSOSN Dispatch Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/csosn_rules.py

Rule: CSOSN Dispatch Rules Hit policy: Unique

Summary: CST Post-Processing Rules; CST 51 Diferimento Calculation

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/cst_post_processing_rules.py

Rule: CST Post-Processing Rules Hit policy: Unique

Rule: CST 51 Diferimento Calculation Hit policy: Unique

Summary: CST Dispatch Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/cst_rules.py

Rule: CST Dispatch Rules Hit policy: Unique

Summary: Full DIFAL and FCP Calculation Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/difal_rules.py

Rule: Full DIFAL and FCP Calculation Rules Hit policy: Unique

Summary: FCP Calculation

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/fcp_rules.py

Rule: FCP Calculation Hit policy: Unique

Summary: FCP ST Calculation Rules; FCP ST Retido Calculation Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/fcp_st_rules.py

Rule: FCP ST Calculation Rules Hit policy: Unique

Rule: FCP ST Retido Calculation Rules Hit policy: Unique

Summary: IBPT Calculation Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/ibpt_rules.py

Rule: IBPT Calculation Rules Hit policy: Unique

Summary: IBS/CBS Base Calculation; IBS Calculation; IBS Municipal Calculation; CBS Calculation

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/ibs_cbs_rules.py

Rule: IBS/CBS Base Calculation Hit policy: Unique

Rule: IBS Calculation Hit policy: Unique

Rule: IBS Municipal Calculation Hit policy: Unique

Rule: CBS Calculation Hit policy: Unique

Summary: ICMS Desonerado Preprocessing; ICMS Desonerado Calculation Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/icms_desonerado_rules.py

Rule: ICMS Desonerado Preprocessing Hit policy: First

Rule: ICMS Desonerado Calculation Rules Hit policy: First

Summary: ICMS Efetivo Preprocessing; ICMS Efetivo Base Calculation; ICMS Efetivo Calculation

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/icms_efetivo_rules.py

Rule: ICMS Efetivo Preprocessing Hit policy: Unique

Rule: ICMS Efetivo Base Calculation Hit policy: Unique

Rule: ICMS Efetivo Calculation Hit policy: Unique

Summary: ICMS Monofásico Calculation

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/icms_monofasico_rules.py

Rule: ICMS Monofásico Calculation Hit policy: Unique

Summary: Full ICMS Calculation Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/icms_rules.py

Rule: Full ICMS Calculation Rules Hit policy: Unique

Summary: Full ICMS ST Calculation Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/icms_st_rules.py

Rule: Full ICMS ST Calculation Rules Hit policy: Unique

Summary: Full IPI Calculation Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/ipi_rules.py

Rule: Full IPI Calculation Rules Hit policy: Unique

Summary: ISSQN Base Calculation; ISSQN Tax Calculation

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/issqn_rules.py

Rule: ISSQN Base Calculation Hit policy: Unique

Rule: ISSQN Tax Calculation Hit policy: Unique

Summary: Full PIS/COFINS Calculation Rules

Source file: /home/maxwell/Rule/motor_tributario_py/motor_tributario_py/rules/pis_cofins_rules.py

Rule: Full PIS/COFINS Calculation Rules Hit policy: Unique