gtmedics-observability

Imported from gtellapolinario/gtmedics-observability (AGENTS.md). Install upstream with npx skills add gtellapolinario/gtmedics-observability. Copyright stays with the author.

AGENTS.md — GTMedics FastAPI Template

Este documento orienta agentes de IA que trabalham no template de backend GTMedics (gtmedics-observability). Ele reflete o estado atual das skills do projeto, especialmente harden-gtmedics-backend, gtmedics-backend-profiles, gtmedics-observability, gtmedics-fastapi-template e gtmedics-ai-agents.

Leia este arquivo antes de editar qualquer código no repositório.

1. O que é este repositório

Template profissional, seguro e escalável para APIs FastAPI no ecossistema GTMedics. Não contém regra de negócio clínica real: fornece estrutura reutilizável com segurança, observabilidade, workers assíncronos e camada de IA isolada, configurável por YAML.

Stack principal: FastAPI, Pydantic v2, Pydantic Settings, structlog, Prometheus, OpenTelemetry, Pydantic AI + OpenRouter, Docker Compose.

2. Skills disponíveis e quando usar

Nunca conduza o processo de hardening usando gtmedics-backend-profiles, nem reimplemente o tooling de profiles dentro do hardening.

3. Regras inegociáveis de qualquer trabalho aqui

R0. Nunca edite código antes de ler o SKILL.md correspondente e as fontes locais obrigatórias. R1. Não edite antes de produzir inventário e delta entre estado atual e alvo. R2. Não copie module keys, planos, roles, collections ou regras comerciais do App A. R3. Não aceite identidade, tenant, role ou entitlement enviados pelo cliente como fonte de autorização. R4. Não use defaults previsíveis de secrets em staging ou produção. R5. Nunca converta falha de banco, Redis ou upstream em falso 401. Indisponibilidade de infraestrutura retorna 503. R6. Não logue bodies, cookies, Authorization, prompts, respostas clínicas, CPF, CNS, e-mail, telefone, tokens ou segredos. Dados pessoais são PII sob LGPD — em caso de dúvida, trate como protegido. R7. Não crie cliente HTTP, pool de banco ou pool Redis por request. R8. Não use rate limiter em memória com mais de uma réplica ou em produção. R9. Não habilite bypass de autenticação em staging/produção. R10. Não execute migração destrutiva sem backup com restore verificado, dry-run e rollback. R11. Não exponha docs, métricas, dashboards ou portas internas sem decisão explícita. R12. Não marque fase ou tarefa como concluída sem teste e evidência numérica.

4. Processo obrigatório para hardening

Siga estritamente a ordem abaixo:

1. Ler integralmente o SKILL.md de harden-gtmedics-backend.
2. Ler as fontes locais obrigatórias: AGENTS.md (este arquivo), README.md, docs/architecture.md, docs/security.md, .env.example, factory FastAPI, lifespan, settings, middlewares, dependências, testes, Dockerfiles, Compose e workflows CI.
3. Executar a Fase 0 (inventário + threat model) — leitura, nunca escrita.
4. Criar docs/BACKEND_HARDENING_TASKS.md a partir do template em .agents/skills/harden-gtmedics-backend/agents/references/tasks-template.md, preenchido com dados reais do repositório.
5. Apresentar o arquivo ao usuário e obter aprovação explícita (ou autorização prévia registrada no próprio pedido).
6. Somente então editar código, e somente fases marcadas no tracker.

Se você se perceber editando sem o tracker existir: pare, crie o tracker, registre o desvio na seção de riscos e recomece da fase correta.

Atualize os checkboxes do tracker durante o trabalho — nunca tudo no final. Estados: [ ] pendente, [~] em andamento, [x] concluída com evidência, [!] bloqueada (registrar motivo).

5. Perfis de capacidade

Classifique o backend na Fase 0 antes de escolher medidas. Aplique apenas perfis reais, justificados pelo threat model:

Se nenhum perfil de autenticação se aplicar, mantenha interfaces para extensão, mas não adicione fluxo de login fictício.

6. Fases do hardening e dependências

Leia o arquivo de referência da fase ANTES de executá-la. O SKILL.md contém o mapa; os passos e critérios de aceite estão nas referências.

7. Padrões de código e arquitetura

• Organização modular: app/core, app/api, app/schemas, app/security, app/observability, app/workers, app/ai, app/services, app/repositories.
• Não misture IA com core, services ou observability.
• Não misture observability com business logic; use helpers e dependências.
• Novos módulos de negócio devem nascer em services e repositories, com schemas próprios e testes.
• Mantenha settings em Pydantic Settings com .env.example atualizado.
• Preserve a integração com app/core/config.py e a factory create_app().
• Use tipagem Python moderna (from __future__ import annotations).
• Código completo, sem placeholders.
• Baixo acoplamento; evite vendor lock-in.

8. Segurança básica do template

• Headers seguros via middleware (app/security/headers.py).
• API key opcional (app/security/api_keys.py).
• Rate limiter em memória (app/security/rate_limit.py) apenas para desenvolvimento/testes.
• Endpoints operacionais (/health, /system/info, /docs, /redoc, /openapi.json, /metrics) permanecem públicos em ambiente local quando a API key está habilitada.
• Qualquer alteração que expanda a superfície de ataque deve passar pelo processo de hardening.

9. Observabilidade e privacidade

A camada em app/observability é preservada e integrada via:

setup_observability(app, settings.observability)

Requisitos:

• Logs estruturados em JSON com request_id, trace_id e span_id.
• Métricas Prometheus: HTTP, LLM, workers.
• Tracing OpenTelemetry com exportação OTLP.
• Redaction/allowlist de dados sensíveis (CPF, CNS, e-mail, telefone, tokens, prompts, payloads clínicos).
• Nunca logar corpo completo de requisição, prompt completo, transcrição ou relatório médico integral.
• Usar allowlist antes de redaction.
• Atributos de spans devem passar por sanitize_for_observability.
• Para agents, span padrão é ai.agent.run.

10. IA e agents

• Agents definidos por YAML em app/ai/agents/specs/.
• Prompts em Markdown em app/ai/prompts/.
• Outputs tipados em app/ai/schemas/outputs.py.
• Runtime usa Pydantic AI + OpenRouter.
• Imports tardios para que /health e testes básicos não exijam OPENROUTER_API_KEY.
• Nunca logar input completo, output completo ou prompt completo.
• Sempre instrumentar métricas LLM e span sanitizado.

11. Optional profiles (gtmedics-backend-profiles)

Capacidades opcionais são empacotadas em optional_profiles/<name>/ e ativadas via backend-profiles.json. Nunca misture código de profile desabilitado no runtime básico.

Estrutura de um profile:

optional_profiles/<name>/
  profile.yml           # manifesto validado por schemas Pydantic/JSON
  app/                  # código a ativar
  tests/                # testes isolados
  migrations/           # migrations e rollback
  env.example           # variáveis adicionais (sem secrets)
  compose.fragment.yml  # serviços/volumes opcionais

Scripts:

• python scripts/enable_profile.py <name> [--yes] [--allow-experimental]
• python scripts/disable_profile.py <name> [--yes]

Regras:

• Ativação é idempotente; desativação não apaga dados nem reverte migrations.
• Profiles experimental exigem --allow-experimental.
• Profiles deprecated recusam ativação e apontam superseded_by.
• requires e conflicts são validados antes da ativação.
• Testes do profile rodam antes de atualizar backend-profiles.json.
• CI valida manifests, testa core puro e cada profile isolado.

12. Testes

Sempre adicione ou atualize testes para alterações de arquitetura, segurança, observabilidade, workers ou IA.

Testes obrigatórios existentes:

• tests/test_health.py
• tests/test_security.py
• tests/test_observability.py
• tests/test_workers.py
• tests/test_ai_agents.py
• tests/test_profile_scripts.py

Durante o hardening, adicione testes de caracterização antes de alterar contratos sensíveis.

13. Documentação

Atualize a documentação em docs/ quando mudar arquitetura, rotas, variáveis, Docker ou perfis:

• docs/architecture.md
• docs/security.md
• docs/observability.md
• docs/workers.md
• docs/ai-agents.md
• docs/codex.md

Durante o hardening, mantenha docs/BACKEND_HARDENING_TASKS.md como fonte de verdade do progresso.

14. Docker e supply chain

• docker-compose.yml para desenvolvimento da aplicação.
• docker-compose.observability.yml para stack local de observabilidade (Grafana, Prometheus, Loki, Tempo, OTEL Collector).
• Dockerfile atual.
• Qualquer mudança em container/CI deve considerar: usuário non-root, healthcheck, shutdown gracioso, cache previsível, imagens versionadas, SBOM e scan de vulnerabilidades.

15. Entrega obrigatória do modelo

Ao terminar (ou pausar) qualquer trabalho, informar objetivamente:

1. Fases concluídas, em andamento e bloqueadas.
2. Arquivos alterados.
3. Contratos preservados.
4. Testes e smokes com resultados numéricos.
5. Schema/migrations e necessidade de deploy.
6. Secrets/variáveis novas sem revelar valores.
7. Ordem de rollout e rollback.
8. Riscos residuais.
9. Itens opcionais não implementados e por que não se aplicam.

16. Definição de pronto

Considere o trabalho concluído somente quando:

• Configuração de produção falha fechada (quando aplicável).
• Recursos externos reutilizam pools e fecham no shutdown.
• Identidade/autorização/tenant possuem fonte canônica (quando aplicável).
• Erros de infraestrutura não se tornam falsos erros de autenticação.
• Rate limit distribuído existe quando necessário.
• PII e secrets estão ausentes de logs e respostas.
• Audit trail de acesso a dado clínico existe quando o perfil se aplica.
• Health/readiness, security headers e observabilidade estão operacionais.
• Docker e CI aplicam controles de supply chain (quando aplicável).
• Testes de segurança e arquitetura impedem regressão.
• Backup com restore verificado, rollout e rollback estão documentados.
• Nenhuma regra específica do App A foi incorporada sem requisito do produto.
• Se o repositório usa optional profiles, o estado deles foi validado com a skill gtmedics-backend-profiles.