Metadata-Version: 2.4
Name: agentnexusplatform
Version: 0.1.0
Summary: Control plane Git-native para coordenação de agentes: trabalho, decisões, handoffs e conflitos explícitos, versionados e auditáveis.
Author: AgentNexusPlatform
License: MIT
Keywords: agents,coordination,git,multi-agent,control-plane
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: semantic
Requires-Dist: fastembed>=0.4; extra == "semantic"

# AgentNexusPlatform

Produto: transformar em SaaS o protocolo de coordenação multi-agente
(roteador + wiki por tópico + decisões + quadro de trabalho) validado dentro
do repositório **GymAi Pro** entre 06/09/2026 e 14/09/2026. Este documento é o
handoff — tudo que foi decidido numa sessão de ideação longa, pra continuar
aqui sem arrastar aquele histórico nem misturar com o desenvolvimento do app.

## Por que isto é um produto

O GymAi Pro roda com várias sessões de IA (Claude Code, Codex, Cursor, Kimi)
editando a mesma árvore git ao mesmo tempo. Isso já causou perda de commit,
furo de segurança (~40 min aberto) e horas de diagnóstico errado. A solução —
uma base de conhecimento em markdown versionada no git (router → wiki por
tópico → decisões → quadro de trabalho), mais um manual de sobrevivência pra
git compartilhado — funcionou bem o suficiente pra virar tese de produto: com
o volume de vídeos no YouTube propondo variações do mesmo problema (memória
persistente pra IA de código), esta solução, medida, saiu na frente.

Documentos de referência publicados (Claude Artifacts — acessíveis fora deste
projeto, independente de onde a conversa aconteceu):

- **[Kit de Coordenação Multi-Agente](https://claude.ai/code/artifact/b1604567-bed3-4241-acc1-f4b43ecf4689)** — os dois prompts vendáveis: o Instalador (bootstrap da estrutura em qualquer repo) e o Auditor (disciplina recorrente, o que vira assinatura).
- **[Infra do Kit de Coordenação](https://claude.ai/artifact/EieUEVezZeYAQkFoYkTHdV)** — topologia Oracle (quente) × Locaweb (fria), schema MySQL completo, plano de implementação em 7 fases, funil de onboarding do cliente.

## Decisões já tomadas (não reabrir sem motivo novo)

1. **Não centralizar o artefato de coordenação em si.** `router.md`/`wiki/`/`decisoes/`/quadro continuam sendo arquivo, na árvore do cliente — é isso que dá zero-setup, diff em PR e funcionamento offline. Avaliamos e descartamos mover isso pra MySQL (recriaria o erro do "ai-memory"/Akita: segunda fonte de verdade divergindo do git).
2. **O que centraliza**: biblioteca de padrões curada pela empresa (não pelo cliente), dashboard de auditoria hospedado, licenciamento. Nunca o conteúdo bruto do cliente (incidente, decisão, segredo de arquitetura).
3. **Modelo de acesso ao repo do cliente**: Agente instalado (CLI local) primeiro, GitHub App como possível "modo enterprise" depois — não o contrário.
4. **Licenciamento nunca por chamada de ferramenta.** Validação 1×/sessão ou 1×/dia, com cache e graça offline. Isto é lição paga: o hook `PreToolUse` do graphify custava ~400ms por chamada de Bash/Grep/Read/Glob, aplicado à árvore inteira — medido e revertido em 13/09/2026 no próprio GymAi Pro.
5. **Banco: PostgreSQL (SaaS) + SQLite (agente local).** Revogado o MySQL. O PostgreSQL é a base única do servidor — ACID, JSONB compacto, FTS nativo (`tsvector`) e busca vetorial via `pgvector` para recuperação top-k (minimiza tokens), migrations via Alembic, replication/arquivamento. O SQLite (FTS5 + sqlite-vec) é apenas cache/índice offline do agente local, derivado do Git — nunca uma segunda fonte de verdade. Tabelas desenhadas por padrão de acesso, não por entidade pura.
6. **Topologia**: tudo que responde uma sessão em andamento (API, Redis, PostgreSQL primário) fica na VM Oracle, como mais um serviço no `docker-compose.yml` que já roda `hermes-agent`/`hermes-support`. Sem arquivo frio em fornecedor separado: o PostgreSQL é a base única, e o arquivamento/retenção sai de replicação e particionamento na própria instância — não de uma segunda infraestrutura com deploy manual.
7. **Funil**: cadastro → instalação local (funciona offline, nunca bloqueia) → primeiro valor imediato (auditoria roda na hora da instalação, dashboard não nasce vazio) → loop recorrente (hook de git ou cron do cliente) → conversão trial→pago via Asaas (gatilho por tempo ou por 2º repo) → equipe (licença por repositório instalado, não por pessoa).
8. **Locaweb como arquivo frio: REVOGADA em 14/09/2026.** A decisão de usar a Locaweb como destino de arquivo frio (deploy manual cPanel/FTP, nginx/PHP na frente, risco de `413` silencioso e `REMOTE_ADDR`/`HTTPS` não confiáveis) foi abandonada. Substituto definido: PostgreSQL (SaaS) + SQLite (agente local), conforme a decisão #5.

## Números medidos que sustentam o pitch (não são estimativa)

- `TRABALHO_EM_ANDAMENTO.md` do GymAi Pro chegou a **245 KB (~66 mil tokens) em 14 dias** — 43% de uma janela de 200k gastos antes de abrir um arquivo de código. Reestruturado (quadro = stub de 6 linhas, história em `docs/trabalho/<slug>.md`) para **20 KB (~5,6k tokens)**, 11,8× menor.
- Hook `PreToolUse` do graphify: **~400ms por chamada** de ferramenta, medido, removido.
- Graphify (grafo de código) no mesmo repo: **144,3× de redução de token** por consulta, medido via `graphify benchmark`.
- Divergência normal entre `main` local e `origin/main` num repo com múltiplas sessões de IA cherry-pickando cada uma o próprio commit: **83 vs. 71 commits**, quase tudo mesmo conteúdo com SHA diferente — isso é o comportamento esperado do fluxo, não bug (lição aprendida depois de eu mesma ler errado da primeira vez).

## Em aberto — próximos passos de ideação/execução

- Nome final do produto (este README usa "AgentNexusPlatform" como nome da pasta/projeto; não foi validado como nome comercial).
- Schema do funil de billing detalhado (webhooks do Asaas, estados de trial expirado).
- Decisão sobre precificação (por repositório? por conta? por seat de dashboard?).
- Piloto: usar o próprio GymAi Pro como conta zero, comparando os números acima como caso de referência real.

## Estado da implementação (Fase 1 — núcleo local + backbone Postgres)

A Fase 1 está **implementada e testada**. Não é mais só ideação.

### Núcleo local (`agentnexus` — pacote Python instalável)

Control plane Git-native. `pip install -e .` expõe o comando `agentnexus`:

- `agentnexus init` — bootstrap idempotente da estrutura (router, quadro, wiki, decisões, claims, handoffs, histórico).
- `agentnexus doctor` — valida a estrutura; falha com exit≠0 se houver erro.
- `agentnexus audit` — auditoria determinística (sem LLM): arquivos ausentes, quadro inchado, claims expirados/conflitantes, handoffs abandonados, links quebrados.
- `agentnexus claim --actor X <escopo...>` — reserva de escopo de arquivos com TTL; **recusa sobreposição** de outro ator.
- `agentnexus release <id>` — libera um claim.
- `agentnexus handoff create/accept` — handoff com **aceite único** (segundo accept é recusado).
- `agentnexus index rebuild/search` — índice SQLite híbrido (FTS5 + vetores) derivado dos markdown. **Rebuild incremental por sha256**: só re-embedda páginas novas/alteradas e expurga as removidas (8 páginas sem mudança → 0.2s; antes ~5s). `--semantic` força o modelo; `--lexical` desativa; default é automático. Busca combina FTS5 + cosine com **RRF** (Reciprocal Rank Fusion).
- `agentnexus configure --api-url ... --api-key ...` — configura a conexão com o servidor SaaS.
- `agentnexus sync-patterns` — sincroniza os patterns do índice local com o servidor. **Privacidade (decisão #2)**: envia apenas slug/título/sha256/embedding — nunca o corpo dos documentos. Upsert idempotente por sha256 no servidor (`repository_patterns`), com remoção de páginas deletadas.
- `agentnexus report [--actor X]` — roda a auditoria e envia o relatório (métricas apenas) ao servidor; **offline-safe** (enfileira se o servidor estiver fora).
- `agentnexus embed <texto>` — gera embedding local de 384 dimensões. Dois modos: **semântico** (`--semantic`, usa `paraphrase-multilingual-MiniLM-L12-v2` via `fastembed`, 100% local, funciona bem em português) ou **hashing determinístico** (`--hashing`, sem modelo externo). Auto-detecta o melhor disponível.
- `agentnexus license [--force]` — consulta o estado da licença (validação 1×/dia, com cache e graça offline — decisão #4).

Testes: `pytest tests/` — 26 testes (inclui 3 de embedding semântico, que pulam se `fastembed` não estiver instalado).

### Backend (FastAPI + PostgreSQL + pgvector + FTS + Alembic)

- `backend/app/` — API em FastAPI, SQLAlchemy 2.0 + psycopg.
- Modelos: `users`, `repositories`, `audit_events`, `api_keys`, `licenses`, `billing_events`, `patterns` (biblioteca curada com `embedding vector(384)` + `search_vector tsvector`).
- Busca full-text em português (`to_tsvector`/`websearch_to_tsquery`) e vetorial (`cosine_distance` via pgvector) sobre os padrões curados.
- Migrations Alembic (inclui `CREATE EXTENSION vector`).
- **Autenticação (Fase 2):** endpoints admin protegidos por `AGENTNEXUS_ADMIN_TOKEN` (fail-closed se vazio); endpoints do agente protegidos por API key (`api_keys`, SHA-256). Instalação via `POST /api/v1/installations` emite a chave uma única vez.
- **Licenciamento (Fase 3):** trial criado na instalação; validação 1×/sessão ou 1×/dia (`GET /api/v1/license`), com cache e graça offline no agente (decisão #4). Licença por repositório (decisão #7).
- **Billing Asaas (Fase 3):** webhook `POST /api/v1/billing/webhook` idempotente por `event_id`, com máquina de estados (`PAYMENT_CONFIRMED`→ativo, `PAYMENT_OVERDUE`→expirado, `PAYMENT_DELETED`→inativo). **Requere credenciais Asaas para produção.**
- **Dashboard (Fase 3):** `GET /dashboard` (HTML) + `GET /api/v1/dashboard/summary` (métricas apenas — repositórios, usuários, auditorias, licenças por status, auditorias recentes; nunca conteúdo bruto).
- `docker compose up -d db` sobe `pgvector/pgvector:pg16`; `docker compose up api` sobe a API.
- Testes: `backend/.venv/Scripts/python -m pytest backend/tests/` — smoke + integração de auth, licenciamento e billing (13 testes).

### O que ainda NÃO existe (fora do corte da Fase 1–3)

- Credenciais Asaas **reais** em produção (a validação HMAC do webhook já está implementada: `AGENTNEXUS_ASAAS_WEBHOOK_SECRET`, fail-closed — sem o secret o webhook recusa 503; assinatura inválida/ausente/adulterada → 401).
- GitHub App (modo enterprise) — ainda só o agente local (decisão #3).
- Publicação no PyPI (pacote validado: build + twine check + smoke em venv limpo; falta `twine upload` com credenciais do usuário).

## Produção

O guia operacional completo (deploy Docker, variáveis, setup admin, instalação do
agente, publicação no PyPI, webhook Asaas, backup, modelo de ameaças) está em
[docs/runbook-producao.md](./docs/runbook-producao.md).

## Como retomar uma sessão aqui

Leia este README primeiro — ele substitui a necessidade de reler a conversa
original (que ficou no repositório GymAi Pro, sessão longa de 06 a 14/09/2026).
Os dois artefatos linkados têm o conteúdo completo de prompts/schema/plano; não
precisam ser recriados.
