Guia de Uso

Última revisão: 08/07/2026, sobre o estado do branch main (v2.0.0).

Instalação

git clone https://github.com/alexandrebrt14-sys/geo-finops.git
cd geo-finops
pip install -e ".[dev]"
pytest   # suíte roda em <10s, sem dependências externas

O pacote funciona sem configuração: os defaults seguem XDG (~/.config/geo-finops/calls.db). Overrides via GEO_FINOPS_CONFIG_DIR, GEO_FINOPS_DB_PATH e demais variáveis listadas na tabela "Environment variables" do README.

Registrar uma call (API principal)

from geo_finops import track_call

track_call(
    project="geo-orchestrator",
    model_id="claude-opus-4-6",
    tokens_in=500,
    tokens_out=200,
    cost_usd=0.022,
    run_id="20260419T120000_abc123",  # agrupa calls da mesma execução
    task_type="architecture",          # opcional
    success=True,
)

O provider é inferido automaticamente do model_id. Retorna o id da linha inserida ou None (dedup hit ou erro).

Consultas e agregações

from geo_finops import query_calls
from geo_finops.aggregates import totals, top_models, daily_timeseries

rows = query_calls(project="papers", limit=10)
t = totals(start="2026-04-01T00:00:00+00:00")
models = top_models(limit=10)
daily = daily_timeseries(days=30)

CLI

python -m geo_finops.cli status
python -m geo_finops.cli summary --by provider
python -m geo_finops.cli summary --by project --start 2026-04-01
python -m geo_finops.cli list --project papers --limit 20
python -m geo_finops.cli migrate        # históricos legados (idempotente)
python -m geo_finops.cli sync --dry-run
python -m geo_finops.cli sync

Com pip install -e ., os entry points geo-finops e geo-finops-sync ficam disponíveis.

Scripts de operação

python scripts/health_check.py            # 13 dimensões ponta-a-ponta
python scripts/export_snapshot.py         # snapshot JSON para landing-page-geo
python scripts/aggregate_dashboard.py --since 30   # dashboard HTML solo
python scripts/weekly_digest.py --format markdown  # digest semanal
python scripts/bootstrap_supabase.py      # cria a tabela finops_calls se ausente

Sync automático

• Windows: powershell -ExecutionPolicy Bypass -File install_scheduler.ps1 cria a task GeoFinOpsSync diária às 23:50.
• Linux/Mac: crontab 50 23 * * * /usr/bin/env python -m geo_finops.sync >> ~/.config/geo-finops/logs/sync.log 2>&1.

Instrumentar um novo projeto

1. Criar um adapter thin no projeto consumidor que importa geo_finops.track_call via sys.path e vira no-op em ImportError (modelo completo na seção "Instrumentar novo projeto" do README).
2. Chamar o adapter após cada call de LLM.
3. Validar com python scripts/health_check.py.

Troubleshooting rápido

Sintoma	Primeiro passo
Sync não envia para Supabase	python scripts/health_check.py; se a tabela faltar, python scripts/bootstrap_supabase.py; resetar sync_status='error' para pending e rodar python -m geo_finops.sync
Task Scheduler não roda (Windows)	schtasks /Query /TN GeoFinOpsSync /V /FO LIST; recriar a task se necessário
Endpoint live com dados velhos	O snapshot é estático: rodar python scripts/export_snapshot.py e commitar public/finops-snapshot.json no landing-page-geo

O runbook completo está na seção "Runbook de troubleshooting" do README.