Documentação
Aprenda a usar o Questioning Agent para gerar questões educacionais de alta qualidade usando IA.
Introdução
O Questioning Agent é uma plataforma avançada que utiliza tecnologia RAG (Retrieval-Augmented Generation) para gerar questões educacionais a partir de documentos. O sistema analisa seu conteúdo, cria embeddings vetoriais e gera questões em diferentes níveis cognitivos baseados na Taxonomia de Bloom.
- Geração automática de questões em múltiplos níveis cognitivos
- Suporte para PDF, DOCX, TXT e Markdown
- Busca semântica com embeddings vetoriais
- Exportação flexível (JSON, CSV, Markdown, Plain Text)
Início Rápido
Acesse o dashboard e faça upload de arquivos PDF, DOCX, TXT ou Markdown. O sistema processará automaticamente o conteúdo.
Escolha os níveis da Taxonomia de Bloom e deixe a IA gerar questões personalizadas com base no seu documento.
Instalação
# Clone o repositório
git clone https://github.com/ezsouza/questioning-agent.git
# Instale as dependências
pnpm install
# Configure as variáveis de ambiente
cp .env.example .env
# Execute o servidor de desenvolvimento
pnpm dev# Database
DATABASE_URL="postgresql://..."
# IA - OpenAI ou Google Gemini
OPENAI_API_KEY="sk-..."
GOOGLE_API_KEY="AIzaSyB-..."
# Better Auth
BETTER_AUTH_SECRET="..." # minimum 32 characters
BETTER_AUTH_URL="http://localhost:3000"
# Application
NEXT_PUBLIC_URL="http://localhost:3000"
# Cloudflare R2 Storage (300MB/usuário)
R2_ACCOUNT_ID="your-account-id"
R2_ACCESS_KEY_ID="your-access-key"
R2_SECRET_ACCESS_KEY="your-secret-key"
R2_BUCKET_NAME="questioning-agent-storage"
R2_PUBLIC_URL="https://pub-xxxxx.r2.dev"
R2_ENDPOINT="https://account-id.r2.cloudflarestorage.com"
# Google OAuth (Social Provider)
GOOGLE_CLIENT_ID="...apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="..."Upload de Documentos
O sistema suporta diversos formatos de documentos e processa automaticamente o conteúdo para geração de questões.
- PDF (.pdf)
- Word (.docx)
- Texto (.txt)
- Markdown (.md)
- ✓ Tamanho máximo por arquivo: 10MB
- ✓ Storage por usuário: 300MB (Cloudflare R2)
- ✓ Processamento: ~30 segundos por documento
Armazenamento
O sistema utiliza Cloudflare R2 para armazenamento de documentos e avatares, oferecendo 300MB gratuitos por usuário com URLs seguras e renovação automática.
✓ 300MB por usuário
✓ URLs assinadas com expiração segura
✓ Renovação automática de URLs
✓ Auditoria de storage
✓ Soft delete para recuperação
• Avatars: 24 horas de validade
• Documentos: 1 hora de validade
• Limite máximo: 7 dias
• Renovação 5 min antes de expirar
• Cache inteligente client-side
Pipeline RAG
O sistema utiliza Retrieval-Augmented Generation (RAG) para garantir que as questões geradas sejam precisas e baseadas no conteúdo do documento.
1. Chunking
O documento é dividido em chunks semânticos de tamanho otimizado (512-1024 tokens).
2. Embeddings
Cada chunk é convertido em um vetor de embeddings usando modelos de última geração (text-embedding-3).
3. Indexação
Os vetores são armazenados no PostgreSQL com pgvector para busca eficiente.
4. Retrieval
Durante a geração, o sistema recupera os chunks mais relevantes usando busca por similaridade.
Geração de Questões
Gere questões em diferentes níveis cognitivos baseados na Taxonomia de Bloom.
Recordar fatos e conceitos básicos
Explicar ideias ou conceitos
Usar informação em novas situações
Estabelecer conexões entre ideias
Criar ou gerar algo novo
Justificar uma posição ou decisão
Sistema de Feedback
Ajude a melhorar a qualidade das questões geradas avaliando e fornecendo feedback detalhado sobre cada questão.
Útil
Questão bem formulada, relevante e com gabarito correto
Não útil
Questão precisa de melhorias - abre popup com motivos específicos
- Fora de contexto do documento
- Gabarito incorreto ou impreciso
- Questão mal formulada ou confusa
- Nível cognitivo inadequado
- Duplicada ou muito similar
- Outros motivos (campo livre)
1. Avalie a Questão
Ao visualizar suas questões, você verá botões "Útil" e "Não útil" em cada uma. Use "Útil" para questões de qualidade e "Não útil" para aquelas que precisam melhorias.
2. Forneça Detalhes (Quando não útil)
Ao clicar em "Não útil", um popup aparecerá solicitando o motivo específico. Selecione uma ou mais opções que se aplicam e, opcionalmente, adicione um comentário detalhado.
3. Sistema Aprende Continuamente
Seu feedback é analisado por IA e usado automaticamente na próxima geração de questões. O sistema identifica padrões nos feedbacks negativos e ajusta o prompt para evitar erros semelhantes, melhorando progressivamente a qualidade.
Exportação
Exporte suas questões em diferentes formatos para integração com sistemas de aprendizagem.
{
"questions": [
{
"id": "q1",
"text": "...",
"level": "aplicacao",
"difficulty": "medium"
}
]
}id,text,level,difficulty
q1,"...",aplicacao,medium
q2,"...",analise,hard# Questões Geradas
## Questão 1
**Nível:** Aplicação | **Dificuldade:** Médio
...
**Resposta:** ...QUESTÃO 1 [Aplicação - Médio]
...
RESPOSTA: ...
---Arquitetura
Frontend
Backend
IA & ML
Banco de Dados
users- Dados dos usuáriosdocuments- Metadados dos documentoschunks- Chunks de texto com embeddingsquestions- Questões geradas
Segurança
Levamos a segurança dos seus dados muito a sério e implementamos as melhores práticas do setor.
✓ Better Auth com sessões seguras
✓ Suporte a OAuth (Google)
✓ Hashing de senhas com bcrypt
✓ Proteção CSRF e XSS
✓ Criptografia em trânsito (HTTPS)
✓ Isolamento de dados por usuário
✓ Backups regulares
✓ Conformidade com LGPD
Contribuições & Roadmap
O Questioning Agent está em constante evolução. Confira as próximas funcionalidades planejadas e como você pode contribuir para o projeto.
Quiz Interativo
Transformar questões geradas em quizzes interativos com timer, pontuação e feedback imediato
Suporte a Novos Formatos
Upload e análise de apresentações (PowerPoint, Google Slides), áudio (transcrição automática) e vídeos
Banco de Questões Colaborativo
Compartilhar e descobrir questões criadas por outros educadores na comunidade
Análise de Performance
Dashboard de analytics com métricas de desempenho dos alunos e identificação de pontos de dificuldade
Integração com LMS
Conectar com plataformas como Moodle, Canvas e Google Classroom para exportação direta
Geração de Imagens para Questões
Criar automaticamente diagramas, gráficos e ilustrações relevantes usando IA
API Pública
Documentação e endpoints REST para integração com sistemas externos
Suporte Multilíngue
Geração de questões em múltiplos idiomas (inglês, espanhol, francês, etc.)
Editor de Questões Avançado
Interface rica para edição, formatação e personalização de questões geradas
Gamificação
Sistema de badges, níveis e conquistas para engajar estudantes e educadores
Desenvolvedores
Contribua com código, correção de bugs ou implementação de novas features:
- Fork o repositório no GitHub
- Crie uma branch para sua feature
- Siga as convenções de código do projeto
- Envie um Pull Request detalhado
Educadores
Compartilhe feedback sobre usabilidade, sugira melhorias pedagógicas e reporte bugs através do nosso formulário de contato.
Comunidade
Ajude outros usuários, crie tutoriais, traduza a documentação ou simplesmente compartilhe o projeto com outros educadores.
Precisa de ajuda? Entre em contato
Começar Agora