README.md

---
license: mit
language:
- pt
tags:
- pytorch
- transformer
- text-classification
- fiscal
- sped
- brazil
- tax
- nlp
- llm
- brazilian-fiscal
pipeline_tag: text-classification
library_name: pytorch
base_model: []
datasets: []
metrics:
- accuracy
model-index:
- name: LLM Fiscal Brasileiro — SPED
  results:
  - task:
      type: text-classification
      name: Brazilian Fiscal Obligation Classification
    metrics:
    - type: accuracy
      value: 0.95
      name: Accuracy (intent classification, 16 classes)
---

# LLM Fiscal Brasileiro — SPED Fiscal System

> **PyTorch-powered LLM for Brazilian fiscal obligations (SPED)**
> Python 3.12 · PyTorch · Pydantic v2 · 117 tests

---

## Table of Contents / Índice

- [English](#english)
  - [Overview](#overview)
  - [Architecture](#architecture)
  - [Project Structure](#project-structure)
  - [Installation](#installation)
  - [Quick Start](#quick-start)
  - [LLM Model](#llm-model)
  - [Tax Calculators](#tax-calculators)
  - [SPED / DFe Generators](#sped--dfe-generators)
  - [Annual Declarations](#annual-declarations)
  - [SEFAZ Transmitter](#sefaz-transmitter)
  - [Training the Model](#training-the-model)
  - [Running Tests](#running-tests)
  - [Fiscal Calendar](#fiscal-calendar)
- [Português Brasileiro](#português-brasileiro)
  - [Visão Geral](#visão-geral)
  - [Arquitetura](#arquitetura)
  - [Estrutura do Projeto](#estrutura-do-projeto)
  - [Instalação](#instalação)
  - [Início Rápido](#início-rápido)
  - [Modelo LLM](#modelo-llm)
  - [Calculadoras Tributárias](#calculadoras-tributárias)
  - [Geradores SPED / DFe](#geradores-sped--dfe)
  - [Declarações Anuais](#declarações-anuais)
  - [Transmissor SEFAZ](#transmissor-sefaz)
  - [Treinamento do Modelo](#treinamento-do-modelo)
  - [Execução dos Testes](#execução-dos-testes)
  - [Calendário Fiscal](#calendário-fiscal)

---

# English

## Overview

The **Brazilian Fiscal LLM** is a Python 3.12 library that combines a custom **PyTorch Transformer** with a complete set of Brazilian tax compliance tools. It is designed to be consumed as a library by any application — there is no CLI or UI bundled in.

The system covers the full lifecycle of Brazilian fiscal obligations:

- **Intent classification** of natural-language fiscal queries (16 obligation classes)
- **RAG (Retrieval-Augmented Generation)** with 25 indexed fiscal knowledge documents
- **Tax calculators** for all major Brazilian taxes (ICMS, IPI, PIS/COFINS, IRPJ/CSLL, ISS, Simples Nacional)
- **SPED file generators** for all federal digital bookkeeping obligations
- **Electronic document generators** (NF-e, NFC-e, CT-e, MDF-e) with digital signatures
- **SEFAZ SOAP transmitter** for NF-e authorization

The single entry point is `PipelineFiscal`, which orchestrates all components.

---

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                        PipelineFiscal                            │
│  (src/models/fiscal_llm.py)                                      │
│                                                                  │
│  ┌─────────────────────┐   ┌──────────────────────────────────┐  │
│  │  TransformerFiscal  │   │   BancoEmbeddingsFiscais (RAG)   │  │
│  │  PyTorch 4-layer    │   │   25 knowledge documents         │  │
│  │  encoder, d=256     │   │   cosine similarity search       │  │
│  │  8 heads, Pre-LN    │   └──────────────────────────────────┘  │
│  └─────────────────────┘                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Intent Classification (16 classes)             │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐  │
│  │  Tax Calculators │  │  SPED Generators │  │  DFe / XML    │  │
│  │  ICMS · IPI      │  │  EFD ICMS/IPI    │  │  NF-e · NFC-e │  │
│  │  PIS/COFINS      │  │  EFD Contribu.   │  │  CT-e · MDF-e │  │
│  │  IRPJ/CSLL · ISS │  │  ECD · ECF       │  │  EFD-Reinf    │  │
│  │  Simples Nac.    │  │  DCTF · GIA      │  │  e-Social     │  │
│  └──────────────────┘  │  DIRF · DEFIS    │  └───────────────┘  │
│                         │  DeSTDA          │                     │
│                         └──────────────────┘                     │
└──────────────────────────────────────────────────────────────────┘
```

**Key design decisions:**
- The LLM (`TransformerFiscal`) uses character-level tokenization — no external tokenizer dependency.
- RAG runs entirely in-memory using normalized cosine similarity on CLS embeddings.
- All monetary values use Python `Decimal` with `ROUND_HALF_UP` — no floating-point arithmetic.
- SPED files are pipe-delimited (`|REGISTRO|CAMPO1|`) UTF-8, matching the official Receita Federal spec.
- NF-e/CT-e/MDF-e use XML v4.00 with RSA-SHA1 XMLDSig digital signatures via the `cryptography` library.

---

## Project Structure

```
llm-speed/
├── src/
│   ├── __init__.py                  # Exports PipelineFiscal
│   ├── fiscal/
│   │   ├── entities.py              # Pydantic v2 models (Empresa, NotaFiscal, …)
│   │   └── constants.py             # Tax rates, CST tables, CFOP codes, deadlines
│   ├── calculators/
│   │   ├── icms.py                  # ICMS (own + ST + DIFAL + FCP)
│   │   ├── ipi.py                   # IPI (TIPI rates by NCM chapter)
│   │   ├── pis_cofins.py            # PIS/COFINS (cumulative + non-cumulative + withholding)
│   │   ├── irpj_csll.py             # IRPJ/CSLL (Lucro Real + Lucro Presumido + monthly estimates)
│   │   ├── iss.py                   # ISS (LC 116/2003 + Simples Nacional annexes)
│   │   └── simples_nacional.py      # Simples Nacional (5 annexes, Fator R, PGDAS-D, MEI)
│   ├── generators/
│   │   ├── sped_writer.py           # Base SPED pipe-delimited writer
│   │   ├── efd_icms_ipi.py          # EFD ICMS/IPI (blocks 0,C,E,G,H,K,1,9)
│   │   ├── efd_contribuicoes.py     # EFD Contribuições PIS/COFINS (blocks 0,C,M,1,9)
│   │   ├── ecd.py                   # ECD — Escrituração Contábil Digital
│   │   ├── ecf.py                   # ECF — Escrituração Contábil Fiscal (LALUR/LACS)
│   │   ├── nfe_xml.py               # NF-e XML v4.00 (model 55) + digital signature
│   │   ├── nfce_xml.py              # NFC-e XML v4.00 (model 65, consumer/POS)
│   │   ├── cte.py                   # CT-e XML v4.00 (model 57, freight)
│   │   ├── mdfe.py                  # MDF-e XML v3.00 (manifest, model 58)
│   │   ├── efd_reinf.py             # EFD-Reinf XML events (R-1000…R-2099)
│   │   ├── esocial.py               # e-Social XML events (S-1000…S-1299, S-2200, S-2299)
│   │   ├── dctf.py                  # DCTF XML (federal tax debit declaration)
│   │   ├── dirf.py                  # DIRF text file (annual IRRF withholding declaration)
│   │   ├── defis.py                 # DEFIS XML (Simples Nacional annual declaration)
│   │   ├── destda.py                # DeSTDA XML (Simples Nacional monthly ICMS-ST/DIFAL)
│   │   └── gia.py                   # GIA/GIA-ST AIE file (São Paulo monthly ICMS)
│   ├── models/
│   │   ├── fiscal_llm.py            # TransformerFiscal + RAG + PipelineFiscal
│   │   └── trainer.py               # TrainerFiscal (173 examples, early stopping, class weights)
│   └── transmitters/
│       └── receita_federal.py       # NF-e SEFAZ SOAP transmitter + SPED local validator
├── tests/
│   ├── test_calculators.py          # 43 tests for all tax calculators
│   └── test_generators.py           # 74 tests for all generators
├── pyproject.toml
└── requirements.txt
```

---

## Installation

**Requirements:** Python 3.12+, pip

```bash
# Clone the repository
git clone <repo-url>
cd llm-speed

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate        # Linux/macOS
# venv\Scripts\activate         # Windows

# Install dependencies
pip install -r requirements.txt
```

**Core dependencies:**

| Package | Purpose |
|---------|---------|
| `torch>=2.3.0` | TransformerFiscal model + training |
| `pydantic>=2.7.0` | Validated fiscal data models |
| `cryptography>=42.0.0` | NF-e/CT-e XML digital signatures (RSA-SHA1) |
| `lxml>=5.2.0` | C14N canonicalization for XMLDSig |
| `httpx>=0.27.0` | SEFAZ SOAP HTTP client |
| `zeep>=4.2.1` | SOAP envelope helpers |
| `python-dateutil>=2.9.0` | Brazilian fiscal calendar calculations |

---

## Quick Start

```python
from src import PipelineFiscal

# Instantiate the LLM pipeline (uses random weights until trained)
pipeline = PipelineFiscal(diretorio_saida="./output")

# --- Natural language processing ---
resultado = pipeline.processar(
    "calculate ICMS for a sale",
    {"valor_mercadoria": 10000, "aliquota": 18, "uf_origem": "SP", "uf_destino": "RJ"}
)
print(resultado.resumo())
# [calcular_icms]
#   base_calculo: R$ 10,000.00
#   aliquota: R$ 18.00
#   valor_icms: R$ 1,800.00
#   valor_total_icms: R$ 1,800.00

# --- Direct tax calculation ---
r = pipeline.calcular_pis_cofins({
    "valor": 100000,
    "regime": "lucro_presumido",
})
print(r["pis_a_recolher"])   # 650.00
print(r["cofins_a_recolher"]) # 3000.00

# --- Generate SPED files for an entire period ---
from src.fiscal.entities import PeriodoApuracao, Empresa, ...
periodo = PeriodoApuracao(...)
arquivos = pipeline.gerar_obrigacoes(periodo)
# Returns: {"EFD_ICMS_IPI": ResultadoFiscal, "EFD_CONTRIBUICOES": ..., ...}

# --- SEFAZ status check ---
status = pipeline.verificar_sefaz(uf="SP")
print(status["mensagem"])
```

---

## LLM Model

### TransformerFiscal

A compact Transformer encoder trained for Brazilian fiscal intent classification.

| Parameter | Value |
|-----------|-------|
| Architecture | Transformer Encoder (Pre-LN) |
| Layers | 4 |
| d_model | 256 |
| Attention heads | 8 |
| FFN dimension | 1,024 |
| Tokenizer | Character-level (vocab ~200 chars) |
| Max sequence length | 1,024 tokens |
| Output classes | 16 fiscal obligation types |

**16 Intent Classes:**

| Class | Description |
|-------|-------------|
| `EFD_ICMS_IPI` | Generate EFD ICMS/IPI digital bookkeeping |
| `EFD_CONTRIBUICOES` | Generate EFD Contribuições (PIS/COFINS) |
| `ECD` | Generate Escrituração Contábil Digital |
| `ECF` | Generate Escrituração Contábil Fiscal |
| `NFe` | Emit / cancel NF-e or NFC-e |
| `NFSe` | Emit NFS-e (municipal service invoice) |
| `CTe` | Generate CT-e freight document |
| `eSocial` | Generate e-Social payroll events |
| `EFD_REINF` | Generate EFD-Reinf withholding events |
| `DCTF` | Generate DCTF federal tax declaration |
| `PGDAS` | Calculate Simples Nacional DAS / PGDAS-D |
| `calculo_icms` | Calculate ICMS for a transaction |
| `calculo_ipi` | Calculate IPI for industrial products |
| `calculo_pis_cofins` | Calculate PIS and COFINS on revenue |
| `calculo_irpj_csll` | Calculate IRPJ and CSLL (corporate taxes) |
| `calculo_iss` | Calculate ISS (municipal services tax) |

### RAG Knowledge Base

`BancoEmbeddingsFiscais` indexes 25 fiscal knowledge documents covering all major obligations, rates, deadlines, and legislation. Retrieval uses cosine similarity on CLS token embeddings.

```python
# Direct access to RAG
pipeline.rag.buscar("prazo EFD ICMS IPI", top_k=3)
# Returns: [(text, similarity_score), ...]
```

---

## Tax Calculators

All calculators are available directly via `PipelineFiscal` or imported from `src.calculators.*`. All monetary values use `Decimal` with `ROUND_HALF_UP`.

### ICMS (`src/calculators/icms.py`)

```python
resultado = pipeline.calcular_icms({
    "valor_mercadoria": 10000,
    "aliquota": 18,              # internal rate (%)
    "uf_origem": "SP",
    "uf_destino": "RJ",
    "frete": 500,
    "cst": "000",                # CST: 000=taxed, 020=reduced, 040=exempt, 060=ST
    "calcular_difal": False,
    "consumidor_final": False,
    # Optional ST parameters:
    # "calcular_st": True, "mva": 40, "aliq_interna_destino": 18
})
```

Supports: CST 000/010/020/030/040/041/050/051/060/070, ICMS-ST with MVA, FCP (Fundo de Combate à Pobreza), DIFAL (EC 87/2015).

### IPI (`src/calculators/ipi.py`)

```python
resultado = pipeline.calcular_ipi({
    "valor_produtos": 5000,
    "aliquota": 10,
    "cst": "50",   # 50=taxed, 52=exempt, 54=suspended
    "frete": 200,
})
```

Includes TIPI rates by NCM chapter (0% pharmaceuticals, 25% vehicles, 300% tobacco).

### PIS/COFINS (`src/calculators/pis_cofins.py`)

```python
resultado = pipeline.calcular_pis_cofins({
    "valor": 100000,
    "regime": "lucro_real",      # or "lucro_presumido"
    # Optional credits (non-cumulative regime only):
    "receitas": [
        {"descricao": "Vendas", "valor": 100000, "cst_pis": "01", "cst_cofins": "01"}
    ],
})
```

| Regime | PIS | COFINS |
|--------|-----|--------|
| Lucro Presumido (cumulative) | 0.65% | 3.00% |
| Lucro Real (non-cumulative) | 1.65% | 7.60% |

Supports credits on purchases, energy, rent, depreciation (Lei 10.637/2002 and 10.833/2003).

### IRPJ / CSLL (`src/calculators/irpj_csll.py`)

```python
resultado = pipeline.calcular_irpj_csll({
    "valor": 500000,             # Lucro Real: net profit / Lucro Presumido: gross revenue
    "regime": "lucro_presumido", # or "lucro_real"
    "atividade": "venda_mercadorias",  # or "servicos_em_geral", "intermediacao"
})
```

| Rule | Value |
|------|-------|
| IRPJ base rate | 15% |
| IRPJ surcharge | +10% on profit > R$ 20,000/month |
| CSLL rate | 9% (general) / 15% (financial institutions) |
| Lucro Presumido — commerce/industry | 8% of revenue |
| Lucro Presumido — services | 32% of revenue |
| Tax loss carryforward limit | 30% of taxable profit |

### ISS (`src/calculators/iss.py`)

```python
resultado = pipeline.calcular_iss({
    "valor_servico": 10000,
    "codigo_servico": "17",      # LC 116/2003 service code
    "aliquota": 3,               # municipal rate (2%–5%)
    "retencao_fonte": True,
})
```

### Simples Nacional (`src/calculators/simples_nacional.py`)

```python
# Single activity DAS calculation
resultado = pipeline.calcular_simples({
    "receita_mes": 50000,
    "rbt12": 600000,   # 12-month accumulated revenue
    "anexo": "I",      # I=commerce, II=industry, III-V=services
})

# Full PGDAS-D with multiple activities
resultado = pipeline.calcular_pgdas({
    "periodo": "2024-01",
    "rbt12": 600000,
    "atividades": [
        {"tipo": "comercio", "receita": 30000},
        {"tipo": "servicos_advocacia", "receita": 20000},
    ],
})
```

Covers all 5 annexes (6 revenue brackets each), Fator R calculation for Annex III vs V, and MEI fixed amounts.

---

## SPED / DFe Generators

### EFD ICMS/IPI (`src/generators/efd_icms_ipi.py`)

Layout version 017. Generates all mandatory blocks:

| Block | Contents |
|-------|----------|
| 0 | Establishment identification, participants (0150), products (0200) |
| C | NF-e records (C100, C110, C170, C190) |
| E | ICMS settlement (E110), IPI settlement (E520) |
| G | CIAP — ICMS credits on permanent assets (G001, G110) |
| H | Physical inventory (H005, H010) |
| K | Production and stock control (K100, K200) — industrial companies |
| 1 | Other information |
| 9 | File control and closing |

```python
from src.generators.efd_icms_ipi import GeradorEFDICMSIPI
gerador = GeradorEFDICMSIPI(periodo)
caminho = gerador.gerar("./output")
```

### EFD Contribuições (`src/generators/efd_contribuicoes.py`)

Layout version 006. PIS/COFINS digital bookkeeping.

Blocks: 0, C (documents), M (PIS/COFINS settlement — M100, M200, M600), 1, 9.

### ECD (`src/generators/ecd.py`)

Layout version 010. Digital accounting bookkeeping.

Includes default chart of accounts (50+ accounts), journal entries (I200/I250), balance sheet (J150).

### ECF (`src/generators/ecf.py`)

Layout version 009. Replaces the old DIPJ declaration.

| Block | Contents |
|-------|----------|
| 0 | Tax parameters (0010), accountant (0930) |
| L | LALUR/LACS adjustments (Lucro Real) |
| N | IRPJ/CSLL calculation (N620, N630) |
| P | Lucro Presumido quarterly breakdown |
| Y | Partner information (Y600) |

### NF-e (`src/generators/nfe_xml.py`)

NF-e XML v4.00, model 55. Full document with all fiscal groups:

- `ide` — identification with 44-digit access key (Módulo 11)
- `emit` / `dest` — emitter and recipient
- `det` — items with ICMS (CST 000–090), IPI, PIS, COFINS per item
- `total` / `transp` / `pag` — totals, transport, payment
- `AssinadorNFe` — RSA-SHA1 XMLDSig using PKCS#12 certificate

```python
from src.generators.nfe_xml import GeradorNFeXML, AssinadorNFe
gerador = GeradorNFeXML(emitente, destinatario, itens)
xml = gerador.gerar_xml()
xml_assinado = AssinadorNFe(cert_path, cert_password).assinar(xml)
```

### NFC-e (`src/generators/nfce_xml.py`)

NFC-e XML v4.00, model 65. Consumer invoice for POS/retail. Optional CPF identification, QR Code URL.

### CT-e (`src/generators/cte.py`)

CT-e XML v4.00, model 57. Freight transport fiscal document.

- Road modal (rodoviário) with RNTRC registration
- 44-digit access key (Módulo 11, model 57)
- ICMS calculation on freight service
- Referenced NF-e documents

### MDF-e (`src/generators/mdfe.py`)

MDF-e XML v3.00, model 58. Groups CT-e and NF-e documents in transport routes.

- Unload municipalities with referenced documents
- Driver registration
- Cargo insurance data
- 44-digit access key (Módulo 11, model 58)

### EFD-Reinf (`src/generators/efd_reinf.py`)

XML events for the EFD-Reinf (withholdings and social security information).

| Event | Description |
|-------|-------------|
| R-1000 | Employer registration |
| R-2010 | Services taken — INSS withholding |
| R-2020 | Services provided — INSS withholding |
| R-2060 | CPRB (payroll tax exemption) |
| R-2099 | Period closing |

### e-Social (`src/generators/esocial.py`)

XML events for Brazil's digital labor bookkeeping system.

| Event | Description |
|-------|-------------|
| S-1000 | Employer data table |
| S-1010 | Payroll items (rubricas) table — 16 standard CLT items |
| S-1200 | Monthly payroll (remuneração) |
| S-1299 | Monthly payroll closing |
| S-2200 | Employee admission |
| S-2299 | Employment termination (rescisão) |

### DCTF (`src/generators/dctf.py`)

XML for PGD DCTF Web. Monthly declaration of federal tax debits and credits.

```python
from src.generators.dctf import montar_dctf_do_periodo
gerador = montar_dctf_do_periodo(
    empresa=empresa,
    periodo="2024-01",
    valor_irpj=Decimal("5000"),
    valor_csll=Decimal("1800"),
    valor_pis=Decimal("650"),
    valor_cofins=Decimal("3000"),
)
caminho = gerador.salvar("./output")
print(gerador.relatorio_resumo())
```

---

## Annual Declarations

### DIRF (`src/generators/dirf.py`)

Annual declaration of income tax withheld at source (IRRF). Text file format for PGD DIRF.

**Deadline:** Last business day of February.

```python
from src.generators.dirf import GeradorDIRF, BeneficiarioDIRF, ResponsavelDIRF
gerador = GeradorDIRF(empresa, ano_calendario=2024, beneficiarios=[...], responsavel=...)
caminho = gerador.salvar("./output")
```

### DEFIS (`src/generators/defis.py`)

Annual fiscal information declaration for Simples Nacional companies. XML format for the Simples Nacional portal.

**Deadline:** March 31 of the following year.

```python
from src.generators.defis import GeradorDEFIS, ReceitaMensalDEFIS, SocioDEFIS
gerador = GeradorDEFIS(empresa, ano_calendario=2024, receitas_mensais=[...], socios=[...])
xml = gerador.gerar_xml()
print(gerador.relatorio_resumo())
```

### DeSTDA (`src/generators/destda.py`)

Monthly declaration of ICMS-ST, DIFAL, and tax anticipation for Simples Nacional companies.

**Deadline:** 20th of the following month.

```python
from src.generators.destda import GeradorDeSTDA, OperacaoSTDeSTDA
ops = [
    OperacaoSTDeSTDA("SP", "RJ", "ST",  base_calculo=Decimal("10000"),
                     aliquota=Decimal("18"), valor_imposto=Decimal("1800")),
    OperacaoSTDeSTDA("SP", "MG", "DIFAL", base_calculo=Decimal("5000"),
                     aliquota=Decimal("6"), valor_imposto=Decimal("300")),
]
gerador = GeradorDeSTDA(empresa, "2024-01", ops)
print(gerador.relatorio_resumo())
```

### GIA / GIA-ST — São Paulo (`src/generators/gia.py`)

Monthly ICMS information and settlement guide for São Paulo state. AIE pipe-delimited file format for SEFAZ-SP / SCANC.

**Deadline:** 20th of the following month (may vary by revenue tier).

```python
from src.generators.gia import GeradorGIA, ApuracaoGIA, ApuracaoGIAST
apuracao = ApuracaoGIA(
    debitos_operacoes_proprias=Decimal("50000"),
    creditos_entradas=Decimal("30000"),
)
gerador = GeradorGIA(empresa, "2024-01", apuracao, apuracoes_st=[
    ApuracaoGIAST("MG", Decimal("20000"), Decimal("12"), Decimal("2400")),
])
caminho = gerador.salvar("./output")   # → GIA_CNPJ_2024-01.aie
```

---

## SEFAZ Transmitter

### NF-e (`src/transmitters/receita_federal.py`)

```python
from src.transmitters.receita_federal import TransmissorNFe

transmissor = TransmissorNFe(uf="SP", ambiente="2")  # ambiente 2=homologação

# Check service availability
status = transmissor.verificar_status_servico()

# Submit NF-e for authorization
resultado = transmissor.autorizar_nfe(xml_assinado)
print(resultado.protocolo)   # authorization protocol

# Cancel NF-e
resultado = transmissor.cancelar_nfe(chave, protocolo, justificativa)
```

SOAP endpoints: SP (SEFAZ-SP), SVRS (other states), SVAN (national contingency).

### SPED Local Validator

```python
from src.transmitters.receita_federal import TransmissorSPEDLocal, ValidadorArquivoSPED

# Validates required records and line counts
valido, erros = ValidadorArquivoSPED().validar(caminho_arquivo)

# Prepares file for PGE (Java program) transmission
resultado = TransmissorSPEDLocal("./output").preparar_efd_icms_ipi(caminho)
```

> **Note:** EFD ICMS/IPI, EFD Contribuições, and ECD files must be transmitted through the Receita Federal's local PGE/Validador program — direct HTTP upload is not supported for SPED. Only NF-e uses direct SEFAZ SOAP webservices.

---

## Training the Model

The `TransformerFiscal` ships with random weights. Use `TrainerFiscal` to train it on the built-in dataset (173 labeled examples) or your own data.

```python
from src import PipelineFiscal

pipeline = PipelineFiscal()

# Train with built-in examples
history = pipeline.treinar(
    epochs=50,                          # early stopping kicks in before if val_loss plateaus
    caminho_saida="./checkpoints/fiscal_llm.pt",
)

# Load trained model
pipeline = PipelineFiscal(caminho_modelo="./checkpoints/fiscal_llm.pt")

# Evaluate per-class accuracy
from src.models.trainer import TrainerFiscal, EXEMPLOS_CLASSIFICACAO
from src.models.fiscal_llm import TokenizadorFiscal, TransformerFiscal, CLASSES_OBRIGACAO

tokenizador = TokenizadorFiscal()
trainer = TrainerFiscal(pipeline.modelo, tokenizador)
metricas = trainer.avaliar_por_classe(EXEMPLOS_CLASSIFICACAO)
print(f"Overall accuracy: {metricas['acuracia_geral']:.1%}")
```

**Training configuration:**

| Parameter | Default |
|-----------|---------|
| Epochs | 50 |
| Optimizer | AdamW |
| Learning rate | 3e-4 (OneCycleLR) |
| Batch size | 16 |
| Gradient clipping | 1.0 |
| Val split | 15% |
| Early stopping patience | 8 epochs |
| Class weights | Enabled (inverse frequency) |

---

## Running Tests

```bash
pip install pytest pytest-asyncio
python -m pytest tests/ -v
```

**117 tests** covering all components:

| Module | Tests |
|--------|-------|
| ICMS calculator | 9 |
| IPI calculator | 6 |
| PIS/COFINS calculator | 6 |
| IRPJ/CSLL calculator | 7 |
| ISS calculator | 5 |
| Simples Nacional calculator | 9 |
| SPED writer | 3 |
| EFD ICMS/IPI (incl. Blocks G+K) | 10 |
| EFD Contribuições | 3 |
| ECD | 5 |
| ECF | 3 |
| NF-e | 6 |
| NFC-e | 4 |
| CT-e | 4 |
| MDF-e | 4 |
| EFD-Reinf | 3 |
| e-Social | 3 |
| DCTF | 5 |
| DIRF | 4 |
| DEFIS | 5 |
| DeSTDA | 5 |
| GIA | 5 |

---

## Fiscal Calendar

| Obligation | Frequency | Deadline |
|-----------|-----------|----------|
| DAS (Simples Nacional) | Monthly | Day 20 of following month |
| DeSTDA (ICMS-ST Simples) | Monthly | Day 20 of following month |
| GIA-SP | Monthly | Day 20 of following month |
| EFD ICMS/IPI | Monthly | 15th business day of following month |
| DCTF | Monthly | 15th business day of 2nd following month |
| EFD Contribuições | Monthly | 10th business day of 2nd following month |
| EFD-Reinf | Monthly | Day 15 of following month |
| e-Social (payroll) | Monthly | Day 7 of following month |
| ECD | Annual | Last business day of June |
| DEFIS (Simples Nacional) | Annual | March 31 |
| ECF | Annual | Last business day of July |
| DIRF | Annual | Last business day of February |

---

---

# Português Brasileiro

## Visão Geral

O **LLM Fiscal Brasileiro** é uma biblioteca Python 3.12 que combina um **Transformer PyTorch** customizado com um conjunto completo de ferramentas de compliance tributário brasileiro. O sistema é projetado para ser consumido como biblioteca por qualquer aplicação — não há CLI ou interface gráfica embutida.

O sistema cobre o ciclo de vida completo das obrigações fiscais brasileiras:

- **Classificação de intenção** de consultas fiscais em linguagem natural (16 classes de obrigações)
- **RAG (Geração Aumentada por Recuperação)** com 25 documentos de conhecimento fiscal indexados
- **Calculadoras tributárias** para todos os principais tributos brasileiros (ICMS, IPI, PIS/COFINS, IRPJ/CSLL, ISS, Simples Nacional)
- **Geradores de arquivos SPED** para todas as obrigações de escrituração digital federal
- **Geradores de documentos eletrônicos** (NF-e, NFC-e, CT-e, MDF-e) com assinatura digital
- **Transmissor SOAP SEFAZ** para autorização de NF-e

O ponto de entrada único é o `PipelineFiscal`, que orquestra todos os componentes.

---

## Arquitetura

```
┌──────────────────────────────────────────────────────────────────┐
│                        PipelineFiscal                            │
│  (src/models/fiscal_llm.py)                                      │
│                                                                  │
│  ┌─────────────────────┐   ┌──────────────────────────────────┐  │
│  │  TransformerFiscal  │   │   BancoEmbeddingsFiscais (RAG)   │  │
│  │  PyTorch encoder    │   │   25 documentos de conhecimento  │  │
│  │  4 camadas, d=256   │   │   busca por similaridade cosseno │  │
│  │  8 cabeças, Pre-LN  │   └──────────────────────────────────┘  │
│  └─────────────────────┘                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │         Classificação de Intenção (16 classes)              │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐  │
│  │   Calculadoras   │  │ Geradores SPED   │  │  DFe / XML    │  │
│  │  ICMS · IPI      │  │  EFD ICMS/IPI   │  │  NF-e · NFC-e │  │
│  │  PIS/COFINS      │  │  EFD Contribu.  │  │  CT-e · MDF-e │  │
│  │  IRPJ/CSLL · ISS │  │  ECD · ECF      │  │  EFD-Reinf    │  │
│  │  Simples Nac.    │  │  DCTF · GIA     │  │  e-Social     │  │
│  └──────────────────┘  │  DIRF · DEFIS   │  └───────────────┘  │
│                         │  DeSTDA         │                     │
│                         └──────────────────┘                     │
└──────────────────────────────────────────────────────────────────┘
```

**Decisões de design:**
- O LLM usa tokenização em nível de caractere — sem dependência de tokenizador externo.
- O RAG roda inteiramente em memória usando similaridade cosseno nos embeddings CLS.
- Todos os valores monetários usam `Decimal` Python com `ROUND_HALF_UP` — zero aritmética de ponto flutuante.
- Arquivos SPED são pipe-delimitados (`|REGISTRO|CAMPO1|`) em UTF-8, seguindo a especificação oficial da Receita Federal.
- NF-e/CT-e/MDF-e usam XML v4.00 com assinaturas digitais RSA-SHA1 XMLDSig via biblioteca `cryptography`.

---

## Estrutura do Projeto

```
llm-speed/
├── src/
│   ├── __init__.py                  # Exporta PipelineFiscal
│   ├── fiscal/
│   │   ├── entities.py              # Modelos Pydantic v2 (Empresa, NotaFiscal, …)
│   │   └── constants.py             # Alíquotas, tabelas CST, CFOPs, prazos
│   ├── calculators/
│   │   ├── icms.py                  # ICMS (próprio + ST + DIFAL + FCP)
│   │   ├── ipi.py                   # IPI (alíquotas TIPI por capítulo NCM)
│   │   ├── pis_cofins.py            # PIS/COFINS (cumulativo + não cumulativo + retenção)
│   │   ├── irpj_csll.py             # IRPJ/CSLL (Lucro Real + Lucro Presumido + estimativa)
│   │   ├── iss.py                   # ISS (LC 116/2003 + anexos Simples Nacional)
│   │   └── simples_nacional.py      # Simples Nacional (5 anexos, Fator R, PGDAS-D, MEI)
│   ├── generators/
│   │   ├── sped_writer.py           # Escritor base SPED pipe-delimitado
│   │   ├── efd_icms_ipi.py          # EFD ICMS/IPI (blocos 0,C,E,G,H,K,1,9)
│   │   ├── efd_contribuicoes.py     # EFD Contribuições PIS/COFINS (blocos 0,C,M,1,9)
│   │   ├── ecd.py                   # ECD — Escrituração Contábil Digital
│   │   ├── ecf.py                   # ECF — Escrituração Contábil Fiscal (LALUR/LACS)
│   │   ├── nfe_xml.py               # NF-e XML v4.00 (modelo 55) + assinatura digital
│   │   ├── nfce_xml.py              # NFC-e XML v4.00 (modelo 65, consumidor/PDV)
│   │   ├── cte.py                   # CT-e XML v4.00 (modelo 57, transporte)
│   │   ├── mdfe.py                  # MDF-e XML v3.00 (manifesto, modelo 58)
│   │   ├── efd_reinf.py             # EFD-Reinf XML eventos (R-1000…R-2099)
│   │   ├── esocial.py               # e-Social XML eventos (S-1000…S-1299, S-2200, S-2299)
│   │   ├── dctf.py                  # DCTF XML (declaração de débitos tributários federais)
│   │   ├── dirf.py                  # DIRF arquivo texto (declaração anual IRRF)
│   │   ├── defis.py                 # DEFIS XML (declaração anual Simples Nacional)
│   │   ├── destda.py                # DeSTDA XML (ICMS-ST/DIFAL mensal Simples Nacional)
│   │   └── gia.py                   # GIA/GIA-ST arquivo AIE (ICMS mensal São Paulo)
│   ├── models/
│   │   ├── fiscal_llm.py            # TransformerFiscal + RAG + PipelineFiscal
│   │   └── trainer.py               # TrainerFiscal (173 exemplos, early stopping, pesos por classe)
│   └── transmitters/
│       └── receita_federal.py       # Transmissor NF-e SOAP SEFAZ + validador SPED local
├── tests/
│   ├── test_calculators.py          # 43 testes das calculadoras tributárias
│   └── test_generators.py           # 74 testes dos geradores
├── pyproject.toml
└── requirements.txt
```

---

## Instalação

**Requisitos:** Python 3.12+, pip

```bash
# Clonar o repositório
git clone <repo-url>
cd llm-speed

# Criar e ativar ambiente virtual
python -m venv venv
source venv/bin/activate        # Linux/macOS
# venv\Scripts\activate         # Windows

# Instalar dependências
pip install -r requirements.txt
```

**Dependências principais:**

| Pacote | Finalidade |
|--------|-----------|
| `torch>=2.3.0` | Modelo TransformerFiscal + treinamento |
| `pydantic>=2.7.0` | Modelos de dados fiscais validados |
| `cryptography>=42.0.0` | Assinatura digital NF-e/CT-e (RSA-SHA1) |
| `lxml>=5.2.0` | Canonicalização C14N para XMLDSig |
| `httpx>=0.27.0` | Cliente HTTP SOAP SEFAZ |
| `zeep>=4.2.1` | Auxiliares para envelope SOAP |
| `python-dateutil>=2.9.0` | Cálculos de calendário fiscal brasileiro |

---

## Início Rápido

```python
from src import PipelineFiscal

# Instanciar o pipeline LLM (pesos aleatórios até ser treinado)
pipeline = PipelineFiscal(diretorio_saida="./output")

# --- Processamento em linguagem natural ---
resultado = pipeline.processar(
    "calcule o ICMS de uma venda",
    {"valor_mercadoria": 10000, "aliquota": 18, "uf_origem": "SP", "uf_destino": "RJ"}
)
print(resultado.resumo())
# [calcular_icms]
#   base_calculo: R$ 10.000,00
#   valor_icms:   R$ 1.800,00
#   valor_total_icms: R$ 1.800,00

# --- Cálculo direto de tributos ---
r = pipeline.calcular_pis_cofins({
    "valor": 100000,
    "regime": "lucro_presumido",
})
print(r["pis_a_recolher"])    # 650.00
print(r["cofins_a_recolher"]) # 3000.00

# --- Gerar obrigações SPED do período ---
from src.fiscal.entities import PeriodoApuracao, Empresa, ...
periodo = PeriodoApuracao(...)
arquivos = pipeline.gerar_obrigacoes(periodo)
# Retorna: {"EFD_ICMS_IPI": ResultadoFiscal, "EFD_CONTRIBUICOES": ..., ...}

# --- Verificar status SEFAZ ---
status = pipeline.verificar_sefaz(uf="SP")
print(status["mensagem"])
```

---

## Modelo LLM

### TransformerFiscal

Encoder Transformer compacto treinado para classificação de intenção fiscal brasileira.

| Parâmetro | Valor |
|-----------|-------|
| Arquitetura | Transformer Encoder (Pre-LN) |
| Camadas | 4 |
| d_model | 256 |
| Cabeças de atenção | 8 |
| Dimensão FFN | 1.024 |
| Tokenizador | Nível de caractere (vocab ~200 chars) |
| Comprimento máximo de sequência | 1.024 tokens |
| Classes de saída | 16 tipos de obrigação fiscal |

**16 Classes de Intenção:**

| Classe | Descrição |
|--------|-----------|
| `EFD_ICMS_IPI` | Gerar EFD ICMS/IPI |
| `EFD_CONTRIBUICOES` | Gerar EFD Contribuições (PIS/COFINS) |
| `ECD` | Gerar Escrituração Contábil Digital |
| `ECF` | Gerar Escrituração Contábil Fiscal |
| `NFe` | Emitir/cancelar NF-e ou NFC-e |
| `NFSe` | Emitir NFS-e (nota de serviço municipal) |
| `CTe` | Gerar CT-e (conhecimento de transporte) |
| `eSocial` | Gerar eventos e-Social (folha/admissão) |
| `EFD_REINF` | Gerar eventos EFD-Reinf (retenções) |
| `DCTF` | Gerar DCTF (débitos tributários federais) |
| `PGDAS` | Calcular DAS Simples Nacional / PGDAS-D |
| `calculo_icms` | Calcular ICMS de uma operação |
| `calculo_ipi` | Calcular IPI de produto industrializado |
| `calculo_pis_cofins` | Calcular PIS e COFINS sobre receitas |
| `calculo_irpj_csll` | Calcular IRPJ e CSLL (tributos corporativos) |
| `calculo_iss` | Calcular ISS (imposto municipal sobre serviços) |

### Base de Conhecimento RAG

`BancoEmbeddingsFiscais` indexa 25 documentos de conhecimento fiscal cobrindo todas as principais obrigações, alíquotas, prazos e legislação. A recuperação usa similaridade cosseno nos embeddings do token CLS.

```python
# Acesso direto ao RAG
pipeline.rag.buscar("prazo EFD ICMS IPI", top_k=3)
# Retorna: [(texto, score_similaridade), ...]
```

---

## Calculadoras Tributárias

Todas as calculadoras estão disponíveis via `PipelineFiscal` ou importadas de `src.calculators.*`. Todos os valores monetários usam `Decimal` com `ROUND_HALF_UP`.

### ICMS (`src/calculators/icms.py`)

```python
resultado = pipeline.calcular_icms({
    "valor_mercadoria": 10000,
    "aliquota": 18,              # alíquota interna (%)
    "uf_origem": "SP",
    "uf_destino": "RJ",
    "frete": 500,
    "cst": "000",                # CST: 000=tributado, 020=redução, 040=isento, 060=ST
    "calcular_difal": False,
    "consumidor_final": False,
    # Parâmetros opcionais ST:
    # "calcular_st": True, "mva": 40, "aliq_interna_destino": 18
})
```

Suporta: CST 000/010/020/030/040/041/050/051/060/070, ICMS-ST com MVA, FCP (Fundo de Combate à Pobreza), DIFAL (EC 87/2015).

### IPI (`src/calculators/ipi.py`)

```python
resultado = pipeline.calcular_ipi({
    "valor_produtos": 5000,
    "aliquota": 10,
    "cst": "50",   # 50=tributado, 52=isento, 54=suspenso
    "frete": 200,
})
```

Inclui alíquotas TIPI por capítulo NCM (0% farmacêuticos, 25% veículos, 300% cigarro).

### PIS/COFINS (`src/calculators/pis_cofins.py`)

```python
resultado = pipeline.calcular_pis_cofins({
    "valor": 100000,
    "regime": "lucro_real",      # ou "lucro_presumido"
    "receitas": [
        {"descricao": "Vendas", "valor": 100000, "cst_pis": "01", "cst_cofins": "01"}
    ],
})
```

| Regime | PIS | COFINS |
|--------|-----|--------|
| Lucro Presumido (cumulativo) | 0,65% | 3,00% |
| Lucro Real (não cumulativo) | 1,65% | 7,60% |

Suporta créditos sobre compras, energia, aluguéis, depreciação (Leis 10.637/2002 e 10.833/2003).

### IRPJ / CSLL (`src/calculators/irpj_csll.py`)

```python
resultado = pipeline.calcular_irpj_csll({
    "valor": 500000,             # Lucro Real: lucro líquido / Lucro Presumido: receita bruta
    "regime": "lucro_presumido", # ou "lucro_real"
    "atividade": "venda_mercadorias",  # ou "servicos_em_geral", "intermediacao"
})
```

| Regra | Valor |
|-------|-------|
| IRPJ alíquota base | 15% |
| IRPJ adicional | +10% sobre lucro > R$ 20.000/mês |
| CSLL alíquota | 9% (geral) / 15% (financeiras) |
| Lucro Presumido — comércio/indústria | 8% da receita |
| Lucro Presumido — serviços | 32% da receita |
| Limite compensação prejuízos | 30% do lucro tributável |

### ISS (`src/calculators/iss.py`)

```python
resultado = pipeline.calcular_iss({
    "valor_servico": 10000,
    "codigo_servico": "17",      # código da LC 116/2003
    "aliquota": 3,               # alíquota municipal (2%–5%)
    "retencao_fonte": True,
})
```

### Simples Nacional (`src/calculators/simples_nacional.py`)

```python
# Cálculo do DAS para uma atividade
resultado = pipeline.calcular_simples({
    "receita_mes": 50000,
    "rbt12": 600000,   # receita acumulada 12 meses
    "anexo": "I",      # I=comércio, II=indústria, III-V=serviços
})

# PGDAS-D completo com múltiplas atividades
resultado = pipeline.calcular_pgdas({
    "periodo": "2024-01",
    "rbt12": 600000,
    "atividades": [
        {"tipo": "comercio", "receita": 30000},
        {"tipo": "servicos_advocacia", "receita": 20000},
    ],
})
```

Cobre todos os 5 anexos (6 faixas cada), cálculo do Fator R para Anexo III vs V, e valores fixos do MEI.

---

## Geradores SPED / DFe

### EFD ICMS/IPI (`src/generators/efd_icms_ipi.py`)

Layout versão 017. Gera todos os blocos obrigatórios:

| Bloco | Conteúdo |
|-------|----------|
| 0 | Identificação do estabelecimento, participantes (0150), produtos (0200) |
| C | Registros NF-e (C100, C110, C170, C190) |
| E | Apuração ICMS (E110), apuração IPI (E520) |
| G | CIAP — crédito ICMS sobre ativo permanente (G001, G110) |
| H | Inventário físico (H005, H010) |
| K | Controle de produção e estoque (K100, K200) — indústrias |
| 1 | Outras informações |
| 9 | Controle e encerramento do arquivo |

```python
from src.generators.efd_icms_ipi import GeradorEFDICMSIPI
gerador = GeradorEFDICMSIPI(periodo)
caminho = gerador.gerar("./output")
```

### EFD Contribuições (`src/generators/efd_contribuicoes.py`)

Layout versão 006. Escrituração digital de PIS/COFINS.

Blocos: 0, C (documentos), M (apuração PIS/COFINS — M100, M200, M600), 1, 9.

### ECD (`src/generators/ecd.py`)

Layout versão 010. Escrituração contábil digital.

Inclui plano de contas padrão (50+ contas), lançamentos (I200/I250), balanço (J150).

### ECF (`src/generators/ecf.py`)

Layout versão 009. Substitui a DIPJ.

| Bloco | Conteúdo |
|-------|----------|
| 0 | Parâmetros fiscais (0010), contador (0930) |
| L | Ajustes LALUR/LACS (Lucro Real) |
| N | Cálculo IRPJ/CSLL (N620, N630) |
| P | Lucro Presumido por trimestre |
| Y | Quadro societário (Y600) |

### NF-e (`src/generators/nfe_xml.py`)

NF-e XML v4.00, modelo 55. Documento completo com todos os grupos fiscais:

- `ide` — identificação com chave de acesso 44 dígitos (Módulo 11)
- `emit` / `dest` — emitente e destinatário
- `det` — itens com ICMS (CST 000–090), IPI, PIS, COFINS por item
- `total` / `transp` / `pag` — totais, transporte, pagamento
- `AssinadorNFe` — assinatura RSA-SHA1 XMLDSig com certificado PKCS#12

```python
from src.generators.nfe_xml import GeradorNFeXML, AssinadorNFe
gerador = GeradorNFeXML(emitente, destinatario, itens)
xml = gerador.gerar_xml()
xml_assinado = AssinadorNFe(cert_path, cert_password).assinar(xml)
```

### NFC-e (`src/generators/nfce_xml.py`)

NFC-e XML v4.00, modelo 65. Nota do consumidor para PDV/varejo. Identificação do CPF opcional, URL QR Code.

### CT-e (`src/generators/cte.py`)

CT-e XML v4.00, modelo 57. Documento fiscal para transporte de carga.

- Modal rodoviário com registro RNTRC
- Chave de acesso 44 dígitos (Módulo 11, modelo 57)
- Cálculo do ICMS sobre o serviço de transporte
- Documentos NF-e referenciados

### MDF-e (`src/generators/mdfe.py`)

MDF-e XML v3.00, modelo 58. Agrupa CT-e e NF-e em rotas de transporte.

- Municípios de descarga com documentos referenciados
- Cadastro de condutores
- Dados do seguro de carga
- Chave de acesso 44 dígitos (Módulo 11, modelo 58)

### EFD-Reinf (`src/generators/efd_reinf.py`)

Eventos XML para o EFD-Reinf (retenções e informações previdenciárias).

| Evento | Descrição |
|--------|-----------|
| R-1000 | Cadastro do empregador |
| R-2010 | Serviços tomados — retenção INSS |
| R-2020 | Serviços prestados — retenção INSS |
| R-2060 | CPRB (contribuição previdenciária sobre receita bruta) |
| R-2099 | Fechamento do período |

### e-Social (`src/generators/esocial.py`)

Eventos XML para o sistema de escrituração digital trabalhista brasileiro.

| Evento | Descrição |
|--------|-----------|
| S-1000 | Dados do empregador |
| S-1010 | Tabela de rubricas — 16 itens CLT padrão |
| S-1200 | Remuneração mensal (folha de pagamento) |
| S-1299 | Fechamento da folha mensal |
| S-2200 | Admissão de empregado |
| S-2299 | Desligamento (rescisão contratual) |

### DCTF (`src/generators/dctf.py`)

XML para o PGD DCTF Web. Declaração mensal de débitos e créditos tributários federais.

```python
from src.generators.dctf import montar_dctf_do_periodo
gerador = montar_dctf_do_periodo(
    empresa=empresa,
    periodo="2024-01",
    valor_irpj=Decimal("5000"),
    valor_csll=Decimal("1800"),
    valor_pis=Decimal("650"),
    valor_cofins=Decimal("3000"),
)
caminho = gerador.salvar("./output")
print(gerador.relatorio_resumo())
```

---

## Declarações Anuais

### DIRF (`src/generators/dirf.py`)

Declaração anual do imposto de renda retido na fonte. Arquivo texto para o PGD DIRF.

**Prazo:** Último dia útil de fevereiro.

```python
from src.generators.dirf import GeradorDIRF, BeneficiarioDIRF, ResponsavelDIRF
gerador = GeradorDIRF(empresa, ano_calendario=2024, beneficiarios=[...], responsavel=...)
caminho = gerador.salvar("./output")
```

### DEFIS (`src/generators/defis.py`)

Declaração de informações socioeconômicas e fiscais para empresas do Simples Nacional. XML para o portal do Simples Nacional.

**Prazo:** 31 de março do ano seguinte.

```python
from src.generators.defis import GeradorDEFIS, ReceitaMensalDEFIS, SocioDEFIS
gerador = GeradorDEFIS(empresa, ano_calendario=2024, receitas_mensais=[...], socios=[...])
xml = gerador.gerar_xml()
print(gerador.relatorio_resumo())
```

### DeSTDA (`src/generators/destda.py`)

Declaração mensal de substituição tributária, diferencial de alíquota e antecipação para empresas do Simples Nacional.

**Prazo:** Dia 20 do mês seguinte.

```python
from src.generators.destda import GeradorDeSTDA, OperacaoSTDeSTDA
ops = [
    OperacaoSTDeSTDA("SP", "RJ", "ST",    base_calculo=Decimal("10000"),
                     aliquota=Decimal("18"), valor_imposto=Decimal("1800")),
    OperacaoSTDeSTDA("SP", "MG", "DIFAL", base_calculo=Decimal("5000"),
                     aliquota=Decimal("6"),  valor_imposto=Decimal("300")),
]
gerador = GeradorDeSTDA(empresa, "2024-01", ops)
print(gerador.relatorio_resumo())
```

### GIA / GIA-ST — São Paulo (`src/generators/gia.py`)

Guia de informação e apuração do ICMS mensal para o estado de São Paulo. Arquivo AIE pipe-delimitado para SEFAZ-SP / SCANC.

**Prazo:** Dia 20 do mês seguinte (pode variar por faixa de faturamento).

```python
from src.generators.gia import GeradorGIA, ApuracaoGIA, ApuracaoGIAST
apuracao = ApuracaoGIA(
    debitos_operacoes_proprias=Decimal("50000"),
    creditos_entradas=Decimal("30000"),
)
gerador = GeradorGIA(empresa, "2024-01", apuracao, apuracoes_st=[
    ApuracaoGIAST("MG", Decimal("20000"), Decimal("12"), Decimal("2400")),
])
caminho = gerador.salvar("./output")   # → GIA_CNPJ_2024-01.aie
```

---

## Transmissor SEFAZ

### NF-e (`src/transmitters/receita_federal.py`)

```python
from src.transmitters.receita_federal import TransmissorNFe

transmissor = TransmissorNFe(uf="SP", ambiente="2")  # ambiente 2=homologação

# Verificar disponibilidade do serviço
status = transmissor.verificar_status_servico()

# Transmitir NF-e para autorização
resultado = transmissor.autorizar_nfe(xml_assinado)
print(resultado.protocolo)   # protocolo de autorização

# Cancelar NF-e
resultado = transmissor.cancelar_nfe(chave, protocolo, justificativa)
```

Endpoints SOAP: SP (SEFAZ-SP), SVRS (demais estados), SVAN (contingência nacional).

### Validador SPED Local

```python
from src.transmitters.receita_federal import TransmissorSPEDLocal, ValidadorArquivoSPED

# Valida presença de registros obrigatórios e contagem de linhas
valido, erros = ValidadorArquivoSPED().validar(caminho_arquivo)

# Prepara arquivo para transmissão via PGE (programa Java)
resultado = TransmissorSPEDLocal("./output").preparar_efd_icms_ipi(caminho)
```

> **Observação:** Os arquivos EFD ICMS/IPI, EFD Contribuições e ECD devem ser transmitidos pelo programa PGE/Validador da Receita Federal — não há upload HTTP direto para o SPED. Apenas a NF-e usa webservices SOAP diretos da SEFAZ.

---

## Treinamento do Modelo

O `TransformerFiscal` é iniciado com pesos aleatórios. Use o `TrainerFiscal` para treiná-lo com o dataset built-in (173 exemplos rotulados) ou seus próprios dados.

```python
from src import PipelineFiscal

pipeline = PipelineFiscal()

# Treinar com os exemplos built-in
historico = pipeline.treinar(
    epochs=50,                          # early stopping pode parar antes se val_loss parar de melhorar
    caminho_saida="./checkpoints/fiscal_llm.pt",
)

# Carregar modelo treinado
pipeline = PipelineFiscal(caminho_modelo="./checkpoints/fiscal_llm.pt")

# Avaliar acurácia por classe
from src.models.trainer import TrainerFiscal, EXEMPLOS_CLASSIFICACAO
from src.models.fiscal_llm import TokenizadorFiscal

tokenizador = TokenizadorFiscal()
trainer = TrainerFiscal(pipeline.modelo, tokenizador)
metricas = trainer.avaliar_por_classe(EXEMPLOS_CLASSIFICACAO)
print(f"Acurácia geral: {metricas['acuracia_geral']:.1%}")
for classe, acc in metricas["acuracia_por_classe"].items():
    print(f"  {classe}: {acc:.1%}")
```

**Configuração de treinamento:**

| Parâmetro | Padrão |
|-----------|--------|
| Épocas | 50 |
| Otimizador | AdamW |
| Learning rate | 3e-4 (OneCycleLR) |
| Batch size | 16 |
| Gradient clipping | 1,0 |
| Divisão validação | 15% |
| Paciência early stopping | 8 épocas |
| Pesos por classe | Habilitado (frequência inversa) |

---

## Execução dos Testes

```bash
pip install pytest pytest-asyncio
python -m pytest tests/ -v
```

**117 testes** cobrindo todos os componentes:

| Módulo | Testes |
|--------|--------|
| Calculadora ICMS | 9 |
| Calculadora IPI | 6 |
| Calculadora PIS/COFINS | 6 |
| Calculadora IRPJ/CSLL | 7 |
| Calculadora ISS | 5 |
| Simples Nacional | 9 |
| Escritor SPED | 3 |
| EFD ICMS/IPI (incl. Blocos G+K) | 10 |
| EFD Contribuições | 3 |
| ECD | 5 |
| ECF | 3 |
| NF-e | 6 |
| NFC-e | 4 |
| CT-e | 4 |
| MDF-e | 4 |
| EFD-Reinf | 3 |
| e-Social | 3 |
| DCTF | 5 |
| DIRF | 4 |
| DEFIS | 5 |
| DeSTDA | 5 |
| GIA | 5 |

---

## Calendário Fiscal

| Obrigação | Periodicidade | Prazo |
|-----------|--------------|-------|
| DAS (Simples Nacional) | Mensal | Dia 20 do mês seguinte |
| DeSTDA (ICMS-ST Simples) | Mensal | Dia 20 do mês seguinte |
| GIA-SP | Mensal | Dia 20 do mês seguinte |
| EFD ICMS/IPI | Mensal | 15º dia útil do mês seguinte |
| DCTF | Mensal | 15º dia útil do 2º mês seguinte |
| EFD Contribuições | Mensal | 10º dia útil do 2º mês seguinte |
| EFD-Reinf | Mensal | Dia 15 do mês seguinte |
| e-Social (folha) | Mensal | Dia 7 do mês seguinte |
| ECD | Anual | Último dia útil de junho |
| DEFIS (Simples Nacional) | Anual | 31 de março |
| ECF | Anual | Último dia útil de julho |
| DIRF | Anual | Último dia útil de fevereiro |

---

*Sistema desenvolvido em Python 3.12 com PyTorch para o ecossistema fiscal brasileiro (SPED).*
*117 testes · 20 obrigações cobertas · 6 tributos calculados*