Speed / README.md

Building Speed LLM

eea7ef1 15 days ago

51.6 kB

	---
	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