compliance-agent

# Compliance Agent Pipeline auditável para coletar normativos PIX fictícios, extrair regras, aplicar guardrails, comparar versões, indexar conteúdo para RAG e publicar relatórios JSON/PDF por FastAPI. O fluxo padrão é local, determinístico e não requer conta AWS nem chamadas a LLM real. ## Sumário - [Avaliação em cinco minutos](#avaliação-em-cinco-minutos) - [Problema e capacidades](#problema-e-capacidades) - [Estado da entrega](#estado-da-entrega) - [Arquitetura e agentes](#arquitetura-e-agentes) - [Estrutura do repositório](#estrutura-do-repositório) - [Pré-requisitos](#pré-requisitos) - [Quickstart com Docker](#quickstart-com-docker) - [Quickstart sem Docker](#quickstart-sem-docker) - [Configuração](#configuração) - [MCP](#mcp) - [FastAPI e exemplos](#fastapi-e-exemplos) - [RAG e pgvector](#rag-e-pgvector) - [Bedrock e AWS](#bedrock-e-aws) - [Fixtures e relatórios](#fixtures-e-relatórios) - [Testes e desenvolvimento](#testes-e-desenvolvimento) - [Observabilidade, segurança e FinOps](#observabilidade-segurança-e-finops) - [Idempotência e falhas parciais](#idempotência-e-falhas-parciais) - [Metodologia spec-driven e IA assistida](#metodologia-spec-driven-e-ia-assistida) - [Evidências e demonstração](#evidências-e-demonstração) - [Limitações e trabalhos futuros](#limitações-e-trabalhos-futuros) - [Troubleshooting](#troubleshooting) - [Uso no desafio](#uso-no-desafio) ## Avaliação em cinco minutos 1. Leia a [matriz de rastreabilidade](docs/evidence/REQUIREMENTS_TRACEABILITY.md). 2. Consulte os [cinco diagramas](docs/architecture/system-context.md) e o [índice das Skills](skills/README.md). 3. Veja respostas reais em [`docs/evidence/api`](docs/evidence/api/) e os [exemplos copiáveis](docs/api/EXAMPLES.md). 4. Valide `report.json`, `report.pdf` e os [SHA-256](docs/evidence/hashes/SHA256SUMS.txt). 5. Confira a [validação final](docs/evidence/FINAL_VALIDATION.md), screenshots e o [vídeo de demonstração](https://drive.google.com/file/d/1PQqJEYo3k3EiJL3TsG2mYkkwP8NMccu8/view?usp=sharing), documentado em [`VIDEO.md`](docs/demo/VIDEO.md). Para executar: ```powershell $env:UV_CACHE_DIR = "$PWD\.uv-cache" uv sync --locked uv run pytest -q ``` Sem PostgreSQL, os testes pgvector são ignorados; com o Compose saudável, apenas os dois testes AWS live permanecem ignorados. ## Problema e capacidades O projeto demonstra como transformar documentos regulatórios não confiáveis em evidência estruturada e rastreável: - catálogo mock com 50 normativos e três documentos PDF/HTML fictícios; - coleta com SHA-256 e estados `new`, `modified` e `unchanged`; - Scraper Agent consumindo uma tool MCP e transporte SSE real; - extração determinística de 12 regras e guardrails de PII/prompt injection; - diff, gap analysis e resultados parciais explícitos; - chunks, embeddings locais determinísticos, busca com proveniência e pgvector; - relatórios JSON e PDF derivados do mesmo modelo, manifest e hashes; - FastAPI com `/health`, `/normativos`, `/compliance`, `/search` e `/reports`; - adapters Bedrock/S3 reais testados offline com `botocore.stub.Stubber`; - imagem multi-stage e Compose com API, MCP, worker e PostgreSQL/pgvector. ## Estado da entrega A implementação das Fases 2–10 está concluída. A reprodução/E2E passa e a publicação HTTP é disparada pelo Report Consolidator Agent por meio de sua única tool tipada, após o worker persistir JSON/PDF. O projeto está publicado em <https://github.com/andmartins7/compliance-agent>, branch `main`, e a submissão está pronta. A AWS live não foi executada. Consulte [STATUS.md](docs/project/STATUS.md). ## Arquitetura e agentes Diagramas: - [contexto do sistema](docs/architecture/system-context.md); - [containers](docs/architecture/container-diagram.md); - [componentes](docs/architecture/component-diagram.md); - [sequência do pipeline](docs/architecture/pipeline-sequence.md); - [deployment local](docs/architecture/deployment-local.md). Fluxo ponta a ponta: ```text MCP collect → PDF/HTML extract → guardrails → chunks/embeddings/pgvector → diff/gap analysis → JSON/PDF → registro HTTP → consultas FastAPI ``` Os sete agentes são Orchestrator, Scraper, Extractor, Compliance Analyzer, Conformance Validator, Knowledge Builder e Report Consolidator. Cada um possui saída Pydantic e responsabilidade exclusiva. Tools com `RunContext` delegam aos ports e casos de uso determinísticos; após a persistência de JSON/PDF, o worker executa o Report Consolidator, cuja única tool registra o relatório via `ReportApiClient`. O Scraper recebe `MCPToolset` na execução. Consulte [Skills](skills/README.md). O worker Docker usa `McpDocumentCollector` para consumir o MCP por SSE; ele não instancia diretamente o objeto Scraper Agent. A prova específica do agente está em `tests/integration/test_scraper_agent_mcp.py`. ## Estrutura do repositório ```text src/compliance_agent/ domínio, aplicação, agentes, ports, adapters, API fixtures/ catálogo e documentos exclusivamente fictícios specs/ requisitos, contratos, arquitetura e ADRs skills/ sete contratos operacionais dos agentes tests/ unitários, integração, E2E, Docker e documentação docs/ operação, arquitetura, API, demo e evidências infra/docker/ init SQL e exemplo de ambiente scripts/ geração de fixtures e demonstração ``` ## Pré-requisitos - Python 3.12; - `uv`; - Docker Engine e Docker Compose para a prova pgvector/containerizada; - PowerShell 7 ou shell POSIX para os scripts de demonstração. Versões exatas Python são restringidas em `pyproject.toml`; dependências estão em `uv.lock`. Docker usa Python 3.12.11 slim, PostgreSQL 16 e `pgvector/pgvector:0.8.0-pg16`. ## Quickstart com Docker PowerShell: ```powershell Copy-Item infra/docker/.env.docker.example .env $env:CA_POSTGRES_PASSWORD = Read-Host "Senha local temporária" -MaskInput docker compose --project-name compliance-demo build docker compose --project-name compliance-demo up -d docker compose --project-name compliance-demo --profile worker run --rm worker Invoke-RestMethod http://127.0.0.1:8000/health Start-Process http://127.0.0.1:8000/docs Invoke-RestMethod "http://127.0.0.1:8000/search?query=autenticacao&limit=3" docker compose --project-name compliance-demo down -v Remove-Item -LiteralPath .env ``` Shell POSIX: ```bash cp infra/docker/.env.docker.example .env read -rsp "Senha local temporária: " CA_POSTGRES_PASSWORD && echo export CA_POSTGRES_PASSWORD docker compose --project-name compliance-demo build docker compose --project-name compliance-demo up -d docker compose --project-name compliance-demo --profile worker run --rm worker curl -fsS http://127.0.0.1:8000/health curl -fsS 'http://127.0.0.1:8000/search?query=autenticacao&limit=3' docker compose --project-name compliance-demo down -v rm .env ``` O arquivo `.env` é ignorado. Não reutilize a senha fora deste ambiente local. ## Quickstart sem Docker ```powershell $env:UV_CACHE_DIR = "$PWD\.uv-cache" uv sync --locked uv run python -m compliance_agent.cli worker --run-id local-demo uv run python -m compliance_agent.cli api --host 127.0.0.1 --port 8000 ``` Sem `CA_PGVECTOR_DSN`, o worker usa vector store em memória quando RAG é habilitado. O registry de relatórios da API também é em memória e reinicia vazio. ## Configuração Copie `.env.example` apenas como referência. O prefixo é `CA_`. Defaults locais importantes: | Variável | Uso | |---|---| | `CA_AWS_ENABLED=false` | impede composição AWS | | `CA_CHAT_PROVIDER=test` | modelo substituto | | `CA_EMBEDDING_PROVIDER=local` | embeddings determinísticos | | `CA_STORAGE_BACKEND=filesystem` | artefatos locais | | `CA_ENABLE_RAG` | habilita indexação | | `CA_PGVECTOR_DSN` | conexão pgvector; nunca registrar o valor | | `CA_COLLECTION_BACKEND` | `local` ou `mcp` | | `CA_MCP_SERVER_URL` | endpoint SSE | | `CA_API_PUBLISH_ENABLED` | registro HTTP pelo worker | Credenciais AWS seguem somente a cadeia padrão do SDK e não pertencem a arquivos versionados. ## MCP O FastMCP expõe `collect_normatives`. Há três evidências distintas: - objeto Scraper Agent usando `MCPToolset`: `test_scraper_agent_mcp.py`; - cliente/servidor via SSE real: `test_mcp_sse_transport.py`; - worker Docker usando `McpDocumentCollector`: `run_worker.py`, Compose e log curado da demonstração. Não há fallback silencioso do Scraper Agent para a fonte local. ## FastAPI e exemplos Swagger: `http://127.0.0.1:8000/docs`. | Método | Path | Finalidade | |---|---|---| | GET | `/health` | saúde sem chamada externa | | GET | `/normativos` | regras paginadas e filtradas | | GET | `/compliance` | resultados de conformidade | | GET | `/search` | busca RAG | | POST | `/reports` | registro idempotente | | GET | `/reports` | lista de registros | | GET | `/reports/{report_id}` | detalhe ou 404 | | GET | `/openapi.json` | contrato OpenAPI | Exemplos `curl`, PowerShell e Python, incluindo 404/409/422/503, estão em [EXAMPLES.md](docs/api/EXAMPLES.md). `X-Request-ID` correlaciona a requisição; `Idempotency-Key` é enviado pelo cliente HTTP de publicação. O contrato exigido de busca é `GET /search?query=...`, implementado com `SearchQuery`/`SearchResponse` e documentado no Swagger/OpenAPI. ## RAG e pgvector `ChunkContent` produz IDs e hashes determinísticos. `IndexContent` reutiliza embeddings, remove chunks obsoletos e faz upsert pelo port `VectorStore`. `SearchContent` devolve hits com proveniência e suficiência sem usar LLM. O Compose fornece PostgreSQL/pgvector real; fora dele existe `InMemoryVectorStore`. ## Bedrock e AWS ### Execução sem conta AWS Nada adicional é necessário: mantenha `CA_AWS_ENABLED=false`, `CA_CHAT_PROVIDER=test`, `CA_EMBEDDING_PROVIDER=local` e `CA_STORAGE_BACKEND=filesystem`. `AWSClientFactory`, `ModelFactory`, `BedrockEmbeddingProvider`, `S3RawDocumentStorage` e `S3ReportArtifactStore` são adapters reais com clients injetáveis. Os testes usam `Stubber`; não houve chamada real a Bedrock ou S3 e compatibilidade de produção não é alegada. Testes live exigem flags explícitas e permanecem skipped por padrão. OpenSearch, SQS, SNS, EventBridge provisionado e deploy AWS não foram implementados. ## Fixtures e relatórios `fixtures/normative_catalog.json` contém exatamente 50 registros mock. O manifest referencia dois HTML e um PDF, todos fictícios, que resultam em 12 `NormativoItem`. O relatório representativo está em [`docs/evidence/reports`](docs/evidence/reports/), com manifest, resumo e hashes. ## Testes e desenvolvimento ```powershell uv sync --locked uv run ruff check . uv run ruff format --check . uv run mypy uv run pytest -q ``` Na validação de 2026-07-27, Ruff/formatação/lock passaram; `uv run mypy` falhou com 89 erros nos testes, embora `uv run mypy src/compliance_agent` passe. Consulte a evidência antes de usar os comandos como gate de aprovação. Com pgvector: ```powershell $env:CA_PGVECTOR_DSN = Read-Host "DSN local temporária" uv run pytest tests/integration/test_pgvector_store.py tests/integration/test_pgvector_search_api.py -q ``` Nunca grave a DSN em log ou evidência. Resultados executados estão em [FINAL_VALIDATION.md](docs/evidence/FINAL_VALIDATION.md). ## Observabilidade, segurança e FinOps Consulte [OBSERVABILITY.md](docs/operations/OBSERVABILITY.md), [FINOPS.md](docs/operations/FINOPS.md) e a [revisão final de segurança](docs/security/FINAL_REVIEW.md). Logs correlacionam `run_id`, `request_id`, estágio, status e duração sem conteúdo integral. Guardrails detectam PII e prompt injection antes da indexação. Portas são loopback, containers são non-root/read-only e exemplos não contêm segredos. Custos AWS não foram medidos; não se alega custo zero. O fluxo local evita chamadas pagas, reutiliza hashes/embeddings e impõe limites. ## Idempotência e falhas parciais As garantias são separadas: - coleta: SHA-256 identifica conteúdo inalterado; - chunks/embeddings: IDs determinísticos e reutilização; - pgvector: upsert por ID; - HTTP: mesmo `run_id` e hash reutiliza o registro; conteúdo diferente retorna 409; - artefatos: mesma chave e mesmos bytes são reutilizados; bytes diferentes colidem; - pipeline completo: repetir o mesmo `run_id` pode terminar `PARTIAL` por colisão intencional do artifact store. Portanto, não se afirma idempotência integral irrestrita. Falhas não fatais preservam warnings/erros estruturados; guardrail impeditivo ou artefato inseguro não é ocultado. ## Metodologia spec-driven e IA assistida O trabalho partiu de requisitos, critérios de aceite, contratos, ADRs e decisões em `specs/` e `docs/project/`. O Codex foi usado como executor e assistente de implementação/documentação. Código assistido por IA foi submetido aos mesmos testes, tipagem e revisão humana esperada; não se afirma autoria exclusivamente manual. As fontes técnicas adotadas são as documentações oficiais de Pydantic AI, AWS SDK/Bedrock/S3, MCP/FastMCP, FastAPI, pgvector, PostgreSQL, Docker e uv. Workflow, transições, parsing, hashing e persistência ficam em código determinístico; LLM não controla sequência nem efeitos. ## Evidências e demonstração - [índice de evidências](docs/evidence/README.md); - [matriz requisito → implementação → teste → evidência](docs/evidence/REQUIREMENTS_TRACEABILITY.md); - [ambiente](docs/evidence/ENVIRONMENT.md); - [validação final](docs/evidence/FINAL_VALIDATION.md); - [roteiro de 5–8 minutos](docs/demo/DEMO_SCRIPT.md); - [vídeo de demonstração](https://drive.google.com/file/d/1PQqJEYo3k3EiJL3TsG2mYkkwP8NMccu8/view?usp=sharing) e seu [registro de validação](docs/demo/VIDEO.md); - `scripts/demo.ps1` e `scripts/demo.sh`. Screenshots e vídeo são evidências reais. O MP4 permanece hospedado externamente e não integra o repositório Git. ## Limitações e trabalhos futuros - Git publicado na branch `main` do repositório oficial; - a publicação HTTP é executada pelo Report Consolidator Agent: sua única tool tipada delega ao `ReportApiClient`, enquanto o worker apenas compõe dependências e inicia a execução após persistir JSON/PDF; - AWS live não executada; - registry HTTP em memória; - autenticação/autorização fora do MVP; - OpenSearch, mensageria e deploy AWS não implementados; - embedding local é um double, não mede qualidade semântica Bedrock; - métricas de token/custo só existem quando o provider as oferece. Trabalhos futuros possíveis, fora deste desafio: persistência do registry, autenticação, infraestrutura AWS e testes live controlados. ## Troubleshooting - `CA_POSTGRES_PASSWORD must be set`: exporte uma senha local antes do Compose. - `/search` retorna 503: o backend de busca não foi composto; use o Compose ou configure `CA_PGVECTOR_DSN`. - pgvector tests skipped: a DSN de teste não está configurada. - worker retorna `1`: examine o log sanitizado; repetir o mesmo `run_id` com artefato divergente pode produzir `PARTIAL`. - erro de cache/permissão no Windows: defina `UV_CACHE_DIR`, `TEMP` e `TMP` para diretórios graváveis. - porta ocupada: use outro projeto/porta ou derrube somente o Compose criado para a demonstração. ## Uso no desafio Projeto preparado exclusivamente para avaliação técnica, com dados fictícios. Nenhuma licença adicional é declarada além do contexto do desafio; confirme os termos do processo seletivo antes de reutilizar ou distribuir.