https://github.com/0x41337/kity
Dashboard personalizado para estudantes que desejam registrar com precisão seu desempenho.
https://github.com/0x41337/kity
dashboard revision shadcn-ui statistics
Last synced: 3 months ago
JSON representation
Dashboard personalizado para estudantes que desejam registrar com precisão seu desempenho.
- Host: GitHub
- URL: https://github.com/0x41337/kity
- Owner: 0x41337
- License: mit
- Created: 2026-02-28T23:35:11.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-27T00:06:50.000Z (3 months ago)
- Last Synced: 2026-03-27T12:35:26.114Z (3 months ago)
- Topics: dashboard, revision, shadcn-ui, statistics
- Language: TypeScript
- Homepage: https://kityme.vercel.app/
- Size: 316 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Finalidade
O **Kity** é um sistema para analisar desempenho em estudos usando estatística e modelagem de memória.
Diferente de planilhas ou apps comuns — que mostram apenas a porcentagem de acertos — ele tenta responder duas perguntas fundamentais:
> **Quanto você realmente sabe?**
> **E quanto disso você ainda lembra agora?**
A ideia principal é:
> A porcentagem de acertos é apenas uma estimativa — e além disso, o conhecimento se deteriora com o tempo.
## Modelagem de Desempenho
Cada questão é tratada como um experimento independente:
- Acerto → sucesso
- Erro → falha
- Existe uma probabilidade real de acerto (**p**), desconhecida
Se você respondeu:
- **k** questões corretamente
- **n** questões no total
A estimativa de aproveitamento é:
$$
\hat{p} = \frac{k}{n}
$$
Essa é a **taxa de acerto observada** — direta e sem ajustes.
## Modelo de Esquecimento — Half-Life Regression (HLR)
Saber algo não significa **lembrar disso no futuro**.
O Kity modela a memória usando **Half-Life Regression**, inspirado no modelo publicado pelo Duolingo (Settles & Meeder, 2016).
A ideia central é que cada pessoa tem uma *Half-Life de memória* para cada assunto — o tempo que leva para a retenção cair à metade.
## Modelo Adaptativo
Diferente de implementações estáticas, o Kity aprende com o seu comportamento.
Os parâmetros do modelo:
$$
\theta = (\theta_0, \theta_1, \theta_2)
$$
são ajustados automaticamente ao longo do uso, com base nas suas revisões.
Cada nova sessão de estudo contribui para calibrar o modelo, tornando as estimativas cada vez mais personalizadas.
## Half-Life
A Half-Life é estimada a partir do seu desempenho observado:
$$
h = 2^{\,\theta_0 + \theta_1 \cdot \hat{p} + \theta_2 \cdot \log_2(n+1)}
$$
Onde:
- $\hat{p}$ = aproveitamento (acertos / total)
- $n$ = número de questões respondidas
- $\theta_0, \theta_1, \theta_2$ = parâmetros aprendidos pelo sistema
Interpretação dos fatores:
| Fator | Efeito |
|---|---|
| Aproveitamento alto | Half-Life maior — esquece mais devagar |
| Mais questões respondidas | Half-Life maior — conhecimento mais consolidado |
| Pouco treino ou baixo acerto | Half-Life curta — esquecimento rápido |
## Interpretação dos Parâmetros
Os parâmetros $\theta$ definem como **você aprende**:
### $\theta_0$ — memória base
Controla o nível inicial de retenção.
- Menor valor → esquecimento mais rápido
- Maior valor → retenção mais estável mesmo sem prática
### $\theta_1$ — impacto do acerto
Define o quanto acertar melhora sua memória.
- Baixo → acertos têm pouco efeito
- Alto → acertos fortalecem significativamente o aprendizado
### $\theta_2$ — impacto da repetição
Define o quanto a quantidade de prática influencia.
- Baixo → repetir não muda tanto
- Alto → repetição consolida fortemente o conhecimento
## Retenção estimada
Com a Half-Life calculada, a retenção após $t$ dias é:
$$
R(t) = 2^{-t/h}
$$
- $R(0) = 1$ → logo após revisar, retenção máxima
- $R(h) = 0.5$ → após $h$ dias, metade foi esquecida
- $t \uparrow$ → retenção $\downarrow$
## Aprendizado do Modelo
Os parâmetros $\theta$ são atualizados usando aprendizado online a cada revisão.
Cada tentativa (acerto ou erro) contribui para ajustar o modelo com base no erro entre:
- retenção prevista
- resultado observado
Isso permite que o sistema:
- se adapte ao seu ritmo de aprendizado
- corrija previsões ao longo do tempo
- se torne mais preciso conforme você usa
## Dados legados
Revisões sem registro de data são tratadas como antigas (28 dias), resultando em retenção baixa. Isso incentiva o usuário a refazer a revisão e gerar dados recentes.
## Métricas
### Aproveitamento (`accuracyRate`)
$$
\text{accuracy} = \frac{k}{n} \times 100
$$
Taxa observada de acertos. Não considera tempo nem incerteza — é o dado bruto.
### Retenção estimada (`currentRetention`)
$$
R(t) = 2^{-t/h}
$$
O quanto do conhecimento você provavelmente ainda lembra hoje. É a métrica principal para decisão de revisão.
### Half-Life (`halfLifeDays`)
$$
h = 2^{\,\theta_0 + \theta_1 \cdot \hat{p} + \theta_2 \cdot \log_2(n+1)}
$$
Durabilidade do conhecimento em dias. Indica o ritmo de esquecimento — não apenas o estado atual, mas a tendência futura.
## Status de Revisão
O sistema classifica automaticamente com base na retenção atual:
| Status | Retenção | Comportamento na UI |
|---|---|---|
| 🟡 Atenção | 40% – 70% | Bolinha amarela no card |
| 🔴 Pendente | < 40% | Bolinha vermelha no card |
O indicador visual só aparece quando há algo a alertar — inspirado no princípio de alertas de instrumentos: não interrompa o usuário quando tudo está bem.
## Interpretação Completa
### Antes:
> "Você acertou 80%"
### Agora:
> "Seu aproveitamento foi 80%, com Half-Life de 12 dias —
> e você provavelmente ainda lembra ~74% disso hoje."
## Decisão de Estudo
O Kity não serve só para medir — ele ajuda a decidir:
- O que revisar (retenção baixa → bolinha vermelha)
- Quando revisar (Half-Life curta → revise antes)
- O que já está consolidado (Half-Life longa + retenção alta → sem alerta)
## Comportamento do Sistema
### Número de questões
- $n \uparrow$ → Half-Life maior, conhecimento mais consolidado
- $n \downarrow$ → Half-Life curta, esquecimento mais rápido
### Tempo
- $t \uparrow$ → retenção $\downarrow$
- Revisão → reinicia o ciclo, retenção volta a 100%
### Aproveitamento
- $\hat{p} \uparrow$ → Half-Life maior
- $\hat{p} \downarrow$ → Half-Life menor — errar frequentemente acelera o esquecimento
### Adaptação
- Mais revisões → modelo mais preciso
- Padrões consistentes → θ converge
- Mudança de comportamento → modelo se ajusta
## Resumo
| Métrica | Significado |
---|---|
| Aproveitamento | O que você acertou |
| Retenção estimada | O que você ainda lembra hoje |
| Half-Life | Por quanto tempo seu conhecimento dura |
| θ (parâmetros) | Como você aprende |
## Conclusão
Um modelo mais realista e adaptativo de aprendizado, levando em conta:
- **Desempenho** — aproveitamento observado
- **Volume** — quantidade de questões respondidas
- **Tempo** — decaimento real da memória via HLR
- **Adaptação** — personalização automática do modelo
Em termos práticos:
- Use **Retenção estimada** para decidir o que revisar agora
- Use **Half-Life** para entender a durabilidade do seu conhecimento
- Confie no **silêncio** — ausência de alerta significa que está tudo bem