TP2: Infraestrutura de Retrieval e Recomendação Híbrida de Skills WOKDEX

Avaliação reproduzível de recomendação multi-label

Projeto de 60 horas em equipe para comparar recomendação supervisionada, recuperação por embeddings e híbrida no corpus WOKDEX.

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.

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.

---

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.

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.

---

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.

---

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.

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.

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.

---

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.

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.

---

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.

---

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.

---

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.

---

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.

---

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

---

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.

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.