convez.ai
AgenteFinanceiroAvançado
sterlingdiazd

Agente de Validação de Faturamento

sterlingdiazd/TP-EvaluationProject-AITransformation

Detecta erros de faturamento e gera recomendações auditáveis via IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent multi-modelo (Anthropic + OpenAI) que detecta overbilling, desajustes de taxa e violações de contrato em registros de faturamento. Inclui pipeline orquestrado com auditoria, controle de acesso (RBAC), kill switch e interface Streamlit para revisão estruturada de exceções antes da emissão de faturas.

Instalação

$npx convez-ai sterlingdiazd/TP-EvaluationProject-AITransformation

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Validação automática de faturas e detecção de overbilling em equipes de cobrança
  • Auditoria de conformidade com contratos e limites de taxa
  • Geração de explicações estruturadas para exceções de faturamento com rastreabilidade completa

Veredito

Agent robusto e bem-estruturado para validação de faturamento com governança apropriada (auditoria, aprovações, kill switch). Requer supervisão humana nas recomendações de remediação, o que está bem documentado. Excelente para times financeiras que precisam escalar revisão de exceções com rastreabilidade total.

README

A tradução para o português deste README ainda está na fila.

Billing Validation Agent System

An AI-assisted billing validation prototype that detects incorrect rates, excess billed hours, and contract-limit breaches across work logs, agreed rates, and invoice records. It produces audit-friendly output with plain-English explanations so teams can review exceptions before invoices reach the client.

AI-generated remediation recommendations are advisory. A billing supervisor should review and approve them before credits, invoice adjustments, or client-facing corrections are issued.


Quick Start

# 1. Clone and enter the repo using your favorite terminal
git clone https://github.com/AI-Transformation-Technical-TestPack/TP-EvaluationProject-AITransformation.git
cd TP-EvaluationProject-AITransformation

# 2. Create a local virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

# 3. Set your API key (optional)
cp .env.example .env
# edit AI_PROVIDER and the matching API key for Anthropic, OpenAI, or a compatible endpoint

# 4. Run validation
python main.py --mode orchestrated --input data/input/billing.csv --verbose

On Windows, use python instead of python3 and activate the environment with .venv\Scripts\activate.

Or launch the web UI:

streamlit run app.py

What It Does

The system reads billing source files, validates their structure, compares expected charges against proposed invoice values, and marks rows that require review. For each error row, it generates a structured JSON explanation using the configured AI provider. The final report is written to output/validation_report.csv, while the orchestrator records pipeline activity in output/audit.log.

The sample quick start run should process 5 records: 1 OK row and 4 ERROR rows. It should create output/validation_report.csv and output/audit.log.

CapabilityHow It Works
Data intakeThe ingestion step reads the sample files from data/input/ and verifies that required columns are present before validation begins.
Billing checksThe validation step calculates expected amount, billed amount, capped expected amount (strict-cap interpretation), difference, and over-cap exposure, then marks rows with RATE_MISMATCH, OVERBILLING, UNDERBILLING, CONTRACT_VIOLATION, BILLING_OVER_MAX, GHOST_BILLING, MISSING_BILLING, MISSING_CONTRACT, or DUPLICATE_RECORD. Formulas are documented in docs/validation-logic.md.
Explanation outputThe explanation step generates a structured JSON explanation for each error row using the configured AI provider, and stores it in the AI_Explanation field in the final report. A deterministic fallback is available.
Client rulesThe validation policy comes from config/client_rules.json, so client-specific tolerances can change without editing validation code.
Review pathsA user can run the pipeline from the CLI, follow the local interactive menu, or use the Streamlit interface to upload files and inspect results in a browser.

System Overview

flowchart TD
    CLI[CLI / Menu / Streamlit] --> ORCH[Orchestrator]
    ORCH --> ING[Data Ingestion]
    ING --> VAL[Validation Rules]
    VAL --> AI[AI Explanations]
    AI --> REP[Report Output]
    ORCH --> GOV[Governance: kill switch + audit log]

The README is focused on understanding and running the project. For more detailed design rationale, validation logic, governance controls, and ADRs, refer to docs/.


CLI Reference

# Full orchestrated run
python main.py --mode orchestrated --input data/input/billing.csv --verbose

# Choose an AI provider
python main.py --ai-provider openai --input data/input/billing.csv

# Run without AI provider calls
python main.py --no-ai --input data/input/billing.csv

# Select a different client rule set
python main.py --client client_b --input data/input/billing.csv

# Launch guided terminal menu
python main.py --interactive

Repository Structure

EvaluationProject/
├── agents/              # Worker agents: ingestion, validation, AI explanation, report
├── config/              # Client-specific validation rules
├── data/input/          # Sample timesheet, contracts, and billing CSV files
├── docs/                # Architecture, validation, governance, requirements, ADRs
├── governance/          # Kill switch and RBAC configuration
├── orchestrator/        # Central workflow coordinator
├── output/              # Generated report and audit log
├── prompts/             # Version-controlled AI prompt template
├── tests/               # Pytest validation coverage
├── app.py               # Streamlit web UI
├── main.py              # CLI entry point
└── requirements.txt

Documentation Guide

NeedStart Here
Understand the workflow and diagramsdocs/architecture.md
Review billing rules and calculationsdocs/validation-logic.md
Review audit, safety, and Human-in-the-Loop controlsdocs/governance.md
Review functional requirementsdocs/requirements.md
Review design decisionsdocs/decisions/

Running Tests

python3 -m pytest tests/ -v

Expected result: 27 passed.


Sterling Díaz · sterlingdiazd@gmail.com · MIT License

Ver o original no GitHub

Bom para

Relacionados