grahama1970/assistant

PARE. LEIA TODO ESTE SKILL.MD ANTES DE CHAMAR QUALQUER ENDPOINT.

O que assistant faz?

Gateway de inferência compartilhado (GPT + classificador + regressor) para tarefas de monitoramento de persona.

O "lago morno" — /assistant pode evoluir autonomamente sua pilha de inferência via /assistant-lab (bancada de auto-melhoria: create-*, *-lab, fábrica de modelos) enquanto /monitor-skills fornece observabilidade em todo o ecossistema de skills.

Regra de Iteração de Prompt (IRREVOGÁVEL)

Todos os prompts de sistema para modelos /assistant DEVEM ser iterados através do /prompt-lab antes de serem consolidados em dados de treinamento via /create-gpt. NUNCA crie prompts de sistema manualmente em strings Python.

• Novo prompt de modelo → /prompt-lab eval contra ground truth primeiro
• Platô de prompt (80-90% de concordância shadow) → /prompt-lab compare entre variantes
• Retreinamento de modelo → validar prompt com /prompt-lab find-minimum antes de /create-gpt

Cascata de Camadas

Camada	Método	Custo	Latência	Criado Por
0	Heurística (regex/keyword/schema)	grátis	microssegundos	codificado manualmente
0.5	Classificador (DistilBERT/sklearn)	grátis	5-25ms	/create-classifier
0.75	Regressor (sklearn/XGB)	grátis	5-10ms	/create-regressor
1.5	GPT Compartilhado (Qwen3-0.6B GGUF)	grátis	~200ms	/create-gpt
2	scillm (DeepSeek V3.2 via Chutes)	$0.12/1K	2-5s	persona teacher

Ciclo de Vida do Modelo (Lago Morno)

Modelo da camada 2 (persona teacher) cria rótulos
    ↓ harvest.py extrai shadow.jsonl
    ↓
ModelFactory.auto_improve(task)
    ↓ lê taxa de concordância shadow
    ├─ >= 90%: promover (shadow_mode → false)
    ├─ 80-90%: platô → /prompt-lab redesenho
    ├─ 70-80%: /create-gpt ou /create-classifier retreinar
    └─ < 70%: retreinar agressivamente + mudança de arquitetura
    ↓
/gpt-lab benchmark ou /classifier-lab avaliar
    ↓ passou? → promover para registro
    ↓
/monitor-skills detecta deriva ou problemas de saúde
    ↓
/assistant-lab auto-melhoria (diagnosticar → treinar → avaliar → promover)

Uso

# Validar dados através da cascata de camadas
./run.sh validate --task qra-assessor --scope brandon_bailey --input '{"question":"...", "answer":"..."}'

# Classificar texto
./run.sh classify --task bridge-tagger --text "avaliação de vulnerabilidade de satélites"

# Registrar um novo modelo
./run.sh register --task NOME --model-path CAMINHO --type gpt|classifier --threshold 0.85

# Mostrar modelos registrados, taxas de acerto, distribuição de camadas
./run.sh status

# Executar entrada sintética por todas as camadas
./run.sh self-test

# Extrair escalonamentos da camada 2 como dados de treinamento
./run.sh harvest --since 24h

API Python

from assistant import validate, classify

# Validar com cascata de 4 camadas
result = validate(
    input_data={"question": "O que é CWE-79?", "answer": "Cross-site scripting..."},
    task="qra-assessor",
    scope="brandon_bailey",
)
print(result.tier, result.confidence, result.result)

# Classificar com cascata de 3 camadas
result = classify(
    text="avaliação de vulnerabilidade de satélites",
    task="bridge-tagger",
)
print(result.prediction, result.confidence, result.source)

Contrato

• Entrada: Dicionário específico da tarefa (validadores) ou string de texto (classificadores)
• Saída: GatewayResult ou ClassifyResult com camada, confiança, latência
• Dependências: loguru, typer; opcionais: llama-cpp-python, torch, joblib
• Métricas: Anexa JSONL a ~/.pi/assistant/metrics.jsonl

Fábrica de Modelos

# Verificar quais modelos uma tarefa precisa
./run.sh factory needs --task stress-test-grader

# Treinar um GPT a partir de rótulos do professor colhidos
./run.sh factory train-gpt --task stress-test-grader

# Avaliar via /gpt-lab
./run.sh factory evaluate --task stress-test-grader --type gpt

# Promover um modelo aprovado (desativa modo shadow)
./run.sh factory promote --task stress-test-grader --type gpt

# Loop de melhoria autônoma (decidir + treinar + avaliar + promover)
./run.sh factory auto-improve --task stress-test-grader

from model_factory import ModelFactory

factory = ModelFactory()
result = factory.auto_improve("stress-test-grader")
# → lê concordância shadow, treina/avalia/promove conforme necessário

Comportamentos Chave

1. Carregamento lazy de modelo: Pesos carregados na primeira chamada, armazenados em cache no processo
2. Injeção de memória: Recupera do escopo da persona, antepõe ao prompt de sistema do GPT
3. Modo passagem: Cai diretamente para scillm se nenhum modelo local existir
4. Modo shadow: Tarefas com "shadow_mode": true executam modelo local E scillm em paralelo, registram discordâncias em shadow.jsonl, retornam o resultado do professor (scillm). Permite ramp-up seguro de novos modelos alunos.
5. Colheita: Extração noturna de escalonamentos da camada 2 como rótulos do professor
6. Fábrica de Modelos: Via /assistant-lab, treina, avalia e promove modelos autonomamente quando o modo shadow mostra que uma tarefa precisa de melhoria
7. Lago Morno: /monitor-skills observa o ecossistema (observabilidade), /assistant-lab corrige problemas (auto-melhoria). Juntos formam o lago morno onde /assistant evolui.

Erros Comuns

ERRADO: Criar prompts de sistema manualmente em strings Python

SYSTEM_PROMPT = "Você é um validador QRA. Verifique se a resposta está correta..."

CERTO: Iterar prompts através do /prompt-lab antes de consolidar em dados de treinamento

.pi/skills/prompt-lab/run.sh eval --prompt qra_validator_v1 --model deepseek
# Apenas após validação no prompt-lab → criar dados de treinamento

ERRADO: Treinar com dados insuficientes (< 200 amostras por classe)

./run.sh factory train-gpt --task sparta-intent  # 50 amostras, 12 classes = 4/classe!

CERTO: Permanecer na camada 2 e colher mais rótulos do professor primeiro

./run.sh harvest --since 7d  # acumular rótulos shadow
./run.sh status              # verificar contagens de amostras antes de treinar

ERRADO: Pular modo shadow e promover modelos não testados

./run.sh factory promote --task stress-test-grader  # sem comparação shadow!

CERTO: Executar modo shadow, verificar taxa de concordância, depois promover

./run.sh factory auto-improve --task stress-test-grader
# auto-improve lê a taxa de concordância shadow e decide