Trabalhos Práticos: A Fábrica de Pesquisa WOKDEX
Visão Geral do Ecossistema
Página principal e informações gerais sobre Trabalhos Práticos: A Fábrica de Pesquisa WOKDEX - Inteligência Artificial II. Prof. Aléssio M. Jr no CEFET-MG.
Bem-vindos à Missão 🚀
Nesta disciplina, os Trabalhos Práticos não são exercícios isolados nem projetinhos descartáveis. Vocês vão construir, do zero, um sistema real de Inteligência Artificial que resolve um problema de pesquisa aberto: ajudar alunos novatos de programação a entenderem seus próprios erros.
Se o sistema que a turma construir funcionar, os melhores rascunhos e códigos serão consolidados em um Artigo Científico Real, submetido a congressos nacionais e internacionais (como o CBIE/SBIE), com os melhores alunos figurando como coautores.
Antes de falar sobre código, vocês precisam entender o problema que estão resolvendo.
🔇 O Problema: O Silêncio Pedagógico
Você já participou ou ouviu falar de competições como a Maratona de Programação? Ou talvez já tenha se divertido (e passado um pouco de raiva) em alguma disciplina onde o professor Aléssio utilizou o maratona.alessiojr.com (baseado no DOMjudge)? Além desses, é bem provável que já tenha esbarrado em juízes online clássicos como o Beecrowd (antigo URI), Codeforces ou LeetCode. Se a resposta for sim para qualquer uma dessas opções, então você definitivamente já passou por isso:
- Você escreve seu código com carinho.
- Submete a solução.
- O juiz responde:
Wrong Answer. - Você fica olhando para a tela sem saber o quê errou.
Isso é o que chamamos de Silêncio Pedagógico: o juiz online sabe que você errou, mas não te diz por quê. Ele não diz se o seu erro é de lógica, de formatação, ou se a sua solução está correta mas é lenta demais. Ele simplesmente diz “errado” e te abandona.
Esse problema é grave:
- Pesquisas científicas mostram que mais de 30% dos alunos reprovam em disciplinas introdutórias de programação, em parte porque o feedback que recebem é insuficiente.
- O professor não consegue analisar o raciocínio de 100 alunos individualmente.
- Sem orientação, o aluno recorre a tentativas aleatórias (guess-checking) ou, pior ainda hoje em dia, simplesmente joga o problema em uma LLM (como o ChatGPT) e copia a resposta pronta. Como ele não acompanha criticamente o raciocínio, o aprendizado real não acontece e ele acaba travando e errando novamente no próximo obstáculo ou na prova.
💡 A Solução: O WOKDEX
O WOKDEX (World of Kode: Open Didactic Exchange) é um modelo de metadados pedagógicos criado pelo professor desta disciplina como parte de sua tese de doutorado.
A ideia é simples e poderosa: em vez de deixar a inteligência pedagógica presa dentro de uma plataforma (como o Moodle ou o CodeRunner), o WOKDEX embutiu essa inteligência diretamente dentro do exercício, na forma de um arquivo metadata.yaml.
Esse arquivo YAML acompanha cada exercício de programação e diz ao sistema:
- Quais habilidades (skills) o exercício exige do aluno (ex:
condicionais,lacos,vetores). - Quais testes existem e qual é a intenção pedagógica de cada um.
- Se um teste específico foi criado para detectar um erro conceitual comum (misconception) que o aluno provavelmente está cometendo.
- Qual dica formativa (helpTip) deve ser exibida caso o aluno falhe naquele cenário.
Dessa forma, o juiz online deixa de ser um robô binário (“certo/errado”) e passa a ser um tutor assíncrono que diagnostica o tipo de erro e orienta o aluno.
🧬 As 3 Camadas do YAML WOKDEX
O arquivo metadata.yaml de cada exercício é organizado em três camadas:
Camada 1: Descritiva (O que é este exercício?)
Informações gerais como título, nível curricular (CS1, CS2 ou CS3), dificuldade e complexidade de tempo/espaço.
name: "Divisão"
difficultyLevelId: "D"
timeComplexity: "O(1)"
skills:
- "matematica"
- "io"Camada 2: Pedagógica (O que o aluno precisa saber?)
Lista de habilidades (skills) exigidas e dicas formativas (helpTip) por cenário de teste. Se o aluno errar, ele recebe uma dica contextualizada, não um genérico “Wrong Answer”.
helpTip: "Erro na declaração de tipo de variável.
Suas variáveis são inteiras, mas a divisão
pode gerar resultado decimal."
skills:
- { skill: matematica, points: 1 }Camada 3: Avaliativa (Como o aluno é testado?)
Os cenários de teste (testScenarios), cada um com um tipo pedagógico que define por que aquele teste existe.
🎯 Os 4 Tipos de Teste do WOKDEX
Esta é a inovação central do modelo. Em vez de tratar todos os testes como iguais (como fazem os juízes tradicionais), o WOKDEX classifica cada cenário de teste:
| Tipo | Visível? | O que ele faz? |
|---|---|---|
SAMPLE |
✅ Sim | Testes dos exemplos do enunciado. O aluno pode usá-los para depurar antes de submeter. |
FUNCTIONAL |
❌ Não | Testes secretos que verificam comportamentos específicos não revelados ao aluno. |
MISCONCEPTION |
❌ Não | A “armadilha pedagógica”. Testes projetados para capturar erros conceituais comuns. Se o aluno cai nessa armadilha, o WOKDEX sabe exatamente qual é o erro mental dele. |
PERFORMANCE |
❌ Não | Testes que verificam a eficiência do algoritmo (tempo/memória), separando a questão “seu código está certo?” de “seu código é rápido?”. |
O caso mais interessante: MISCONCEPTION
Imagine um exercício que pede para dividir dois números e exibir o resultado com duas casas decimais. Um aluno que declara variáveis como int em vez de double vai obter:
10 / 2 = 5.00→ ✅ Parece correto! (mas é um acidente: a divisão é exata)19 / 6 = 3.00→ ❌ Deveria ser 3.17 (a divisão inteira truncou o resultado)
O juiz tradicional daria apenas “Wrong Answer” no segundo caso. O WOKDEX, ao contrário, reconhece que a saída 3.00 é exatamente a saída que um aluno com o erro de int vs double produziria. Ele então emite a dica: “Erro na declaração de tipo de variável. Verifique se está usando double/float.”
📋 Exemplo Real: O Exercício “Divisão”
Abaixo está um trecho real do metadata.yaml do exercício “Divisão” do corpus WOKDEX. Este é o tipo de arquivo que o agente de I.A. de vocês vai ter que gerar automaticamente no TP3.
name: "Divisão"
difficultyLevelId: "D"
timeComplexity: "O(1)"
skills:
- "matematica"
- "io"
testScenarios:
- id: "d-sample"
name: "Exemplos"
level: "D"
testType: SAMPLE # Testes visíveis do enunciado
helpTip: "Verifique os testes básicos do enunciado."
skills:
- { skill: io, points: 1 }
- { skill: mathematics, points: 1 }
- id: "c-falso-positivo-inteiros"
name: "Inteiros - Falso Positivo"
level: "C"
testType: MISCONCEPTION # Armadilha pedagógica!
helpTip: "Erro na declaração de tipo de variável."
targetLanguages: ["c", "cpp", "java"]
skills:
- { skill: mathematics, points: 1 }[!NOTE] Observe: o cenário
d-sampleé do tipoSAMPLE(testes visíveis do enunciado). Já o cenárioc-falso-positivo-inteirosé do tipoMISCONCEPTION: ele foi construído especificamente para capturar o aluno que usouintem vez dedouble. O campotargetLanguagesrestringe este cenário às linguagens onde a misconception se manifesta.
⚙️ O Pipeline de 5 Fases (O Mapa do Semestre)
O segundo artigo da pesquisa (submetido à RBIE) propõe um pipeline de I.A. Generativa em 5 fases para gerar o metadata.yaml automaticamente. Cada TP que vocês farão corresponde a uma ou mais fases deste pipeline:
| Fase | O que acontece | Qual TP cobre isso |
|---|---|---|
| 1 | Leitura do enunciado: O sistema recebe o texto bruto de um exercício de programação. | TP1 |
| 2 | Inferência de Skills: Uma Rede Neural ou um LLM analisa o texto e prevê quais habilidades são exigidas (condicionais, vetores, etc.). |
TP1 |
| 3 | Busca de exercícios similares (RAG): O sistema busca no banco vetorial exercícios parecidos para usar como contexto, evitando que a I.A. “invente” coisas. | TP2 |
| 4 | Geração de Misconceptions: A I.A. simula o raciocínio de um aluno novato e tenta cometer erros conceituais. A partir desses erros, ela gera os cenários MISCONCEPTION. |
TP3 |
| 5 | Montagem e validação do YAML: O agente monta o metadata.yaml final e valida contra o JSON Schema oficial. Se algo estiver fora do formato, o validador rejeita e a I.A. tenta novamente (Self-Healing). |
TP3 |
É por isso que os TPs não são trabalhos soltos: cada TP constrói um pedaço deste pipeline, e no final do semestre, o sistema inteiro roda do zero à emissão do YAML pedagógico.
[!IMPORTANT] Recursos Disponíveis Desde o Dia 1: O professor disponibilizará no repositório base dois artefatos essenciais: (1) O Corpus Starter WOKDEX — um conjunto curado de 50–100 exercícios de programação já anotados com skills e cenários de teste, pronto para treino e indexação; e (2) O JSON Schema oficial (
wok-scheme.json) — o contrato formal que define todos os campos, enums e restrições dometadata.yaml. Esses dois arquivos são o alicerce de todos os TPs.
👥 Como as Equipes Funcionam?
Para simular o ambiente de uma verdadeira Start-up de Inteligência Artificial, os grupos serão formados por exatos 4 alunos.
A divisão de trabalho segue uma hierarquia rígida de responsabilidades projetada para garantir colaboração, mas impedir completamente a existência de “caroneiros”. Funciona nos seguintes níveis:
- 🌐 Nível 1 - O Grupo (4 alunos): É a entidade final. O grupo todo é responsável por fazer as peças funcionarem juntas e escrever o rascunho do Artigo Científico. Todos recebem a mesma nota pela qualidade do texto e do deploy final.
- 🤝 Nível 2 - A Dupla (2 alunos): O grupo de 4 pessoas é quebrado em duas metades (Dupla 1 e Dupla 2). Cada dupla assume um “pilar” da arquitetura. Por exemplo, enquanto a Dupla 1 constrói a Inteligência Artificial, a Dupla 2 constrói o Banco de Dados. A dupla deve dialogar muito para que seus códigos se conectem.
- 👤 Nível 3 - O Indivíduo (Você): Dentro da sua dupla, não existe “trabalho genérico”. Você receberá um cargo específico de programação (ex: Aluno A limpa os dados; Aluno B constrói a Rede Neural). Você é o único responsável por programar e entregar o código da sua missão. Se o seu código falhar, o serviço da dupla cai, e o projeto do grupo não compila.
[!WARNING] A sua nota individual técnica será auditada diretamente pelo seu histórico de commits no GitLab. Se não houver commits seus construindo a sua parte, sua nota individual será zero, mesmo que o grupo entregue o sistema funcionando.
🕵️♂️ Regras de Auditoria no GitLab (Como comprovar sua parte)
Para que o professor saiba exatamente qual linha de código foi feita por qual aluno e consiga avaliar o “Nível 3” (O Indivíduo), o grupo é obrigado a seguir estas três regras de ouro no repositório do GitLab da disciplina:
- O Manifesto de Autoria (
README.md): Na raiz do repositório do grupo, deve existir uma tabela fixa mapeando quem assumiu qual cargo naquele TP. Atenção: Para permitir a auditoria automatizada (inclusive por agentes de Inteligência Artificial), a tabela precisa conter o nome completo, o papel (Ex: Aluno A), e o exato@username(login) do GitLab de cada membro. - Branches Individuais: Nunca faça commit direto na
main. O Aluno A deve criar uma branch chamadafeat/aluno-a-nlpe codificar sua parte lá. O Aluno B cria a branchfeat/aluno-b-fastapi. - Merge Requests (MRs): Quando o Aluno A terminar a sua parte, ele abre um Merge Request para a
main. Atenção: O Merge Request deve ter uma descrição clara (ex: “Implementado script de extração de dados e vetorização Word2Vec”).
[!TIP] O professor usará o recurso de Git Blame e o painel de Contributors do GitLab. Se o código inteiro da dupla foi empurrado pelo computador de um único aluno (usando a mesma conta do git), o sistema entenderá que o outro não programou nada e ele ficará sem a nota da parte de Engenharia.
🏆 Estrutura de Pontuação e Entregas (36 Pontos)
Os TPs somam 36 Pontos da sua nota final, divididos em três grandes marcos (Checkpoints):
| Entrega | Data Limite | Foco Técnico | Valor |
|---|---|---|---|
| TP1 (Checkpoint 1) | 12/09 (Sex) | Redes Neurais Clássicas e MLOps (FastAPI) | 8 pts |
| TP2 (Checkpoint 2) | 26/10 (Seg) | Oráculo RAG, Bancos Vetoriais e Spring AI | 8 pts |
| TP3 (Checkpoint 3) | 30/11 (Seg) | Agentes Autônomos (Demoday e Defesa) | 20 pts |
A Balança da Nota (Como você será avaliado)
A nota de cada TP é sempre dividida em duas metades exatas:
- 50% - Entrega em Grupo (Produção Científica e Integração): O grupo unifica os códigos, faz o microsserviço rodar, e submete um Draft (Rascunho) de Artigo de 2 a 3 páginas. A nota aqui é coletiva. Se o texto for ruim ou a API do grupo não subir no Docker, todo mundo perde ponto.
- 50% - Entrega Individual (Engenharia): A qualidade do seu código. Você usou as bibliotecas certas? O código está limpo? O seu módulo faz o que deveria fazer? A nota aqui é sua.
🔬 Trilha IC: Equipes de Pesquisa (Voluntário)
Além do caminho regular (TP1→TP2→TP3), esta disciplina oferece uma trilha de Iniciação Científica para equipes que querem ir além.
Como funciona?
- Todas as 10 equipes fazem o mesmo TP1 e TP2 (pipeline WOKDEX).
- No TP3, as equipes regulares constroem o Agente Curador (Fases 4–5 do pipeline).
- As equipes IC fazem um TP3 Master: em vez de construir o agente que gera os YAMLs, elas constroem o sistema que valida e testa os YAMLs gerados por todas as equipes — simulando alunos que erram de propósito para descobrir se os exercícios realmente capturam os erros certos.
O que muda nos TP1 e TP2?
Quase nada. As equipes IC fazem o mesmo trabalho que todas, com um pequeno adendo opcional (marcado com 🔬 nos documentos de cada TP) que as prepara para o TP3 Master. Se a equipe desistir da trilha IC no meio do caminho, o adendo já feito conta como bônus na nota regular.
O que a equipe IC ganha?
- Coautoria em artigo científico real (SBIE 2027 / AIED 2027)
- Acesso a GPU na nuvem (AWS com crédito de pesquisa)
- Carta de recomendação do professor
Como se candidatar?
A candidatura é voluntária e aberta desde o primeiro dia. A equipe inteira (4 alunos) se candidata preenchendo um formulário rápido. O professor avalia:
- A equipe tem disponibilidade extra (~4h/semana além da disciplina)?
- Todos os membros concordam com o compromisso?
- Há interesse genuíno em pesquisa?
[!TIP] Conselho do professor: Se vocês estão empolgados, façam um TP1 muito bem feito primeiro. A excelência no TP1 é o melhor indicador de que a equipe está pronta para a trilha IC. Não adianta querer correr se o alicerce não está sólido. O TP1 é a fundação de tudo.
Se mais de 3 equipes se candidatarem (ótimo!), todas serão aceitas — quanto mais dados experimentais, melhor para a pesquisa. Os detalhes completos estão no Programa IC Especial.
A Jornada Completa
TP1 (todas) TP2 (todas) TP3
├─ NN + FastAPI ├─ RAG + Spring AI ├─ Regular (8 equipes)
│ │ │ └─ Agente WOKDEX
└─ 🔬 Adendo IC: └─ 🔬 Adendo IC: └─ Master (IC equipes)
Diagnóstico Taxonomia erros └─ Simulated Students
pipeline v1 + Setup LangGraph 3 Agents + Ablation
+ Valida 10 pipelines🗺️ O Mapa de Integração do Semestre
📂 Acesse os Detalhes de Cada Entrega
Navegue abaixo para entender as regras, o escopo técnico e o papel individual de cada aluno dentro dos três grandes ciclos da disciplina: