ifinho

Assistente virtual (RAG com citações) para os Institutos Federais do Brasil. Responde dúvidas de estudantes sobre editais, regulamentos e calendário acadêmico, sempre citando a fonte. É multi-instituto e multi-campus — cada pergunta é escopada ao campus do aluno, então um estudante do IFSC nunca recebe um documento do IFRS. O desenvolvimento começa pelo IFRS – Campus Canoas.

Como funciona

Arquitetura híbrida, separando dado de geração:

• Plano de dados (Spring AI): ingestão de PDF (PagePdfDocumentReader + TokenTextSplitter) → embeddings bge-m3 via Ollama (1024 dims) → armazenamento e busca vetorial em pgvector. A recuperação é filtrada por instituto/campus e por validade do documento.
• Plano de geração: em dev, roda no Ollama local (custo zero, qualidade menor, sem citação nativa); em produção (planejado), roda no SDK oficial da Anthropic com citações nativas (blocos document com citations). A troca é por perfil do Spring, atrás da mesma interface AssistantHarness.

Datas do calendário acadêmico serão tratadas como dado estruturado + tool (não RAG) — planejado.

Modelo de dados

institute (IFRS, IFSC, …)  →  campus (Canoas, …)  →  source_document (edital, anexo, …)
   acronym / uf / base_url      institute_id / slug     institute_id (obrig.) + campus_id (opcional)

• source_document carrega escopo (institute_id, campus_id nulo = vale pro instituto todo), validade (status: ACTIVE/SUPERSEDED/REVOKED/EXPIRED/DRAFT + superseded_by), URL da fonte (usada na citação) e content_hash (ingestão idempotente).
• Relações tipadas entre documentos (ANNEX_OF, SUPERSEDES, …).
• Documentos revogados/expirados saem do grounding; um documento substituído aponta para o que o substituiu.

Stack

• Java 25, Spring Boot 4.1, Spring AI 2.0
• PostgreSQL + pgvector (busca vetorial) · Flyway (migrations)
• Ollama (bge-m3 para embeddings; llama3.1 para chat em dev)
• SDK oficial da Anthropic (com.anthropic:anthropic-java) para a geração com citações em prod

Rodando localmente (perfil local)

Pré-requisitos:

1. pgvector (container, no WSL a partir da raiz do projeto):

   docker compose up -d

2. Ollama nativo rodando (localhost:11434) com os modelos:

   ollama pull bge-m3
   ollama pull llama3.1

3. Rodar a aplicação (perfil local é o padrão):

   ./gradlew bootRun

Telas de admin (dev)

Servidas pelo próprio app:

• /documents.html — cadastrar/atualizar documentos (por instituto/campus), status/validade, relações, exclusão
• /orgs.html — cadastrar institutos e campi
• /ask.html — testar o /api/ask escolhendo o campus do aluno

API

Método	Rota	Descrição
POST	/api/ask	Pergunta do aluno ({ question, campusId }) → resposta + fontes
POST	/api/admin/ingest	Ingestão de PDF (multipart: file, instituteId/campusId, sourceUrl, title, type, identifier)
GET/DELETE	/api/admin/documents	Lista / apaga documentos
PATCH	/api/admin/documents/{id}/status	Muda validade/status
GET/POST	/api/admin/documents/{id}/relations	Lista / cria relações
GET/POST	/api/admin/institutes	Lista / cria institutos
GET/POST	/api/admin/campuses	Lista / cria campi

Status

Pronto: ingestão idempotente com escopo por instituto/campus; recuperação escopada e filtrada por validade; citações com URL da fonte; relações entre documentos; /api/ask com Ollama; seed dos 38 Institutos Federais e dos campi do IFRS; telas de admin.

Próximos passos: harness de produção (Anthropic + citações nativas), calendário acadêmico (dado estruturado + tool), cache semântico e avaliação (evals), campi dos demais institutos.