Objetivo
Nesse projeto você vai desenvolver uma API HTTP simples de chat com Inteligência Artificial. A aplicação irá expor rotas para criação e gerenciamento de conversas com modelos de IA, persistindo todo o histórico em banco de dados.
Propósito Didático
Nesse projeto irá praticar os seguintes conceitos:
- HTTP e Redes: Criação de um servidor HTTP com rotas REST, manipulação de requisições/respostas JSON e upload de arquivos
- Persistência de Dados: Modelagem e armazenamento com SQLite3 e ActiveRecord, incluindo associações entre tabelas
- Inteligência Artificial com RubyLLM: Integração com provedores de IA (OpenAI, Anthropic, Gemini, etc.), gerenciamento de chats, envio de arquivos para interpretação pela IA e controle de tokens consumidos
Funcionalidades Principais
- Criação e gerenciamento de conversas (chats) com IA
- Envio de mensagens e recebimento de respostas da IA
- Histórico completo de mensagens persistido em banco de dados
- Controle de tokens consumidos por conversa
- Suporte a múltiplos modelos de IA
- Definição de comportamento do assistente via system prompt
Especificações
1. Gestão de Chats
1.1 Criação de Chat
Ao criar um novo chat, o usuário pode configurar a conversa.
Campos opcionais (com valores padrão):
- Modelo de IA (ex:
gpt-4o-mini, claude-sonnet-4-6, gemini-2.5-flash — padrão: modelo default do provedor configurado)
- System prompt (instrução inicial que define o comportamento do assistente, ex: "Você é um assistente especialista em Ruby")
- Título da conversa (caso não informado, pode ser gerado automaticamente a partir da primeira mensagem)
Campos gerados automaticamente:
- ID único do chat
- Data de criação
- Contadores de tokens (input e output)
1.2 Listagem de Chats
- Retorno de todos os chats existentes em formato JSON
- Informações resumidas: ID, título, modelo utilizado, data de criação, total de mensagens e total de tokens consumidos
- Ordenação por data de criação (mais recente primeiro)
1.3 Detalhes do Chat
- Retorno das informações completas de um chat específico
- Inclusão de todas as mensagens da conversa ordenadas cronologicamente
- Metadados do chat: modelo, contadores de tokens
1.4 Exclusão de Chat
- Remoção permanente do chat e todas as suas mensagens associadas
- Retorno de confirmação da exclusão
2. Mensagens e Interação com a IA
2.1 Envio de Mensagem
Ao enviar uma mensagem para um chat existente, o sistema deve:
- Persistir a mensagem do usuário no banco de dados (role:
user)
- Enviar a mensagem para o provedor de IA via RubyLLM, incluindo o histórico da conversa
- Receber a resposta da IA
- Persistir a resposta da IA no banco de dados (role:
assistant)
- Atualizar os contadores de tokens do chat
- Retornar a resposta da IA ao cliente
Campos da mensagem do usuário:
- Conteúdo da mensagem (obrigatório)
Campos persistidos da resposta da IA:
- Conteúdo da resposta
- Role (
assistant)
- Modelo que gerou a resposta (
model_id)
- Tokens de entrada (
input_tokens)
- Tokens de saída (
output_tokens)
2.2 Listagem de Mensagens
- Retorno de todas as mensagens de um chat específico
- Ordenação cronológica
- Informações por mensagem: role, conteúdo, modelo (quando assistente), tokens consumidos, arquivo anexado (se houver) e data de criação
2.3 Contexto da Conversa
- Cada nova mensagem enviada deve considerar o histórico completo da conversa
- O system prompt (se definido) deve ser enviado como contexto em todas as interações
- A IA deve "lembrar" de mensagens anteriores da mesma conversa
3. Persistência de Dados
3.1 Banco de Dados
- Utilizar SQLite3 como banco de dados
- Utilizar ActiveRecord como ORM (standalone, sem Rails)
- Criar as tabelas via migrations ou criação direta
3.2 Associações
- Um Chat possui muitas Messages (
has_many)
- Uma Message pertence a um Chat (
belongs_to)
- A exclusão de um Chat deve remover todas as suas Messages em cascata
4. API REST — Rotas HTTP
A API deve seguir o padrão REST com respostas em JSON.
4.1 Rotas de Chats
| Método | Rota | Descrição |
|---|
POST | /chats | Criar um novo chat |
GET | /chats | Listar todos os chats |
GET | /chats/:id | Obter detalhes de um chat com suas mensagens |
DELETE | /chats/:id | Excluir um chat |
4.2 Rotas de Mensagens
| Método | Rota | Descrição |
|---|
POST | /chats/:id/messages | Enviar uma mensagem e receber resposta da IA |
GET | /chats/:id/messages | Listar todas as mensagens de um chat |
5. Tratamento de Erros
A API deve tratar os seguintes cenários com os status codes HTTP adequados:
- Chat não encontrado: quando o ID informado não existe
- Requisição inválida: quando campos obrigatórios estão ausentes (ex: mensagem sem conteúdo)
- Erro do provedor de IA: quando a chamada ao provedor falha (timeout, chave inválida, etc.)
- Erro interno: para erros inesperados, com mensagem genérica
6. Configuração do Provedor de IA
- A chave de API do provedor deve ser lida de variáveis de ambiente (nunca hardcoded no código)
- O provedor padrão pode ser configurado no início da aplicação via
RubyLLM.configure
- A aplicação deve funcionar com pelo menos um provedor (sugestão: OpenAI ou Gemini)
Indo além
Interface Web com ERB
Como desafio extra, crie uma interface web para interagir com a API de chat utilizando templates ERB (Embedded Ruby) renderizados pelo Sinatra. ERB é o sistema de templates padrão do Ruby que permite embutir código Ruby diretamente dentro de arquivos HTML usando as tags <%= %> (para saída) e <% %> (para lógica), gerando páginas dinâmicas no servidor.
Funcionalidades sugeridas:
- Página inicial (
GET /chats): Lista todos os chats existentes com opção de criar um novo
- Página do chat (
GET /chats/:id): Exibe o histórico de mensagens e um formulário para enviar novas mensagens
- Formulário de criação (
GET /chats/new): Formulário para criar um novo chat com campos de modelo, system prompt e título
- Envio de mensagem via formulário (
POST /chats/:id/messages): O formulário de mensagem faz POST e redireciona de volta para a página do chat com a resposta da IA exibida
Dicas
Gems sugeridas
- ruby_llm — Interface unificada para múltiplos provedores de IA
- sinatra ou webrick — Para criar o servidor HTTP (escolha um)
- activerecord — ORM para persistência (standalone, sem Rails)
- sqlite3 — Adaptador do banco de dados
- dotenv — Carrega variáveis de ambiente a partir de um arquivo
.env
Integração RubyLLM + ActiveRecord
A gem RubyLLM oferece helpers para integração com ActiveRecord que facilitam a persistência automática de chats e mensagens. Consulte a documentação da gem para utilizar acts_as_chat e acts_as_message nos seus models, o que simplifica bastante o fluxo de enviar mensagens e salvar respostas automaticamente.
Interface Web
- Utilize o layout do Sinatra (
views/layout.erb) para reaproveitar a estrutura HTML entre páginas
- Crie os templates em uma pasta
views/ (ex: views/index.erb, views/chat.erb, views/new_chat.erb)
- Estilize com CSS simples ou um framework como Pico CSS para ter uma interface limpa sem configuração complexa
- As rotas da interface web podem coexistir com as rotas JSON da API — use
Content-Type ou rotas separadas para distingui-las
Objetivo
Nesse projeto você vai desenvolver uma API HTTP simples de chat com Inteligência Artificial. A aplicação irá expor rotas para criação e gerenciamento de conversas com modelos de IA, persistindo todo o histórico em banco de dados.
Propósito Didático
Nesse projeto irá praticar os seguintes conceitos:
- HTTP e Redes: Criação de um servidor HTTP com rotas REST, manipulação de requisições/respostas JSON e upload de arquivos
- Persistência de Dados: Modelagem e armazenamento com SQLite3 e ActiveRecord, incluindo associações entre tabelas
- Inteligência Artificial com RubyLLM: Integração com provedores de IA (OpenAI, Anthropic, Gemini, etc.), gerenciamento de chats, envio de arquivos para interpretação pela IA e controle de tokens consumidos
Funcionalidades Principais
- Criação e gerenciamento de conversas (chats) com IA
- Envio de mensagens e recebimento de respostas da IA
- Histórico completo de mensagens persistido em banco de dados
- Controle de tokens consumidos por conversa
- Suporte a múltiplos modelos de IA
- Definição de comportamento do assistente via system prompt
Especificações
1. Gestão de Chats
1.1 Criação de Chat
Ao criar um novo chat, o usuário pode configurar a conversa.
Campos opcionais (com valores padrão):
- Modelo de IA (ex:
gpt-4o-mini, claude-sonnet-4-6, gemini-2.5-flash — padrão: modelo default do provedor configurado)
- System prompt (instrução inicial que define o comportamento do assistente, ex: "Você é um assistente especialista em Ruby")
- Título da conversa (caso não informado, pode ser gerado automaticamente a partir da primeira mensagem)
Campos gerados automaticamente:
- ID único do chat
- Data de criação
- Contadores de tokens (input e output)
1.2 Listagem de Chats
- Retorno de todos os chats existentes em formato JSON
- Informações resumidas: ID, título, modelo utilizado, data de criação, total de mensagens e total de tokens consumidos
- Ordenação por data de criação (mais recente primeiro)
1.3 Detalhes do Chat
- Retorno das informações completas de um chat específico
- Inclusão de todas as mensagens da conversa ordenadas cronologicamente
- Metadados do chat: modelo, contadores de tokens
1.4 Exclusão de Chat
- Remoção permanente do chat e todas as suas mensagens associadas
- Retorno de confirmação da exclusão
2. Mensagens e Interação com a IA
2.1 Envio de Mensagem
Ao enviar uma mensagem para um chat existente, o sistema deve:
- Persistir a mensagem do usuário no banco de dados (role:
user)
- Enviar a mensagem para o provedor de IA via RubyLLM, incluindo o histórico da conversa
- Receber a resposta da IA
- Persistir a resposta da IA no banco de dados (role:
assistant)
- Atualizar os contadores de tokens do chat
- Retornar a resposta da IA ao cliente
Campos da mensagem do usuário:
- Conteúdo da mensagem (obrigatório)
Campos persistidos da resposta da IA:
- Conteúdo da resposta
- Role (
assistant)
- Modelo que gerou a resposta (
model_id)
- Tokens de entrada (
input_tokens)
- Tokens de saída (
output_tokens)
2.2 Listagem de Mensagens
- Retorno de todas as mensagens de um chat específico
- Ordenação cronológica
- Informações por mensagem: role, conteúdo, modelo (quando assistente), tokens consumidos, arquivo anexado (se houver) e data de criação
2.3 Contexto da Conversa
- Cada nova mensagem enviada deve considerar o histórico completo da conversa
- O system prompt (se definido) deve ser enviado como contexto em todas as interações
- A IA deve "lembrar" de mensagens anteriores da mesma conversa
3. Persistência de Dados
3.1 Banco de Dados
- Utilizar SQLite3 como banco de dados
- Utilizar ActiveRecord como ORM (standalone, sem Rails)
- Criar as tabelas via migrations ou criação direta
3.2 Associações
- Um Chat possui muitas Messages (
has_many)
- Uma Message pertence a um Chat (
belongs_to)
- A exclusão de um Chat deve remover todas as suas Messages em cascata
4. API REST — Rotas HTTP
A API deve seguir o padrão REST com respostas em JSON.
4.1 Rotas de Chats
| Método | Rota | Descrição |
|---|
POST | /chats | Criar um novo chat |
GET | /chats | Listar todos os chats |
GET | /chats/:id | Obter detalhes de um chat com suas mensagens |
DELETE | /chats/:id | Excluir um chat |
4.2 Rotas de Mensagens
| Método | Rota | Descrição |
|---|
POST | /chats/:id/messages | Enviar uma mensagem e receber resposta da IA |
GET | /chats/:id/messages | Listar todas as mensagens de um chat |
5. Tratamento de Erros
A API deve tratar os seguintes cenários com os status codes HTTP adequados:
- Chat não encontrado: quando o ID informado não existe
- Requisição inválida: quando campos obrigatórios estão ausentes (ex: mensagem sem conteúdo)
- Erro do provedor de IA: quando a chamada ao provedor falha (timeout, chave inválida, etc.)
- Erro interno: para erros inesperados, com mensagem genérica
6. Configuração do Provedor de IA
- A chave de API do provedor deve ser lida de variáveis de ambiente (nunca hardcoded no código)
- O provedor padrão pode ser configurado no início da aplicação via
RubyLLM.configure
- A aplicação deve funcionar com pelo menos um provedor (sugestão: OpenAI ou Gemini)
Indo além
Interface Web com ERB
Como desafio extra, crie uma interface web para interagir com a API de chat utilizando templates ERB (Embedded Ruby) renderizados pelo Sinatra. ERB é o sistema de templates padrão do Ruby que permite embutir código Ruby diretamente dentro de arquivos HTML usando as tags <%= %> (para saída) e <% %> (para lógica), gerando páginas dinâmicas no servidor.
Funcionalidades sugeridas:
- Página inicial (
GET /chats): Lista todos os chats existentes com opção de criar um novo
- Página do chat (
GET /chats/:id): Exibe o histórico de mensagens e um formulário para enviar novas mensagens
- Formulário de criação (
GET /chats/new): Formulário para criar um novo chat com campos de modelo, system prompt e título
- Envio de mensagem via formulário (
POST /chats/:id/messages): O formulário de mensagem faz POST e redireciona de volta para a página do chat com a resposta da IA exibida
Dicas
Gems sugeridas
- ruby_llm — Interface unificada para múltiplos provedores de IA
- sinatra ou webrick — Para criar o servidor HTTP (escolha um)
- activerecord — ORM para persistência (standalone, sem Rails)
- sqlite3 — Adaptador do banco de dados
- dotenv — Carrega variáveis de ambiente a partir de um arquivo
.env
Integração RubyLLM + ActiveRecord
A gem RubyLLM oferece helpers para integração com ActiveRecord que facilitam a persistência automática de chats e mensagens. Consulte a documentação da gem para utilizar acts_as_chat e acts_as_message nos seus models, o que simplifica bastante o fluxo de enviar mensagens e salvar respostas automaticamente.
Interface Web
- Utilize o layout do Sinatra (
views/layout.erb) para reaproveitar a estrutura HTML entre páginas
- Crie os templates em uma pasta
views/ (ex: views/index.erb, views/chat.erb, views/new_chat.erb)
- Estilize com CSS simples ou um framework como Pico CSS para ter uma interface limpa sem configuração complexa
- As rotas da interface web podem coexistir com as rotas JSON da API — use
Content-Type ou rotas separadas para distingui-las
