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.
Data de Publicação

08/09/2026

Data de Modificação

04/09/2026

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:

  1. Você escreve seu código com carinho.
  2. Submete a solução.
  3. O juiz responde: Wrong Answer.
  4. 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 tipo SAMPLE (testes visíveis do enunciado). Já o cenário c-falso-positivo-inteiros é do tipo MISCONCEPTION: ele foi construído especificamente para capturar o aluno que usou int em vez de double. O campo targetLanguages restringe 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 do metadata.yaml. Esses dois arquivos são o alicerce de todos os TPs.

👥 Como as Equipes Funcionam? (Pareamento e Colaboração)

Para simular o ambiente de uma verdadeira Start-up de Inteligência Artificial, os grupos serão formados por exatos 4 alunos, organizados em 2 Duplas Operacionais.

A metodologia de trabalho adota o conceito de Programação em Par (Pair Programming) e Desenvolvimento Baseado em Contratos, garantindo que ninguém fique bloqueado esperando o outro terminar:

  • 🌐 Nível 1 - O Grupo (4 alunos): É a entidade final. O grupo todo é responsável pela integração fim a fim dos microsserviços, pelo deploy no Docker e pelo Artigo Científico Consolidado no TP3.
  • 🤝 Nível 2 - As Duplas Operacionais (2 alunos por pilar):
    • Dupla 1 (Dados & Inteligência Artificial): Aluno A e Aluno B trabalham em regime de pareamento nos pipelines de NLP, vetorização e modelagem da Rede Neural.
    • Dupla 2 (Engenharia de Software & MLOps): Aluno C e Aluno D trabalham em regime de pareamento no desenvolvimento da API REST (FastAPI/Spring), conteinerização Docker, testes automatizados e CI/CD.
  • 👤 Nível 3 - O Indivíduo (Você): Dentro da sua dupla, cada aluno assume protagonismo em tarefas complementares, mas com código compartilhado, revisado e construído em conjunto.

[!IMPORTANT] 🚀 Como Evitar Gargalos e Bloqueios (Trabalho em Paralelo via Mocks):
Nenhum aluno deve ficar parado esperando o colega terminar!
A Dupla 2 (Backend/Docker) não precisa esperar a Dupla 1 treinar o modelo final para começar a programar. No primeiro dia, o grupo define o contrato Pydantic/DTO (PredictRequest e PredictResponse). A Dupla 2 utiliza um modelo fictício (mock/stub) que retorna dados fixos para construir toda a API, o Dockerfile e a suite de pytest imediatamente. Quando a Dupla 1 exporta o modelo_skills.keras, basta plugar o arquivo real.

[!TIP] 🤝 Pareamento (Pair Programming) e Ajuda Mútua:
Apesar da distribuição de papéis, a equipe é uma só e deve se ajudar mutuamente. O pareamento na dupla é altamente incentivado: commits conjuntos, code reviews e coautoria em branches da sprint são práticas recomendadas da indústria. Se um colega tiver dificuldades, ajude-o a destravar.

🕵️‍♂️ Regras de Auditoria no GitLab (Como comprovar sua parte)

Para que a avaliação seja justa e transparente para todos os membros da equipe, o repositório deve seguir três boas práticas:

  1. O Manifesto de Autoria (README.md): Na raiz do repositório, inclua a tabela indicando a composição das duplas, os papéis e os logins @username do GitLab.
  2. Branches de Feature e Pareamento: Trabalhem em branches organizadas (ex.: feat/dupla1-dados-nlp, feat/dupla2-fastapi-docker). Commits de ambos os membros da dupla na branch são esperados e valorizados.
  3. Merge Requests (MRs) com Revisão: Quando a funcionalidade da dupla estiver pronta, abram um Merge Request para a main com descrição clara e revisão do código pelo parceiro da dupla antes do merge.

🏆 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 (Integração e Engenharia):
    • No TP1 e TP2: O grupo entrega o microsserviço funcional em Docker, a suite de testes automatizados (pytest / integração) e o Relatório Técnico Executivo no README.md (com tabelas de métricas e gráficos). Não há exigência de formatar artigo científico nessas duas primeiras fases.
    • No TP3 (O Capstone Final): O grupo unifica todo o ecossistema, defende a solução no Demoday e submete o Artigo Científico Consolidado (4 a 6 páginas em formato SBC), reunindo a metodologia e os resultados empíricos do semestre inteiro (Rede Neural vs. RAG vs. LLM).
  • 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 focado em engenharia).
  • No TP3, as equipes regulares constroem o Agente Curador (Fases 4–5 do pipeline) e redigem o Artigo Científico Consolidado.
  • As equipes IC fazem o 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:

  1. A equipe tem disponibilidade extra (~4h/semana além da disciplina)?
  2. Todos os membros concordam com o compromisso?
  3. 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 + Artigo SBC
└─ 🔬 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:

Trilha Regular (Todas as Equipes)

Trilha IC (Equipes Voluntárias)

Recursos e Documentação Integrada

De volta ao topo