📦 Recursos Oficiais e Base de Dados WOKDEX

Referência Técnica para os Trabalhos Práticos (TP1, TP2, TP3 e Trilha IC)

Documentação técnica, JSON Schema, Dataset Canônico Bilíngue (PT-BR) e Relatório Exploratório para os Trabalhos Práticos da disciplina de Inteligência Artificial II.

Nota📖 Documento Mestre Consolidado

Este documento reúne, de forma dinâmica e automatizada (via {{< include >}}), todas as especificações oficiais da disciplina de IA II: 1. Trilha Regular: TP1 (Classificador Multi-Label), TP2 (RAG & Spring AI) e TP3 (Agente Autônomo & Demoday). 2. Trilha de Iniciação Científica (IC): Programa IC Especial e TP3 Master (Simulated Students). 3. Recursos Oficiais: Especificação do Dataset LeetCode PT-BR (2.830 problemas), Schemas e Diretrizes de Engenharia.

---

1 🗺️ Visão Geral e Arquitetura do Semestre

2 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.

NotaAtualização da oferta 2026-2

O percurso obrigatório atual é TP1: classificação supervisionada, TP2: retrieval e recomendação híbrida de skills e TP3: integração TP1–TP2 com assistente RAG fundamentado. O TP2 é entregue antes do Módulo 3; encontros posteriores apenas reutilizam seus contratos, índice e evidências para preparar o TP3, sem acrescentar requisitos retroativos ao TP2. Java/Spring AI é uma opção de adaptador, não requisito do TP2. Agentes, Tool Calling e Fine-Tuning foram deslocados para a trilha opcional TP3.5. As seções desta página que descrevem geração autônoma de YAML registram o contexto de pesquisa WOKDEX e não constituem requisito avaliativo do núcleo da oferta.

Datas, pesos, escopo obrigatório e avaliação da oferta são definidos exclusivamente no Plano de Ensino e Cronograma 2026-2.

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.

---

2.1 🔇 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.

---

2.2 💡 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.

---

2.3 🧬 As 3 Camadas do YAML WOKDEX

O arquivo metadata.yaml de cada exercício é organizado em três camadas:

2.3.1 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"

2.3.2 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 }

2.3.3 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.

---

2.4 🎯 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?”.

2.4.1 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.”

---

2.5 📋 Exemplo Real: O Exercício “Divisão”

Abaixo está um trecho real do metadata.yaml do exercício “Divisão” do corpus WOKDEX. Este é um exemplo de evidência pedagógica que os sistemas dos trabalhos recuperam, analisam e apresentam com proveniência.

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.

---

2.6 ⚙️ 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	Recomendação híbrida de skills: O sistema compara o classificador do TP1, as skills derivadas dos vizinhos recuperados e uma combinação calibrada.	TP2
5	Resposta RAG fundamentada: O assistente apresenta evidências, citações, limites e abstenção quando a recuperação não sustenta uma resposta.	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 integra classificação, retrieval, recomendação híbrida e resposta RAG fundamentada. A emissão autônoma de YAML não faz parte do núcleo avaliativo de 2026-2.

[!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.

---

2.7 👥 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 ou outra stack documentada), 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.

---

2.8 🕵️‍♂️ 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.

---

2.9 🏆 Entregas e Avaliação

Consulte o Plano de Ensino e Cronograma 2026-2 para os prazos, pesos, escopo obrigatório e avaliação dos TPs. As páginas específicas dos trabalhos detalham somente a implementação e as evidências técnicas esperadas.

2.9.1 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 (Dossiê de Integração): O grupo integra TP1 e TP2, defende a solução e conclui o Artigo Científico SBC (4 a 6 páginas), reunindo método, métricas, evidências, limitações e resultados de classificação, retrieval e RAG.
• 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.

---

2.10 🔬 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 integram TP1 e TP2 em um assistente RAG fundamentado e redigem o Artigo Científico Consolidado.
• As equipes IC fazem o TP3 Master: em vez do TP3 regular, auditam evidências, citações, abstenções e reprodutibilidade dos artefatos TP2–TP3.

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.

2.10.1 A Jornada Completa

TP1 (todas)          TP2 (todas)          TP3
├─ Classificação      ├─ Retrieval +       ├─ Regular
│  supervisionada     │  recomendação      │  └─ Assistente RAG fundamentado
│                     │  híbrida de skills │     + Artigo SBC
└─ Artefato TP1       └─ Artefatos TP2     └─ Master (equipes IC aceitas)
   versionado            versionados          └─ Auditoria de evidências,
                                                  citações e reprodução

---

2.10.2 🗺️ O Mapa de Integração do Semestre

---

2.11 📂 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:

2.11.1 Trilha Regular (Todas as Equipes)

• 👥 Acompanhamento das Equipes e Repositórios (TP1)
• TP1: O Classificador de Habilidades (Redes Neurais e MLOps)
• TP2: Retrieval e Recomendação Híbrida de Skills
• TP3: Dossiê de Integração TP1–TP2 e Assistente RAG
• TP3.5: Trilha Avançada de Agentes e LLMs

2.11.2 Trilha IC (Equipes Voluntárias)

• 🔬 Programa IC Especial — Visão Geral
• 🧬 TP3 Master: Simulated Students

2.11.3 Recursos e Documentação Integrada

• 📑 Manual Integrado Consolidado (Visão Geral em Documento Único)
• 🧭 Editorial Docente da Revisão dos TPs 2026-2
• 📦 Recursos WOKDEX (JSON Schema, Artigo SBIE e Especificações)
• 📊 Relatório Exploratório do Dataset (Gráficos e Estatísticas - HTML)
• 📄 Relatório Exploratório do Dataset (Versão PDF)
• 📥 Download Dataset CSV PT-BR (23.3 MB)
• 📥 Download Dataset JSON PT-BR (25.4 MB)

---

3 🎯 TP1: O Classificador de Habilidades (MLOps & Deep Learning)

3.1 🧭 Por que este TP existe?

Volte ao metadata.yaml do exercício “Divisão” que você viu na página de Visão Geral. Repare no campo skills:

skills:
  - "matematica"
  - "io"

Esses rótulos dizem quais habilidades cognitivas um aluno precisa dominar para resolver aquele exercício. Hoje, quem classifica essas skills é o professor, manualmente. Isso é lento, subjetivo e não escala para centenas de exercícios.

A missão do TP1 é construir uma Rede Neural Clássica que leia o texto bruto de um enunciado de programação e preveja automaticamente quais skills ele exige. Esse modelo será o motor das Fases 1 e 2 do Pipeline WOKDEX.

Dica👥 Repositórios e Composição das Equipes

O acompanhamento dos grupos registrados no GitLab, links diretos dos repositórios e a listagem de alunos com sinalizadores de status estão disponíveis em Grupos do TP1 (2026-2).

---

3.2 📖 Leitura Obrigatória (Fundamentação)

Antes de programar, vocês precisam ler e entender estes dois artigos científicos. Eles serão a base do Draft 1 na seção de Trabalhos Relacionados.

Artigo 1: Kim, Y. (2014). “Convolutional Neural Networks for Sentence Classification”. arXiv:1408.5882

Por que ler: É exatamente o que vocês vão construir — uma rede neural que recebe uma frase e classifica em categorias. O paper tem apenas 6 páginas e mostra como vetorizações de texto (Word2Vec, TF-IDF) alimentam um classificador profundo. A arquitetura descrita é a referência mais citada do mundo para classificação de texto com Deep Learning.

Artigo 2: Feng, Z. et al. (2020). “CodeBERT: A Pre-Trained Model for Programming and Natural Language”. arXiv:2002.08155

Por que ler: Enquanto o artigo anterior trata de classificação de textos genéricos, este mostra que existe um campo de pesquisa inteiro dedicado a aplicar NLP especificamente em código-fonte e enunciados de programação. Vocês não vão usar o CodeBERT em si (ele é pesado demais para o escopo do TP), mas entender que o problema que vocês estão atacando já é estudado por grandes labs (Microsoft Research) dá lastro científico ao Draft 1.

---

3.3 📚 O que é uma Skill no WOKDEX e no Dataset?

As habilidades (skills) representam os conceitos algorítmicos e estruturas de dados necessários para resolver um exercício.

Para o TP1, trabalharemos com as 25 Skills/Tópicos mais representativos da amostra (que cobrem 94% do volume de problemas e incluem desde estruturas básicas até paradigmas avançados como Grafos e Backtracking):

#	Skill / Tópico	Ocorrências no Dataset	Exemplo Típico
1	Array (Vetores)	1.626	“Encontre o par de elementos que soma o alvo”
2	String (Textos)	683	“Verifique se a palavra é um palíndromo”
3	Hash Table (Tabela Hash / Dicionário)	589	“Conte a frequência de cada caractere em \(O(N)\)”
4	Dynamic Programming (Programação Dinâmica)	508	“Calcule o número de formas de subir uma escada”
5	Math (Matemática)	503	“Converta números romanos para inteiros”
6	Sorting (Ordenação)	391	“Ordene o array por frequência decrescente”
7	Greedy (Algoritmos Gulosos)	366	“Distribua doces minimizando o total”
8	Binary Search (Busca Binária)	259	“Encontre a raiz quadrada inteira em \(O(\log N)\)”
9	Depth-First Search (Busca em Profundidade / DFS)	242	“Percorra todos os caminhos válidos da árvore”
10	Matrix (Matrizes / Arrays 2D)	216	“Rotacione uma imagem \(N \times N\) em 90 graus”
11	Bit Manipulation (Manipulação de Bits)	212	“Conte o número de bits 1 na representação binária”
12	Breadth-First Search (Busca em Largura / BFS)	193	“Encontre o menor caminho no grafo”
13	Prefix Sum (Soma de Prefixos)	184	“Calcule a soma de um intervalo em \(O(1)\)”
14	Tree (Árvores)	182	“Calcule a profundidade máxima da árvore”
15	Two Pointers (Dois Ponteiros)	181	“Remova duplicatas de um vetor ordenado in-place”
16	Simulation (Simulação)	165	“Simule o movimento de um robô no grid”
17	Heap (Priority Queue) (Heap / Fila de Prioridade)	164	“Encontre o K-ésimo maior elemento”
18	Counting (Contagem de Elementos)	145	“Conte elementos com frequências específicas”
19	Stack (Pilhas)	138	“Valide se parênteses e colchetes estão balanceados”
20	Graph (Grafos)	133	“Detecte ciclos ou caminhos em grafos direcionados”
21	Sliding Window (Janela Deslizante)	130	“Maior substring contígua sem caracteres repetidos”
22	Binary Tree (Árvore Binária)	129	“Inverta ou reconstrua uma árvore binária”
23	Enumeration (Enumeração)	112	“Gere todas as combinações válidas de 3 dígitos”
24	Design (Projeto de Estruturas)	94	“Implemente um LRU Cache ou Fila usando Pilhas”
25	Backtracking (Retrocesso / Busca Exaustiva)	87	“Resolva o problema das N Rainhas ou Sudoku”

[!IMPORTANT] Formulação do Problema: Classificação Multi-Label
Um mesmo problema pode exigir múltiplas skills simultâneas (por exemplo, um exercício pode ter rótulos ['Array', 'Sorting', 'Two Pointers']).
Portanto, sua Rede Neural NÃO deve usar Softmax na saída!
Utilize: 1. Camada de saída com 25 neurônios e função de ativação sigmoid. 2. Função de perda (loss): binary_crossentropy. 3. Binarização dos alvos: MultiLabelBinarizer da biblioteca scikit-learn.

---

3.4 📦 O Dataset Oficial (leetcode_problems_pt)

A base oficial de dados para o TP1 é o LeetCode Problems Dataset Bilíngue, disponibilizado em formato tabular (CSV) e estruturado (JSON), com 2.830 enunciados completos em Português (PT-BR).

Nota🔗 Links para Acesso e Download

• 📊 Visualizar Relatório Exploratório Interativo (HTML) (Distribuições de tamanho de texto, frequências e estatísticas)
• 📄 Download do Relatório Exploratório (PDF) (Versão consolidada para leitura e impressão)
• 📥 Download do Dataset em CSV (23.3 MB)
• 📥 Download do Dataset em JSON (25.4 MB)
• 📖 Documentação Técnica & Especificação de Schemas

3.4.1 🐍 Snippet de Carga Rápida (Python / Pandas)

O Aluno A (Engenheiro de Dados) pode iniciar o pipeline com o seguinte fluxo:

import pandas as pd
import ast
from sklearn.preprocessing import MultiLabelBinarizer

# 1. Carregar dataset oficial
df = pd.read_csv("trabalho/database/leetcode_problems_pt.csv")

# 2. Selecionar features de entrada e target
# X: Texto do enunciado em Português (título + descrição completa contendo exemplos e restrições)
X_text = (df["title_pt"].fillna("").astype(str) + "\n\n" + df["description_pt"].fillna("").astype(str))

# 3. Tratar a coluna de tópicos (que vem como string de lista)
def parse_topics(val):
    if pd.isna(val): return []
    try: return ast.literal_eval(val) if isinstance(val, str) else val
    except: return []

df["topics_list"] = df["topics"].apply(parse_topics)

# 4. Filtrar para as Top 25 Skills
TOP_25_SKILLS = [
    "Array", "String", "Hash Table", "Dynamic Programming", "Math",
    "Sorting", "Greedy", "Binary Search", "Depth-First Search", "Matrix",
    "Bit Manipulation", "Breadth-First Search", "Prefix Sum", "Tree", "Two Pointers",
    "Simulation", "Heap (Priority Queue)", "Counting", "Stack", "Graph",
    "Sliding Window", "Binary Tree", "Enumeration", "Design", "Backtracking"
]

df["target_skills"] = df["topics_list"].apply(
    lambda topics: [t for t in topics if t in TOP_25_SKILLS]
)

# 5. Binarizar alvos para Multi-Label (Y terá shape: [N, 25])
mlb = MultiLabelBinarizer(classes=TOP_25_SKILLS)
Y = mlb.fit_transform(df["target_skills"])
print("Total de classes mapeadas:", len(mlb.classes_))
print(f"Shape final de Y: {Y.shape}")

Datas, peso, escopo obrigatório e avaliação normativos constam do Plano de Ensino e Cronograma 2026-2; esta página descreve as evidências técnicas do projeto.

[!IMPORTANT] Sobre o timing do NLP: A vetorização de texto (TF-IDF, Word2Vec) será coberta no módulo de Embeddings. Vocês podem começar a construir toda a infraestrutura (Keras, FastAPI, Docker, testes) usando o conhecimento dos materiais iniciais enquanto aguardam essa unidade para fechar o pipeline de dados do Aluno A. Consultem o plano para a sequência de encontros e prazos.

[!TIP] Baseline Obrigatório: No Draft 1, o grupo deve comparar a performance da Rede Neural contra um baseline simples (ex: TF-IDF + Logistic Regression / LinearSVC com OneVsRestClassifier). A tabela comparativa (Precision, Recall, F1-Macro, tempo de treino) é item obrigatório da avaliação.

---

3.5 👥 A Divisão de Tarefas na Equipe (4 Alunos em 2 Duplas)

Para garantir que o trabalho seja executado de forma fluida ao longo dos 20 dias, a carga horária estimada é de 10 a 15 horas de dedicação individual por aluno (~3 a 4 horas por semana). A equipe divide-se em duas duplas complementares:

┌────────────────────────────────────────────────────────┐
│                   EQUIPE DE 4 ALUNOS                   │
├───────────────────────────┬────────────────────────────┤
│  🔬 DUPLA 1: DADOS & ML   │  ⚙️ DUPLA 2: ENGENHARIA    │
│  (O Cérebro Matemático)   │  (A Casca MLOps / Docker)  │
├───────────────────────────┼────────────────────────────┤
│  Aluno A: Dados & NLP     │  Aluno C: Backend FastAPI  │
│  Aluno B: Redes Neurais   │  Aluno D: DevOps & Pytest  │
└───────────────────────────┴────────────────────────────┘

3.5.1 🔬 Dupla 1: Ciência e Dados (O Cérebro) — ~10 a 15h por aluno

Esta dupla é focada no pré-processamento de linguagem natural (NLP) em português e no treinamento da Rede Neural. O output final da dupla é o pipeline serializado (vectorizer.pkl / mlb.pkl), o modelo treinado (modelo_skills.keras) e as métricas de convergência.

• Aluno A (Engenheiro de Dados):
  • Dedicação: ~10–12 horas.
  • Tarefas: Carregar leetcode_problems_pt.csv, limpar os enunciados em português (description_pt), tratar as 25 skills com MultiLabelBinarizer, criar e serializar a vetorização de texto (ex: TfidfVectorizer(max_features=5000, ngram_range=(1,2))), e gerar a divisão estratificada Treino/Validação/Teste (80/10/10).
• Aluno B (Engenheiro de Machine Learning):
  • Dedicação: ~12–15 horas.
  • Tarefas: Construir e treinar o Baseline (ex: LogisticRegression / LinearSVC OvR), construir a Rede Neural Keras (camadas Densas, Dropout 0.3-0.5, saída 25 neurônios Sigmoid + binary_crossentropy), calibrar o limiar de decisão (\(\tau\)), gerar gráficos de loss/épocas e calcular o F1-Score Macro e Micro.

3.5.2 ⚙️ Dupla 2: Engenharia de Software e MLOps (A Casca) — ~10 a 15h por aluno

Esta dupla pega o modelo exportado pela Dupla 1 e constrói um microsserviço moderno, conteinerizado e testado, pronto para a integração e comparação com o retrieval nos TP2 e TP3.

• Aluno C (Dev Backend Python / FastAPI):
  • Dedicação: ~10–12 horas.
  • Tarefas: Criar a API FastAPI, definir contratos estritos de entrada e saída com Pydantic (PredictRequest, PredictResponse), carregar os artefatos (modelo_skills.keras e vectorizer.pkl) na inicialização da aplicação (usando lifespan), e implementar os endpoints POST /predict e GET /health.
• Aluno D (DevOps, QA e Docker):
  • Dedicação: ~10–12 horas.
  • Tarefas: Escrever o Dockerfile otimizado e docker-compose.yml, configurar a suite de testes automatizados com pytest (mínimo 5 testes), configurar a pipeline de CI no GitLab (.gitlab-ci.yml), e garantir que a API suba limpa em qualquer máquina com um único comando docker run.

[!TIP] 🤝 Dinâmica de Pareamento (Pair Programming) e Desenvolvimento Não-Bloqueante:
A Dupla 2 não deve esperar a Dupla 1 concluir o treinamento da rede neural para começar a trabalhar. Usem a abordagem de Contrato Primeiro (API-First / Contract-Driven): 1. No primeiro dia, a equipe alinha os modelos Pydantic (PredictRequest e PredictResponse). 2. A Dupla 2 cria um modelo simulado (mock) que devolve predições estáticas e constrói toda a API FastAPI, o Dockerfile e a suite de pytest em paralelo. 3. Os membros de cada dupla devem praticar pareamento contínuo, code reviews e ajuda mútua para manter o fluxo de entrega sem gargalos.

---

3.6 🔌 A API que você vai construir

O produto final de engenharia do TP1 é uma API REST conteinerizada. Abaixo está o contrato exato:

3.6.1 Requisição: POST /predict

{
  "enunciado": "Dada uma lista de inteiros nums e um inteiro target, retorne os índices dos dois números cuja soma seja igual a target."
}

3.6.2 Resposta esperada:

{
  "skills": [
    { "skill": "Array", "confidence": 0.94 },
    { "skill": "Hash Table", "confidence": 0.88 },
    { "skill": "Two Pointers", "confidence": 0.72 }
  ],
  "model_version": "v1.0",
  "input_length": 132
}

[!IMPORTANT] No TP2 e no TP3, esta API fornece a evidência supervisionada que será comparada à recomendação por retrieval e exibida no assistente RAG. Se a API não estiver de pé e respondendo neste formato, a integração e os testes de contrato não poderão ser executados. É por isso que o Docker é obrigatório.

---

3.7 📝 Relatório Técnico no README.md (Documentação do TP1)

O TP1 inicia o artigo SBC incremental: a equipe cria a estrutura do documento e registra problema, dataset, método supervisionado, métricas e limitações. O foco principal continua sendo Engenharia, Código e Métricas Técnicas; as seções serão ampliadas no TP2 e consolidadas no TP3.

O grupo deve documentar de forma clara e estruturada no próprio README.md do repositório GitLab (que servirá de base direta para o Artigo Final no TP3):

1. Trabalhos Relacionados e Fundamentação:
   • Contextualizar brevemente os artigos base (Kim 2014 para CNN/NLP e CodeBERT para representação de código).
2. Metodologia Preditiva (Dupla 1):
   • Justificativa da Formulação Multi-Label: Explicar matematicamente por que a saída usa Sigmoid independente por neurônio + binary_crossentropy em vez de Softmax.
   • Arquitetura da Rede: Tabela com as camadas da rede neural, número de neurônios, funções de ativação, taxa de Dropout e otimizador.
3. Resultados e Tabela Comparativa Obrigatória (Dupla 1 e 2):
   • Tabela comparando o Baseline (TF-IDF + Logistic Regression / SVM) contra a Rede Neural (Keras):

Modelo	Precision (Macro)	Recall (Macro)	F1-Score (Macro)	F1-Score (Micro)	Tempo de Treino
Baseline (TF-IDF + Regressão Logística OvR)	…	…	…	…	~2s
Rede Neural Keras (Dense + Dropout)	…	…	…	…	~45s

4. Análise de Desbalanceamento, Threshold \(\tau\) e o Abismo Semântico (Dupla 1):
   • Gráfico de convergência (Loss de Treino vs. Validação).
   • Discussão do Abismo Semântico (Semantic Gap): Analisar criticamente quais das 25 classes foram mais fáceis/difíceis. Por que classes sintáticas como String ou Tree apresentam F1 mais elevado do que paradigmas abstratos como Dynamic Programming ou Greedy?
   • Efeito do limiar de decisão \(\tau\) dinâmico no F1-Score das classes minoritárias (ex: Backtracking).
5. Engenharia e Arquitetura MLOps (Dupla 2):
   • Diagrama ou descrição da conteinerização Docker, latência média da rota POST /predict (em milissegundos) e testes unitários.

---

3.8 🧪 Sugestões de Testes Automatizados Obrigatórios (pytest)

O Aluno D (DevOps) deve implementar, no mínimo, a seguinte suite de testes com pytest (arquivo tests/test_api.py):

#	Função de Teste	O que deve verificar
1	test_api_health	A rota GET /health responde HTTP 200 e status "ok"
2	test_predict_valid_input	POST /predict com enunciado válido retorna HTTP 200 e campos skills, model_version, input_length
3	test_skills_in_top25	Todas as skills retornadas na lista pertencem estritamente às 25 classes válidas
4	test_confidence_range	O valor de confidence de cada skill prevista está rigorosamente no intervalo \([0.0, 1.0]\)
5	test_empty_input_validation	Enunciado vazio ("" ou whitespace) retorna HTTP 422 (validação Pydantic)
6	test_predict_deterministic	Duas chamadas com o mesmo texto produzem as mesmas predições

---

3.9 📊 Rubrica de Avaliação Detalhada (8 Pontos)

3.9.1 Nota Individual (4 pts)

Critério	Pontos	Detalhes
Commits individuais na branch correta	1	Avaliado via Git Blame (evidência de autoria)
Entrega técnica individual funcionando	2	Pipeline do Aluno A OU Rede do Aluno B OU FastAPI do Aluno C OU Docker/Testes do Aluno D
Qualidade e organização do código	1	Boas práticas, docstrings, código modular e limpo

3.9.2 Nota do Grupo (4 pts)

Critério	Pontos	Detalhes
API integrada responde no formato correto	1	docker run + curl POST /predict funcional
Performance da Rede Neural (F1-Score Macro)	1	Veja escala progressiva calibrada abaixo
Relatório Técnico no README.md completo	2	Tabela comparativa baseline vs. rede, matriz de confusão, discussão do abismo semântico

3.9.3 Escala Progressiva de Performance (F1-Score Macro)

Nível	F1-Score Macro	Pontuação	Critério de Engenharia
Mínimo	\(\ge 35\%\)	0.3 pt	Supera o baseline ingênuo / classe majoritária
Bom	\(\ge 50\%\)	0.7 pt	Rede Keras regularizada (Dropout, limiar \(\tau\) calibrado)
Excelente	\(\ge 65\%\)	1.0 pt	Otimização avançada de hiperparâmetros ou análise exemplar de erro

[!NOTE] Por que a régua de F1-Macro é calibrada nesta faixa?
Lembre-se do Abismo Semântico (Semantic Gap): os enunciados usam metáforas narrativas (“Alice divide doces”) e a técnica algorítmica (DP, Guloso) é uma abstração matemática implícita. Um F1-Macro de 50–65% em 25 classes multi-label desbalanceadas é um resultado de engenharia sólido e realista. A profundidade da sua análise crítica no README.md tem peso decisivo na pontuação do grupo.

---

3.10 📅 Cronograma Sugerido (4 Semanas)

Para não acumular trabalho e perder a data de entrega, sugerimos o seguinte ritmo para a equipe:

Período	Foco da Equipe	Meta da Semana
Semana 1	Pesquisa e Setup	Leitura do artigo (Kim 2014), divisão de papéis, setup do repositório GitLab e script base de TF-IDF.
Semana 2	Modelagem	Treinamento do baseline (SVM/LR) e primeira versão da Rede Neural (Keras).
Semana 3	Engenharia MLOps	Otimização do F1-Score, criação da API em FastAPI e criação do Dockerfile.
Semana 4	Qualidade e README	Escrita dos testes pytest, validação final, preenchimento do relatório no README.md e Merge Request final.

---

3.11 ✅ Checklist de Entrega — TP1

• Repositório GitLab com branches individuais (feat/aluno-a-*, feat/aluno-b-*, etc.)
• README.md na raiz com tabela de autoria (nome, papel, @username)
• docker build e docker run funcionais (sem erros)
• POST /predict retorna JSON no formato especificado
• 6 testes pytest passando (ver seção de Testes Obrigatórios)
• F1-Score macro ≥ 35% no dataset de teste do professor
• Relatório Técnico no README.md contendo:
  • Trabalhos Relacionados (citando Kim 2014 e CodeBERT)
  • Tabela comparativa: baseline (TF-IDF + SVM/LR) vs Rede Neural
  • Matriz de confusão / F1 por classe nas 25 skills
  • Curva de loss (treino vs validação)
  • Justificativa da formulação Multi-Label com Sigmoid
  • Discussão crítica sobre o Abismo Semântico nas classes conceituais

---

3.12 🔬 Adendo IC — Golden Benchmark e Estudo de Ablação Textual (Opcional)

Esta seção é exclusiva para equipes da Trilha de Iniciação Científica (IC). As equipes regulares podem ignorá-la. Se uma equipe IC desistir da trilha, o adendo já executado conta como +1 ponto bônus na nota regular do TP1.

Enquanto as equipes regulares treinam seus classificadores na divisão padrão, as equipes IC atuam como o Comitê Científico de Validação do ecossistema WOKDEX, conduzindo experimentos aprofundados que fundamentarão os artigos da disciplina.

3.12.1 O que fazer

1. Curadoria do Golden Benchmark Set (100 Problemas):
   • Selecionar e auditar minuciosamente uma amostra estratificada de 100 problemas do dataset leetcode_problems_pt.csv, cobrindo as 25 skills e os níveis Easy, Medium e Hard.
   • Verificar a fidelidade do enunciado em português e validar a consistência das skills anotadas.
   • Este conjunto será o teste cego do professor para avaliar as APIs de todas as equipes no Demoday.
2. Estudo de Ablação Textual (TF-IDF vs. Embeddings em Português):
   • Comparar o desempenho da Rede Neural sob diferentes representações vetoriais de texto em PT-BR:
     1. TF-IDF esparso (unigramas + bigramas).
     2. paraphrase-multilingual-MiniLM-L12-v2 (Sentence-Transformers).
     3. BERTimbau (neuralmind/bert-base-portuguese-cased).
     4. text-embedding-3-small (OpenAI).
   • Tabular o F1-Macro e a latência de inferência de cada abordagem.
3. Análise de Sensibilidade ao Desbalanceamento:
   • Testar o impacto de Class Weights e limiares de decisão dinâmicos (\(\tau_i\)) nas classes com menor suporte estatístico (ex: Backtracking com 87 amostras vs. Array com 1.626).

3.12.2 Entregáveis IC-TP1

• Arquivo golden_benchmark_100.csv catalogado e revisado.
• Draft 1 Estendido (3–4 páginas formato SBC) contendo a tabela comparativa de ablação vetorial e o estudo de desbalanceamento.

[!TIP] Os dados gerados neste adendo comporão diretamente a seção experimental do Artigo 1 da Disciplina (Classificação Semântica de Enunciados em Língua Portuguesa para Educação em Computação).

---

4 📚 TP2: O Oráculo RAG (Bancos Vetoriais & Spring AI)

4.1 Por que este TP existe?

No TP1, cada equipe treinou um preditor supervisionado que recebe o enunciado de um exercício e estima suas skills. Essa é uma fonte útil de recomendação, mas não é a única: também é possível recuperar exercícios semanticamente próximos e aproveitar as skills anotadas nesses vizinhos. O TP2 investiga, com uma infraestrutura única e avaliável, quando cada estratégia ajuda, falha ou discorda das demais.

O produto não é um sistema que promete ser superior em todos os cenários. É uma comparação empírica, honesta e reproduzível entre três recomendadores de skills para o WOKDEX:

1. Supervisionado (TP1): probabilidades multi-label produzidas pelo modelo do TP1.
2. Retrieval por embeddings: skills inferidas a partir dos exercícios recuperados por similaridade semântica.
3. Híbrido ajustado na validação: combinação dos dois escores, com pesos e limiares escolhidos sem consultar o conjunto de teste.

Cada equipe tem quatro estudantes, cerca de 15 horas por estudante, totalizando 60 horas de equipe. O prazo de entrega do TP2 é 19/10/2026. Datas, peso, escopo obrigatório e avaliação normativos constam do Plano de Ensino e Cronograma 2026-2; esta página descreve as evidências técnicas do projeto.

4.2 Start Pack e checkpoint técnico

Os marcos abaixo são de acompanhamento técnico e não têm nota própria:

Data	Marco	Expectativa
30/09/2026	Start Pack	Registrar papéis, corpus e proveniência, divisão inicial em splits.json, proposta de embedding-contract.json e plano do Golden Set.
05/10/2026	Checkpoint técnico não avaliativo	Apresentar a planilha de seleção do embedding, uma tabela inicial de benchmark/custo e o estado da recuperação ou seus impedimentos.

O prazo público de entrega continua sendo 19/10/2026. A governança de qualquer eventual alteração oficial de prazo está exclusivamente no Plano de Ensino e Cronograma.

DicaPergunta de pesquisa

RQ: Como os recomendadores supervisionado, baseado em recuperação e híbrido diferem na recomendação multi-label de skills para enunciados WOKDEX mantidos fora do índice?

H1: O recomendador supervisionado e o de recuperação apresentarão perfis de erro distintos, especialmente para skills frequentes e raras.

H2: Um híbrido ajustado somente na validação pode alterar o compromisso entre precisão e revocação em relação aos componentes isolados.

Estas são hipóteses a investigar, não garantias de superioridade. Resultados equivalentes, inferiores ou inconclusivos são resultados válidos se forem corretamente medidos e discutidos.

---

4.3 Corpus, proveniência e contrato de embeddings

O corpus oficial é o LeetCode Problems Dataset Bilíngue (PT-BR), disponibilizado em database/leetcode_problems_pt.json ou database/leetcode_problems_pt.csv. A documentação dos campos e do processo de curadoria está em database/README.md. Registrem no repositório a versão, URL/arquivo de origem, data de obtenção, número de registros lidos, número descartado e o SHA-256 do arquivo efetivamente usado. Não misturem dados externos sem documentar licença, origem e finalidade.

Os campos mínimos são id, title_pt, description_pt, difficulty e topics. topics é o conjunto de rótulos verdadeiros para avaliação; ele não pode ser enviado ao modelo supervisionado como entrada nem incluído no texto vetorizado. hints_pt pode ser usado apenas se a equipe declarar a decisão e aplicar o mesmo contrato em todos os subconjuntos.

4.3.1 Contrato de embedding

Antes de indexar, criem embedding-contract.json versionado. Ele deve registrar, no mínimo:

{
  "contract_version": "1.0",
  "model_id": "nome-e-versao-exata-do-modelo",
  "dimensions": 384,
  "distance": "cosine",
  "normalization": "L2",
  "language": "pt-BR",
  "input_template": "{title_pt}\n\n{description_pt}",
  "chunking": {"strategy": "one-document-per-problem", "max_chunks_per_problem": 1},
  "corpus_sha256": "..."
}

O modelo de embedding pode ser local ou hospedado, desde que sua versão, dimensionalidade, normalização, custo/limitação de execução e licença sejam declarados. O contrato existe para impedir comparações entre vetores incompatíveis e para permitir reindexação. Título, descrição, limpeza de HTML/Markdown e qualquer truncamento precisam ser aplicados de forma determinística e descritos no README.

[!IMPORTANT] Para evitar vazamento de rótulos, topics, dificuldade e taxa de aceitação não entram no texto do embedding nem no escore de similaridade. Eles podem aparecer apenas como metadados de resposta e, no caso de topics, como anotação dos vizinhos para derivar recomendações após a recuperação.

---

4.4 Metodologia honesta e sem vazamento

1. Fixem uma semente e dividam os IDs de problemas antes de qualquer indexação em treino, validação e teste. Recomendação: 70%/15%/15%, com estratificação multi-label quando viável. Publiquem splits.json com os IDs e a semente.
2. Treinem ou reutilizem o artefato congelado do TP1 apenas com treino. Se o TP1 tiver usado outra divisão, reexecutem a avaliação com esta divisão ou documentem claramente a limitação; não reportem resultado como teste comparável sem isso.
3. Construam o índice de retrieval somente com documentos de treino. Os textos de validação e teste são consultas, nunca documentos recuperáveis. Uma consulta não pode recuperar a si mesma, uma duplicata identificada, nem um item do mesmo grupo de duplicatas quando esse agrupamento estiver disponível.
4. Usem validação para escolher K, a regra de agregação dos vizinhos, limiares por skill e o peso do híbrido. Fixem esses valores antes de abrir os rótulos do teste.
5. Executem uma única avaliação final no teste. Não alterem parâmetros após examiná-la; correções de defeito exigem novo registro de experimento e justificativa.

Para a recomendação por retrieval, uma regra simples e auditável é somar, para cada skill \(s\), as similaridades normalizadas dos \(K\) vizinhos de treino que possuem \(s\). Para o híbrido, combinem escores comparáveis, por exemplo:

\[ score_{hibrido}(s \mid q) = \alpha\,p_{TP1}(s \mid q) + (1-\alpha)\,score_{retrieval}(s \mid q), \]

com \(\alpha\), normalização e limiar definidos na validação. Outras regras são aceitas se forem especificadas, implementadas e testadas. Não é permitido escolher manualmente a melhor estratégia para cada consulta de teste.

---

4.5 API de recuperação e contrato de recomendação

O serviço pode ser implementado em Java/Spring Boot, Python/FastAPI ou outra stack HTTP documentada. A avaliação valoriza o contrato e a reprodutibilidade, não uma biblioteca específica. O ambiente deve subir com Docker Compose.

4.5.1 GET /search

Exemplo: GET /search?q=inverter+lista+encadeada&k=3

Parâmetros obrigatórios: q não vazio e k inteiro entre 1 e 20. A resposta deve informar o contrato e os vizinhos usados:

{
  "query": "inverter lista encadeada",
  "k": 3,
  "embedding_contract_version": "1.0",
  "index_split": "train",
  "results": [
    {
      "exercise_id": 206,
      "title_pt": "Inverter Lista Encadeada",
      "similarity_score": 0.94,
      "difficulty": "Easy",
      "skills": ["Linked List", "Recursion"],
      "snippet": "Dada a cabeça de uma lista encadeada..."
    }
  ],
  "search_time_ms": 42
}

similarity_score deve ter semântica documentada (por exemplo, cosseno) e os resultados devem vir em ordem não crescente de similaridade. Retornem 400 para parâmetros inválidos e uma resposta JSON de erro com code e message.

4.5.2 Recomendação de skills

Implementem POST /skills/recommend ou forneçam o campo equivalente na resposta de /search. A equipe deve publicar um único contrato, com recomendação dos três métodos e evidência de proveniência. Exemplo para POST /skills/recommend:

{
  "query": "encontre o menor caminho em um grafo sem pesos",
  "k": 5,
  "methods": {
    "supervised_tp1": {
      "skills": [{"name": "Breadth-First Search", "score": 0.81}]
    },
    "retrieval": {
      "skills": [{"name": "Breadth-First Search", "score": 0.76, "supporting_ids": [127, 433]}]
    },
    "hybrid": {
      "alpha": 0.60,
      "threshold": 0.50,
      "skills": [{"name": "Breadth-First Search", "score": 0.79}]
    }
  }
}

O endpoint não precisa expor os rótulos verdadeiros da consulta. supporting_ids torna explícito quais documentos indexados sustentam uma recomendação por retrieval.

---

4.6 Golden Set e avaliação multi-label

Criem e versionem evaluation/golden-set.yaml com pelo menos 15 consultas, todas derivadas de itens do conjunto de teste, mas sem expor os rótulos ao serviço. Cada entrada deve conter query_id, texto da consulta, source_exercise_id, expected_skills, e uma breve justificativa de anotação. O Golden Set deve cobrir ao menos cinco famílias de skills, consultas com uma e com múltiplas skills, e casos potencialmente ambíguos. Ele é um recorte legível para auditoria humana; as métricas principais devem ser calculadas também sobre todo o teste.

Para cada um dos três métodos, reportem no README e em arquivo tabular versionado:

Métrica	Como reportar
Precision@K	Média da proporção de skills relevantes nas primeiras \(K\) recomendações, para pelo menos K=1, 3, 5 quando aplicável.
Recall@K	Média da fração das skills verdadeiras presente nas primeiras \(K\) recomendações.
F1 micro	Calculado sobre todas as decisões rótulo-consulta.
F1 macro	Média do F1 por skill, incluindo a política para classes sem suporte.
Exact match	Fração de consultas cujo conjunto previsto é exatamente o conjunto verdadeiro.

Definam como desempates, skills fora do vocabulário e consultas sem recomendação são tratados. Reportem suporte por skill para tornar o F1 macro interpretável. Latência e tamanho do índice são métricas operacionais recomendadas, mas não substituem as métricas de qualidade acima.

4.6.1 Análise de discordância

Selecionem pelo menos cinco consultas em que dois métodos discordam e classifiquem cada caso como acerto exclusivo, erro compartilhado, diferença de granularidade, ambiguidade de anotação, similaridade superficial ou outro motivo justificado. Mostrem consulta, rótulos esperados, previsões, vizinhos relevantes e interpretação. Discordância não é defeito por si só: ela é evidência para responder à pergunta de pesquisa.

---

4.7 Entregáveis de engenharia

O repositório deve conter:

• docker-compose.yml e instruções para subir serviço, dependências e carga inicial sem segredo versionado;
• código de ingestão, índice persistente ou procedimento reprodutível de construção, contrato de embeddings e manifesto de proveniência;
• API GET /search e contrato de recomendação de skills;
• testes unitários e de integração para validação de entrada, ordenação/forma de /search, exclusão de documentos fora do treino, agregação de skills e cálculo de métricas;
• pipeline de CI que execute testes e, quando o ambiente permitir, valide build/Compose sem depender de credenciais privadas;
• README.md com arquitetura, como executar, papéis, decisões experimentais, limitações, tabela das métricas, análise de discordância e links para os artefatos;
• evaluation/golden-set.yaml, splits.json, resultados reproduzíveis e script/comando que os gere.

Uma demonstração manual não substitui testes. Um serviço que exija chave privada deve disponibilizar modo local, fixture determinística ou instruções claras para que a suíte básica possa ser executada sem a chave.

---

4.8 Papéis e entregas individuais

Os papéis organizam o trabalho, mas toda pessoa deve revisar uma contribuição de colega e contribuir com commits identificáveis. Ajustes de divisão são possíveis se forem declarados no README e preservarem carga e responsabilidade comparáveis.

Papel	Estimativa	Entregas verificáveis
Pessoa A – Dados e protocolo experimental	~15h	Proveniência, limpeza determinística, splits.json, Golden Set, verificação anti-vazamento e script de avaliação.
Pessoa B – Retrieval e índice vetorial	~15h	Contrato de embeddings, ingestão/indexação apenas do treino, busca KNN, GET /search e testes de recuperação.
Pessoa C – Integração TP1 e recomendador híbrido	~15h	Adaptador do artefato/API congelado do TP1, recomendador por vizinhos, ajuste na validação, endpoint/contrato de skills e testes.
Pessoa D – Qualidade, reprodução e comunicação científica	~15h	Docker Compose, CI, testes de integração, README de execução, tabelas/gráficos e consolidação das seções SBC.

---

4.9 Artigo SBC incremental

Escrevam agora, no repositório, artigo/ ou docs/artigo/ com as seções abaixo em Markdown ou LaTeX. Elas serão insumo para a versão consolidada posterior, mas já precisam refletir o experimento real deste TP:

1. Introdução e RQ: problema, objetivo comparativo, pergunta e hipóteses sem alegação antecipada de ganho.
2. Trabalhos relacionados: ao menos duas fontes sobre recuperação densa, recomendação baseada em vizinhos ou classificação multi-label, com relação explícita ao projeto.
3. Método: corpus e proveniência, divisão, contrato de embeddings, três recomendadores, tuning e salvaguardas anti-vazamento.
4. Protocolo de avaliação: Golden Set, métricas, ambiente e política de reprodutibilidade.
5. Resultados e discussão inicial: tabela dos três métodos, discordâncias, ameaças à validade e limitações. Não preencham resultados inexistentes; usem pendente até executar o experimento.

---

4.10 Roteiro de desenvolvimento

Período	Marco	Evidência
Etapa	Marco	Evidência
:—	:—	:—
1	Start Pack: protocolo, papéis, corpus e divisão	splits.json, proveniência, plano do Golden Set e esqueleto do artigo.
2	Checkpoint: contrato e retrieval mínimo	embedding-contract.json, planilha de seleção do embedding, tabela de benchmark/custo, índice de treino e /search testado.
3	Três recomendadores	Adaptador TP1, agregação dos vizinhos e híbrido com tuning somente na validação.
4	Avaliação	Golden Set com >=15 consultas, métricas completas e análise de discordância.
5	Qualidade e entrega	Docker, CI, testes de integração, README, seções SBC e resultados versionados.

---

4.11 Rubrica (10,0 pontos)

Critério	Pontos	Evidência
Protocolo, corpus, proveniência e proteção contra vazamento	1,5	Divisão versionada, contrato, índice só de treino e justificativas.
Retrieval e API	1,5	GET /search, índice funcional, erros tratados e contrato cumprido.
Três recomendadores e tuning válido	2,0	TP1, retrieval e híbrido reproduzíveis; parâmetros escolhidos na validação.
Golden Set, métricas e análise de discordância	2,0	>=15 consultas, todas as métricas requeridas e cinco discordâncias analisadas.
Engenharia reprodutível	1,5	Docker, testes, CI, README e execução documentada.
Contribuições individuais e seções SBC incrementais	1,5	Papéis verificáveis, revisão entre pares, commits e texto científico consistente.
Total	10,0

---

4.12 Desafios avançados opcionais

Estes desafios não são pré-requisitos nem exigem agentes ou LLMs. Podem enriquecer a discussão, sem substituir os entregáveis obrigatórios:

• comparar dois modelos de embedding sob o mesmo protocolo e orçamento declarado;
• testar busca híbrida léxica+densa, com pesos escolhidos na validação;
• medir estabilidade por diferentes sementes de divisão ou bootstrap com intervalos de confiança;
• criar uma interface simples para inspecionar consulta, vizinhos e origem de cada skill recomendada;
• avaliar efeito de remover título, exemplos ou restrições do texto de consulta.

4.13 Checklist de entrega

• Repositório GitLab com autoria, papéis e revisão entre pares documentados.
• Corpus, SHA-256, divisão e contrato de embedding versionados.
• Índice contém somente documentos de treino; validação e teste são apenas consultas.
• GET /search e o contrato de recomendação de skills implementados e testados.
• Comparação supervisionado, retrieval e híbrido, sem tuning no teste.
• Golden Set com >=15 consultas e resultados completos no teste.
• Precision@K, Recall@K, F1 micro, F1 macro e exact match para os três métodos.
• Cinco ou mais discordâncias analisadas.
• Docker, testes, CI e README reproduzíveis.
• Seções incrementais do artigo SBC escritas agora.

NotaDocumentação complementar

A visão geral da oferta e as relações entre os três trabalhos foram atualizadas em index.qmd e no editorial docente. Manuais de pesquisa e a trilha IC podem preservar propostas históricas de agentes e YAML; eles não alteram os requisitos deste enunciado.

---

5 🤖 TP3: O Agente Autônomo WOKDEX & Demoday

5.1 Proposito e escopo

O TP3 consolida o que a equipe construiu no TP1 e no TP2. Em vez de criar um novo sistema isolado, a equipe deve integrar os contratos dos dois servicos e entregar um assistente RAG fundamentado: para uma pergunta ou enunciado de programacao, o sistema apresenta a classificacao de skills, recupera evidencias do corpus e produz uma resposta rastreavel, com citacoes e possibilidade explicita de abstencao.

O produto central nao e um agente autonomo. Nao sao requisitos do TP3: LangChain, LlamaIndex, tool calling, cadeia de raciocinio, auto-correcao, geracao de YAML ou loop autonomo. Uma LLM pode ser usada apenas na etapa de geracao da resposta RAG, desde que a resposta seja fundamentada exclusivamente nas evidencias recuperadas e que seu uso seja mensurado. A implementacao pode ser inteiramente deterministica quando a equipe justificar a decisao.

Esforco planejado: 60 horas por equipe, aproximadamente 15 horas por estudante.

Equipe: 4 estudantes.

Prazo de entrega: 26/11/2026. Apresentação: 30/11 e 02/12/2026.

Datas, peso, escopo obrigatório e avaliação normativos constam do Plano de Ensino e Cronograma 2026-2; esta página descreve as evidências técnicas do projeto.

5.2 Objetivos de aprendizagem

Ao concluir o TP3, a equipe devera demonstrar que consegue:

1. Integrar sistemas independentes por contratos HTTP/documentados, sem acoplamento ao codigo interno do TP1 ou TP2.
2. Explicar, com exemplos e limites, quando usar classificacao, recuperacao e uma arquitetura hibrida.
3. Construir uma resposta RAG cujas afirmacoes sejam apoiadas por fontes recuperadas identificaveis.
4. Projetar uma abstencao segura para entradas ambiguas, sem evidencia suficiente ou fora do dominio.
5. Avaliar o sistema com casos definidos antes da demonstracao e analisar falhas de integracao.
6. Consolidar em artigo SBC o material, as metricas e as decisoes dos TPs 1 e 2.

5.3 Produto a entregar

Entreguem um repositorio executavel e um dossie tecnico-cientifico. A interface pode ser uma CLI ou uma UI web simples; escolha uma e documente como executa-la. A demonstracao deve aceitar uma entrada textual e apresentar, no minimo:

1. A classificacao de skills fornecida pelo contrato do TP1, com escore ou indicacao de confianca quando disponivel.
2. Os documentos ou exercicios recuperados pelo TP2, com identificador, titulo e escore/ranking quando disponivel.
3. Uma resposta ao usuario que diferencie claramente fato recuperado, inferencia e recomendacao.
4. Citacoes na propria resposta, por exemplo [E1] e [E2], que apontem para os itens recuperados exibidos pela interface.
5. A decisao de responder ou abster-se e sua justificativa objetiva.
6. Um identificador de requisicao e os eventos minimos de observabilidade descritos adiante.
7. Um diagrama de fluxo de dados, em Mermaid textual ou formato equivalente, mostrando entrada, TP1, TP2, integrador, evidencias/citacoes, resposta e destinos de logs ou dados persistidos.

O assistente deve tratar perguntas sobre exercicios, skills e estrategias de resolucao presentes no escopo do corpus. Ele nao deve apresentar uma resposta inventada como se fosse evidenciada. Quando a base nao sustentar a resposta, deve declarar a limitacao, indicar a ausencia de evidencia e, se pertinente, pedir esclarecimento.

5.4 Integracao por contratos

Antes de integrar, a equipe deve registrar no README.md ou no dossie uma tabela de contratos. Ela deve conter endpoint, metodo, entrada, saida, codigos de erro, timeout e responsavel pelo contrato. Adaptem os nomes reais definidos pela equipe no TP1 e TP2; nao e permitido presumir uma biblioteca especifica.

Componente	Responsabilidade minima	Evidencia exigida
TP1	Receber texto e retornar skills previstas	Exemplo de requisicao/resposta e teste de contrato
TP2	Receber consulta e retornar itens recuperados	Exemplo de requisicao/resposta e teste de contrato
Integrador TP3	Compor as respostas e aplicar a politica de evidencia/abstencao	Fluxo executavel, logs e testes de integracao

O integrador deve usar configuracao externa para URLs e timeouts. Durante o desenvolvimento, mocks que respeitem o contrato sao permitidos; a entrega deve incluir ao menos uma execucao com as implementacoes reais da equipe ou uma justificativa objetiva para indisponibilidade temporaria.

5.5 Governanca de dados e provedor

Documentem uma decisao de dados e provedor no README ou dossie. Ela deve declarar se ha PII nos textos de entrada, logs ou corpus; como a equipe a evita, minimiza ou anonimiza; o prazo e local de retencao; e se cada componente e local ou hospedado. Para cada provedor hospedado, registrem finalidade, dados enviados, configuracao relevante, custo/limite conhecido e alternativa de mock ou execucao local. Nao enviem PII, segredos ou logs completos a provedores sem uma decisao documentada e justificavel.

5.5.1 Testes de contrato e falhas

Implementem testes automatizados para, no minimo, os seguintes casos:

Falha ou contrato	Comportamento esperado
Resposta valida do TP1	Skills sao interpretadas sem alterar seu significado
Resposta valida do TP2	Evidencias citadas correspondem aos itens retornados
Campo obrigatorio ausente ou tipo invalido	Falha clara, sem resposta aparentemente confiavel
Timeout ou indisponibilidade de um servico	Mensagem degradada; nao inventar resultado do componente ausente
Lista vazia de recuperacao	Abstencao ou pedido de refinamento, com registro no log

Documentem ao menos dois defeitos reais encontrados na integracao, sua causa, como foram reproduzidos e a correcao ou limitacao remanescente.

5.6 Classificador, recuperacao e arquitetura hibrida

O dossie e o artigo devem comparar as tres estrategias, usando o proprio sistema e nao apenas definicoes teoricas.

Estrategia	Entrada e saida	Vantagem	Limitacao a investigar
Classificador (TP1)	Enunciado para skills	Baixa latencia e rotulos consistentes	Pode errar classes proximas ou desconhecidas
Recuperacao (TP2)	Consulta para itens semelhantes	Traz evidencias observaveis do corpus	Similaridade nao garante relevancia pedagogica
Hibrida (TP3)	Skills + recuperacao para resposta fundamentada	Combina sinal preditivo e evidencia	Exige contratos, politica de citacao e controle de falhas

Na arquitetura hibrida, explicitem a regra de composicao. Por exemplo: as skills do TP1 podem orientar a consulta do TP2, mas uma recomendacao especifica so pode aparecer se houver evidencia recuperada que a apoie. A equipe deve declarar o valor de k, o limiar ou criterio de qualidade usado e como esses parametros foram escolhidos.

5.7 Resposta RAG fundamentada

Uma resposta e considerada fundamentada quando cada afirmacao relevante pode ser ligada a uma ou mais evidencias recuperadas. Para cada resposta avaliada, guardem:

Item	Registro necessario
Entrada	Pergunta/enunciado exatamente como recebido
Predicao	Skills e confianca, quando existir
Recuperacao	IDs, titulos, ranking/escores e trecho utilizado
Resposta	Texto mostrado ao usuario com marcadores de citacao
Decisao	RESPONDER, ABSTER ou PEDIR_ESCLARECIMENTO
Justificativa	Regra, limiar ou ausencia de evidencia que motivou a decisao

Se houver componente gerativo, o prompt ou a instrucao deve exigir que ele use somente os trechos recuperados e cite os identificadores recebidos. A equipe deve verificar programaticamente que toda citacao exibida referencia uma evidencia da requisicao corrente. Nao exibam raciocinio interno do modelo; registrem apenas entradas, saidas, parametros relevantes e evidencias.

5.7.1 Politica de abstencao

Definam uma politica simples, reproduzivel e testavel. Ela pode combinar, por exemplo, pontuacao baixa de recuperacao, divergencia entre skills e evidencias, consulta curta/ambigua, ou ausencia de resultados. A politica deve produzir uma mensagem util, como: “Nao encontrei evidencia suficiente no corpus para recomendar uma estrategia. Informe as restricoes, o formato de entrada e um exemplo.”

Abstencao correta vale mais que uma resposta confiante sem suporte.

5.7.2 Rubrica de fundamentacao por resposta

Avaliem cada resposta dos seis casos nesta rubrica e incluam o resultado na tabela de casos:

Nivel	Criterio
fundamentada	Todas as afirmacoes relevantes possuem citacao valida para evidencia retornada na requisicao; limites e recomendacoes sao explicitados.
parcial	A resposta tem evidencias validas, mas ao menos uma afirmacao relevante, inferencia ou recomendacao carece de suporte suficiente ou de delimitacao.
nao fundamentada	Ha afirmacao relevante sem suporte, citacao invalida/ausente ou resposta apresentada como evidenciada sem que a recuperacao a sustente.
abstencao adequada	O sistema nao responde de modo afirmativo quando falta evidencia e explica objetivamente a limitacao ou o esclarecimento necessario.

5.8 Observabilidade

Cada requisicao deve gerar logs estruturados ou registros equivalentes que permitam reconstruir o fluxo. Nao registrem chaves, tokens, dados sensiveis ou texto de raciocinio interno de LLMs.

Registrem ao menos: request_id, horario, rota/acao, versao dos servicos, latencia do TP1, latencia do TP2, numero de itens recuperados, decisao final, codigos de erro e identificadores das evidencias citadas. Incluam no dossie uma amostra legivel de dois fluxos: uma resposta fundamentada e uma abstencao/degradacao.

5.9 Avaliacao experimental: seis casos obrigatorios

Construam uma colecao fixa de seis casos antes da rodada final. Cada caso deve ter entrada, expectativa, criterio de julgamento e resultado observado. Pelo menos um membro que nao implementou diretamente aquele modulo deve revisar cada expectativa.

Caso	Tipo	Expectativa minima
1	No dominio, direto	Skills e evidencias coerentes; resposta com citacoes validas
2	No dominio, estrategia distinta	Comparacao entre classificador, recuperacao e hibrido
3	Consulta com vocabulário diferente/parafrase	Recuperacao ou abstencao explicada; sem citacao falsa
4	Ambiguo	Pedido de esclarecimento ou resposta condicionada e citada
5	Fora do dominio	Abstencao clara, sem inventar fontes ou skills
6	Falha controlada de contrato/servico	Degradacao segura, log e mensagem compreensivel

Para os seis casos, apresentem uma tabela com saida do classificador, evidencias recuperadas, decisao final, nivel da rubrica de fundamentacao, latencia e julgamento humano breve (adequado, parcial, inadequado). A analise deve explicar pelo menos uma situacao em que a arquitetura hibrida nao foi melhor que um componente isolado.

5.10 Artigo SBC incremental

Completem o artigo no formato SBC, com 4 a 6 paginas (sem contar referencias e apendices, se o modelo adotado os separar). O texto deve evoluir os materiais iniciados nos TPs 1 e 2: nao recomecem a narrativa nem descartem metricas ja produzidas.

Estrutura minima:

1. Introducao e problema pedagogico.
2. Fundamentacao e trabalhos relacionados, incluindo classificacao e RAG.
3. Metodo: contratos TP1/TP2, arquitetura hibrida e politica de abstencao.
4. Avaliacao: protocolo dos seis casos, metricas herdadas do TP1/TP2 e resultados do TP3.
5. Discussao: classificacao versus recuperacao versus hibrido, falhas, custo/latencia e ameacas a validade.
6. Conclusao e proximo passo justificavel.

O artigo deve conter pelo menos um diagrama de arquitetura, uma tabela comparativa das tres estrategias e a tabela resumida dos seis casos. Citem as fontes efetivamente usadas; a leitura recomendada do TP2, Lewis et al. (2020), e um ponto de partida apropriado para contextualizar RAG.

5.11 Papeis e estimativa de esforco

Cada estudante assume um papel principal de aproximadamente 15 horas, sem impedir revisao cruzada e pareamento. Registrem autoria, tarefas e evidencias no README.md.

Papel	Responsabilidades principais	Evidencia individual
Integrador de contratos	Clientes TP1/TP2, configuracao, mocks e testes de contrato	MR/commits e testes executaveis
Responsavel por recuperacao e evidencia	Consulta hibrida, formatacao de fontes, verificacao de citacoes	Casos com trilha de evidencia
Responsavel por experiencia e abstencao	CLI/UI, mensagens de degradacao, politica de abstencao	Fluxos demonstraveis e testes de decisao
Responsavel por avaliacao e artigo	Protocolo de seis casos, observabilidade, tabelas e consolidacao SBC	Resultados reproduziveis e secao do artigo

5.12 Sequência de desenvolvimento

Organizem contratos, integração, avaliação, síntese e ensaio de modo a cumprir o prazo normativo do TP3. As apresentações e defesa técnica ocorrem em 30/11 e 02/12/2026.

Até 16/11/2026, entreguem um alerta técnico de risco não avaliativo: contratos e mocks verificados, um caso fundamentado e um caso de abstenção executados, e um risco registrado com responsável e próximo passo. O alerta antecipa bloqueios de integração; não é uma nova aula nem substitui a entrega final.

5.13 Apresentações em 30/11 e 02/12

Apresentem em ate 6 minutos, com participacao de todos os integrantes:

1. Problema, contratos e arquitetura hibrida (1 minuto).
2. Demo da CLI/UI em um caso no dominio, mostrando evidencias e citacoes (2 minutos).
3. Demo de abstencao, ambiguidade ou falha degradada (1 minuto).
4. Resultados dos seis casos e comparacao das tres estrategias (1 minuto).
5. Uma falha real, sua correcao e uma limitacao remanescente (1 minuto).

Preparem uma captura de tela ou video curto como contingencia. O material de contingencia nao substitui a defesa tecnica nem os testes no repositorio.

5.14 Rubrica (20 pontos)

Criterio	Pontos	Evidencia de avaliacao
Integracao dos contratos TP1 e TP2	3,0	Clientes configuraveis, execucao integrada e testes de contrato
Resposta RAG com evidencia e citacoes validas	3,5	Trilha de evidencia, rubrica de fundamentacao por resposta e verificacao de citacoes por requisicao
Politica de abstencao e tratamento seguro de degradacao	2,0	Casos ambiguo, fora do dominio e falha controlada
CLI/UI e observabilidade	2,0	Fluxo utilizavel, logs/rastreabilidade e mensagens claras
Avaliacao dos seis casos e analise critica	3,0	Protocolo, resultados, comparacao e limites identificados
Falhas reais e testes de contrato/integracao	2,0	Dois defeitos documentados e suite automatizada relevante
Artigo SBC incremental TP1-TP2-TP3	2,5	Estrutura, evidencias, metricas e discussao cientifica
Apresentacao e defesa tecnica	1,0	Clareza, participacao e demonstracao consistente
Contribuicao individual comprovavel	1,0	Papel, commits/MRs, revisao e evidencia de autoria
Total	20,0

5.15 Checklist de entrega final

• Repositorio com instrucoes de execucao, configuracao e autoria dos quatro papeis.
• CLI ou UI funcional com classificacao, recuperacao, resposta citada e abstencao.
• Diagrama de fluxo de dados e decisao de PII, retencao e provedor documentados.
• Tabela de contratos TP1/TP2 e testes automatizados de contrato/integracao.
• Logs ou registros de observabilidade sem segredos.
• Seis casos avaliados, incluindo ambiguo, fora do dominio e falha controlada.
• Dois defeitos de integracao documentados com causa e resolucao/limitacao.
• Artigo SBC incremental completo, com diagrama e tabelas exigidas.
• Slides ou roteiro da apresentacao e material de contingencia.
• Desafios opcionais, se realizados, claramente separados do nucleo avaliado.

5.16 Desafios avancados opcionais

Equipes que desejarem explorar LLMs, tool calling ou agentes podem seguir a TP3.5: Trilha Avancada Opcional. Essa trilha nao substitui nenhum item desta rubrica, nao e pre-requisito para a nota e deve permanecer isolada do caminho principal de execucao.

---

6 🔬 Programa IC Especial: Equipes de Pesquisa WOKDEX

6.1 O que é o Programa IC Especial?

A disciplina oferece uma trilha opcional de Iniciação Científica para equipes que demonstrem interesse e condições de conduzir uma investigação experimental curta. Em 2026-2, a proposta é auditar os artefatos que a própria turma produz no TP2 e no TP3: retrieval, proveniência, contratos, evidências, citações, abstinção e reprodução.

ImportanteRegra de avaliação

O TP3 Master substitui o TP3 regular somente para equipes explicitamente aceitas na Trilha IC pelo professor. Para elas, a entrega vale os mesmos 20 pontos, tem prazo em 26/11 e apresentação em 30/11 e 02/12. Não há acúmulo de TP3 regular e Master. Todas as demais equipes seguem o TP3 regular.

A seleção ocorre após o TP1 e a substituição precisa ser confirmada antes do início do TP3. A participação na IC é voluntária; quem não aceitar o convite, ou não for formalmente aceito, segue o percurso regular sem penalidade.

6.2 Objetivo científico

A investigação pergunta se as respostas RAG integradas no TP3 são sustentadas pelas evidências recuperadas no TP2, se citam corretamente suas fontes, se se abstêm quando não há suporte e se outra pessoa consegue reproduzir os resultados a partir dos artefatos versionados.

O trabalho não tenta criar agentes ou gerar metadata.yaml. Em 2026-2, o TP3 regular é um assistente RAG fundamentado, e os dados da auditoria são seus contratos, logs, casos de avaliação, citações e artefatos de retrieval. Agentes, LLMs com tool calling e orquestração pertencem à TP3.5, que é opcional, isolada e nunca fonte de dados obrigatória para a IC.

6.3 Quem pode participar?

6.3.1 Critérios de seleção

Critério	Como é observado
Trabalho consistente no TP1	Métricas, organização e correção do experimento
Contribuições identificáveis	Commits/MRs, revisão de colega e responsabilidade assumida
Qualidade de engenharia	Testes, documentação, controle de versão e comunicação de limites
Interesse em pesquisa	Formulário e conversa breve com o professor
Disponibilidade	Cerca de 15 horas por estudante no TP3, sem promessa de trabalho extra ilimitado

O professor pode aceitar uma ou mais equipes de quatro estudantes conforme a capacidade de mentoria e a disponibilidade de artefatos. A aceitação será documentada no repositório/canal da disciplina.

6.4 Método e entregáveis IC

As equipes aceitas seguem o método fixo do TP3 Master:

1. Inventariar e congelar os artefatos do TP2 até 19/10: corpus, hashes, splits.json, contrato de embeddings, Golden Set, resultados e comandos.
2. Definir antes da rodada final ao menos 12 casos: os seis casos exigidos no TP3 e seis derivados do Golden Set ou das discordâncias do TP2.
3. Auditar, por caso, o suporte das evidências, a validade das citações e a decisão de responder, abster-se ou pedir esclarecimento.
4. Reexecutar a auditoria com uma pessoa diferente da autora principal em ambiente limpo ou perfil separado.
5. Consolidar resultados, divergências, limitações e um artigo curto SBC de 3-4 páginas.

Os entregáveis detalhados, papéis, rubrica e checklist estão no TP3 Master. Dados de terceiros só podem ser usados com origem, permissão/licença e anonimização documentadas. Não versionem segredos, dados pessoais ou raciocínio interno de modelos.

6.5 Papéis realistas para uma equipe de quatro

Papel	Foco
Pessoa A - Protocolo e dados	Proveniência, inventário, hashes, anonimização e casos
Pessoa B - Evidência e citações	Vínculo entre retrieval, trechos, IDs e citações RAG
Pessoa C - Abstenção e integração	Decisões, falhas de contrato, degradação segura e logs
Pessoa D - Reprodução e artigo	Ambiente, scripts, segunda execução, tabelas e texto SBC

Toda pessoa revisa uma entrega de colega e mantém autoria verificável. Os papéis podem ser ajustados quando documentados no README, desde que preservem responsabilidades comparáveis.

6.6 Cronograma 2026-2

Marco	Data/período	Resultado esperado
Seleção e confirmação IC	Após TP1, antes do TP3	Equipe aceita e escopo de substituição confirmado
Fechamento dos artefatos TP2	Até 19/10	Inventário, protocolo e casos candidatos preparados
Congelamento e piloto	20/10-10/11	Contratos, hashes, dois casos auditados e política de abstinção verificável
Alerta técnico de risco (não avaliativo)	16/11	Contratos e mocks verificados, um caso fundamentado, um caso de abstenção e risco com responsável
Auditoria e reprodução	11/11-25/11	12+ casos, revisão cruzada, segunda execução e tabelas
Entrega TP3 Master	26/11	Repositório e artigo SBC de 3-4 páginas
Apresentação	30/11 e 02/12	Defesa dos resultados, limitações e recomendação

6.7 Mentoria e resultados esperados

• Reunião curta semanal, em horário combinado, para revisar protocolo, impedimentos e qualidade dos artefatos.
• Revisão de código/documentação por meio de MRs ou mecanismo equivalente.
• Resultados podem ser positivos, negativos ou inconclusivos; a qualidade do método e a transparência dos limites são o critério central.
• Uma evolução para projeto de IC, relatório técnico ou artigo posterior depende dos resultados, disponibilidade e avaliação do professor. Coautoria não é garantida pela participação na disciplina.

6.8 Riscos e mitigação

Risco	Mitigação
Serviço TP1/TP2 indisponível	Usar mock explicitamente identificado para testar contrato, sem confundi-lo com execução real
Artefato sem versão ou hash	Registrar a lacuna como achado; não reconstruir silenciosamente o experimento
Poucos dados de outras equipes	Priorizar os artefatos da própria equipe e dados autorizados; não depender de coleta ampla
Resultado sem melhora aparente	Reportar falhas, abstinções inadequadas e limites como evidência válida
Experimento com agentes	Mantê-lo em TP3.5, separado da auditoria e da nota-base

---

7 🧬 TP3 Master: Simulated Students (Plano 2 da Pesquisa)

7.1 Natureza e elegibilidade

Esta é uma alternativa de pesquisa ao TP3 regular, destinada somente a equipes da Trilha IC explicitamente aceitas pelo professor. Para essas equipes, o TP3 Master substitui o TP3 regular, vale os mesmos 20 pontos e mantém as apresentações em 30/11 e 02/12. Equipes não aceitas na Trilha IC devem realizar integralmente o TP3 regular.

O TP3 Master não cria uma obrigação extra e não acumula duas notas de TP3. A aceitação será confirmada pelo professor após o TP1, com confirmação do escopo e da equipe antes do início do TP3. Caso uma equipe IC não seja formalmente aceita para esta substituição, permanece no TP3 regular.

ImportanteEscopo revisado de 2026-2

O TP3 regular não exige agentes, LangChain, LangGraph, tool calling, geração de YAML ou qualquer sistema multiagente. Este TP3 Master também não usa YAMLs ou agentes como fonte de dados. Seus objetos de estudo são os artefatos reais do TP2 (índice, contrato de embedding, splits.json, Golden Set, resultados e proveniência) e do TP3 (contratos, evidências recuperadas, citações, decisões de abstinção, logs e seis casos avaliados).

Agentes pertencem exclusivamente à TP3.5, trilha opcional e experimental. Se uma equipe a explorar, seus resultados devem ficar separados e não podem ser a fonte dos dados nem condição para a auditoria.

7.2 Pergunta de pesquisa

RQ: Em casos de avaliação previamente definidos ou coletados sob protocolo, as respostas RAG do TP3 apresentam evidência rastreável, citações válidas, abstinção apropriada e resultados reproduzíveis a partir dos artefatos do TP2?

O objetivo não é provar que uma estratégia é sempre melhor. A equipe deve identificar evidências suficientes, falhas de suporte, decisões de abstinção adequadas ou inadequadas e lacunas que impeçam a reprodução. Resultado negativo ou inconclusivo é válido quando o protocolo, os dados e as limitações estiverem claros.

7.3 Dados, contratos e cuidados éticos

Usem apenas artefatos versionados da própria equipe, fornecidos voluntariamente por equipes participantes ou disponibilizados pelo professor. Não coletem dados pessoais, conversas privadas, chaves, tokens ou raciocínio interno de LLM. Casos coletados devem ser anonimizados e registrados com origem, data, licença/permissão e finalidade.

O conjunto auditado deve preservar o vínculo entre:

• o manifesto e SHA-256 do corpus, o splits.json e o embedding-contract.json do TP2;
• a consulta, o resultado de retrieval e os supporting_ids/trechos que sustentam a recomendação;
• o contrato TP1/TP2, a resposta RAG, as citações e a decisão RESPONDER, ABSTER ou PEDIR_ESCLARECIMENTO do TP3;
• versão de código, ambiente, semente, comando de execução, data e resultados produzidos.

Não alterem rótulos, citações, logs ou resultados após a auditoria sem criar nova execução identificada. Dados brutos eventualmente sensíveis ficam fora do repositório público; publiquem somente versões anonimizadas, agregadas ou instruções de acesso autorizadas.

7.4 Método fixo

O método abaixo é obrigatório para tornar os resultados comparáveis e viáveis no tempo disponível.

1. Congelamento e inventário. Até 19/10, registrem versões, hashes, responsáveis, comandos e disponibilidade dos artefatos TP2 já produzidos. A falta de um artefato é um achado de reprodutibilidade, não algo a ser preenchido retroativamente sem registro.
2. Casos auditáveis. Definam antes da rodada final pelo menos 12 casos: os seis tipos obrigatórios do TP3 (direto, estratégia distinta, paráfrase, ambíguo, fora do domínio e falha controlada) mais seis casos derivados do Golden Set ou de discordâncias do TP2. Cada caso deve conter entrada, expectativa, critério de julgamento, origem e revisor que não o implementou.
3. Auditoria de evidência e citação. Para cada caso, verifiquem se cada afirmação relevante está apoiada por item retornado na mesma requisição, se a citação aponta para o ID/título correto e se a evidência foi recuperada do índice de treino conforme o contrato TP2. Classifiquem como suportada, parcial, não suportada ou não verificável.
4. Auditoria de abstinção. Apliquem a política documentada do TP3 aos casos ambíguos, fora do domínio, sem recuperação e com falha controlada. Julguem se a decisão e a mensagem evitam inventar fonte, skill ou recomendação. Registrem falsos RESPONDER e abstinções excessivas.
5. Reprodução independente. Uma pessoa diferente da autora principal executa os comandos em ambiente limpo ou perfil separado, usando as versões congeladas. Comparem decisões, citações, IDs recuperados e métricas; expliquem qualquer divergência.
6. Síntese. Produzam tabelas de cobertura de evidência, validade de citações, adequação de abstinção e sucesso de reprodução, além de uma análise qualitativa de pelo menos quatro falhas ou limitações.

Não é exigido teste estatístico. Se a equipe usar intervalos de confiança ou outro método adicional, deve justificá-lo e manter o protocolo principal intacto.

Até 16/11/2026, registrem um alerta técnico de risco não avaliativo: contratos e mocks verificados, um caso fundamentado e um caso de abstenção executados, e um risco com responsável. O marco não cria aula adicional nem substitui a entrega final.

7.5 Entregáveis

O repositório da equipe deve conter:

• audit/protocol.md com pergunta, método fixo, critérios de julgamento, papéis e ameaças à validade;
• audit/artifact-inventory.csv ou equivalente com origem, versão/hash, licença/permissão, responsável e comando de reprodução de cada artefato TP2/TP3;
• audit/cases.yaml com os 12 ou mais casos, expectativas congeladas, origem e revisão cruzada;
• decisão documentada de PII, retenção e provedor para os dados e serviços usados na auditoria ou herdados do TP3;
• registros de auditoria por caso, incluindo consulta, evidências, resposta, citações, decisão, julgamento e justificativa;
• scripts/comandos para gerar as tabelas e repetir a auditoria, com ambiente, dependências e sementes documentados;
• resultado da reprodução independente e relatório de divergências;
• artigo/ ou docs/artigo/ com o artigo curto no formato SBC;
• README.md com instruções de execução, autoria, limitações, dados que não podem ser publicados e localização dos artefatos.

É aceitável usar mocks compatíveis quando um serviço estiver indisponível, desde que o caso seja marcado como tal. Mocks não contam como reprodução da execução real e não podem substituir silenciosamente os resultados reais.

7.6 Papéis para quatro estudantes

Cada estudante assume aproximadamente 15 horas, faz revisão de uma entrega de colega e mantém commits/MRs identificáveis.

Papel	Responsabilidade principal	Evidência individual
Pessoa A - Protocolo e dados	Inventário, proveniência, anonimização, congelamento e cases.yaml	Protocolo, hashes, permissões e casos revisados
Pessoa B - Evidência e citações	Auditoria de retrieval, trechos, supporting_ids e correspondência das citações	Planilhas/registros de cobertura e testes de validação
Pessoa C - Abstenção e integração	Auditoria das decisões, falhas de contrato e mensagens degradadas	Casos de abstinção, logs e análise de decisões
Pessoa D - Reprodução e artigo	Ambiente limpo, scripts, comparação de execuções, tabelas e redação SBC	Relatório de reprodução, tabelas geradas e seção do artigo

7.7 Artigo curto SBC (3-4 páginas)

Entreguem um artigo de 3 a 4 páginas, sem contar referências e apêndices quando o modelo SBC os separar. O texto deve ser baseado nos casos predefinidos/coletados e nos registros reais da auditoria, não em resultados ilustrativos.

Estrutura mínima:

1. Problema e pergunta de pesquisa.
2. Artefatos TP2/TP3, contratos e proveniência dos dados.
3. Método: casos, critérios para evidência/citação, política de abstinção e reprodução independente.
4. Resultados: tabelas de cobertura de evidência, validade de citações, abstinção e reprodução.
5. Discussão: falhas, limitações, ameaças à validade e próximo passo justificável.

Incluam pelo menos uma tabela de casos, uma tabela de resultados e as citações acadêmicas efetivamente usadas. A seção de método deve permitir que outra equipe refaça a auditoria sem depender de conhecimento oral.

7.8 Cronograma

Período	Marco	Evidência
Até 19/10	Fechamento do TP2 e preparação IC	Inventário inicial, papéis, protocolo e casos candidatos do Golden Set/discordâncias
20/10-31/10	Congelamento de artefatos	Hashes, contratos TP2, comandos e casos auditáveis definidos antes da rodada final
01/11-10/11	Integração TP3 e piloto	Registros de evidência/citação, política de abstinção e dois casos piloto revisados
11/11-17/11	Auditoria principal	Doze ou mais casos executados, julgamentos cruzados e falhas registradas
18/11-25/11	Reprodução e síntese	Execução independente, comparação, tabelas e artigo SBC revisado
26/11	Entrega do TP3 Master	Repositório, auditoria e artigo SBC de 3-4 páginas
30/11 e 02/12	Apresentações	Demonstração dos achados, defesa do método e limitações

7.9 Apresentações em 30/11 e 02/12

Apresentem em até 6 minutos, com participação de todos:

1. Pergunta, artefatos e protocolo (1 minuto).
2. Um caso com resposta fundamentada e citações verificadas (1 minuto).
3. Um caso de abstinção ou falha degradada (1 minuto).
4. Resultados da auditoria e da reprodução independente (2 minutos).
5. Limitação relevante e recomendação concreta para o TP3 (1 minuto).

Preparem captura de tela ou vídeo curto como contingência, sem substituir os registros e scripts versionados.

7.10 Rubrica (20 pontos)

Critério	Pontos	Evidência
Protocolo, casos e governança de dados	3,0	Método fixo, 12+ casos, origem, revisão cruzada e tratamento de dados
Auditoria de evidências e citações	4,0	Registros por caso, rastreabilidade TP2 e classificação justificada
Auditoria de abstinção e falhas seguras	3,0	Casos ambíguos, fora do domínio e falha controlada, sem fonte inventada
Reprodutibilidade e engenharia	3,0	Inventário, hashes, scripts, ambiente e execução independente
Análise crítica e resultados	2,5	Tabelas, divergências, quatro ou mais falhas/limitações e conclusões proporcionais
Artigo curto SBC	2,5	3-4 páginas, método, casos, contratos, citações e resultados reais
Apresentação e defesa técnica	1,0	Clareza, participação e limites explicitados
Contribuição individual comprovável	1,0	Papel, commits/MRs e revisão de colega
Total	20,0

7.11 Checklist de entrega em 26/11

• Aceitação explícita da equipe na Trilha IC registrada pelo professor.
• Protocolo, inventário e 12 ou mais casos versionados antes da rodada final.
• Artefatos TP2 e TP3 rastreáveis por versão/hash, contrato e comando.
• Auditoria de evidência, citação e abstinção registrada para todos os casos.
• Reprodução independente executada e divergências explicadas.
• Scripts, ambiente e instruções suficientes para repetir as tabelas.
• Artigo SBC de 3-4 páginas baseado nos resultados reais.
• Material da apresentação de 30/11 e 02/12 e contingência preparados.
• Qualquer experimento com agentes isolado como TP3.5 opcional, sem compor a fonte de dados.

---

8 📦 Recursos Oficiais & Especificação do Dataset

9 Recursos Oficiais do WOKDEX 📦

Este documento centraliza todos os artefatos canônicos, bases de dados e especificações formais do ecossistema WOKDEX utilizados na disciplina de Inteligência Artificial II (IA II).

---

9.1 📊 Dataset Oficial da Disciplina: LeetCode Problems Dataset Bilíngue (PT-BR)

Para viabilizar o treinamento de redes neurais profundas (TP1), a indexação semântica em banco vetorial (TP2) e a curadoria autônoma com agentes (TP3), a disciplina adota o LeetCode Problems Dataset Bilíngue, uma base curada com 2.830 problemas públicos de programação traduzidos e auditados em Português Brasileiro (PT-BR).

Nota🔗 Links Oficiais para Acesso e Download

• 📊 Relatório Exploratório Interativo (HTML do Jupyter Notebook) (Gráficos de distribuição, vocabulário e contagem de palavras)
• 📄 Relatório Exploratório Consolidado (PDF) (Versão para leitura e impressão)
• 📥 Download do Dataset em CSV (23.3 MB)
• 📥 Download do Dataset em JSON Estruturado (25.4 MB)
• 📖 Documentação Técnica & Especificação de Schemas

9.1.1 📈 Composição e Estatísticas do Dataset

• Total de Registros: 2.830 problemas gratuitos com enunciado completo.
• Distribuição por Dificuldade:
  • Easy (CS1/CS2): 752 problemas (26,6%) — ideal para conceitos introdutórios e estruturas básicas.
  • Medium (CS2/CS3): 1.417 problemas (50,1%) — estruturas de dados avançadas e algoritmos clássicos.
  • Hard (CS3/Maratona): 661 problemas (23,3%) — benchmarks avançados e otimização complexa.
• Metodologia de Curadoria: Tradução técnica assistida por LLM (gpt-5.4-mini via OpenAI Batch API com Structured Outputs), garantindo 98,9% de fidelidade estrutural perfeita na preservação de tags HTML, expressões matemáticas, tabelas, código inline e variáveis originais.

9.1.2 🧩 Campos Disponíveis para os Modelos

Campo	Tipo	Aplicação nos TPs
id	Inteiro	Identificador unívoco do problema (1 a 3549).
title_pt	Texto	Título do problema em português.
description_pt	Texto (HTML/Markdown)	Feature Textual (\(X_{text}\)) para NLP no TP1 e Documento de Chunk no TP2 (RAG).
difficulty	Categórico (Easy, Medium, Hard)	Feature tabular de entrada ou baseline de classificação.
topics	Lista de Strings (JSON)	Rótulos Alvo (\(y\)) — skills e tópicos algorítmicos em português.
hints_pt	Lista de Textos	Dicas pedagógicas oficiais traduzidas para enriquecimento no TP2/TP3.
acceptance_rate	Float (\(0.0\) a \(100.0\))	Métrica de taxa de aceitação (feature tabular para modelos Multi-Input).
likes / dislikes	Inteiro	Métricas de engajamento da comunidade de programadores.
solution_code_python	Código Python	Implementação de referência para validação de testes.

---

9.2 📄 Artigo Científico Base

Miranda Junior, A.; Santos, V. F. (2026). “Quebrando o Silêncio Pedagógico: O Modelo WOKDEX para Feedback Formativo em Juízes Online”. SBIE 2026 — Trilha TPIE (Trabalhos e Pesquisas em Informática na Educação). CBIE 2026.

• PDF Local do Artigo: artigo-sbie-wokdex.pdf
• Contribuições Formalizadas: contribuicoes-artigo-sbie.md
• Afiliação: CEFET-MG (DECOM-TM) / UFMG (DCC)

9.2.1 As 4 Contribuições Científicas do Artigo

ID	Contribuição	Descrição
C1	Schema WOKDEX	Modelo de metadados estruturado (YAML validado por JSON Schema) que formaliza atributos pedagógicos para exercícios de programação.
C2	Tipologia de 4 Testes	Formalização das categorias SAMPLE, FUNCTIONAL, MISCONCEPTION e PERFORMANCE.
C3	Corpus de Referência Golden	Catálogo com exercícios anotados manualmente com cenários pedagógicos ricos.
C4	Heurística de Modulação de Dica (HMD)	Algoritmo que modula a emissão e a assertividade do feedback formativo com base na taxa de falha dos testes.

---

9.3 🔗 JSON Schema Oficial (wok-problem.json)

O arquivo wok-problem.json define a especificação sintática estrita (JSON Schema Draft-07) que todo artefato pedagógico do WOKDEX deve respeitar.

• Arquivo Local: wok-problem.json (28 KB)
• URL de Produção: https://api.mundodocodigo.com.br/api/public/json/wok-problem.json

9.3.1 Campos Obrigatórios (required)

id, name, slug, version, origin, description, editorial,
difficultyLevelId, timeComplexity, skills, solutions,
statements, successmsg, testScenarios

---

9.4 🎯 Os 4 Tipos de Teste (TestType)

Tipo	Visível ao Aluno?	Função Pedagógica no WOKDEX
SAMPLE	✅ Sim	Testes dos exemplos do enunciado para depuração inicial do aluno.
FUNCTIONAL	❌ Não	Testes que verificam a corretude funcional da solução em casos de borda normais.
MISCONCEPTION	❌ Não	Armadilha pedagógica — testes projetados para capturar erros conceituais específicos (ex.: divisão inteira vs. ponto flutuante).
PERFORMANCE	❌ Não	Testes com entradas volumosas para avaliar a complexidade assintótica de tempo e memória.

9.4.1 Subtipos de MISCONCEPTION

Subtipo	Alvo Pedagógico	Exemplo Clássico
TYPE	Tipo de dado inadequado (CS1)	Uso de int no lugar de double na divisão.
FORMAT	Formatação de saída incorreta (CS1)	Omissão de quebra de linha \n ou espaço sobressalente.
STRATEGY	Abordagem algorítmica insuficiente (CS2/CS3)	Resolução por força bruta onde se exige Programação Dinâmica.

---

9.5 📚 Heurística de Modulação de Dica (HMD)

A HMD (Contribuição C4 do artigo) define quando o sistema deve emitir a dica pedagógica (helpTip):

Nível de Confiança	Condição do Teste	Ação do Juiz Online
Alta	Todos os testes do cenário falharam	Emite helpTip com máxima certeza do diagnóstico.
Moderada	Maioria dos testes falhou	Emite helpTip acompanhado de ressalva investigativa.
Baixa	Apenas 1 teste isolado falhou	Não emite dica (evita falso diagnóstico por erro de digitação pontual).

---

9.6 🗂️ Arquivos Locais deste Diretório

Arquivo	Descrição
wok-problem.json	JSON Schema oficial do modelo WOKDEX (Draft-07) — 28 KB
artigo-sbie-wokdex.pdf	Artigo científico completo publicado no SBIE 2026 — 250 KB
contribuicoes-artigo-sbie.md	Detalhamento das 4 contribuições acadêmicas formais
index.qmd	Esta página de referência técnica e documentação