deploy/DISTRIBUTION_GUIDE.md

🌐 Guia Oficial de Distribuição: Simplicio 27B

Ollama · OpenRouter · OpenCode / Aider / Cursor / Continue.dev

Este documento detalha como disponibilizar e consumir o Simplicio 27B nas principais plataformas de distribuição de modelos abertos e ferramentas de desenvolvimento agentico.

---

1. 🦙 Distribuição no Ollama

O Ollama requer que o modelo esteja no formato GGUF. Como o modelo é de 27B de parâmetros, a quantização recomendada para rodar em hardware de consumo é Q4_K_M (16.8 GB) ou Q8_0 (28.5 GB).

Passo 1: Converter os pesos para GGUF (via llama.cpp)

Caso esteja com os pesos do modelo salvos (após merge do LoRA ou download do Hugging Face):

# 1. Clone o llama.cpp se ainda não tiver
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && cmake -B build && cmake --build build --config Release -j && cd ..

# 2. Converta Hugging Face -> GGUF BF16
python3 llama.cpp/convert_hf_to_gguf.py ./checkpoint-final --outfile simplicio-27b-bf16.gguf --outtype bf16

# 3. Quantize para 4-bit (ideal para Macs com 32GB+ ou GPUs com 24GB VRAM)
./llama.cpp/build/bin/llama-quantize simplicio-27b-bf16.gguf simplicio-27b-Q4_K_M.gguf Q4_K_M

Passo 2: Criar o modelo no Ollama local

Com o arquivo Modelfile presente na raiz do repositório:

ollama create wesleysimplicio/simplicio-27b -f Modelfile

Passo 3: Publicar na Biblioteca do Ollama (Ollama Registry)

1. Crie sua conta em ollama.com e cadastre sua chave pública SSH (~/.ollama/id_ed25519.pub).
2. Faça login no terminal:

   ollama login
   

3. Envie o modelo para a comunidade:

   ollama push wesleysimplicio/simplicio-27b
   

4. Qualquer desenvolvedor no mundo poderá rodar instantaneamente:

   ollama run wesleysimplicio/simplicio-27b
   

---

2. ⚡ Distribuição no OpenRouter

O OpenRouter não hospeda GPUs próprias; ele funciona como um roteador e agregador inteligente de provedores de inferência em nuvem. Existem dois caminhos práticos para colocar o Simplicio 27B no OpenRouter:

Opção A: Hospedagem via DeepInfra / Chutes / Together (Mais Fácil)

1. DeepInfra (deepinfra.com):
   • Acesse o painel do DeepInfra e clique em Deploy Model.
   • Aponte para o repositório público do Hugging Face: wesleysimplicio/Simplicio-27B.
   • O DeepInfra criará um endpoint de alta velocidade compatível com OpenAI API.
2. Como o OpenRouter monitora e consome provedores integrados, o modelo pode ser submetido diretamente no formulário de parceria do OpenRouter ou adicionado via Custom Provider.

Opção B: Cadastrar seu próprio Endpoint como Provedor (BYO Endpoint)

Se você hospedar o Simplicio 27B em uma instância com GPU (ex: RunPod, Lambda Labs, Scaleway ou servidor próprio com vLLM):

1. Inicie o servidor vLLM:

   ./deploy/serve_vllm.sh wesleysimplicio/Simplicio-27B 8000
   

2. Exponha o endpoint via HTTPS (usando Cloudflare Tunnel, Caddy ou Nginx).
3. Acesse openrouter.ai/provider:
   • Cadastre seu endpoint OpenAI-compatible: https://seu-dominio.com/v1
   • O OpenRouter validará a latência e o throughput e listará o modelo como wesleysimplicio/simplicio-27b.
   • Usuários do OpenRouter poderão chamá-lo via API global e você recebe créditos/pagamentos por milhão de tokens gerados.

---

3. 💻 Integração com OpenCode, Aider, Continue e Cursor

O Simplicio 27B foi desenhado para agir como motor cirúrgico de código (SEARCH/REPLACE) e execuções agenticas. Veja como conectá-lo às ferramentas:

A. Aider (CLI Agent - 96.5% de Precisão Cirúrgica)

O Aider é a principal ferramenta de pair programming via terminal.

# Via Ollama local:
aider --model ollama/wesleysimplicio/simplicio-27b --edit-format diff

# Via vLLM local ou OpenRouter:
aider --openai-api-base http://localhost:8000/v1 \
      --openai-api-key none \
      --model openai/simplicio-27b \
      --edit-format diff

B. OpenCode / Open Interpreter

Para executar código em terminal com autonomia:

# Via Ollama:
interpreter --model ollama/wesleysimplicio/simplicio-27b

# Via OpenAI-compatible endpoint:
interpreter --api_base http://localhost:8000/v1 --model simplicio-27b

C. Continue.dev (Extensão VS Code / JetBrains)

Adicione em ~/.continue/config.json:

{
  "models": [
    {
      "title": "Simplicio 27B (Ollama)",
      "provider": "ollama",
      "model": "wesleysimplicio/simplicio-27b"
    },
    {
      "title": "Simplicio 27B (vLLM / OpenRouter)",
      "provider": "openai",
      "model": "simplicio-27b",
      "apiBase": "http://localhost:8000/v1",
      "apiKey": "none"
    }
  ]
}

D. Cursor / Windsurf / Cline

1. Vá em Settings ➔ Models (ou Custom OpenAI API).
2. Insira a Base URL: http://localhost:8000/v1 (ou a URL do OpenRouter).
3. Insira o nome do modelo: simplicio-27b ou wesleysimplicio/simplicio-27b.