Contexto e
Memória de Sistema

# CLAUDE.md — Sistema de Folha de Pagamento (FP-MAIN)

## Contexto do Projeto
- Sistema legado em COBOL rodando em IBM z/OS 2.5
- DB2 v13 como banco de dados primário (esquema: FPROD.V_FUNCIONARIOS)
- APIs REST em Python 3.11 + FastAPI fazendo ponte com o mainframe
- Pipeline de integração via IBM MQ 9.3

## Regras de Negócio Críticas
- NUNCA modificar os copybooks sem aprovação do arquiteto COBOL
- Campos de salário usam COMP-3 (packed decimal) — sempre validar antes de converter
- Cálculo de INSS: tabela mensal em TABINSS-TABLE no programa FPINSS01
- Qualquer alteração em FPFOLHA00.cbl requer testes de regressão completos

## Stack e Convenções
- COBOL: estilo IBM Enterprise COBOL 6.3, 80 colunas
- Python: Black formatter, type hints obrigatórios, docstrings no padrão Google
- Commits: Conventional Commits (feat/fix/refactor/docs)
- Testes: pytest, cobertura mínima 85%

## Arquivos-chave
- src/cobol/FPFOLHA00.cbl    → programa principal de folha
- src/cobol/copybooks/       → definições de dados compartilhadas
- src/api/folha_router.py    → endpoints REST de folha
- docs/decisoes/            → ADRs (Architecture Decision Records)

## Contexto da Consultora
- Kyol está refatorando a interface Python-COBOL
- Preferência: exemplos com código real, sem simplificações
- Objetivo atual: migrar lógica de cálculo de férias para microsserviço

## O que NÃO fazer
- Não sugerir reescrita completa em Java/.NET sem discussão prévia
- Não usar bibliotecas não aprovadas pelo comitê de arquitetura
- Não alterar PROCEDURE DIVISION sem comentar o que mudou e por quê

-- Habilitar extensão (uma vez por banco)
CREATE EXTENSION IF NOT EXISTS vector;

-- Tabela de chunks com metadados do sistema COBOL
CREATE TABLE documentos_cobol (
    id          SERIAL PRIMARY KEY,
    conteudo    TEXT NOT NULL,
    embedding   vector(1536),          -- dimensão do modelo
    programa    VARCHAR(8),            -- ex: FPFOLHA00
    secao       VARCHAR(40),           -- ex: PROCEDURE DIVISION
    paragraph   VARCHAR(40),
    updated_at  TIMESTAMP DEFAULT NOW()
);

-- Índice HNSW para busca rápida
CREATE INDEX ON documentos_cobol
    USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 64);

-- Query: encontrar chunks similares à pergunta do usuário
SELECT conteudo, programa, secao,
       1 - (embedding <=> '[0.12, 0.87, ...]'::vector) AS similaridade
FROM documentos_cobol
WHERE programa = 'FPFOLHA00'          -- filtro por metadado
ORDER BY embedding <=> '[0.12, 0.87, ...]'::vector
LIMIT 5;

from dataclasses import dataclass
from typing import List, Optional
import anthropic

@dataclass
class ContextParts:
    system_prompt: str
    semantic_memory: str
    rag_chunks: List[str]
    episode_summary: str
    recent_history: List[dict]

class ContextBuilder:
    def __init__(self, max_tokens: int = 150_000):
        self.max_tokens = max_tokens
        self.token_budget = {
            "system":    5_000,   # system prompt base
            "semantic":  3_000,   # memória semântica do usuário
            "rag":       20_000,  # chunks recuperados
            "episode":   5_000,   # sumário de sessões passadas
            "history":   15_000,  # histórico recente da conversa
        }

    def build(self, query: str, parts: ContextParts) -> dict:
        # 1. System prompt (início — alta atenção do modelo)
        system = self._build_system(parts)

        # 2. Histórico de mensagens com contexto injetado
        messages = []

        # Injetar memória semântica como primeira mensagem humana
        if parts.semantic_memory:
            messages.append({
                "role": "user",
                "content": f"[CONTEXTO DO USUÁRIO]\n{parts.semantic_memory}"
            })
            messages.append({"role": "assistant", "content": "Entendido."})

        # Sumário episódico se houver
        if parts.episode_summary:
            messages.append({
                "role": "user",
                "content": f"[HISTÓRICO ANTERIOR]\n{parts.episode_summary}"
            })
            messages.append({"role": "assistant", "content": "Ok, contexto registrado."})

        # Histórico recente da conversa atual
        messages.extend(parts.recent_history)

        # Query com chunks RAG (no FIM — alta atenção)
        rag_context = "\n\n".join([
            f"[DOCUMENTO {i+1}]\n{chunk}"
            for i, chunk in enumerate(parts.rag_chunks)
        ])
        messages.append({
            "role": "user",
            "content": f"{rag_context}\n\n[PERGUNTA]\n{query}"
        })

        return {"system": system, "messages": messages}

    def _build_system(self, parts: ContextParts) -> str:
        return f"""Você é um assistente corporativo especializado.

{parts.system_prompt}

Responda sempre com base nos documentos fornecidos.
Se não encontrar a informação, diga claramente que não sabe."""

import anthropic

client = anthropic.Anthropic()

# 1. Upload do manual COBOL (uma vez)
with open("manual_cobol_folha.pdf", "rb") as f:
    file_response = client.beta.files.upload(
        file=(
            "manual_cobol_folha.pdf",
            f,
            "application/pdf"
        )
    )

file_id = file_response.id
# file_id: "file_abc123..." — salvar no banco para reutilizar
print(f"Upload: {file_id}")

# 2. Usar o arquivo em qualquer chamada subsequente
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "file",
                    "file_id": file_id        # referência, não re-envio
                }
            },
            {
                "type": "text",
                "text": "Como o programa FPINSS01 calcula a alíquota de INSS para salários acima do teto?"
            }
        ]
    }],
    betas=["files-api-2025-04-14"]
)

# 3. Listar arquivos disponíveis
files = client.beta.files.list()
for f in files.data:
    print(f"{f.id} — {f.filename} — {f.size} bytes")

# 4. Deletar quando não precisar mais
client.beta.files.delete(file_id)