TP3 Master: Simulated Students — Validação do Pipeline WOKDEX

Trilha IC — O Plano 2 da Pesquisa

Trabalho Prático especial para equipes da Trilha IC. Construção de um sistema multi-agente que simula alunos e valida os artefatos gerados por todas as equipes da turma.

Published

21/08/2026

Modified

21/08/2026

🧬 TP3 Master: Simulated Students

Este TP substitui o TP3 regular apenas para equipes da Trilha IC. As equipes regulares devem seguir o TP3 padrão. A nota vale os mesmos 20 pontos e o Demoday é compartilhado.

🧭 O Contexto: Dois Planos que Conversam

Na pesquisa do professor, existem dois pipelines de IA que se retroalimentam:

Plano 1 (Pipeline de Exercícios): Recebe um enunciado e gera o metadata.yaml completo. → É isso que as 10 equipes da turma constroem nos TPs regulares.
Plano 2 (Simulated Students): Simula alunos cometendo erros para testar se os exercícios gerados pelo Plano 1 realmente capturam os erros certos e geram dicas úteis. → É isso que vocês, equipes IC, vão construir.

  10 EQUIPES (Plano 1)                    EQUIPES IC (Plano 2)
  ┌────────────────────┐                  ┌────────────────────┐
  │ TP1: Classificador │                  │ Agent Novice       │
  │ TP2: RAG           │──── YAMLs ──────▶│ Agent Instructor   │
  │ TP3: Agente        │   gerados        │ Schema Validator   │
  └────────────────────┘                  └────────┬───────────┘
                                                   │
                                          ┌────────▼───────────┐
                                          │  Relatório de      │
                                          │  Falhas + Métricas │
                                          │  → Artigo 3        │
                                          └────────────────────┘

A mágica: enquanto as 8 equipes regulares constroem o agente que gera YAMLs, vocês constroem o agente que valida esses YAMLs. No Demoday, vocês apresentam os resultados da validação de todas as equipes — incluindo quais pipelines geraram as melhores misconceptions e quais alucinaram.

🤖 LLM e Infraestrutura

Componente	Tecnologia
Modelo	Provedor Agnóstico: DeepSeek Coder, GPT-4o-mini ou similar (via API)
Orquestração	LangGraph (grafos de agentes com loops de reflexão)
Saída Estruturada	Pydantic + Instructor (garante JSON WOKDEX válido)
Acesso	API Key centralizada fornecida pelo professor
Estatística	scipy + statsmodels (McNemar, Fleiss’ κ)

[!NOTE] O professor fornece a API key do modelo (DeepSeek / OpenAI). Vocês não precisam gastar dinheiro. O custo total do experimento inteiro consumirá cerca de US$ 10 a US$ 20.

🏗️ Os 3 Agentes que Vocês Vão Construir

Agent 1: Novice Student (O Aluno que Erra de Propósito)

System Prompt: “Você é um aluno de 1º período. Resolva o exercício abaixo, mas cometa o seguinte tipo de erro: [TIPO_ERRO].”

Parâmetro	Valor
Temperature	0.4 (erros controlados, não aleatórios)
Few-shot	2–3 exemplos de submissões erradas reais do histórico
Saída	Código-fonte em C contendo o erro solicitado
Validação	Compilar + rodar contra os test cases → deve falhar no cenário correto

Exemplo de uso:

response = agent_novice.run(
    exercise="Divisão: leia A e B, imprima A/B com 2 casas decimais",
    error_type="TYPE",  # Usar int em vez de double
    target_scenario="c-falso-positivo-inteiros"
)
# Saída: código em C com "int a, b;" em vez de "double a, b;"

Agent 2: Instructor (O Professor que Gera Dicas)

System Prompt: “Analise o código bugado abaixo. Gere uma dica que NÃO entregue a resposta, mas guie o raciocínio do aluno.”

Parâmetro	Valor
Loop de reflexão	2 rounds (o agente auto-critica a própria dica)
Regra de rejeição	Se a dica contém código idêntico ao golden code → rejeitar
Saída	Texto da hint refinada

Agent 3: Schema Validator (O Guardião do Formato)

Parâmetro	Valor
Ferramenta	Pydantic + Instructor
Self-Healing	Se o JSON falhar na validação, reenvia o erro ao LLM
Saída	JSON 100% compatível com `wok-problem.json`

O Orquestrador

O fluxo completo é:

Enunciado + Cenários WOKDEX
        │
        ▼
   Agent Novice ──→ Código bugado
        │
        ▼
   Agent Instructor ──→ Hint (com reflexão)
        │
        ▼
   Agent Validator ──→ JSON válido
        │
        ▼
   Relatório de Falhas

👥 Divisão de Tarefas (4 Alunos)

Aluno	Cargo	O que codifica
Aluno A	Engenheiro do Agent Novice	`agents/novice_student.py` — prompt, few-shot, compilação
Aluno B	Engenheiro do Agent Instructor	`agents/instructor.py` — prompt, loop de reflexão, rejeição
Aluno C	Engenheiro do Validator + Orquestrador	`agents/schema_validator.py` + `orchestrator.py`
Aluno D	Engenheiro de Avaliação + Estatística	`evaluation/ablation.py` + `evaluation/mcnemar_test.py`

🧪 O Experimento: Validação Cruzada nos 10 Pipelines

Esta é a parte mais poderosa do TP3 Master. No Demoday (semana 14), a equipe IC:

Coleta os YAMLs gerados por cada uma das 10 equipes da turma.
Roda o Agent Novice para cada cenário de erro listado em cada YAML.
Mede:

Métrica	Fórmula	O que revela
Scenario Trap Rate	% de vezes que o código errado do Novice é capturado pelo cenário correto	Os test cases do pipeline estão bons?
Hint Relevance	% de hints avaliadas como “úteis” pelo Agent Instructor	As dicas geradas ajudam o aluno?
Golden Code Pass Rate	% de golden codes que compilam e passam em todos os testes	O pipeline gera código correto?
Schema Compliance	% de YAMLs que validam contra `wok-problem.json`	O pipeline respeita o formato?

Gera uma tabela comparativa dos 10 pipelines:

Grupo	LLM usado	Scenario Trap Rate	Hint Relevance	Schema Compliance
G1	Gemini Flash	78%	85%	100%
G2	GPT-4o-mini	82%	90%	95%
G3	Llama 3 local	65%	70%	88%
…	…	…	…	…

[!IMPORTANT] Esta tabela é ouro puro para a tese do professor. Ela mostra, com dados reais de 10 implementações independentes, qual LLM gera os melhores artefatos pedagógicos.

🔬 Ablation Study (4 Condições)

Além de validar os pipelines das outras equipes, a equipe IC executa um ablation study no seu próprio sistema de Simulated Students:

Condição	O que está desligado	Flag
C1: Sem Data Anchoring	Agent Validator simplificado	`use_data_anchoring=False`
C2: Sem Reflexão	Agent Instructor sem loop	`use_reflection=False`
C3: Sem Few-Shot	Agent Novice sem exemplos	`use_few_shot=False`
C4: Pipeline Completo	Nada desligado (controle)	Todos `True`

Para cada condição, rodar em 10 exercícios e reportar: - Scenario Trap Rate por condição - Hint Relevance por condição - McNemar pareado: cada condição ablada vs. C4

🎤 Demoday: O que a Equipe IC Apresenta

No Demoday, a equipe IC tem 7 minutos (em vez de 5) + 3 de perguntas:

Fase	Tempo	Conteúdo
1. O Problema	30s	“Os pipelines das equipes geram YAMLs, mas são bons?”
2. Os 3 Agentes	90s	Diagrama + demo: Agent Novice erra, Instructor corrige, Validator valida
3. Resultados dos 10 Pipelines	120s	Tabela comparativa — qual equipe gerou os melhores exercícios?
4. Ablation Study	90s	Gráficos mostrando o impacto de cada componente
5. Conclusões para a Tese	30s	“O que aprendemos? O que o professor deve publicar?”

📊 Rubrica de Avaliação (20 Pontos)

Nota Individual (10 pts)

Critério	Pontos	Detalhes
Commits individuais na branch correta	2	Avaliado via Git Blame
Agente ou módulo funciona isoladamente	6	Novice (A), Instructor (B), Validator+Orquestrador (C), Avaliação (D)
Qualidade e organização do código	2	Docstrings, tipagem, separação de responsabilidades

Nota do Grupo (10 pts)

Critério	Pontos	Detalhes
Pipeline multi-agente end-to-end funciona	3	Cenário → Código bugado → Hint → JSON válido
Validação cruzada de ≥ 5 pipelines da turma	2	Tabela comparativa com métricas
Ablation Study com 4 condições	2	McNemar + gráficos
Draft 3 Master (3–4 páginas SBC)	1	Seção completa de Methodology + Results
Demoday: apresentação dos resultados	2	Clareza, rigor, impacto dos dados

🏆 Bônus de Excelência

Bônus	Valor	Critério
Validou todos os 10 pipelines da turma	+1.0 pt	Tabela completa de 10 linhas
Scenario Trap Rate ≥ 80% no pipeline completo	+0.5 pt	Os cenários realmente capturam erros
Artigo aceito em conferência	+5 pts	Publicação real com coautoria

📅 Passo a Passo Completo (Semana a Semana)

Semana	O que a equipe IC faz
1–2	TP1 regular + Adendo IC-TP1: rodar pipeline v1 nos 45 exercícios, catalogar falhas
3	Entregar TP1 + planilha de diagnóstico. Reunião com professor.
4–5	Começar TP2 regular. Adendo IC-TP2: taxonomia de erros (≥ 15 tipos)
6	TP2: RAG funcional. Setup LangGraph + conexão vLLM.
7–8	Construir Agent Novice (Aluno A) + Agent Instructor (Aluno B)
9	Entregar TP2 + Adendo IC-TP2. Testar agentes em 1 exercício piloto.
10	Construir Validator + Orquestrador (Aluno C). Pipeline multi-agente rodando.
11	Loop de Validação: testar em 5 exercícios piloto. Ajustar prompts.
12	Ablation Study: rodar as 4 condições em 10 exercícios. McNemar.
13	Coleta dos YAMLs das 10 equipes (pós-entrega do TP3 regular).
14	Validação cruzada completa. Tabela comparativa dos 10 pipelines.
14	Demoday. Apresentação dos resultados.
15	Escrita do Draft 3 Master. Rascunho do Artigo 3 com o professor.

[!TIP] A mensagem mais importante: Façam o TP1 e TP2 com excelência primeiro. A qualidade do vosso RAG e classificador impacta diretamente os dados do experimento. O TP3 Master só funciona se a fundação estiver sólida.

🧬 TP3 Master: Simulated Students

🧭 O Contexto: Dois Planos que Conversam

🤖 LLM e Infraestrutura

🏗️ Os 3 Agentes que Vocês Vão Construir

Agent 1: Novice Student (O Aluno que Erra de Propósito)

Agent 2: Instructor (O Professor que Gera Dicas)

Agent 3: Schema Validator (O Guardião do Formato)

O Orquestrador

👥 Divisão de Tarefas (4 Alunos)

🧪 O Experimento: Validação Cruzada nos 10 Pipelines

🔬 Ablation Study (4 Condições)

🎤 Demoday: O que a Equipe IC Apresenta

📊 Rubrica de Avaliação (20 Pontos)

Nota Individual (10 pts)

Nota do Grupo (10 pts)

🏆 Bônus de Excelência

✅ Checklist de Entrega — TP3 Master

📅 Passo a Passo Completo (Semana a Semana)