Chatbot COJUD

Chatbot inteligente para o Centro de Formação e de Desenvolvimento de Pessoas do Poder Judiciário do RS – CJUD. O assistente virtual COJUD utiliza técnicas de RAG (Retrieval-Augmented Generation) para fornecer informações precisas sobre cursos EAD-Autoaprendizagem.

🦉 Sobre o COJUD

COJUD é o assistente virtual do CJUD, representado por uma coruja verde. Atualmente em beta, o chatbot pode:

• Responder dúvidas sobre cursos
• Recomendar cursos da categoria EAD-Autoaprendizagem
• Manter contexto da conversa
• Exibir informações detalhadas dos cursos com imagens e cards visuais

📁 Estrutura do Projeto

moodle-chatbot/
├── backend/              # API Node.js + Express + TypeScript
│   ├── src/
│   │   ├── routes/      # Rotas da API
│   │   ├── services/    # Serviços (Gemini, embeddings, knowledge base)
│   │   └── config.ts    # Configurações
│   ├── data/
│   │   └── courses.json # Base de conhecimento (cursos)
│   └── package.json
├── frontend/            # Widget React + TypeScript
│   ├── src/
│   │   ├── components/  # Componentes React
│   │   ├── hooks/       # Hooks customizados
│   │   └── utils/       # Utilitários
│   ├── public/
│   │   └── widget-loader.js # Script de carregamento para Moodle
│   └── package.json
├── base_conhecimento/   # Base de conhecimento original
│   └── info_cursos.json # Arquivo fonte dos cursos
└── README.md

🚀 Configuração

Pré-requisitos

• Node.js 20+ ou 22+
• npm ou yarn
• Chave de API do Google Gemini

Backend

1. Instale as dependências:

cd backend
npm install

2. Configure as variáveis de ambiente:

# Copie o arquivo de exemplo
cp env.example .env

# Edite o .env com suas configurações:
GEMINI_API_KEY=sua_chave_aqui
GEMINI_MODEL=gemini-2.5-flash
PORT=3001
NODE_ENV=development
CORS_ORIGIN=*
USE_EMBEDDINGS=false  # Opcional: habilita busca semântica com embeddings

3. Copie a base de conhecimento:

# Certifique-se de que backend/data/courses.json existe
# Ele deve ser uma cópia de base_conhecimento/info_cursos.json

4. Execute o servidor:

npm run dev

O servidor estará disponível em http://localhost:3001

Frontend

1. Instale as dependências:

cd frontend
npm install

2. Configure a URL da API (opcional):

# Crie um arquivo .env
VITE_API_URL=http://localhost:3001

3. Execute em modo desenvolvimento:

npm run dev

4. Build para produção:

npm run build

Os arquivos serão gerados em frontend/dist/

🔌 Integração no Moodle

Opção 1: Script de Embed (Recomendado)

1. Faça o build do frontend:

cd frontend
npm run build

2. Faça upload dos arquivos para seu CDN/servidor:

   • dist/cojud-chatbot.es.js ou dist/cojud-chatbot.umd.js
   • dist/assets/* (CSS e outros assets)
   • public/widget-loader.js

3. Adicione no footer do Moodle ou em um bloco HTML:

<div id="cojud-chatbot-root"></div>
<script>
  window.COJUD_API_URL = 'https://sua-api.com';
  window.COJUD_WIDGET_URL = 'https://seu-cdn.com';
</script>
<script src="https://seu-cdn.com/widget-loader.js"></script>

Opção 2: Iframe

<iframe 
  src="https://seu-cdn.com/widget.html" 
  style="position: fixed; bottom: 20px; right: 20px; width: 400px; height: 600px; border: none; z-index: 10000;"
  allow="clipboard-read; clipboard-write">
</iframe>

✨ Funcionalidades

Chat Inteligente

• ✅ Integração com Google Gemini 2.5 Flash
• ✅ Manutenção de contexto da conversa
• ✅ Detecção de referências a mensagens anteriores
• ✅ Extração automática de contexto do usuário (área, função)

Busca e Recomendação

• ✅ Busca por palavras-chave otimizada
• ✅ Busca semântica com embeddings (opcional)
• ✅ Filtros por carga horária, modalidade, área
• ✅ Até 20 cursos por resposta
• ✅ Cache de respostas para performance

Interface do Usuário

• ✅ Widget flutuante moderno e responsivo
• ✅ Modo expandido (sidebar à direita)
• ✅ Cards visuais para cursos individuais
• ✅ Lista compacta para múltiplos cursos
• ✅ Botão de nova conversa
• ✅ Renderização de HTML nas mensagens
• ✅ Animações suaves

Cards de Curso

• ✅ Cabeçalho com imagem e título
• ✅ Informações organizadas em seções:
  • Introdução
  • Objetivo
  • Conteúdo
  • Público-alvo
  • Carga horária e modalidade
• ✅ Link direto para o curso no Moodle

🧠 Arquitetura RAG

O chatbot utiliza Retrieval-Augmented Generation (RAG) para fornecer respostas precisas:

1. Base de Conhecimento: Cursos armazenados em JSON (backend/data/courses.json)
2. Retrieval: Busca por palavras-chave ou embeddings semânticos
3. Augmentation: Contexto dos cursos relevantes é injetado no prompt
4. Generation: Gemini gera resposta baseada no contexto

Para mais detalhes, consulte RAG_IMPLEMENTATION.md

📊 Estrutura de Dados dos Cursos

Cada curso na base de conhecimento possui:

{
  filename: string;
  courseName: string;
  titulo: string;
  introducao: string;
  modalidade: string;
  cargaHoraria: string;
  disponibilidade: string;
  publicoAlvo: string;
  certificado: string;
  instrutor: string;
  avaliacao: string;
  objetivo: string;
  conteudo: string;
  qualityScore: number;
  id: string;
  cursoUrl: string;
  pdfUrl: string;
  imageUrl: string;
  inscricoesStatus: string;
  cursoFechado: string;
}

🔧 Variáveis de Ambiente

Backend (.env)

Variável	Descrição	Padrão
GEMINI_API_KEY	Chave da API do Google Gemini	Obrigatório
GEMINI_MODEL	Modelo do Gemini a usar	gemini-2.5-flash
PORT	Porta do servidor	3001
NODE_ENV	Ambiente (development/production)	development
CORS_ORIGIN	Origem permitida para CORS	*
USE_EMBEDDINGS	Habilita busca semântica	false

Frontend (.env)

Variável	Descrição	Padrão
VITE_API_URL	URL da API backend	http://localhost:3001

🛠️ Desenvolvimento

Scripts Disponíveis

Backend:

npm run dev      # Desenvolvimento com hot-reload
npm run build    # Compila TypeScript
npm run start    # Executa versão compilada
npm run type-check  # Verifica tipos sem compilar

Frontend:

npm run dev      # Servidor de desenvolvimento Vite
npm run build    # Build para produção
npm run preview  # Preview do build
npm run type-check  # Verifica tipos TypeScript

Tecnologias Utilizadas

Backend:

• TypeScript
• Express.js
• Google Gemini API (@google/generative-ai)
• CORS
• dotenv

Frontend:

• React 18
• TypeScript
• Vite
• CSS puro (sem frameworks)

📦 Deploy

Backend

Opções de deploy:

• Vercel (Serverless Functions)
• Netlify Functions
• Railway
• Heroku
• Servidor próprio (Node.js)

Variáveis de ambiente necessárias:

• GEMINI_API_KEY
• GEMINI_MODEL (opcional)
• PORT (opcional)
• NODE_ENV=production

Frontend

Opções de deploy:

• Vercel
• Netlify
• Cloudflare Pages
• Qualquer CDN/servidor estático

Após o build:

1. Faça upload da pasta dist/ para seu servidor/CDN
2. Configure a URL da API no .env ou via variáveis de ambiente
3. Adicione o script de carregamento no Moodle

🐛 Troubleshooting

Backend não inicia

• Verifique se a porta 3001 está disponível
• Confirme que o arquivo .env existe e tem GEMINI_API_KEY
• Verifique se backend/data/courses.json existe

Frontend não conecta ao backend

• Verifique se VITE_API_URL está correto
• Confirme que o backend está rodando
• Verifique CORS no backend

Widget não aparece no Moodle

• Verifique se o script widget-loader.js está acessível
• Confirme que #cojud-chatbot-root existe no DOM
• Verifique o console do navegador para erros

Busca não retorna resultados

• Verifique se backend/data/courses.json está atualizado
• Confirme que a estrutura do JSON está correta
• Verifique os logs do backend

📝 Notas de Desenvolvimento

• O chatbot está em beta e atualmente suporta apenas cursos EAD-Autoaprendizagem
• Futuras expansões incluirão outras categorias de cursos e FAQ
• O cache de respostas está em memória (Map). Para produção com múltiplas instâncias, considere Redis
• Embeddings são opcionais e podem melhorar a precisão da busca semântica

📄 Licença

ISC