geo-finops — Wiki

Tracking centralizado de uso de LLMs para os projetos do ecossistema Brasil GEO. Substitui 4 sistemas de tracking paralelos por um único SQLite local com sincronização diária para Supabase e publicação em https://alexandrecaramaschi.com/finops.

Versão atual: 2.0.0 (produção). Licença: MIT (arquivo LICENSE adicionado em 08/07/2026 via PR #6).

Páginas desta wiki

• Arquitetura — pipeline SQLite local → Supabase → snapshot → site, schema e adapters.
• Guia de Uso — instalação, API Python, CLI, scripts de operação e troubleshooting.

Documentação no repositório

• README — referência completa (API, CLI, env vars, runbook).
• Roadmap 2026 Q2–Q4 — plano CTO; próxima revisão em 01/08/2026.
• Refatoração v2.0 (19/04/2026)
• Lições aprendidas — 9 bugs reais encontrados.
• CHANGELOG

Estado do repositório (30/09/2026)

• Testes no CI desde 09/08/2026: até essa data o repositório nunca tinha rodado teste em servidor; as 18 execuções de Actions da vida do repo eram todas do scan de segurança. O PR #8 criou o test.yml (pytest em Python 3.11 e 3.12) com uma sentinela que reprova o build se a coleta cair abaixo de 155 testes, e consertou o teste de série diária que quebrava sozinho com o calendário. A suíte tem 155 testes e roda em cerca de 8 s.
• Digest com validade declarada desde 10/08/2026: o payload leva valid_for_hours (48) e stale_after ao lado do generated_at. O motivo foi o endpoint público /api/finops/llm-usage ter servido por 112 dias um retrato de 19/04 sem nada que denunciasse a idade.
• Consumidores ativos: papers e caramaschi. O adaptador do geo-orchestrator foi removido como código morto na refatoração 5.1 dele (08/09/2026) e o de curso-factory não existe mais; ver Arquitetura.
• Tabela de preços defasada: prices.yaml segue na versão de 2026-04-09 (Claude 4.6, GPT-4o, Gemini 2.5, Sonar, Groq Llama). O parque do geo-orchestrator, desde 25/09/2026, tem 16 modelos em Anthropic, OpenAI, Google, Perplexity e xAI, sem Groq. Modelo fora da tabela cai no preço de fallback (US$ 0,001 e 0,003 por mil tokens).
• Issues abertas do owner: #1 (roadmap), #2 (coverage), #3 e #4 (ratificar Alembic e prices.yaml, já implementados), #7 (número de WhatsApp como default em repositório público).

Estado de 08/07/2026

• Segurança: workflow "Security scan (Python)" (bandit + pip-audit + gitleaks) reabilitado e verde nos 3 jobs após o PR #5 (que zerou os falsos positivos B608 do bandit e adicionou .env ao .gitignore). Atenção: workflows agendados são desabilitados automaticamente pelo GitHub após cerca de 60 dias sem atividade no repositório.
• Governança: LICENSE MIT adicionado (PR #6, 08/07/2026), alinhando o repositório ao badge do README.
• Decisões pendentes do owner (bloqueiam o roadmap Q3):
  • Issue #3 — B-014 Alembic migrations (já implementado no main; falta ratificar).
  • Issue #4 — B-020 prices.yaml versionado (já implementado no main; falta ratificar e definir cadência de verificação de preços).
  • Issue #7 — default de WhatsApp em repositório público.
• Qualidade: Issue #2 — meta de coverage 54% → 70% (janela Q3-W2, 05/08 a 20/08/2026).