TP3: Dossie de Integracao TP1-TP2 e Assistente RAG Fundamentado
Classificacao, recuperacao, RAG fundamentado e evidencia experimental
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.
Objetivos de aprendizagem
Ao concluir o TP3, a equipe devera demonstrar que consegue:
- Integrar sistemas independentes por contratos HTTP/documentados, sem acoplamento ao codigo interno do TP1 ou TP2.
- Explicar, com exemplos e limites, quando usar classificacao, recuperacao e uma arquitetura hibrida.
- Construir uma resposta RAG cujas afirmacoes sejam apoiadas por fontes recuperadas identificaveis.
- Projetar uma abstencao segura para entradas ambiguas, sem evidencia suficiente ou fora do dominio.
- Avaliar o sistema com casos definidos antes da demonstracao e analisar falhas de integracao.
- Consolidar em artigo SBC o material, as metricas e as decisoes dos TPs 1 e 2.
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:
- A classificacao de skills fornecida pelo contrato do TP1, com escore ou indicacao de confianca quando disponivel.
- Os documentos ou exercicios recuperados pelo TP2, com identificador, titulo e escore/ranking quando disponivel.
- Uma resposta ao usuario que diferencie claramente fato recuperado, inferencia e recomendacao.
- Citacoes na propria resposta, por exemplo
[E1]e[E2], que apontem para os itens recuperados exibidos pela interface. - A decisao de responder ou abster-se e sua justificativa objetiva.
- Um identificador de requisicao e os eventos minimos de observabilidade descritos adiante.
- 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.
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.
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.
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.
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.
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.
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.
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. |
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.
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.
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:
- Introducao e problema pedagogico.
- Fundamentacao e trabalhos relacionados, incluindo classificacao e RAG.
- Metodo: contratos TP1/TP2, arquitetura hibrida e politica de abstencao.
- Avaliacao: protocolo dos seis casos, metricas herdadas do TP1/TP2 e resultados do TP3.
- Discussao: classificacao versus recuperacao versus hibrido, falhas, custo/latencia e ameacas a validade.
- 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.
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 |
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.
Apresentações em 30/11 e 02/12
Apresentem em ate 6 minutos, com participacao de todos os integrantes:
- Problema, contratos e arquitetura hibrida (1 minuto).
- Demo da CLI/UI em um caso no dominio, mostrando evidencias e citacoes (2 minutos).
- Demo de abstencao, ambiguidade ou falha degradada (1 minuto).
- Resultados dos seis casos e comparacao das tres estrategias (1 minuto).
- 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.
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 |
Checklist de entrega final
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.