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