Demandas complexas decompostas em waves paralelas entre 8 modelos canônicos com circuit breaker em produção e roteamento health-aware. Outage de provider sai de O(N×50s) para O(3×2s + N×0ms). Opus reservado a architecture e critical_review · Sonnet decompõe a wave 1 · Gemini 2.5 Pro protagonista em code e analysis · Groq Heavy primary em review e code_review.
Recebe uma demanda em linguagem natural (PT-BR), decompõe em tasks tipadas com dependências, distribui entre 8 modelos canônicos respeitando o cap por provider, executa em waves paralelas com cache semântico e validação por rubrica, grava métricas e custo, e devolve um relatório estruturado.
Decisões priorizam zero dependência adicional quando possível, padrões da indústria quando necessário e tipagem forte em todas as camadas.
Da demanda em linguagem natural até o relatório estruturado. Cada fase tem responsabilidade única e pode ser substituída isoladamente. Fases determinísticas (sem LLM) reduzem custo e latência; LLMs entram apenas onde raciocínio é necessário.
O usuário descreve a tarefa em PT-BR. Pode ser uma frase ou um briefing de 500 palavras com restrições, exemplos e referências.
Pipeline de 3 etapas determinísticas (parse, enrich, optimize). Sem chamada de LLM. Inspirado em HALO (arXiv 2505.13516).
Gera plano JSON com tasks tipadas e dependências. 1M context aceita briefings longos. Fallback: Sonnet → Opus.
Classifica tier (SIMPLE/MODERATE/COMPLEX) e marca complexity por task. Define quantos LLMs participarão.
Tasks determinísticas (slugify, JSON parse, regex) resolvidas sem LLM. Inspirado em Huryn/Medium. Economia ~30%.
Bag-of-words similarity sobre task description. Hit rate ~25%. TTL ajustado por Quality Judge.
Pré-aloca cada task respeitando PROVIDER_SHARE_CAP. Anthropic ≤ 30%, Google ≤ 55%. Architecture/critical_review hard-pin.
Tasks independentes executam simultaneamente em waves topológicas. Speedup observado: 2-5x. KPI parallelism_efficiency mede.
Rubrica de 5 dimensões (factual, completude, PT-BR, eficiência, fontes). Verdict APROVADO/RESSALVAS/REPROVADO.
execution_*.json gravado, .kpi_history.jsonl atualizado, /health pollable. Auto-trigger de recalibração se drift.
Tasks determinísticas (slugify, JSON parse, regex match) resolvidas sem LLM. Reduz ~30% das chamadas em demandas com componente operacional.
Pipeline de 3 etapas (parse, enrich, optimize) que enriquece a demanda antes de decompor. Aumenta ~25% a qualidade do plano gerado.
Jaccard similarity sobre bag-of-words da task description. Hit rate ~25% em runs repetidos. TTL ajustado pelo Quality Judge.
Classifica demand tier (SIMPLE/MODERATE/COMPLEX) e marca complexity por task. Define quantos LLMs participam e em qual tier.
Macro-plan inicial pode ser detalhado wave-a-wave por demanda complexa. Reduz over-decomposition em demandas simples.
LLM-as-Judge com rubrica de 5 dimensões via Groq. Verdict APROVADO/RESSALVAS/REPROVADO ajusta TTL do cache e dispara retry.
O scheduler agrupa as tasks por dependências em waves e executa cada wave com asyncio.gather(). Tasks independentes na mesma wave rodam simultaneamente em LLMs diferentes — speedup observado em produção: 3-5×.
O fan-out é controlado pelo cap por provider (pré-alocação plan-level). O fan-in passa pelo Quality Judge, que valida e ajusta o TTL do cache.
Decompose gera N tasks. Plan rebalance pré-aloca cada uma respeitando o cap por provider antes da execução. Anthropic ≤ 30%, Google ≤ 55%.
DAG das dependências quebrado em níveis. Tasks no mesmo nível executam paralelo. Speedup = soma(durações)/wall_clock — KPI persistido.
Outputs consolidados passam pelo Quality Judge. Verdict ajusta TTL do cache e pode disparar retry no próximo da fallback chain.
Cada LLM tem papel definido pelas suas forças. Pós-Sprint 9, Opus está reservado a architecture e critical_review; Sonnet decompõe wave 1 (estabilidade); Gemini 2.5 Pro é protagonista em code, analysis e data_processing; Groq Heavy (gpt-oss-120b) primary em review e code_review com latência sub-segundo.
Arquiteto-chefe. Reservado a architecture e critical_review pós-rebalanceamento. Não roteado em code/review padrão.
Tier intermediário Anthropic. Sprint 9 promoveu Sonnet a decomposer canônico (wave 1 estável) e fallback cross-provider em copywriting/code_review. ~80% mais barato que Opus.
Tier econômico Anthropic. Acionado por downgrade automático em complexity LOW. ~95% mais barato que Opus.
Redator e copywriter principal. Conteúdo longo PT-BR, SEO e textos editoriais com voz humana.
Protagonista pós-rebalanceamento em demandas que aproveitam 1M context (code, analysis, data_processing). Sprint 9 cedeu decomposition e review para diversificar — Gemini agora é primary em 3 task types e fallback robusto em outros 11.
Pesquisador profundo. Citações verificáveis, web search e fact-check com fontes academicamente rastreáveis.
Velocista. Latência sub-segundo, ~10x mais barato que GPT-4o. Triagem em massa, classificação e tradução.
Modelo de raciocínio open-weights na infra Groq. 120B parâmetros, 56 reasoning tokens internos. Sprint 9 promoveu para review primary — velocidade sub-segundo + raciocínio profundo + diversifica provider em wave de revisão.
O cap é aplicado por família de provider, não por alias. Anthropic (Opus + Sonnet + Haiku) compartilha o mesmo teto de share por run. O método rebalance_plan_assignments() pré-aloca cada task respeitando esses limites antes da execução.
Sprint 9 elevou de 30% → 40%. Sonnet/Haiku precisam de espaço para cobrir wave 1 (decomposition voltou para Sonnet) + reviews e fallbacks cross-provider. Inclui Opus+Sonnet+Haiku somados.
Capacidade saudável para writing/copywriting/SEO ser primary sem dominar planos analíticos.
Sprint 9 reduziu de 55% → 45%. Cap menor diminui o blast radius em outage do provider e força diversidade na fallback chain. 1M context segue protagonizando code, analysis e data_processing.
Pesquisa profunda com search fees não pode dominar — 50% protege o budget Perplexity em demandas heavy-research.
Cap mais alto reflete o custo ultra-baixo. Volume permitido é grande em classification/translation/summarization sem riscar o budget. Groq Heavy agora também cobre review primary.
Cada tipo de task tem um primary (LLM padrão) e um fallback automático. Quando o primary falha, atinge timeout ou estoura o cap, a fallback chain assume sem perda de tarefa.
| Task type | Categoria | Primary | Fallback |
|---|---|---|---|
| research | PESQUISA | Perplexity | Gemini |
| fact_check | PESQUISA | Perplexity | Gemini |
| analysis | CONSTRUÇÃO | Gemini | Groq Heavy |
| data_processing | CONSTRUÇÃO | Gemini | Groq |
| writing | CONSTRUÇÃO | GPT-4o | Gemini |
| copywriting | CONSTRUÇÃO | GPT-4o | Sonnet |
| seo | CONSTRUÇÃO | GPT-4o | Perplexity |
| code | CONSTRUÇÃO | Gemini | Sonnet |
| review | VALIDAÇÃO | Groq Heavy | Gemini |
| code_review | VALIDAÇÃO | Groq Heavy | Sonnet |
| architecture | VALIDAÇÃO | Opus | Gemini |
| critical_review | VALIDAÇÃO | Opus | Gemini |
| decomposition | CONSTRUÇÃO | Sonnet | Gemini |
| extraction | VELOCIDADE | Groq Heavy | Gemini |
| classification | VELOCIDADE | Groq | Gemini |
| translation | VELOCIDADE | Groq | GPT-4o |
| summarization | VELOCIDADE | Groq | Gemini |
Cada sprint resolveu uma tese específica: fundação CLI, otimização de custo, observabilidade, self-healing, reliability, enterprise readiness, rebalanceamento Gemini-first e — última — resiliência em produção com circuit breaker religado e redistribuição cross-provider. Roadmap atualizado em tempo real com origem de cada decisão.
De abril a maio de 2026, oito sprints entregaram desde a fundação do CLI até o rebalanceamento Gemini-first com cap por provider.
11 fixes P0/P1 cirúrgicos validados por bateria científica
Claude Opus → Sonnet → Haiku acionado automaticamente por complexity
AVG_COST_PER_CALL ajustado + tier_engagement + fallback_save_rate
Loop FinOps fechado com aprendizado de custo a partir do histórico real
Cobertura ponta-a-ponta sem custo de LLM e health check pollable
YAML como single source of truth, HTTP pollable e dashboard publicável
Opus reservado a architecture/critical_review · Gemini protagonista em code/review · Groq Heavy via gpt-oss-120b
Outage de provider deixa de quebrar a wave · circuit breaker religado · backoff por classe · redistribuição cross-provider
Cada item entregue com descrição, justificativa, métricas e arquivos tocados.
11 fixes P0/P1 cirúrgicos validados por bateria científica
Religação completa do cli.py ao Orchestrator(smart=True).run(), removendo o caminho legado v1.0.
Claude Opus → Sonnet → Haiku acionado automaticamente por complexity
O SmartRouter aplica downgrade dentro da família Claude com base em task.complexity (1-2 → Haiku, 3 → Sonnet, 4-5 → Opus).
AVG_COST_PER_CALL ajustado + tier_engagement + fallback_save_rate
Mede a percentagem de tarefas Claude que foram roteadas para Sonnet/Haiku em vez de Opus, validando a adoção do downgrade automático.
Loop FinOps fechado com aprendizado de custo a partir do histórico real
Novo módulo cost_calibrator.py varre os últimos N execution_*.json, agrupa custos por LLM, filtra outliers e persiste a calibração em .cost_calibration.json.
Speedup = sum(task_durations) / total_duration. 1.0 = totalmente sequencial; 5.0 = 5 tarefas paralelas perfeitas.
Cobertura ponta-a-ponta sem custo de LLM e health check pollable
Verifica em uma chamada: api_keys, catalog_consistency, finops_daily, kpi_history freshness, cost_calibration age e drift_detector.
YAML como single source of truth, HTTP pollable e dashboard publicável
build_llm_configs_from_catalog() constrói o dict LLMConfig a partir de catalog/model_catalog.yaml em tempo de import.
Servidor http.server minimal expõe GET /health (200/503), GET /metrics e GET / (docs). Zero dependência adicional.
Opus reservado a architecture/critical_review · Gemini protagonista em code/review · Groq Heavy via gpt-oss-120b
code e review saíram de primary=claude para primary=gemini. Opus reservado exclusivamente a architecture e critical_review (raciocínio arquitetural ou validação final crítica).
Novo alias groq_heavy controlado via env var GROQ_HEAVY_MODEL. Default ativado: openai/gpt-oss-120b (120B parâmetros, 131K context, 56 reasoning tokens internos).
PROVIDER_SHARE_CAP em src/config.py mapeia cada família de provider a um teto de share por run. Anthropic agora soma Opus+Sonnet+Haiku — antes contavam separadamente.
Novo método em SmartRouter que pré-aloca cada task do plano respeitando o cap por provider, antes da execução. Move tasks downgradáveis (low/medium primeiro) de provider sobrecarregado para alternativa viável.
Orchestrator._claude_cfg (legado) agora aponta para gemini. Fallback: gemini → claude_sonnet → claude_opus.
Outage de provider deixa de quebrar a wave · circuit breaker religado · backoff por classe · redistribuição cross-provider
src/circuit_breaker.py existia completo (310 linhas, CLOSED/OPEN/HALF_OPEN, registry singleton) desde o Round 3 mas nunca foi importado em pipeline.py nem llm_client.py — vaporware. Religado: 3 falhas seguidas em qualquer provider abrem o circuito por 90s; tasks subsequentes raise CircuitBreakerError em ~0ms e caem para o próximo da fallback chain.
Antes: 429/500/502/503/504 todos retentavam 3x com backoff 2/4/8s + jitter (até ~14s perdidos). Agora: 5xx e timeout fazem no máximo 1 retry curto de 1s; 429 mantém o exponencial respeitando Retry-After.
Router._is_usable() agora consulta circuit_breaker_registry e o mapa _degraded_until antes de aprovar um LLM. Provider OPEN → bloqueado em todas as próximas tasks da run. Novo método mark_provider_degraded(provider, ttl=120s) permite degradação manual quando há aviso externo (status page, alerta operacional).
decomposition voltou para claude_sonnet primary (wave 1 crítica não pode depender de provider unstable). review virou groq_heavy primary (rápido + diversifica). copywriting e code_review ganharam Sonnet como fallback. Regra dura: os 2 primeiros slots de cada FALLBACK_CHAINS[task_type] são de provedores DIFERENTES.
anthropic 30% → 40% (Sonnet/Haiku precisam de espaço para cobrir wave 1 + reviews). google 55% → 45% (não permitir que um único provider concentre demais e amplifique blast radius). openai 45%, perplexity 50%, groq 65% mantidos.
compute_provider_health() lê o CircuitBreakerRegistry e gera 3 campos novos por entry: provider_health (dict por provider com state, consecutive_failures, totals, health_score), min_provider_health_score (pior provider da run) e providers_open (quantos circuits ficaram OPEN).
tests/test_resilience_outage.py cobre: breaker abre após threshold, short-circuit em <100ms, backoff curto em 503 (vs longo em 429), router pula provider OPEN, degradação manual com TTL, top-2 cross-provider diversity nas chains. Todos com mocks deterministas.
Itens identificados pela análise técnica do orchestrator run #7 (executado pelos próprios 5 LLMs em produção) e pela revisão crítica das sprints anteriores.
Adicionar smoke test E2E gated por env var GEO_E2E_REAL=1 que executa Orchestrator.run() contra APIs reais com budget limitado (ex.: $0.10).
Adicionar QUALITY_JUDGE_MIN_SCORE no config.py (default 0.7) e env var GEO_QUALITY_THRESHOLD. Verdicts abaixo do threshold disparam retry automático.
Pipeline diário que gera o dashboard HTML via cli.py dashboard --html e publica em alexandrecaramaschi.com/geo-orchestrator/dashboard.
Adicionar GET /metrics?format=prometheus que serve as métricas em formato exposition compatível com Prometheus scraping.
GEO_ALERT_WEBHOOK no .env. Quando drift dispara ou um provider passa de 95% do limite, o orchestrator faz POST com payload estruturado.
Adicionar GEO_TENANT env var que prefixa output/, .kpi_history e .cost_calibration por tenant.
Loop de governança fechado sem intervenção humana: detecta drift, recalibra, aplica safety threshold, faz backup automático e segue. Quatro vias de health check (CLI, HTTP, HTML, recovery) para integrar a qualquer pipeline existente.
Detecção → ação corretiva → próxima execução com valores ajustados. Sem dashboard manual.
Cada execution_*.json grava cost por LLM, latência, tokens e verdict.
Se 3 runs consecutivos saem da banda 0.7-1.5x, alerta dispara em .kpi_history.jsonl.
Orchestrator chama recalibrate() varrendo os últimos 30 reports — sem intervenção humana.
Calibrações > 5x ou < 0.2x do default são rejeitadas e logadas em safety_rejections[].
.cost_calibration.json copiado para .backup.json antes de persistir. cli.py finops calibrate-rollback restaura.
Loop fechado: o run seguinte aplica os custos atualizados sem ação humana.
Quatro vias de saúde: síncrona (CLI), assíncrona (HTTP), publicável (HTML) e recuperação manual.
6 health checks (api_keys, catalog, finops, kpi, calibration, drift). Saída humana ou JSON. --strict faz exit 1 — pronto para CI gating.
Servidor HTTP stdlib. GET /health (200/503), /metrics (KPI timeseries), / (docs). Bearer token opcional via GEO_HEALTH_TOKEN.
Gera HTML auto-contido com Chart.js. 5 gráficos + KPI cards + tabela dos 10 últimos runs. Deploy em qualquer servidor estático.
Restaura .cost_calibration.backup.json se a recalibração mais recente apresentou drift suspeito. Recovery one-shot.
Dúvidas técnicas e conceituais sobre o geo-orchestrator pós-Sprint 9.
8 LLMs canônicos em paralelo, cap por provider, governança FinOps automatizada e roadmap público atualizado a cada sprint. Open-source, sem lock-in.