🤖 Ruby AI Chat API

Uma API RESTful de chat com Inteligência Artificial construída em Ruby — 100% server-side, leve e educacional.

📋 Índice

✨ Sobre o Projeto
🛠️ Stack Tecnológica
🚀 Como Executar
📡 Endpoints da API
🗄️ Estrutura do Banco de Dados
📁 Estrutura do Projeto
🌐 Integração com AI Gateway
🧪 Scripts Úteis
💻 Exemplos de Uso
📚 Aprendizados
📄 Licença

✨ Sobre o Projeto

Esta API permite criar conversas com múltiplos modelos de IA (como GPT-4, Claude, Gemini) através de um gateway unificado. Foi construída com Sinatra (micro-framework web do Ruby) e ActiveRecord (ORM do Rails) para persistência em PostgreSQL (via Neon Database).

🎯 O que ela faz?

Funcionalidade	Descrição
💬 Chats	Cria, lista, renomeia e deleta conversas
🧠 Mensagens	Envia mensagens e obtém respostas da IA
🎭 System Prompts	Define instruções de personalidade para o assistente
🏷️ Múltiplos Modelos	Suporta qualquer modelo disponível no gateway
📊 Contagem de Tokens	Monitora uso de tokens por chat
🗺️ Histórico Contextual	A IA enxerga toda a conversa anterior

🧑‍🎓 Para quem é?

Este projeto foi desenvolvido para aprender e ensinar conceitos de Ruby:

✅ Iniciantes em Ruby que já conhecem programação
✅ Desenvolvedores querendo entender APIs com Sinatra
✅ Entusiastas de IA que querem integrar LLMs em Ruby
✅ Portfólio para demonstrar habilidades full-stack em Ruby

🛠️ Stack Tecnológica

Tecnologia	Versão	Propósito
Ruby	4.0	Linguagem principal
Sinatra	~4.0	Framework web minimalista
ActiveRecord	~7.1	ORM para banco de dados
PostgreSQL	~16	Banco de dados relacional (Neon Database)
RubyLLM	~1.0	Gem que abstrai chamadas a APIs de IA
Puma	~6.0	Servidor web HTTP
dotenv	~3.0	Gerenciamento de variáveis de ambiente
Rackup	~2.3	Interface Rack para servidores web

🚀 Como Executar

📋 Pré-requisitos

Ruby 4.0 instalado
Bundler (gem install bundler)
Uma chave de API para o AI Gateway
Uma conta no Neon Database (PostgreSQL grátis)

🔧 Localmente

# 1. Clone o repositório
git clone https://github.com/seu-usuario/ruby-ai-chat.git
cd ruby-ai-chat

# 2. Instale as dependências
bundle install

# 3. Configure as variáveis de ambiente
cp .env.example .env
# Edite o .env e coloque suas chaves

# 4. Execute a aplicação
ruby app.rb

A API estará disponível em http://localhost:4567 🎉

📝 Exemplo de `.env`

# Banco de dados PostgreSQL (Neon Database)
DATABASE_URL="postgres://user:password@ep-exemplo-123456.us-east-2.aws.neon.tech/neondb?sslmode=require"

# AI Gateway
AI_GATEWAY_API_KEY="sua_chave_aqui"
AI_GATEWAY_BASE_URL="https://ai-gateway.vercel.sh/v1"

☁️ Deploy no Render

O Render é uma plataforma de cloud que suporta aplicações Ruby com deploy automático via Git.

Passo a passo

Crie um Web Service no Render
Conecte seu repositório GitHub
Configure o serviço:

Configuração Valor

Runtime Ruby

Build Command bundle install

Start Command bundle exec puma config.ru

Health Check Path /health

Adicione as variáveis de ambiente no Dashboard do Render:

Variável	Descrição
`DATABASE_URL`	Connection string do Neon PostgreSQL
`AI_GATEWAY_API_KEY`	Chave de API do AI Gateway
`AI_GATEWAY_BASE_URL`	(opcional) URL base do gateway
`RACK_ENV`	`production`

Deploy automático! 🎉

💡 O Render usa o arquivo config.ru na raiz do projeto para iniciar a aplicação com Puma.

📡 Endpoints da API

🤖 Chats

Método	Rota	Descrição
`GET`	`/health`	Health check 🩺
`GET`	`/chats`	Lista todos os chats 📋
`POST`	`/chats`	Cria um novo chat ➕
`GET`	`/chats/:id`	Detalhes do chat com mensagens 📖
`PATCH`	`/chats/:id`	Renomeia o título do chat ✏️
`DELETE`	`/chats/:id`	Exclui um chat 🗑️

💬 Mensagens

Método	Rota	Descrição
`GET`	`/chats/:id/messages`	Lista mensagens do chat 📜
`POST`	`/chats/:id/messages`	Envia mensagem e recebe resposta da IA 🤯

📥 Payloads

Criar Chat

POST /chats
{
  "title": "Meu Chat",
  "model_id": "gpt-4o-mini",
  "system_prompt": "Você é um assistente útil e amigável."
}

Enviar Mensagem

POST /chats/1/messages
{
  "content": "Explique o que é Ruby em 3 frases."
}

📤 Respostas

POST /chats/1/messages → 201 Created
{
  "user_message": {
    "id": 1,
    "chat_id": 1,
    "role": "user",
    "content": "Explique o que é Ruby...",
    "input_tokens": 15,
    "output_tokens": 0,
    "created_at": "2025-01-01T..."
  },
  "assistant_message": {
    "id": 2,
    "chat_id": 1,
    "role": "assistant",
    "content": "Ruby é uma linguagem...",
    "model_id": "gpt-4o-mini",
    "input_tokens": 0,
    "output_tokens": 85,
    "created_at": "2025-01-01T..."
  },
  "chat": {
    "id": 1,
    "title": "Explique o que é Ruby...",
    "input_tokens": 15,
    "output_tokens": 85,
    "total_tokens": 100,
    "messages_count": 2
  }
}

🗄️ Estrutura do Banco de Dados

Tabela `chats`

Coluna	Tipo	Descrição
`id`	integer	Chave primária
`title`	string	Título do chat
`model_id`	string	ID do modelo de IA usado
`system_prompt`	text	Instruções para o assistente
`input_tokens`	integer	Total de tokens de entrada
`output_tokens`	integer	Total de tokens de saída
`created_at`	datetime	Data de criação
`updated_at`	datetime	Última atualização

Tabela `messages`

Coluna	Tipo	Descrição
`id`	integer	Chave primária
`chat_id`	integer	Referência ao chat (FK)
`role`	string	`"user"` ou `"assistant"`
`content`	text	Conteúdo da mensagem
`model_id`	string	Modelo que gerou (se for resposta)
`input_tokens`	integer	Tokens usados na requisição
`output_tokens`	integer	Tokens gerados na resposta
`created_at`	datetime	Data de criação
`updated_at`	datetime	Última atualização

Diagrama de Relacionamento

Chat ── has_many ──► Message
 │                      │
 └── dependent: :destroy ┘  (deleta mensagens ao apagar chat)

📁 Estrutura do Projeto

📦 ruby-ai-chat
 ┣ 📜 app.rb                  # 🚀 Ponto de entrada da API
 ┣ 📜 config.ru               # 🏗️ Configuração Rack para deploy (Render)
 ┣ 📜 Gemfile                 # 📦 Dependências do projeto
 ┣ 📜 Gemfile.lock            # 🔒 Versões travadas das gems
 ┣ 📜 .env.example            # 🔑 Template de variáveis de ambiente
 ┣ 📜 .gitignore              # 🙈 Arquivos ignorados pelo Git
 ┣ 📂 config/
 ┃ ┣ 📜 database.rb           # 🗄️ Configuração do banco PostgreSQL (Neon)
 ┃ ┗ 📜 ruby_llm.rb           # 🤖 Configuração do cliente de IA
 ┣ 📂 models/
 ┃ ┣ 📜 chat.rb               # 💬 Modelo ActiveRecord do Chat
 ┃ ┗ 📜 message.rb            # ✉️  Modelo ActiveRecord da Mensagem
 ┣ 📂 routes/
 ┃ ┣ 📜 chats.rb              # 🛣️ Rotas CRUD de chats
 ┃ ┗ 📜 messages.rb           # 🛣️ Rotas de mensagens + integração IA
 ┣ 📂 services/
 ┃ ┗ 📜 ai_chat_service.rb    # 🧠 Lógica de conversação com a IA
 ┣ 📂 support/
 ┃ ┗ 📜 json_helpers.rb       # 🛠️ Helpers para JSON (parsing/resposta)
 ┣ 📂 scripts/
 ┃ ┗ 📜 refresh_models.rb     # 🔄 Atualiza cache dos modelos disponíveis
 ┗ 📂 db/                     # 💾 Pasta para dados locais (se necessário)

🌐 Integração com AI Gateway

O projeto usa a gem ruby_llm que se conecta ao AI Gateway, uma interface unificada compatível com a API da OpenAI.

🔄 Como funciona o fluxo:

Usuário ──POST /chats/1/messages──► API
                                      │
                              ┌───────┴────────┐
                              │  AiChatService  │
                              │  (Constrói      │
                              │   contexto com  │
                              │   histórico)    │
                              └───────┬────────┘
                                      │
                              ┌───────┴────────┐
                              │   RubyLLM       │
                              │  (gem cliente)  │
                              └───────┬────────┘
                                      │
                              ┌───────┴────────┐
                              │   AI Gateway    │
                              │  (roteia para   │
                              │   modelo certo) │
                              └───────┬────────┘
                                      │
                              ┌───────┴────────┐
                              │  Modelo Final   │
                              │ (GPT, Claude,   │
                              │  Gemini, etc.)  │
                              └────────────────┘

🎯 Modelos Suportados

O gateway permite usar qualquer modelo compatível com OpenAI:

gpt-4o, gpt-4o-mini, gpt-4-turbo (OpenAI)
claude-3-opus, claude-3-sonnet (Anthropic)
gemini-2.0-flash (Google)
E muitos outros disponíveis no gateway

🧪 Scripts Úteis

🔄 Atualizar Lista de Modelos

ruby scripts/refresh_models.rb

Este script consulta o AI Gateway e baixa a lista mais recente de modelos disponíveis.

💻 Exemplos de Uso

Com `curl`

# Health check
curl http://localhost:4567/health

# Criar um chat
curl -X POST http://localhost:4567/chats \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Aprendendo Ruby",
    "model_id": "gpt-4o-mini",
    "system_prompt": "Você é um mentor de Ruby para iniciantes."
  }'

# Listar chats
curl http://localhost:4567/chats

# Enviar mensagem
curl -X POST http://localhost:4567/chats/1/messages \
  -H "Content-Type: application/json" \
  -d '{"content": "O que são blocos em Ruby?"}'

# Ver histórico da conversa
curl http://localhost:4567/chats/1

# Renomear chat
curl -X PATCH http://localhost:4567/chats/1 \
  -H "Content-Type: application/json" \
  -d '{"title": "Blocos em Ruby explicados"}'

# Deletar chat
curl -X DELETE http://localhost:4567/chats/1

📚 Aprendizados

🧩 O que você vai aprender estudando este código

Conceito	Onde encontrar
🏗️ Módulos em Ruby	`routes/chats.rb`, `routes/messages.rb`, `support/json_helpers.rb`
🚏 Rotas em Sinatra	`app.rb`, `routes/*`
🗄️ ActiveRecord sem Rails	`models/*`, `config/database.rb`
📦 Gems e Bundler	`Gemfile`
🔐 Variáveis de ambiente	`.env.example`, `config/ruby_llm.rb`
🧠 Serviços (Service Objects)	`services/ai_chat_service.rb`
🛠️ Helpers (Módulos mixin)	`support/json_helpers.rb`
📊 Tratamento de erros	`routes/messages.rb` (rescue + rollback)

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais informações.

Feito com ☕ e Ruby 💎

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
config		config
db		db
models		models
routes		routes
scripts		scripts
services		services
support		support
.env.example		.env.example
.gitignore		.gitignore
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
README.md		README.md
app.rb		app.rb
config.ru		config.ru

Configuração	Valor
Runtime	Ruby
Build Command	`bundle install`
Start Command	`bundle exec puma config.ru`
Health Check Path	`/health`

Folders and files

Latest commit

History

Repository files navigation