Um guia completo sobre como funciona a integração de IA no i-Diário, a arquitetura engine + app principal, e como tudo se encaixa.
O i-Diário é usado por milhares de professores em todo o Brasil. A IA vem para automatizar tarefas repetitivas, economizar tempo e melhorar a qualidade dos registros educacionais.
As funcionalidades de IA não vão para a comunidade open source agora.
Elas vivem exclusivamente no engine i-diario-plus, que é proprietário da Portabilis.
O i-diario-portabilis recebe apenas
pontos de extensão vazios — partials com um comentário e nada mais —
e esse código é replicado para o repositório open source i-diario.
O i-diario-plus é um Rails Engine que estende o app principal usando o padrão Decorator e Partial Slots. Quando instalado, ele sobrescreve comportamentos sem modificar o código-base.
Este é o padrão central usado na PR #4894. O app principal cria partials vazias como "slots" que o engine preenche com conteúdo real.
O engine usa prepend_view_path para que suas views tenham prioridade sobre as do app principal.
Quando o Rails procura shared/_plugin_widget, verifica primeiro o path do engine.
Se encontra lá, usa aquela versão. Caso contrário, usa a partial vazia do app principal.
Duas funcionalidades distintas, cada uma resolvendo uma dor real dos professores.
O professor pode registrar a frequência dos alunos por texto ou voz, usando linguagem natural. Em vez de marcar cada aluno individualmente em uma tabela, ele diz algo como:
A IA recebe o nome do professor, turmas, lista de alunos com IDs, datas e o histórico da conversa. Tudo isso no system prompt.
A IA faz fuzzy matching de nomes (ex: "a Ana" vira "Ana Silva"), infere datas (ex: "hoje"), e seleciona turma automaticamente quando o professor tem só uma.
Nenhum registro é feito sem confirmação explícita do professor. A IA apresenta um resumo e espera o "sim" antes de persistir no banco.
Usa os mesmos services existentes do i-Diário (DailyFrequenciesCreator)
para gravar a frequência, respeitando calendário e deadlines.
Na tela de avaliações descritivas, o professor pode ditar a nota do aluno por voz. A IA transcreve e depois formata o texto em linguagem formal educacional, seguindo as normas do MEC.
Usa a API OpenAI Whisper (modelo whisper-1) para converter áudio em texto, com suporte nativo a português brasileiro.
O texto transcrito passa por um segundo processamento que o transforma em linguagem formal, pedagogicamente adequada para boletins escolares.
Se a formatação falhar, o professor recebe a transcrição bruta. Nunca perde o que ditou.
O administrador pode personalizar o prompt de formatação via painel de configurações, sem alterar código.
Acessível apenas para administradores, no menu Administrativo > Configurações de IA. Permite ligar/desligar cada feature de IA independentemente.
chat_enabled
Boolean (toggle)
Desativado
descriptive_ai_enabled
Boolean (toggle)
Desativado
descriptive_ai_prompt
Texto livre
Template padrão
As features de IA vêm desabilitadas por padrão. O administrador precisa explicitamente ativar cada uma. Sem chave de API do OpenAI configurada nos secrets, nada funciona.
Apenas 5 linhas de código. Nenhuma lógica de IA. Apenas "slots" vazios para o engine preencher.
As partials usam nomes como _plugin_widget e _plugin_scripts
em vez de _ai_chat_widget. Isso é intencional:
não acopla o ponto de extensão a uma funcionalidade específica (IA) e permite
que qualquer plugin/engine use esses slots no futuro.
Chat controller, orchestrator, context builder, attendance registrar, LLM provider, whisper transcriber, modelos, migrations, testes.
Voice assistant JavaScript, controller de transcrição, NoteFormatter service, prompt templates, integração com SummerNote.
AiConfiguration model, admin controller/views, feature flags, decorators (features, user, navigation), migrations.
Acompanhe o fluxo completo desde a ação do professor até a persistência no banco de dados.
Texto ou áudio pelo widget de chat no canto da tela. Vai para ChatController#create_message.
Se for áudio, o WhisperTranscriber converte para texto via API OpenAI Whisper (whisper-1, pt-BR).
ContextBuilder monta o system prompt com: nome do professor, turmas, lista de alunos com IDs, data atual, e sessão anterior.
OpenaiProvider envia para GPT-4o mini com response_format JSON. O modelo retorna uma ação estruturada.
O Orchestrator analisa a ação retornada:
register_attendance (mostrar resumo e pedir confirmação),
ask_clarification (pedir mais info),
ou general_response (conversa livre).
Professor confirma → AttendanceRegistrar usa DailyFrequenciesCreator do i-Diário para persistir a frequência. Valida calendário, deadline e dia letivo.
Na tela de edição de avaliações descritivas, o botão de gravação aparece ao lado do campo de texto do aluno.
JavaScript captura áudio pelo navegador, converte para WAV (8kHz), e envia como base64 para o backend.
WhisperTranscriber recebe o áudio e retorna texto em português.
NoteFormatter envia a transcrição + contexto (aluno, turma, disciplina) para o GPT-4o mini, que reescreve em linguagem formal educacional.
O texto formatado é inserido no campo SummerNote do aluno. O professor revisa, edita se quiser, e salva.
Mergulho nos componentes mais importantes da implementação.
O sistema usa um Factory Pattern para desacoplar a implementação do provider de LLM. Hoje usa OpenAI, mas a arquitetura permite adicionar Claude, Gemini ou outros facilmente.
Os prompts são templates ERB armazenados em app/prompts/, renderizados pelo PromptRenderer.
Isso separa o conteúdo do prompt da lógica de código.
| Tabela | Campos Principais | Propósito |
|---|---|---|
ai_configurations |
chat_enabled, descriptive_ai_enabled, descriptive_ai_prompt |
Singleton com feature flags e prompts customizáveis |
chat_sessions |
user_id, teacher_id, entity_id, conversation_state, pending_action |
Sessão de chat por professor, com estado da conversa e ação pendente (JSONB) |
chat_messages |
chat_session_id, role, content, audio, metadata |
Histórico de mensagens (user/assistant/system) com suporte a áudio |
Máximo de 10 mensagens por minuto por sessão. Protege contra uso excessivo da API.
Limite de 10 MB por arquivo de áudio (base64). Previne uploads gigantescos.
O LLM recebe apenas as últimas 10 mensagens da conversa, evitando excesso de tokens.
O registrador valida: não é data futura, está no calendário escolar, dentro do prazo de lançamento, e é dia letivo.
Decisões arquiteturais que garantem a segurança e privacidade dos dados educacionais.
Cada entidade (rede escolar) tem seu próprio banco de dados no i-Diário.
Os arquivos de áudio são armazenados em diretórios separados por entity_id:
development/entity-{id}/chat_audio/{session_id}/.
As sessões de chat incluem entity_id como chave estrangeira obrigatória.
As chaves da API OpenAI são armazenadas em Rails.application.secrets,
nunca hardcoded no código. Sem a chave configurada, as features simplesmente
não funcionam — sem erros visíveis para o usuário.
Chat: Apenas professores com registro ativo podem usar.
O controller verifica require_teacher em todas as ações.
Configurações: Apenas administradores podem acessar.
O decorator verifica admin? para as features de IA.
Assistente de Voz: Apenas professores com acesso à
tela de avaliações descritivas.
O model AiConfiguration usa a gem audited,
registrando todas as mudanças de configuração com quem, quando e o que mudou.
Erros de API são reportados ao Honeybadger para monitoramento
em tempo real. Todas as mensagens do chat ficam persistidas no banco para
auditoria posterior.
O WhisperTranscriber cria arquivos temporários durante a transcrição.
Esses arquivos são sempre removidos no bloco ensure,
mesmo em caso de erro. Nenhum dado de áudio temporário permanece no servidor.
Respostas para as dúvidas mais comuns sobre IA no i-Diário.
Não neste momento. Toda a lógica de IA vive no engine
i-diario-plus, que é um repositório privado da Portabilis e nunca
vai para o open source. O i-diario-portabilis recebe apenas pontos
de extensão vazios (que depois vão para o i-diario open source).
Sem o engine instalado, a experiência do i-Diário é exatamente a mesma de antes.
Os preços atuais da OpenAI (fev/2026):
| Serviço | Preço | Equivalente |
|---|---|---|
GPT-4o mini (input) |
US$ 0,15 / 1M tokens | ~2.500 páginas por US$ 0,15 |
GPT-4o mini (output) |
US$ 0,60 / 1M tokens | 16x mais barato que o GPT-4o |
Whisper (transcrição) |
US$ 0,006 / minuto | US$ 0,36 por hora de áudio |
Na prática: Uma mensagem de chat (prompt + resposta) custa frações de centavo. Uma transcrição de 30 segundos de áudio custa US$ 0,003. O rate limiting (10 msgs/min por sessão) ajuda a controlar uso. A chave de API é configurada pelo administrador do sistema.
Fonte: openai.com/api/pricing
Sim! A arquitetura já foi pensada para isso. O ProviderFactory
aceita diferentes providers no hash PROVIDERS. Para adicionar um novo,
basta criar uma classe que herda de BaseProvider e implementar
chat_completion. O provider ativo é definido pelo secret
LLM_PROVIDER.
O sistema tem fallback em vários níveis:
Chat: Retorna uma mensagem amigável de erro ao professor. O Honeybadger é
notificado. A sessão permanece intacta para retentativa.
Assistente de Voz: Se a formatação falhar, o professor recebe a
transcrição bruta. Se a transcrição também falhar, recebe erro com explicação.
Em nenhum caso dados são perdidos.
O ContextBuilder consulta o banco do i-Diário em tempo real.
Ele busca todas as turmas de frequência geral do professor, e para cada turma
lista os alunos ativamente matriculados na data corrente. Essas informações
(com nomes e IDs) são injetadas no system prompt, permitindo que a IA
identifique alunos por nome, apelido ou parte do nome.
O schema já suporta o canal whatsapp na tabela chat_sessions,
mas a implementação atual é apenas via web.
A infraestrutura está pronta para expandir para WhatsApp no futuro.
Não. As partials adicionadas contêm apenas um comentário ERB. Renderizam literalmente nada. O risco é extremamente baixo. Sem o engine, essas 5 linhas de código são invisíveis e inofensivas.