Tools agenticas (agentic)¶
Ferramentas de alto nivel orientadas a agentes de IA.
O modulo agentic reune tools compostas que combinam multiplos clientes
de baixo nivel (cnpj, simples, cnae, certidoes, nfe, sped) em respostas
estruturadas otimizadas para uso por LLMs (Claude, GPT, Gemini).
Cada tool expoe: - Inputs simples (CNPJ, XML path, lista de fornecedores) - Outputs ricos via pydantic (campos auto-documentados) - Docstrings detalhadas com exemplos
SimulacaoReformaResult ¶
Bases: BaseModel
Resultado da simulacao de transicao da Reforma Tributaria (LC 214/2025).
Apresenta a carga tributaria estimada ano a ano (2026-2033), mostrando o blend entre os tributos do regime antigo (ICMS/ISS e PIS/COFINS) e os novos (CBS e IBS), conforme o cronograma de transicao da LC 214/2025.
ComplianceReport ¶
Bases: BaseModel
Relatorio agregado de compliance fiscal de um CNPJ.
Combina dados de CNPJ, Simples Nacional, MEI, CNAE e certidoes em uma visao unica orientada a decisão (contratar, recusar, investigar).
NFeValidationReport ¶
Bases: BaseModel
Relatorio completo de validação de uma NFe (XML).
SPEDSummary ¶
Bases: BaseModel
Sumario executivo de um arquivo SPED.
SupplierRiskBatchItem ¶
Bases: BaseModel
Resultado por fornecedor em avaliação em lote.
SupplierRiskBatchResult ¶
Bases: BaseModel
Resultado consolidado da consulta de múltiplos CNPJs.
SupplierRiskScore ¶
Bases: BaseModel
Score de risco de um fornecedor para due diligence.
TaxRegimeComparison ¶
Bases: BaseModel
Comparativo entre regimes tributarios para um cenário.
analyze_cnpj_compliance
async
¶
Analise consolidada de compliance fiscal de um CNPJ brasileiro.
Consulta em paralelo: dados cadastrais (Receita), regime Simples Nacional, status MEI, CNAE principal e secundarios. Retorna um relatório unico com score 0-100, risco classificado e achados acionaveis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cnpj
|
str
|
CNPJ com ou sem formatacao (so digitos são usados). |
required |
Returns:
| Type | Description |
|---|---|
ComplianceReport
|
ComplianceReport com risco_geral, score, achados e resumo executivo. |
Exemplo de uso por um agente
report = await analyze_cnpj_compliance("12.345.678/0001-90") if report.risco_geral in ("alto", "critico"): # bloquear cadastro de fornecedor ...
Nota
Esta tool NAO consulta certidoes negativas reais (somente gera URLs). Para validação de certidoes use as ferramentas especificas do modulo certidoes.
validate_nfe_full
async
¶
Validacao consolidada de uma NFe (XML).
Executa em sequencia: 1. Parse estrutural do XML (lxml) 2. Validacao do digito verificador da chave de acesso 3. Verificacao do CNPJ emissor (situacao ativa via Receita)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xml_path
|
str | Path
|
Caminho para arquivo XML da NFe. |
required |
Returns:
| Type | Description |
|---|---|
NFeValidationReport
|
NFeValidationReport com chave, validade, issues e resumo. |
Exemplo
report = await validate_nfe_full("/tmp/nota.xml") if not report.valida_estruturalmente or report.issues: # rejeitar nota ...
simular_transicao_reforma_tributaria ¶
simular_transicao_reforma_tributaria(faturamento_anual, setor, regime_atual, aliquota_icms_atual=None, aliquota_iss_atual=None, aliquota_pis_cofins=None)
Simula o impacto da transicao da Reforma Tributaria (LC 214/2025) de 2026 a 2033.
Para cada ano, estima (a) a carga do regime antigo (PIS/COFINS + ICMS ou ISS), ja ajustada pela reducao proporcional do cronograma, e (b) a carga do regime novo (CBS + IBS), aplicando as aliquotas de referencia na fracao de transicao prevista pela LC 214/2025.
Cronograma (LC 214/2025, arts. 337, 343, 346): - 2026: fase de teste - CBS 0,9% + IBS 0,1%, compensavel, impacto liquido ~zero. - 2027-2028: CBS plena (ref. ~8,8%) substitui PIS/COFINS; ICMS/ISS integrais. - 2029: IBS assume 10% da carga de referencia; ICMS/ISS recuam para 90%. - 2030: IBS 20%; ICMS/ISS 80%. - 2031: IBS 30%; ICMS/ISS 70%. - 2032: IBS 40%; ICMS/ISS 60%. - 2033: IBS pleno (ref. ~17,7%); ICMS e ISS extintos.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
faturamento_anual
|
float
|
Receita bruta anual em reais. Deve ser positivo. |
required |
setor
|
Literal['comércio', 'serviços', 'indústria']
|
Setor da empresa. Determina o tributo estadual/municipal aplicavel. - "comércio": usa ICMS (aliquota_icms_atual ou 12% se omitido). - "indústria": usa ICMS (mesma logica). - "serviços": usa ISS (aliquota_iss_atual ou 5% se omitido). |
required |
regime_atual
|
Literal['Simples Nacional', 'Lucro Presumido', 'Lucro Real']
|
Regime tributario federal vigente. Determina a aliquota de PIS/COFINS assumida quando aliquota_pis_cofins nao e informada. - "Simples Nacional": PIS/COFINS embutido no DAS; estimativa 3,65%. - "Lucro Presumido": regime cumulativo PIS 0,65% + COFINS 3% = 3,65%. - "Lucro Real": regime nao-cumulativo 1,65% + 7,6% = 9,25%. |
required |
aliquota_icms_atual
|
float | None
|
Aliquota do ICMS em %, declarada pelo usuario (varia por UF). Obrigatoria para precisao maxima em comercio/industria. Se None, assume 12%. |
None
|
aliquota_iss_atual
|
float | None
|
Aliquota do ISS em %, declarada pelo usuario (varia por municipio). Obrigatoria para precisao maxima em servicos. Se None, assume 5%. |
None
|
aliquota_pis_cofins
|
float | None
|
Aliquota efetiva de PIS/COFINS em % sobre o faturamento. Se None, usa o padrao do regime informado. |
None
|
Returns:
| Type | Description |
|---|---|
SimulacaoReformaResult
|
SimulacaoReformaResult com projecao anual 2026-2033, premissas usadas e avisos |
SimulacaoReformaResult
|
obrigatorios sobre as limitacoes e incertezas do calculo. |
Raises:
| Type | Description |
|---|---|
ValueError
|
se faturamento_anual nao for positivo. |
Exemplo
resultado = simular_transicao_reforma_tributaria( faturamento_anual=1_200_000, setor="comércio", regime_atual="Lucro Presumido", aliquota_icms_atual=12.0, ) for r in resultado.resultados_por_ano: print(r.ano, r.carga_total_pct, "%")
compare_tax_regimes ¶
Compara regimes tributarios brasileiros (MEI, Simples, Lucro Presumido, Lucro Real).
Estimativa rápida baseada em tabelas publicas vigentes. NAO substitui parecer de contador. Util para direcionamento em decisões de planejamento tributário.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
faturamento_anual
|
float
|
Receita bruta anual em reais. |
required |
setor
|
Literal['comércio', 'serviços', 'indústria']
|
Setor da empresa (impacta anexo do Simples e presuncoes do LP). |
required |
folha_pagamento_anual
|
float | None
|
Folha anual em reais. Importante para Fator R no Simples (serviços): se folha/faturamento >= 28%, usa Anexo III (mais barato). |
None
|
Returns:
| Type | Description |
|---|---|
TaxRegimeComparison
|
TaxRegimeComparison com opcoes avaliadas, melhor regime e economia estimada. |
Exemplo
resultado = compare_tax_regimes( faturamento_anual=500_000, setor="serviços", folha_pagamento_anual=180_000, ) print(resultado.melhor_opcao) # "simples_nacional" print(resultado.economia_anual_vs_pior) # economia vs pior opção
summarize_sped
async
¶
Sumarizacao executiva de um arquivo SPED.
Le o arquivo, identifica tipo (Fiscal, Contribuicoes, ECF, ECD), extrai período, empresa, total de registros e produz resumo em pt-BR.
Para EFD-Contribuicoes extrai pis_total (M210 VL_CONT_PER) e cofins_total (M610 VL_CONT_PER) - ambos valores a recolher no período. Para EFD ICMS/IPI extrai dois campos do E110: - icms_a_recolher (VL_ICMS_RECOLHER, campo 13): valor LÍQUIDO a recolher, comparável com pis_total e cofins_total. - icms_total_debitos (VL_TOT_DEBITOS, campo 02): total BRUTO de débitos por saídas/prestações, informativo, NÃO comparável com os demais. O regime PIS/COFINS (0110 COD_INC_TRIB) é capturado como regime_pis_cofins (1.0=cumulativo, 2.0=nao-cumulativo).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
str | Path
|
Caminho para arquivo .txt do SPED. |
required |
Returns:
| Type | Description |
|---|---|
SPEDSummary
|
SPEDSummary com período, empresa, metricas e resumo executivo. |
Exemplo
sumário = await summarize_sped("/tmp/sped_fiscal_201912.txt") print(sumário.resumo) for metrica, valor in sumário.metricas_chave.items(): print(f"{metrica}: {valor}")
consultar_empresas_lote
async
¶
Consulta em lote CNPJs para consolidar compliance e score de risco.
Para cada CNPJ, combina: - analyze_cnpj_compliance (contexto de compliance) - risk_score_supplier (score para tomada de decisão de fornecedor)
A resposta devolve por-item resultados de sucesso e erro, facilitando a priorização de contato com fornecedores em cadastros de alto volume.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cnpjs
|
list[str]
|
Lista de CNPJs (com ou sem formatação). |
required |
criterios_estritos
|
bool
|
Se True, repassa para risco e ajusta mais conservadoramente. |
False
|
risk_score_supplier
async
¶
Calcula score de risco para due diligence de fornecedor.
Baseia-se em ComplianceReport e aplica ajustes para o contexto de contratacao de fornecedor (mais conservador que compliance geral).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cnpj
|
str
|
CNPJ do fornecedor (com ou sem formatacao). |
required |
criterios_estritos
|
bool
|
Se True, reduz tolerancia (subtrai 10 pontos do score). Usar quando contratante tem politica anti-corrupcao agressiva. |
False
|
Returns:
| Type | Description |
|---|---|
SupplierRiskScore
|
SupplierRiskScore com recomendacao acionavel. |
Exemplo
score = await risk_score_supplier("12.345.678/0001-90", criterios_estritos=True) if score.recomendacao == "recusar": # bloquear cadastro ...
compliance ¶
Analise consolidada de compliance fiscal de um CNPJ.
analyze_cnpj_compliance
async
¶
Analise consolidada de compliance fiscal de um CNPJ brasileiro.
Consulta em paralelo: dados cadastrais (Receita), regime Simples Nacional, status MEI, CNAE principal e secundarios. Retorna um relatório unico com score 0-100, risco classificado e achados acionaveis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cnpj
|
str
|
CNPJ com ou sem formatacao (so digitos são usados). |
required |
Returns:
| Type | Description |
|---|---|
ComplianceReport
|
ComplianceReport com risco_geral, score, achados e resumo executivo. |
Exemplo de uso por um agente
report = await analyze_cnpj_compliance("12.345.678/0001-90") if report.risco_geral in ("alto", "critico"): # bloquear cadastro de fornecedor ...
Nota
Esta tool NAO consulta certidoes negativas reais (somente gera URLs). Para validação de certidoes use as ferramentas especificas do modulo certidoes.
nfe ¶
Validacao consolidada de NFe (XML + chave + emissor).
validate_nfe_full
async
¶
Validacao consolidada de uma NFe (XML).
Executa em sequencia: 1. Parse estrutural do XML (lxml) 2. Validacao do digito verificador da chave de acesso 3. Verificacao do CNPJ emissor (situacao ativa via Receita)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xml_path
|
str | Path
|
Caminho para arquivo XML da NFe. |
required |
Returns:
| Type | Description |
|---|---|
NFeValidationReport
|
NFeValidationReport com chave, validade, issues e resumo. |
Exemplo
report = await validate_nfe_full("/tmp/nota.xml") if not report.valida_estruturalmente or report.issues: # rejeitar nota ...
reforma ¶
Simulador de transicao da Reforma Tributaria brasileira (LC 214/2025).
Estima o impacto financeiro ano a ano (2026-2033) da substituicao gradual dos tributos atuais (PIS/COFINS, ICMS, ISS) pelos novos (CBS e IBS).
AVISOS LEGAIS: - As aliquotas plenas do IBS (~17,7%) e CBS (~8,8%) sao estimativas de referencia; nao foram fixadas definitivamente em lei ate a publicacao desta versao. Os valores serao definidos pelo CGIBS e Senado Federal. - Empresas do Simples Nacional e MEI entram no novo sistema somente a partir de 2027, com regras especificas ainda em regulamentacao. - Creditos de IBS/CBS (nao-cumulatividade) nao sao modelados nesta v1. - ICMS varia por estado; o valor usado e o informado pelo usuario. - Setores com reducao de aliquota (saude, educacao, cesta basica) possuem aliquotas diferenciadas nao modeladas aqui.
Fontes consultadas para o cronograma: - LC 214/2025 (arts. 6, 7, 337, 343, 346) https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp214.htm - SimTax - Transicao ICMS/IBS 2029-2032 https://simtax.com.br/transicao-do-icms-para-o-ibs-como-funcionara-a-troca-de-carga-entre-2029-e-2032/ - Cronograma Trad & Cavalcanti https://www.tradecavalcanti.com.br/publicacoes/cronograma-reforma-tributaria-lei-complementar-214-2025
ResultadoAnual ¶
Bases: BaseModel
Estimativa de carga tributaria para um ano especifico da transicao.
SimulacaoReformaResult ¶
Bases: BaseModel
Resultado da simulacao de transicao da Reforma Tributaria (LC 214/2025).
Apresenta a carga tributaria estimada ano a ano (2026-2033), mostrando o blend entre os tributos do regime antigo (ICMS/ISS e PIS/COFINS) e os novos (CBS e IBS), conforme o cronograma de transicao da LC 214/2025.
simular_transicao_reforma_tributaria ¶
simular_transicao_reforma_tributaria(faturamento_anual, setor, regime_atual, aliquota_icms_atual=None, aliquota_iss_atual=None, aliquota_pis_cofins=None)
Simula o impacto da transicao da Reforma Tributaria (LC 214/2025) de 2026 a 2033.
Para cada ano, estima (a) a carga do regime antigo (PIS/COFINS + ICMS ou ISS), ja ajustada pela reducao proporcional do cronograma, e (b) a carga do regime novo (CBS + IBS), aplicando as aliquotas de referencia na fracao de transicao prevista pela LC 214/2025.
Cronograma (LC 214/2025, arts. 337, 343, 346): - 2026: fase de teste - CBS 0,9% + IBS 0,1%, compensavel, impacto liquido ~zero. - 2027-2028: CBS plena (ref. ~8,8%) substitui PIS/COFINS; ICMS/ISS integrais. - 2029: IBS assume 10% da carga de referencia; ICMS/ISS recuam para 90%. - 2030: IBS 20%; ICMS/ISS 80%. - 2031: IBS 30%; ICMS/ISS 70%. - 2032: IBS 40%; ICMS/ISS 60%. - 2033: IBS pleno (ref. ~17,7%); ICMS e ISS extintos.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
faturamento_anual
|
float
|
Receita bruta anual em reais. Deve ser positivo. |
required |
setor
|
Literal['comércio', 'serviços', 'indústria']
|
Setor da empresa. Determina o tributo estadual/municipal aplicavel. - "comércio": usa ICMS (aliquota_icms_atual ou 12% se omitido). - "indústria": usa ICMS (mesma logica). - "serviços": usa ISS (aliquota_iss_atual ou 5% se omitido). |
required |
regime_atual
|
Literal['Simples Nacional', 'Lucro Presumido', 'Lucro Real']
|
Regime tributario federal vigente. Determina a aliquota de PIS/COFINS assumida quando aliquota_pis_cofins nao e informada. - "Simples Nacional": PIS/COFINS embutido no DAS; estimativa 3,65%. - "Lucro Presumido": regime cumulativo PIS 0,65% + COFINS 3% = 3,65%. - "Lucro Real": regime nao-cumulativo 1,65% + 7,6% = 9,25%. |
required |
aliquota_icms_atual
|
float | None
|
Aliquota do ICMS em %, declarada pelo usuario (varia por UF). Obrigatoria para precisao maxima em comercio/industria. Se None, assume 12%. |
None
|
aliquota_iss_atual
|
float | None
|
Aliquota do ISS em %, declarada pelo usuario (varia por municipio). Obrigatoria para precisao maxima em servicos. Se None, assume 5%. |
None
|
aliquota_pis_cofins
|
float | None
|
Aliquota efetiva de PIS/COFINS em % sobre o faturamento. Se None, usa o padrao do regime informado. |
None
|
Returns:
| Type | Description |
|---|---|
SimulacaoReformaResult
|
SimulacaoReformaResult com projecao anual 2026-2033, premissas usadas e avisos |
SimulacaoReformaResult
|
obrigatorios sobre as limitacoes e incertezas do calculo. |
Raises:
| Type | Description |
|---|---|
ValueError
|
se faturamento_anual nao for positivo. |
Exemplo
resultado = simular_transicao_reforma_tributaria( faturamento_anual=1_200_000, setor="comércio", regime_atual="Lucro Presumido", aliquota_icms_atual=12.0, ) for r in resultado.resultados_por_ano: print(r.ano, r.carga_total_pct, "%")
regimes ¶
Comparativo entre regimes tributarios brasileiros.
Calculo simplificado, baseado em premissas publicas e tabelas vigentes em 2025. Não substitui parecer de contador. Util para estimativa rápida e direcionamento.
compare_tax_regimes ¶
Compara regimes tributarios brasileiros (MEI, Simples, Lucro Presumido, Lucro Real).
Estimativa rápida baseada em tabelas publicas vigentes. NAO substitui parecer de contador. Util para direcionamento em decisões de planejamento tributário.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
faturamento_anual
|
float
|
Receita bruta anual em reais. |
required |
setor
|
Literal['comércio', 'serviços', 'indústria']
|
Setor da empresa (impacta anexo do Simples e presuncoes do LP). |
required |
folha_pagamento_anual
|
float | None
|
Folha anual em reais. Importante para Fator R no Simples (serviços): se folha/faturamento >= 28%, usa Anexo III (mais barato). |
None
|
Returns:
| Type | Description |
|---|---|
TaxRegimeComparison
|
TaxRegimeComparison com opcoes avaliadas, melhor regime e economia estimada. |
Exemplo
resultado = compare_tax_regimes( faturamento_anual=500_000, setor="serviços", folha_pagamento_anual=180_000, ) print(resultado.melhor_opcao) # "simples_nacional" print(resultado.economia_anual_vs_pior) # economia vs pior opção
schemas ¶
Schemas de saida das tools agenticas.
Cada modelo e desenhado para ser auto-explicativo quando serializado para
um LLM. Campos com description rica ajudam o agente a entender o significado
sem precisar consultar documentacao externa.
ComplianceFinding ¶
Bases: BaseModel
Um achado isolado de uma analise de compliance fiscal.
ComplianceReport ¶
Bases: BaseModel
Relatorio agregado de compliance fiscal de um CNPJ.
Combina dados de CNPJ, Simples Nacional, MEI, CNAE e certidoes em uma visao unica orientada a decisão (contratar, recusar, investigar).
TaxRegimeOption ¶
Bases: BaseModel
Comparativo de um regime tributário para um cenário especifico.
TaxRegimeComparison ¶
Bases: BaseModel
Comparativo entre regimes tributarios para um cenário.
SupplierRiskScore ¶
Bases: BaseModel
Score de risco de um fornecedor para due diligence.
SupplierRiskBatchItem ¶
Bases: BaseModel
Resultado por fornecedor em avaliação em lote.
SupplierRiskBatchResult ¶
Bases: BaseModel
Resultado consolidado da consulta de múltiplos CNPJs.
NFeValidationIssue ¶
Bases: BaseModel
Problema individual detectado em validação de NFe.
NFeValidationReport ¶
Bases: BaseModel
Relatorio completo de validação de uma NFe (XML).
SPEDSummary ¶
Bases: BaseModel
Sumario executivo de um arquivo SPED.
sped ¶
Sumarizacao executiva de arquivos SPED.
summarize_sped
async
¶
Sumarizacao executiva de um arquivo SPED.
Le o arquivo, identifica tipo (Fiscal, Contribuicoes, ECF, ECD), extrai período, empresa, total de registros e produz resumo em pt-BR.
Para EFD-Contribuicoes extrai pis_total (M210 VL_CONT_PER) e cofins_total (M610 VL_CONT_PER) - ambos valores a recolher no período. Para EFD ICMS/IPI extrai dois campos do E110: - icms_a_recolher (VL_ICMS_RECOLHER, campo 13): valor LÍQUIDO a recolher, comparável com pis_total e cofins_total. - icms_total_debitos (VL_TOT_DEBITOS, campo 02): total BRUTO de débitos por saídas/prestações, informativo, NÃO comparável com os demais. O regime PIS/COFINS (0110 COD_INC_TRIB) é capturado como regime_pis_cofins (1.0=cumulativo, 2.0=nao-cumulativo).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
str | Path
|
Caminho para arquivo .txt do SPED. |
required |
Returns:
| Type | Description |
|---|---|
SPEDSummary
|
SPEDSummary com período, empresa, metricas e resumo executivo. |
Exemplo
sumário = await summarize_sped("/tmp/sped_fiscal_201912.txt") print(sumário.resumo) for metrica, valor in sumário.metricas_chave.items(): print(f"{metrica}: {valor}")
supplier ¶
Score de risco de fornecedor combinando compliance + heuristica.
risk_score_supplier
async
¶
Calcula score de risco para due diligence de fornecedor.
Baseia-se em ComplianceReport e aplica ajustes para o contexto de contratacao de fornecedor (mais conservador que compliance geral).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cnpj
|
str
|
CNPJ do fornecedor (com ou sem formatacao). |
required |
criterios_estritos
|
bool
|
Se True, reduz tolerancia (subtrai 10 pontos do score). Usar quando contratante tem politica anti-corrupcao agressiva. |
False
|
Returns:
| Type | Description |
|---|---|
SupplierRiskScore
|
SupplierRiskScore com recomendacao acionavel. |
Exemplo
score = await risk_score_supplier("12.345.678/0001-90", criterios_estritos=True) if score.recomendacao == "recusar": # bloquear cadastro ...
consultar_empresas_lote
async
¶
Consulta em lote CNPJs para consolidar compliance e score de risco.
Para cada CNPJ, combina: - analyze_cnpj_compliance (contexto de compliance) - risk_score_supplier (score para tomada de decisão de fornecedor)
A resposta devolve por-item resultados de sucesso e erro, facilitando a priorização de contato com fornecedores em cadastros de alto volume.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cnpjs
|
list[str]
|
Lista de CNPJs (com ou sem formatação). |
required |
criterios_estritos
|
bool
|
Se True, repassa para risco e ajusta mais conservadoramente. |
False
|