# Caramelo: instruções de uso (para o seu agente)

Você está ajudando alguém a usar o **Caramelo**, um modelo de linguagem gratuito afinado na voz e no estilo de escrita do Guilherme Favaron. A API é compatível com a da OpenAI: qualquer cliente ou SDK que já fala com a OpenAI funciona trocando a base URL e a chave.

- Site: https://ia-caramelo.com
- Base URL da API: `https://ia-caramelo.com/v1`
- Custo: gratuito (com limites de uso por minuto e por dia).

## 1. Obter a chave de API

A forma mais rápida é pela CLI:

```bash
npm install -g caramelo-chat
caramelo login
```

O `caramelo login` sobe um servidor local, abre o navegador e aguarda a aprovação.

**Importante para agentes:** o login usa a conta Google da pessoa, então **quem aprova é o usuário humano**, não você. Ao rodar `caramelo login`, peça para a pessoa concluir o login na janela que abriu. Assim que ela aprova, a CLI cria a chave e salva em `~/.caramelo/config.json`.

Depois do login:

```bash
# usar a CLI direto (ela já usa a chave salva)
caramelo "resuma este texto em uma frase: ..."
caramelo -m caramelo-code "função de debounce em python"

# ler a chave para usar em código ou outra ferramenta (campo apiKey, começa com crml_)
cat ~/.caramelo/config.json

# gerenciar chaves
caramelo keys                  # lista: criada, último uso, tokens, economia estimada
caramelo keys create meu-app   # cria outra chave
caramelo keys revoke <id>      # revoga
```

**Alternativa sem CLI:** a pessoa cria a chave em https://ia-caramelo.com/app, no menu **Chaves de API**. O valor `crml_...` só aparece uma vez.

## 2. Usar a API

A chave vai no header `Authorization: Bearer crml_...`. Dois modelos: `caramelo` (conversa e escrita, padrão) e `caramelo-code` (código).

### curl

```bash
curl https://ia-caramelo.com/v1/chat/completions \
  -H "Authorization: Bearer $CARAMELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caramelo",
    "messages": [{"role": "user", "content": "Resuma o que é um data warehouse em uma frase."}]
  }'
```

### Python (SDK da OpenAI)

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://ia-caramelo.com/v1",
    api_key="crml_suaChaveAqui",
)

resp = client.chat.completions.create(
    model="caramelo",
    messages=[{"role": "user", "content": "Classifique este e-mail como spam ou nao: ..."}],
)
print(resp.choices[0].message.content)
```

### Node (SDK da OpenAI)

```js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ia-caramelo.com/v1",
  apiKey: process.env.CARAMELO_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "caramelo",
  messages: [{ role: "user", content: "Reescreva este paragrafo de forma mais direta: ..." }],
});
console.log(resp.choices[0].message.content);
```

## 3. Pra que serve

Caramelo é um modelo pequeno (4 bilhões de parâmetros). Rende bem em tarefas curtas e objetivas, em português, na voz do Gui:

- Pequenas tarefas e ações repetitivas: reescrever, resumir, padronizar texto.
- Categorizações simples: classificar, marcar, rotular itens.
- Respostas diretas a perguntas pontuais.
- Rascunho rápido de texto no estilo do Gui.

Para raciocínio longo, contexto gigante ou conhecimento de fronteira, prefira um modelo maior. O Caramelo é a ferramenta certa para o trabalho repetitivo e de volume.

## 4. Limites

- Gratuito, com limite por minuto e por dia por usuário.
- Vale usar uma chave por app ou projeto para acompanhar o uso de cada um (veja `caramelo keys` ou o modal **Chaves de API** no `/app`).

## Links

- App e chat: https://ia-caramelo.com/app
- Documentação: https://ia-caramelo.com/docs
- Este guia, para `curl` direto: https://ia-caramelo.com/CLAUDE.md e https://ia-caramelo.com/AGENTS.md