← Voltar a studyAI — Documentação do Projeto

🗺️ Roadmap

studyAI — Documentação do Projeto

Apresentação

Roadmap — studyAI

Plano de desenvolvimento em sprints. Priorização, timeline, checklists e critérios de conclusão.

Índice

Visão e objetivos
Timeline
Sprints
Matriz de prioridades
Dependências entre sprints
Critérios de MVP
Checklist final
Pós-MVP e futuro

Visão e objetivos

Objetivo	Descrição
MVP	User regista, cria projeto, faz upload, pede material, estuda, pratica, avalia. Tudo grounded nos seus docs.
Learning	Spaced repetition (SM-2), material adaptativo, memória de conversa.
Produção	Rate limit, cost control, deploy, observabilidade.

Duração total estimada: 12–14 semanas (6–7 sprints de 2 semanas).

Timeline

A carregar diagrama…

Sprint	Foco	Duração	Entregável principal
1	Fundação	2 sem	Auth, DB, Docker, dashboard
2	Core	2 sem	Projetos, upload, ingestão, RAG simples
3	LangGraph (1)	2 sem	Router, Planner, Writer, generate
4	LangGraph (2)	2 sem	Chat, QA, Evaluator, perguntas
5	Learning	2 sem	SM-2, user_profile, memory
6	Produção	2 sem	Rate limit, deploy, observabilidade

Sprints

Sprint 1 — Fundação

Objetivo: Estrutura a correr localmente. User consegue registar e ver dashboard.

Área	Entregas
Estrutura	`api/` (FastAPI), `web/` (Next.js), `docker-compose.yml` (Postgres, Redis, MinIO)
DB	Alembic, migrations 001–006 (users, projects, files, documents, chunks, jobs, etc.)
Auth	POST /auth/register, login, refresh, GET /auth/me. JWT + refresh tokens.
Frontend	Layout, login, registo, dashboard, API client com interceptors, guard de rotas

Checklist:

Checkpoint:

User regista, faz login, vê dashboard
Docker Compose sobe todos os serviços
Schema completo no Postgres

Docs: TECH_DECISIONS, API_SPEC, DATA_MODEL

Sprint 2 — Core

Objetivo: Projetos, upload, ingestão, RAG funcional. User carrega PDF e obtém resposta baseada no conteúdo.

Área	Entregas
Projetos	CRUD API + UI. Validação `project.user_id == current_user.id`
Upload	POST /projects/:id/files (multipart), MinIO, DB (status=pending)
Ingestão	Job: parse (pdfplumber/pypdf) → chunk → embed → pgvector. Retry com backoff.
RAG	Pipeline híbrido: dense + BM25 → RRF → cross-encoder rerank (ver RAG_DESIGN)
Query	POST /projects/:id/query (sem agentes): query → chunks → LLM → resposta
Index	POST /projects/:id/index, botão "Reindexar" na UI

Checklist:

Checkpoint:

User cria projeto, faz upload de PDF, vê status processed
Query devolve resposta fundamentada nos chunks
Reindexar funciona

Docs: RAG_DESIGN, JOBS_ASYNC, PDF_INGESTION

Sprint 3 — LangGraph (1)

Objetivo: Router, Content Planner, Content Writer. Geração de material sobre tópico.

Área	Entregas
Router	Hybrid (rules + LLM), confidence, fallback < 0.7 → qa
Content Planner	RAG retrieval → sections, confidence, missing_topics
Content Writer	Modos strict/hybrid, loop por secção, progress
State	state.py com GenerateContentState (TypedDict)
Jobs	Tabela jobs, status, progress, message
API	POST /projects/:id/generate, GET /jobs/:id
UI	Botão "Gerar material", progress bar

Checklist:

Router: rules (keywords → intent), LLM classifier, confidence, fallback < 0.7 → qa
Content Planner: RAG retrieval, output sections/confidence/missing_topics
Content Writer: modos strict/hybrid, loop por secção
Streaming progress: "A escrever secção 2...", jobs status/progress/message
state.py com GenerateContentState, ChatState (TypedDict)
POST /projects/:id/generate, GET /jobs/:id
UI: botão "Gerar material", progress bar

Checkpoint:

"Quero estudar X" → documento gerado (secção a secção)
Progress visível durante geração
Documento guardado em DB e re-indexado

Docs: AGENTS, STATE_SCHEMA

Sprint 4 — LangGraph (2)

Objetivo: Chat, RAG QA, Question Generator, Evaluator. MVP completo.

Área	Entregas
RAG QA Agent	Retrieval + LLM, resposta + citações, streaming
Question Generator	Documento → perguntas (difficulty por user_level)
Question Evaluator	Hybrid (0.3 rule + 0.7 LLM), score, feedback
Chat	POST /projects/:id/chat, streaming
Evaluate	POST /projects/:id/evaluate
Persistência	chat_sessions, chat_messages, message_citations
UI	Chat, perguntas com submit, feedback

Checklist:

Question Generator: documento + user_profile.level → questions (difficulty)
RAG QA Agent: retrieval + LLM, resposta + citações, streaming
Question Evaluator: rule-based + LLM (0.3 rule + 0.7 llm), atualizar user_progress
POST /projects/:id/chat, POST /projects/:id/evaluate
chat_sessions, chat_messages, message_citations
POST /chat com session_id → persistir, GET /projects/:id/chat/sessions
UI: chat, perguntas com submit, feedback

Checkpoint:

Chat responde com base no material, citações
"Gerar material" → documento + perguntas
Submeter resposta → score + feedback
POST /documents apenas para criação manual

Docs: AGENTS, FLOWS, CITATIONS_UX

Sprint 5 — Learning (pós-MVP)

Objetivo: Learning Loop, user_profile, memória de conversa.

Área	Entregas
user_profile	Tabela, weak_topics, recent_errors, level
SM-2	ease_factor, interval_days, next_review_at
what_to_review	Intent: perguntas com next_review_at <= now
Loop adaptativo	Score < 60 → material simplificado; score >= 90 → perguntas hard
conversation_memory	Summary, embedding, retrieval no RAG QA
document_versions	Histórico ao editar (opcional)

Checklist:

user_profile: tabela, weak_topics, recent_errors, level, UI settings
SM-2: ease_factor, interval_days, next_review_at após evaluate
Intent what_to_review: perguntas com next_review_at <= now
Loop adaptativo: score < 60 → material simplificado; score >= 90 → perguntas hard
conversation_memory: summary, embedding, LLM resume a cada 5–10 msgs
RAG QA carrega memory como contexto
document_versions ao editar (opcional)

Checkpoint:

"O que devo rever?" devolve perguntas agendadas
Material adaptado a weak_topics
Memória permite continuidade no chat

Docs: LEARNING_LOOP, USER_INTELLIGENCE

Sprint 6 — Produção

Objetivo: Rate limit, cost control, deploy, observabilidade.

Área	Entregas
Rate limiting	Redis sliding window, limites por endpoint, 429
Cost control	Cache embeddings, cache respostas, model selection
RAG evaluation	Amostragem, rag_evaluations, groundedness
Multi-tenant	project_id obrigatório, ownership, testes isolamento
Observabilidade	LangSmith, health checks, logs estruturados
Deploy	Dockerfile, CI, staging/produção

Checklist:

Rate limiting: Redis sliding window, limites por endpoint, 429 + Retry-After
Cache embeddings (Redis), cache respostas, model selection por tarefa
RAG evaluation: amostragem 10–20%, rag_evaluations, LangSmith evals
project_id obrigatório em pesquisas vetoriais, validação ownership
Testes de isolamento (user A não vê dados de user B)
LangSmith: LANGCHAIN_TRACING_V2, LANGCHAIN_API_KEY
Health checks: /health, /health/db, /health/redis
Logs estruturados (request_id, user_id)
Dockerfile API, Web; docker-compose produção; CI test/build

Checkpoint:

Rate limit ativo
LangSmith com traces
Deploy em staging/produção

Docs: SECURITY, COST_CONTROL, DEPLOYMENT

Matriz de prioridades

Item	Prioridade	Sprint	Bloqueia
Auth, DB, Docker	P0	1	Tudo
Projetos CRUD	P0	2	Upload, RAG
Upload + Ingestão	P0	2	RAG, Generate
RAG simples	P0	2	Chat, Generate
Router	P0	3	Planner, Writer
Content Planner + Writer	P0	3	Generate
Question Generator	P0	4	Perguntas
RAG QA Agent	P0	4	Chat
Question Evaluator	P0	4	Avaliação
Chat persistido	P1	4	Histórico
Learning Loop	P1	5	—
user_profile	P1	5	Adaptação
Rate limiting	P0	6	Produção
Deploy	P0	6	—
RAG evaluation	P1	6	Qualidade

P0: Essencial para MVP/produção. P1: Importante, pode ser faseado.

Dependências entre sprints

A carregar diagrama…

Sprint 1 não depende de nada.
Sprint 2 depende de auth e DB.
Sprint 3 depende de RAG e projetos.
Sprint 4 depende de Planner/Writer e jobs.
Sprint 5 pode começar em paralelo com 6 após Sprint 4.
Sprint 6 pode começar após 4 (MVP) ou após 5 (com Learning).

Critérios de MVP

MVP = fim do Sprint 4. Para considerar MVP concluído:

Critério	Verificação
Auth	Registo, login, refresh funcionam
Projetos	CRUD, ownership validado
Upload	PDF → processed, chunks indexados
Generate	"Quero estudar X" → documento + perguntas
Chat	Pergunta → resposta com citações
Evaluate	Resposta submetida → score + feedback
Progress	Barra de progresso durante geração
Testes	Unit (auth, chunking), integration (API), E2E smoke

Ver TESTING.md para critérios de qualidade.

Checklist final

Documentação

Todos os docs em docs/ atualizados
README com link para ROADMAP

Funcionalidades

Qualidade

Testes conforme TESTING.md
Unit: auth, chunking, router rules, evaluator rules
Integration: API, RAG, multi-tenant
E2E smoke: upload → index → chat → generate → evaluate
Golden tests para Router
RAG eval set, retrieval_recall > 0.7

Pós-MVP e futuro

Fase	Itens	Quando
Learning	SM-2, user_profile, memory	Sprint 5
Produção	Rate limit, deploy, observabilidade	Sprint 6
Futuro	Hybrid search (BM25), reranking	—
Futuro	Multi-modal (imagens, áudio)	—
Futuro	Knowledge graph	—
Futuro	OAuth (Google, GitHub)	—

Zona de prática

Sem perguntas. Clica em Editar para adicionar.