Architecture Target — AI Factory

Versão congelada na fase M0 (arquitetura e escopo). Este documento é a referência canônica do que pertence à AI Factory, o que fica fora, quem chama quem, e qual modelo atende cada capability. Deriva do material já produzido (ai_factory_docs/ARCHITECTURE_OVERVIEW.md, task-pack M0).

1. Objetivo

Construir uma AI Factory: infraestrutura de engenharia assistida por agentes onde um control loop junta contexto (o que o agente precisa saber), roteamento de modelos (qual modelo executa) e execução, com agentes trabalhando em workspaces isolados e auditáveis e gates de aprovação humana no caminho crítico.

2. Componentes e responsabilidades

Relações canônicas

DEV-MACHINE
   |  Git / API / SSH / human control
   v
AI FACTORY
   +-- small-pine ----------------------> small-router
   |      contexto via context-provider    |  providers: own-fleet / serverless
   |      frota própria via factory.slurm   v
   +-- context-graph-engine           small-pine (porta 8080, Slurm/vLLM)
   +-- orchestrator (control loop)
   +-- infra / deploy / evals / .ai-factory

• small-router é o router canônico e small-pine é provider próprio + consumidor dele.
• Os dois coexistem em portas separadas (small-router :8081, small-pine :8080).
• O orquestrador não é um segundo router.

3. Fronteira da dev-machine (decisão formal)

A dev-machine está fora do monorepo da AI Factory e fora do refactor.

É apenas:

• ambiente de desenvolvimento;
• control plane humano;
• ponto de acesso ao Git;
• cliente/consumidor dos serviços da AI Factory.

Dentro da AI Factory: small-pine, small-router, context-graph-engine, small-infer/infra dos Sparks, deploy, evals, docs, .ai-factory/.

Fora: dev-machine, dotfiles pessoais, credenciais locais, estado de sessão dos desenvolvedores, configuração específica do editor, tooling pessoal.

4. Política de modelos

Matriz inicial de modelos / capabilities

Spark 02: decidir após medir VRAM, latência, throughput, concorrência e interconnect; então escolher entre réplica do Qwen, segundo modelo local ou serving distribuído.

Política de routing por tier

• coding + private → Qwen Coder / Spark 01 (fallback aprovado se permitido)
• architecture → DeepSeek-V4-Flash → Qwen3.7-Plus → Qwen local (quando adequado)
• review → DeepSeek → Qwen local
• general → Qwen3.7-Plus → outros backends aprovados

O agente pede capabilities, não nomes de modelos. small-router escolhe.

5. Princípios

1. O agente pede capabilities; não escolhe diretamente um modelo.
2. small-pine não conhece hardware/provider específico.
3. small-router centraliza routing.
4. Código privado permanece em backends autorizados.
5. Nenhum agente ganha acesso amplo por padrão.
6. Mudanças agenticas acontecem em workspaces isolados.
7. Nada novo entra no caminho crítico sem justificar impacto no objetivo.

6. Estado atual e encaminhamento

• Fase atual (2026-09-03): M0, M1, M2, M3(subsumido), M4, M6, M10, M11 concluídos

(arquitetura/escopo, inventário read-only, monorepo, refactor small-pine, integração small-router, registry/routing declarativo, context-graph). Pendentes: M5, M7, M8, M9, M12, M13, M14, M15/M15b. Próximo: M5 (decisão A/B/C reaberta com dados; caderno ai-factory-task-pack/M5-medicoes-spark02-2026-09.md — T2.C medida, T2.A/T2.B suspensas pelo slurmctld failed no head desde 2026-08-21).

• small-router e context-graph-engine foram extraídos do monorepo em 2026-08-29 —

agora são repos independentes (~/dev/small-router, ~/dev/context-graph-engine). O small-pine os consome por contrato HTTP/config, não por checkout.

• Roadmap (fonte única): ai-factory-task-pack/ (M0–M15). Ver tabela de encaminhamento

abaixo e o detalhamento em docs/open-work.md.

• orchestrator é construído no M14 (services/orchestrator, Go stdlib pura) — o único

componente com milestone próprio, pois não era executado por nenhum M antes.

Roadmap consolidado (M0–M14)

Os docs legados ai_factory_docs/ (com os M0–M8 antigos, cuja numeração divergia do M5 em diante) foram arquivados em backup/ai_factory_docs/ para eliminar a fonte duplicada.