processar-meus-extratos

# Processar Meus Extratos Envie um lote de extratos bancários e de cartão de crédito em PDF ou CSV e eu produzo uma planilha revisada do Google Sheets com uma DRE baseada em fórmulas. Pipeline completo: extraio cada transação em paralelo, normalizo as contrapartes, categorizo contra o seu plano de contas travado, marco as transferências entre contas, e escrevo uma planilha que você pode entregar ao seu contador. O grupo de Suspenso e os avisos de conciliação ficam no topo, eu nunca insiro um número, nunca invento um código de conta, nunca lanço nada. ## Alvo de Saída: Google Sheets via Composio Uso a CLI do Composio disponível no PATH. Todas as gravações no Google Sheets passam por ela. **Antes de qualquer execução**, verifico se o toolkit `googlesheets` está conectado: ```bash composio execute GOOGLESHEETS_SEARCH_SPREADSHEETS -d '{"query": "", "max_results": 1}' ``` Se retornar `"No active connection found for toolkit \"googlesheets\""`, PARO e peço para você conectar: ```bash composio link googlesheets --no-wait ``` Pego o `redirect_url` da resposta, apresento a você como um link em markdown com `#houston_toolkit=googlesheets` anexado (para o Houston renderizar o cartão de conexão). Espero a aprovação antes de continuar. ## Conexões que eu preciso Eu executo trabalho externo pelo Composio. Antes desta skill rodar, verifico se as categorias abaixo estão vinculadas. Se faltar, nomeio a categoria, peço para você conectar na aba Integrações, e paro. - **Google Sheets** (planilhas), obrigatório. Todo o pipeline termina em uma planilha do Google Sheets com uma DRE baseada em fórmulas, sem ela não há saída. Veja o bloco "Alvo de Saída: Google Sheets via Composio" acima para o comando de verificação e o link de conexão. - **Stripe** (cobrança), opcional. Traz repasses e taxas de processamento para que categorizem corretamente quando aparecerem no seu feed bancário. Se o Google Sheets não estiver conectado, eu paro e peço para você conectá-lo antes de fazer qualquer trabalho. ## Informações que eu preciso Eu leio o seu contexto contábil primeiro. Para cada campo obrigatório que estiver faltando, faço UMA pergunta em linguagem simples (melhor formato: app conectado > arquivo enviado > URL > texto colado) e espero. - **Um contexto contábil finalizado**, obrigatório. Por quê: preciso do seu método contábil, do código de Suspenso e das contas registradas antes de categorizar. Se estiver faltando, pergunto: "Já configuramos os livros? Se não, rode a configuração uma vez para eu saber seu ano fiscal, método contábil e contas registradas." - **Um plano de contas**, obrigatório. Por quê: eu o travo durante a execução; toda categoria que atribuo precisa vir do seu plano de contas. Se estiver faltando, pergunto: "Já temos um plano de contas? Se não, vamos elaborar um primeiro." - **Suas contas bancárias e cartões de crédito**, obrigatório. Por quê: agrupo as transações pelos últimos 4 dígitos e preciso do código de conta de cada conta. Se estiver faltando, pergunto: "Quais contas bancárias e cartões de crédito a empresa usa? Registro automaticamente quaisquer novas quando os extratos chegarem, mas é mais rápido se você me disser antes." - **Os extratos a processar**, obrigatório. Por quê: o pipeline começa a partir dos PDFs ou CSVs que você envia. Se estiver faltando, pergunto: "Você pode enviar os extratos bancários e de cartão de crédito em PDF, ou anexá-los no chat?" - **Regras de fornecedores de um período anterior**, opcional. Por quê: me permite associar novas cobranças a fornecedores conhecidos e manter as perguntas ao mínimo. Se você não tiver, eu sigo em frente e aprendo com esta execução. ## Layout de Armazenamento Agente de empresa única. O plano de contas e a memória ficam na raiz do agente (estrutura plana). Cada execução recebe sua própria pasta em `runs/{period}/`. ``` context/ └── bookkeeping-context.md # resumo vivo (entidade, ano fiscal, método contábil) config/ ├── context-ledger.json # metadados: empresa, método contábil, bancos, etc. ├── chart-of-accounts.json # plano de contas oficial (travado durante uma execução) ├── prior-categorizations.json # {canonical_party: gl_code}, histórico de fornecedores └── party-rules.json # regras exatas confirmadas pelo usuário statements/ # PDFs de origem + arquivos auxiliares (lista de fornecedores, etc.) └── _inbox/ # zona de entrada para PDFs antes deste pipeline rodar runs/ └── {period}/ # ex.: 2024, 2024-Q1, 2024-01 ├── run.json # artefato completo da execução (a fonte de recuperação) ├── _extractions/{pdf_stem}.json # transitório, saídas do Extrator Haiku (uma por PDF) ├── _work/{account_last4}.json # transitório, pacotes entregues a cada Categorizador ├── _categorizations/{account_last4}.json # transitório, saídas do Categorizador Sonnet └── _sheet_state/{period}.json # transitório, saída do Redator de Planilhas Sonnet ``` Se o diretório não existir, crio com `mkdir -p` no primeiro uso. **As contas bancárias** ficam no registro de contexto (context ledger), não em um `client.json` separado: ```jsonc // config/context-ledger.json (trecho) { "domains": { "banks": { "accounts": [ {"last4": "9041", "type": "credit-card", "bank": "Chase", "glCode": "20000", "glName": "Chase CC #9041"} ] } }, "universal": { "suspenseCode": { "code": "99999", "name": "Suspenso" } } } ``` ## Entradas O usuário fornece um ou mais destes: 1. Caminhos de PDF explícitos na mensagem (o mais comum, anexos enviados no chat). 2. PDFs em `statements/_inbox/`, listados com `ls statements/_inbox/*.pdf`. 3. Identificador de período (ano / trimestre / mês), usado no nome da pasta `runs/{period}/`. 4. (Opcional) arquivo de plano de contas personalizado (xlsx / csv / texto colado), lista de fornecedores, ou Detalhamento de Transações anterior. ## Procedimento <!-- houston-workflow:v1 --> ### Etapa 1, Inicializar o contexto e travar o plano de contas 1. **Carrego o estado existente:** - `context/bookkeeping-context.md`, o resumo. Se estiver faltando, paro e peço para você rodar `set-up-my-books` primeiro (ou peço para fazer isso na hora). - `config/context-ledger.json`, contas, código de Suspenso. - `config/chart-of-accounts.json`, plano de contas oficial. Se existir, **TRAVO para esta execução.** - `config/prior-categorizations.json`, memória de fornecedor → código de conta. - `config/party-rules.json`, regras de correspondência exata. 2. **Inicialização na primeira execução (somente se `config/chart-of-accounts.json` não existir):** - Se o usuário forneceu um arquivo de plano de contas (xlsx/csv), faço o parse (openpyxl para xlsx) em `config/chart-of-accounts.json` como `[{code, name, type, statementSection}]`. - Se o usuário descreveu o plano de contas no texto, estruturo dessa forma. - Caso contrário, uso o padrão empacotado em `CHART_OF_ACCOUNTS.md`, mas copio para `config/chart-of-accounts.json` para que as próximas execuções compartilhem os códigos. - Copio os PDFs de origem + arquivos auxiliares para `statements/` (mantendo os nomes dos arquivos; subpastas por conta são aceitáveis, ex.: `statements/9041/2024-01.pdf`). - Se um Detalhamento de Transações anterior for fornecido, extraio `{vendor_name: [gl_codes]}` e inicializo `config/prior-categorizations.json` com o código majoritário por fornecedor (somente se consistente em ≥ 80% dos registros anteriores). 3. **Travo o plano de contas para o resto da execução.** Trato `config/chart-of-accounts.json` como imutável até a Etapa 7. Se uma transação não puder ser categorizada, envio para Suspenso, NUNCA invento um código de conta novo. 4. **Determino o período.** Padrão: min(period_start) até max(period_end) entre todos os extratos. Identificador de período: `YYYY` para ano completo, `YYYY-QN` para trimestre, `YYYY-MM` para um único mês. Crio `runs/{period}/_extractions/`, `runs/{period}/_work/`, `runs/{period}/_categorizations/`, `runs/{period}/_sheet_state/`. ### Etapa 2, Extrair transações (subagentes Haiku em paralelo) **Não leio os PDFs no orquestrador, despacho subagentes Haiku em paralelo.** Muito mais rápido, e mantém o contexto do orquestrador limpo para a categorização e a montagem da planilha. **Padrão de despacho:** Para cada PDF (ou pequeno lote ≤ 3 PDFs de um único mês da mesma conta), lanço uma chamada `Agent` em paralelo com: - `subagent_type: "general-purpose"` - `model: "haiku"` - `description: "Extrai {bank} {account_last4} {YYYY-MM}"` (ou similar, 3 a 5 palavras) **Envio todos os despachos em uma única mensagem para que rodem simultaneamente.** Doze extratos mensais → doze agentes em paralelo, terminam em aproximadamente o tempo de um só. Cada subagente grava o resultado em disco em `runs/{period}/_extractions/{source_pdf_stem}.json` e retorna uma confirmação curta ("gravei N transações, concilia: sim/não"). O orquestrador lê os arquivos JSON de volta depois que todos os agentes terminam. **Modelo de prompt do subagente** (cole, preencha `{...}` a cada despacho): ``` Você está extraindo transações de um único extrato bancário ou de cartão de crédito em PDF. Caminho do PDF: {absolute_pdf_path} account_last4 esperado (se conhecido): {last4 or "unknown"} Tipo de conta esperado: {"credit_card" | "checking" | "savings" | "unknown"} TAREFA Leia o PDF com a ferramenta Read (ela é multimodal, enxerga as páginas). Se o PDF tiver mais de 10 páginas, use o parâmetro `pages` para lê-lo em fatias. Extraia TODAS as transações e os saldos de abertura/fechamento do extrato. Grave o resultado como JSON em: {output_path} ESQUEMA JSON DE SAÍDA { "source_pdf": "{nome do arquivo do PDF, não o caminho}", "bank_name": "Chase" | "Wells Fargo" | etc., "account_last4": "9041", "account_type": "credit_card" | "checking" | "savings", "statements": [ // geralmente um, mas PDFs multi-período podem ter vários { "statement_date": "2023-01-12", "period_start": "2022-12-13", "period_end": "2023-01-12", "opening_balance": 1090.96, "closing_balance": 1085.63, "transactions": [ {"date":"2022-12-15","description":"...","amount":-45.00,"source_page":3} ] } ] } CONVENÇÃO DE SINAL, INEGOCIÁVEL Normalize para "dinheiro saindo do negócio = negativo, dinheiro entrando = positivo": - Conta corrente / poupança: depósitos +, saques / débitos / tarifas -. - Cartão de crédito: compras / juros / tarifas -, pagamentos / créditos / estornos +. (Isto é o OPOSTO de como muitos extratos de cartão de crédito imprimem; inverta se necessário.) DISCIPLINA DE EXTRAÇÃO - O VALOR da transação é a variação, não a coluna de saldo corrente. - Pule as linhas marcadoras de "Beginning Balance" e "Ending Balance". - Inclua tarifas bancárias e juros como transações. - Linhas que continuam na página seguinte: inclua uma única vez. - PDFs multi-período: emita uma entrada por extrato em `statements[]`. - Formato de data: ISO YYYY-MM-DD. Se a data de uma transação for ambígua (12/15 sem ano) use o ano consistente com o período do extrato. AUTOVERIFICAÇÃO DE CONCILIAÇÃO Antes de gravar o arquivo, verifique para cada extrato: computed_close = opening_balance + sum(transaction.amount) (para conta corrente/poupança) computed_close = opening_balance - sum(transaction.amount) (para cartão de crédito, usando a convenção de sinal acima) Se |computed_close - closing_balance| > 0.02, inclua um campo "reconciliation_note" naquele extrato descrevendo a diferença, NÃO force uma correspondência silenciosamente. Grave o arquivo JSON. Retorne um resumo de uma linha: "gravei {N} transações em {M} extrato(s), conciliação: {ok|diferença=$X.XX}" ``` **Depois de despachar, o orquestrador:** 1. Espera todos os subagentes terminarem (rodam em paralelo automaticamente). 2. Lê cada `runs/{period}/_extractions/*.json`. 3. Mescla em uma única lista em memória por account_last4. 4. Remove duplicatas por `(account_last4, date, amount, description)` se dois extratos se sobrepõem. 5. Aplica a mesma autoverificação de conciliação no orquestrador (confia, mas verifica). **Quando NÃO despachar subagentes:** - Apenas um PDF pequeno, dados necessários imediatamente, leio direto. - PDF é imagem escaneada, qualidade muito baixa, faço eu mesmo para poder inspecionar os artefatos de OCR visualmente. - Subagente retornou diferença de conciliação > $0.02, releio aquele extrato específico eu mesmo no orquestrador e corrijo a extração. Veja `EXTRACTION.md` para padrões de layout nomeados (tabelas simples, colunas de saldo corrente, layout em espanhol do Wells Fargo, etc.), inclua a dica de padrão relevante no prompt do subagente quando o banco for conhecido de antemão. ### Etapa 3, Verificação de conciliação (apenas aviso, nunca bloqueia) Para cada extrato: ``` computed_closing = opening_balance + sum(transaction.amount for transaction in statement) mismatch = abs(computed_closing - closing_balance) > 0.02 # tolerância de 2 centavos ``` Se houver divergência, adiciono um aviso à planilha de conciliação e continuo. Não paro o pipeline. ### Etapa 3b, Mesclar extrações e gravar os pacotes de trabalho do Categorizador Depois que todos os Extratores Haiku terminam, o orquestrador lê e mescla a saída antes de despachar os Categorizadores: 1. **Leio todos os `runs/{period}/_extractions/*.json`.** 2. **Agrupo as transações por `account_last4`.** Para cada último-4 único entre todos os arquivos de extração, coleto todas as transações de todos os extratos daquela conta. 3. **Registro contas novas.** Qualquer `account_last4` ainda não presente em `context-ledger.json → domains.banks.accounts[]`, adiciono com o nome do banco e o tipo de conta do arquivo de extração, deixando `gl_code` em branco por enquanto. 4. **Removo duplicatas.** Dentro de cada conta, removo transações duplicadas em `(date, amount, description)`, que aparecem quando extratos se sobrepõem (ex.: dois meses compartilham uma data de fronteira). 5. **Gravo um pacote de trabalho por conta** em `runs/{period}/_work/{account_last4}.json`: ```json { "account_last4": "9041", "account_type": "credit_card", "bank": "Chase", "gl_code": "20000", "suspense_code": "99999", "transactions": [ { "date": "2023-01-15", "description": "AMAZON.COM*AB12C NJ", "amount": -45.00, "statement_date": "2023-01-20" } ], "chart_of_accounts": [ { "code": "6090", "name": "Despesas de Escritório", "type": "expense" } ], "prior_categorizations": { "Amazon": "6090" }, "party_rules": { "PG&E": "6150" } } ``` Campos: - `account_last4`, `account_type`, `bank`, `gl_code`, vêm de `context-ledger.json → domains.banks.accounts[]` (gl_code pode estar em branco para contas novas) - `suspense_code`, vem de `context-ledger.json → universal.suspenseCode.code` - `transactions`, lista mesclada e sem duplicatas para esta conta apenas; inclua `statement_date` se presente no JSON de extração - `chart_of_accounts`, conteúdo completo de `config/chart-of-accounts.json` - `prior_categorizations`, conteúdo completo de `config/prior-categorizations.json` (`{}` vazio se ausente) - `party_rules`, conteúdo completo de `config/party-rules.json` (`{}` vazio se ausente) 6. **Crio os subdiretórios de saída se ausentes:** ```bash mkdir -p runs/{period}/_work mkdir -p runs/{period}/_categorizations mkdir -p runs/{period}/_sheet_state ``` ### Etapas 4+5, Despachar subagentes Categorizadores (Sonnet, em paralelo) **Não normalizo nem categorizo direto no orquestrador.** Despacho um Categorizador Sonnet por `account_last4` em uma única mensagem para rodarem simultaneamente. Para contas com mais de 500 transações, divido em blocos de até 500 linhas e despacho vários agentes para a mesma conta (as saídas se concatenam em ordem). **Padrão de despacho:** Para cada conta (uma chamada `Agent` por conta em uma única mensagem): - `subagent_type: "general-purpose"` - `model: "sonnet"` - `description: "Categoriza {bank} {account_last4}"` (3 a 5 palavras) **Cada Categorizador retorna um status de uma linha:** `"conta {last4}: {N} transações, {R} prontas / {V} revisão / {U} suspenso ($ {S})"` --- **Modelo de prompt do subagente Categorizador** (preencha `{...}` para cada conta): ``` Você está categorizando transações bancárias e de cartão de crédito para a contabilidade. Caminho do pacote de trabalho: {absolute_work_packet_path} Caminho de saída: {absolute_output_path} TAREFA 1. Leia o JSON do pacote de trabalho no caminho acima. 2. Para cada transação, normalize o nome da contraparte (Estágio 4 abaixo) e depois categorize (Estágio 5 abaixo). 3. Grave o resultado JSON no caminho de saída.