Upload README.md with huggingface_hub

README.md

@@ -12,11 +12,20 @@ Um modelo fine-tunado que converte linguagem natural em portugues para comandos
 
 ## 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)
@@ -179,6 +188,152 @@ autotrain spacerunner \
 ### 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"
@@ -219,7 +374,24 @@ BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4")
 TrainingArguments(per_device_train_batch_size=1, gradient_accumulation_steps=8)
 ```
 
-### 7. "openai/arcee-ai/trinity-large-preview:free is not a valid model ID" (PentAGI)
+### 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`.