# Agent OS - Fine-Tuning Guide

Guia completo de como treinar adaptadores LoRA para o Agent OS, incluindo erros encontrados, soluções e boas praticas.

## O que e o Agent OS Adapter?

Um modelo fine-tunado que converte linguagem natural em portugues para comandos JSON (SQL queries, shell commands, GitHub actions) para o sistema Agent OS da Hub Formaturas.

**Exemplo:**
- Input: `"quais contratos ativos"`
- Output: `{"action": "sql", "sql": "SELECT * FROM contratos WHERE status='ativo'"}`

## Modelos Treinados

### Adapters LoRA (precisam do modelo base pra rodar)
| Modelo | Base | Repo HuggingFace |
|--------|------|------------------|
| 1.5B (rapido) | Qwen/Qwen2.5-1.5B-Instruct | [devsomosahub/agent-os-adapter-1.5b](https://huggingface.co/devsomosahub/agent-os-adapter-1.5b) |
| 7B (preciso) | Qwen/Qwen2.5-7B-Instruct | [devsomosahub/agent-os-adapter-7b](https://huggingface.co/devsomosahub/agent-os-adapter-7b) |

### Modelos Merged (prontos pra usar, incluem base + adapter)
| Modelo | Repo HuggingFace | Inference Endpoint |
|--------|------------------|--------------------|
| 1.5B merged | [devsomosahub/agent-os-1b5-merged](https://huggingface.co/devsomosahub/agent-os-1b5-merged) | Sim (T4) |
| 7B merged | [devsomosahub/agent-os-7b-merged](https://huggingface.co/devsomosahub/agent-os-7b-merged) | Sim (A10G) |

**IMPORTANTE:** Use os modelos merged pra Inference Endpoints. Os adapters LoRA nao funcionam direto na Inference API.

## Dataset

- **Repo:** [devsomosahub/agent-os-dataset](https://huggingface.co/datasets/devsomosahub/agent-os-dataset)
- **Formato:** JSONL com campos `input` e `output`
- **Tamanho:** 415 exemplos (duplicados 4x para 1660 amostras no treino)
- **Dominio:** Queries SQL para banco Supabase do sistema Hub Formaturas (contratos, parcelas, turmas, user_profiles)

## Configuracao do Treino

### LoRA Config
```python
LoraConfig(
    r=32,
    lora_alpha=64,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)
```

### Training Args (1.5B - FP16)
```python
TrainingArguments(
    num_train_epochs=7,
    per_device_train_batch_size=8,
    gradient_accumulation_steps=1,
    learning_rate=2e-4,
    fp16=True,
    warmup_ratio=0.1,
    lr_scheduler_type="cosine",
    save_strategy="epoch",
    push_to_hub=True,
    hub_model_id="devsomosahub/agent-os-adapter-1.5b",
)
```

### Training Args (7B - Q4 quantizado)
```python
TrainingArguments(
    num_train_epochs=7,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=2,
    learning_rate=2e-4,
    fp16=True,
    warmup_ratio=0.1,
    lr_scheduler_type="cosine",
    save_strategy="steps",
    save_steps=500,
    push_to_hub=True,
    hub_model_id="devsomosahub/agent-os-adapter-7b",
)
```

### Quantizacao para 7B
```python
BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
)
```

## Como Treinar na Cloud (HuggingFace AutoTrain)

### Pre-requisitos
```bash
pip install autotrain-advanced
```

### 1. Upload do dataset para o HuggingFace
```python
from huggingface_hub import HfApi
api = HfApi(token="SEU_HF_TOKEN")
api.create_repo("SEU_USER/agent-os-dataset", repo_type="dataset")
api.upload_file(
    path_or_fileobj="dataset_v3.jsonl",
    path_in_repo="train.jsonl",
    repo_id="SEU_USER/agent-os-dataset",
    repo_type="dataset",
)
```

### 2. Criar script de treino (cloud-train/script.py)

**IMPORTANTE:** NAO coloque tokens HF hardcoded no script - o HuggingFace bloqueia o upload. Use `os.environ["HF_TOKEN"]`.

```python
import os, torch
from datasets import load_dataset, concatenate_datasets
from transformers import AutoTokenizer, AutoModelForCausalLM, TrainingArguments
from peft import LoraConfig, get_peft_model
from trl import SFTTrainer
from huggingface_hub import login

HF_TOKEN = os.environ["HF_TOKEN"]  # NUNCA hardcode o token!
login(token=HF_TOKEN)

ds = load_dataset("SEU_USER/agent-os-dataset", data_files="train.jsonl", split="train")

def fmt(ex):
    return {"text": f"<|im_start|>system\nYou are a command adapter. Output ONLY valid JSON.<|im_end|>\n<|im_start|>user\n{ex['input']}<|im_end|>\n<|im_start|>assistant\n{ex['output']}<|im_end|>"}

ds = ds.map(fmt)
ds = concatenate_datasets([ds, ds, ds, ds])

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-1.5B-Instruct", trust_remote_code=True)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-1.5B-Instruct", torch_dtype=torch.float16, device_map="auto", trust_remote_code=True)

model = get_peft_model(model, LoraConfig(
    r=32, lora_alpha=64,
    target_modules=["q_proj","v_proj","k_proj","o_proj","gate_proj","up_proj","down_proj"],
    lora_dropout=0.05, bias="none", task_type="CAUSAL_LM",
))

trainer = SFTTrainer(
    model=model,
    train_dataset=ds,
    args=TrainingArguments(
        output_dir="./output",
        num_train_epochs=7,
        per_device_train_batch_size=8,
        learning_rate=2e-4,
        fp16=True,
        save_strategy="epoch",
        push_to_hub=True,
        hub_model_id="SEU_USER/agent-os-adapter-1.5b",
        hub_token=HF_TOKEN,
    ),
    processing_class=tokenizer,
)

trainer.train()
trainer.push_to_hub()
model.push_to_hub("SEU_USER/agent-os-adapter-1.5b", token=HF_TOKEN)
tokenizer.push_to_hub("SEU_USER/agent-os-adapter-1.5b", token=HF_TOKEN)
```

### 3. Lancar o treino na cloud
```bash
autotrain spacerunner \
  --project-name "meu-treino" \
  --script-path ./cloud-train \
  --username SEU_USER \
  --token SEU_HF_TOKEN \
  --backend spaces-t4-small \
  --env "HF_TOKEN=SEU_HF_TOKEN"
```

**Backends disponiveis:**
| Backend | GPU | VRAM | Custo/hr |
|---------|-----|------|----------|
| spaces-t4-small | T4 | 16GB | ~$0.60 |
| spaces-a10g-small | A10G | 24GB | ~$1.05 |
| spaces-a100-large | A100 | 80GB | ~$4.13 |

### 4. Acompanhar o treino
Acesse: `https://huggingface.co/spaces/SEU_USER/autotrain-meu-treino`

## Merge: Adapter LoRA → Modelo Completo

Para usar na Inference API ou Inference Endpoints do HuggingFace, o adapter LoRA precisa ser mergeado com o modelo base.

### REGRA CRITICA: Merge SEMPRE em FP16, NUNCA em Q4

```python
# ERRADO - merge a partir de modelo quantizado Q4 (pesos corrompidos!)
base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B-Instruct", quantization_config=bnb_config)
model = PeftModel.from_pretrained(base, "adapter")
merged = model.merge_and_unload()  # SHAPES ERRADAS! Nao funciona.

# CERTO - merge a partir de modelo FP16 na CPU
base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B-Instruct", torch_dtype=torch.float16, device_map="cpu")
model = PeftModel.from_pretrained(base, "adapter")
merged = model.merge_and_unload()  # OK! Pesos corretos.
```

O merge Q4 gera erro `size mismatch for weight: copying a param with shape torch.Size([33947648, 1])` no Inference Endpoint. O modelo precisa estar em FP16 completo pra merge funcionar.

**RAM necessaria:** 7B em FP16 = ~14GB RAM. Use A100 na cloud ou CPU local com RAM suficiente.

### Script de merge na cloud (HuggingFace AutoTrain)

```python
# cloud-merge/script.py
import os, torch
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer
from huggingface_hub import login

HF_TOKEN = os.environ["HF_TOKEN"]
login(token=HF_TOKEN)

base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B-Instruct", torch_dtype=torch.float16, device_map="cpu", trust_remote_code=True)
model = PeftModel.from_pretrained(base, "devsomosahub/agent-os-adapter-7b")
merged = model.merge_and_unload()
tok = AutoTokenizer.from_pretrained("devsomosahub/agent-os-adapter-7b", trust_remote_code=True)

merged.push_to_hub("devsomosahub/agent-os-7b-merged", token=HF_TOKEN, max_shard_size="2GB")
tok.push_to_hub("devsomosahub/agent-os-7b-merged", token=HF_TOKEN)
```

Lancar: `autotrain spacerunner --project-name "merge-7b" --script-path ./cloud-merge --username SEU_USER --token TOKEN --backend spaces-a100-large --env "HF_TOKEN=TOKEN"`

### Limpar quantization_config do config.json

Se o modelo merged ficou com `quantization_config` no `config.json` (heranca do treino Q4), o Inference Endpoint falha com erro de `bitsandbytes not found`. Remova manualmente:

```python
from huggingface_hub import HfApi, hf_hub_download
import json
api = HfApi(token="TOKEN")
path = hf_hub_download("SEU_USER/modelo-merged", "config.json")
config = json.load(open(path))
if "quantization_config" in config:
    del config["quantization_config"]
    api.upload_file(path_or_fileobj=json.dumps(config, indent=2).encode(), path_in_repo="config.json", repo_id="SEU_USER/modelo-merged")
```

## Inference Endpoints

### Criar Endpoint via SDK
```python
from huggingface_hub import HfApi
api = HfApi(token="TOKEN")
endpoint = api.create_inference_endpoint(
    name="agent-os-1b5",
    repository="devsomosahub/agent-os-1b5-merged",
    framework="pytorch",
    task="text-generation",
    accelerator="gpu",
    vendor="aws",
    region="us-east-1",
    type="protected",
    instance_size="x1",
    instance_type="nvidia-t4",       # T4 pra 1.5B, A10G pra 7B
    namespace="devsomosahub",
)
```

### GPUs recomendadas por modelo
| Modelo | GPU minima | instance_type | instance_size |
|--------|-----------|---------------|---------------|
| 1.5B merged | T4 (16GB) | nvidia-t4 | x1 |
| 7B merged | A10G (24GB) | nvidia-a10g | x1 |

### IMPORTANTE: Pausar endpoints quando nao usar!
Endpoints cobram por hora enquanto rodando (~$0.60/hr T4, ~$1.05/hr A10G).
```python
api.pause_inference_endpoint("agent-os-1b5", namespace="devsomosahub")
# Para religar:
api.resume_inference_endpoint("agent-os-1b5", namespace="devsomosahub")
```

### O modelo merged precisa de pipeline_tag no README
Sem `pipeline_tag: text-generation` no README.md, a Inference API nao reconhece o modelo:
```markdown
---
pipeline_tag: text-generation
library_name: transformers
---
```

### Chamar o Endpoint
```python
import requests
URL = "https://SEU-ENDPOINT.aws.endpoints.huggingface.cloud"
headers = {"Authorization": "Bearer HF_TOKEN"}
prompt = '<|im_start|>system\nYou are a command adapter. Output ONLY valid JSON.<|im_end|>\n<|im_start|>user\nquais tabelas existem<|im_end|>\n<|im_start|>assistant\n'
r = requests.post(URL, headers=headers, json={"inputs": prompt, "parameters": {"max_new_tokens": 200, "return_full_text": False}})
print(r.json()[0]["generated_text"])
```

## Teste Real: Modelo vs Banco Supabase (Cloud-Hub)

Testamos o modelo 1.5B com tabelas que NUNCA viu no treino (Cloud-Hub: users, boards, vms, activity_log, board_memberships).

### Resultados

| Query | SQL gerado | Executou no banco? | Observacao |
|-------|-----------|-------------------|------------|
| quais colunas tem a tabela vms | `information_schema.columns WHERE table_name='vms'` | OK - 25 colunas | Perfeito |
| lista os boards com seus donos | `JOIN boards + users` | OK - 11 resultados | Acertou o JOIN |
| quais usuarios tem role admin | `WHERE role='admin'` | OK - 0 resultados | Query valida |
| qual o ip das vms rodando | `WHERE power_status='running'` | OK - 11 VMs | Acertou a logica |

### Limitacao: modelo inventa colunas

O modelo **generaliza a estrutura** (JSON, action, sql) mas **chuta nomes de colunas** baseado no dataset de treino quando a query e direta. Exemplo:
- Gerou `nome_completo` em vez de `display_name` (coluna real)
- Gerou `user_profiles` em vez de `users` (tabela real)

### Solucao: fluxo de 2 passos

```
1. User pergunta: "quais admins tem?"
2. Agent OS pede ao modelo: "quais colunas tem a tabela users"
   → Modelo: information_schema query (SEMPRE acerta)
   → Executa no banco → descobre colunas reais
3. Agent OS pede ao modelo com contexto: "a tabela users tem (id, email, display_name, role). liste os admins"
   → Modelo gera SQL com colunas corretas
```

O modelo acerta 100% das queries de `information_schema`. O problema so aparece quando ele tenta gerar SQL direto sem conhecer o schema.

## Erros Comuns e Solucoes

### 1. "Script must be base64 encoded"
O `--script-path` na API precisa de base64. Use o CLI `autotrain spacerunner` que faz isso automaticamente.

### 2. "project_name must be alphanumeric but can contain hyphens"
NAO use pontos no nome. `agent-os-1.5b` da erro, use `agent-os-small`.

### 3. "You already created this dataset repo"
O autotrain cria um dataset auxiliar `autotrain-NOME`. Se rodar de novo, mude o `--project-name` ou delete o repo antigo:
```python
api.delete_repo("SEU_USER/autotrain-NOME-ANTIGO", repo_type="dataset")
```

### 4. "Offending files contain valid HuggingFace secrets"
NUNCA coloque tokens HF hardcoded no script. Use `os.environ["HF_TOKEN"]` e passe via `--env`.

### 5. Treino termina mas modelo nao aparece no Hub
**Causa:** O script antigo so salvava local com `model.save_pretrained()`, sem push.
**Solucao:** Use `push_to_hub=True` no TrainingArguments + push explicito no final:
```python
TrainingArguments(
    push_to_hub=True,
    hub_model_id="SEU_USER/MEU_MODELO",
    hub_token=HF_TOKEN,
    save_strategy="epoch",  # salva checkpoints intermediarios
)
# No final do treino:
trainer.push_to_hub()
model.push_to_hub("SEU_USER/MEU_MODELO", token=HF_TOKEN)
tokenizer.push_to_hub("SEU_USER/MEU_MODELO", token=HF_TOKEN)
```

### 6. OOM (Out of Memory) na RTX 5060 (8.5GB VRAM) com 7B
Use quantizacao Q4 + batch_size=1:
```python
BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4")
TrainingArguments(per_device_train_batch_size=1, gradient_accumulation_steps=8)
```

### 7. Merge Q4 gera pesos corrompidos no Inference Endpoint
**Erro:** `RuntimeError: size mismatch for weight: copying a param with shape torch.Size([33947648, 1])`
**Causa:** Merge foi feito com modelo base carregado em Q4 (BitsAndBytes 4-bit). Os pesos quantizados tem shapes diferentes.
**Solucao:** SEMPRE mergear com modelo base em FP16. Use `device_map="cpu"` se nao tiver VRAM suficiente. Precisa de ~14GB RAM pro 7B.

### 8. Inference Endpoint falha com "bitsandbytes not found"
**Causa:** O `config.json` do modelo merged herdou `quantization_config` do treino Q4.
**Solucao:** Remova `quantization_config` do config.json (ver secao Merge acima).

### 9. Memory limit exceeded (14Gi) no AutoTrain Space
**Causa:** Carregar modelo 7B FP16 na RAM do Space excede o limite.
**Solucao:** Use `spaces-a100-large` (80GB) em vez de `spaces-a10g-small` (14GB).

### 10. Inference API retorna "410 Gone" ou "model doesn't support task"
**Causa:** A API antiga `api-inference.huggingface.co` foi desativada. Modelos custom nao rodam na Inference API gratuita.
**Solucao:** Crie um Inference Endpoint pago. Modelos merged com `pipeline_tag: text-generation` no README funcionam.

### 11. "openai/arcee-ai/trinity-large-preview:free is not a valid model ID" (PentAGI)
O PentAGI prefixa o `LLM_SERVER_PROVIDER` ao modelo. Se o provider for `openai` e o modelo `arcee-ai/trinity:free`, vira `openai/arcee-ai/trinity:free`.
**Solucao:** Coloque `LLM_SERVER_PROVIDER=arcee-ai` e `LLM_SERVER_MODEL=trinity-large-preview:free`.

## Entendendo os Numeros do Treino

### loss (erro)
```
loss: 9.21  → modelo perdido, respondendo lixo
loss: 2.31  → comecou a entender o padrao
loss: 0.37  → quase perfeito
loss: 0.01  → memorizou o dataset
```

### grad_norm (forca do ajuste)
```
grad_norm: 14.0  → ajustes grandes (inicio)
grad_norm: 1.0   → ajustes finos (modelo convergindo)
```

### learning_rate (velocidade)
- Comeca baixo (warmup) → sobe ate o maximo → desce devagar (cosine)
- Padrao: 2e-4 = 0.0002

### epoch (passadas pelo dataset)
- epoch 1.0 = viu todo o dataset 1 vez
- Treinamos ate epoch 7 = 7 passadas completas

## Exportar para GGUF (uso local com llama.cpp)

```bash
pip install llama-cpp-python
python -c "
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

base = AutoModelForCausalLM.from_pretrained('Qwen/Qwen2.5-1.5B-Instruct', torch_dtype=torch.float16, device_map='cpu')
model = PeftModel.from_pretrained(base, 'devsomosahub/agent-os-adapter-1.5b')
merged = model.merge_and_unload()
merged.save_pretrained('./merged-model')
AutoTokenizer.from_pretrained('devsomosahub/agent-os-adapter-1.5b').save_pretrained('./merged-model')
"

# Converter para GGUF
python llama.cpp/convert_hf_to_gguf.py ./merged-model --outfile adapter-q8.gguf --outtype q8_0
```

## Infraestrutura

### PentAGI (Pentest AI Autonomo)
- **Servidor:** Vultr Sao Paulo, 4CPU 8GB RAM, Ubuntu 24.04
- **URL:** https://216.238.107.254:8443
- **Login:** admin@pentagi.com / admin
- **LLM:** OpenRouter + arcee-ai/trinity-large-preview:free (gratis)
- **Ferramentas:** nmap, nikto, sqlmap, metasploit em containers Docker isolados

### Agent OS
- **Frontend:** React + TypeScript
- **Backend:** Python (smol-daemon.py) com smolagents
- **Modelo local:** llama.cpp servindo o adapter GGUF
- **Banco:** Supabase (PostgreSQL)