feat: Implement KnowledgeLevel repository and memorizing algorithm

[apomalyn]

As a developer, I want a central place to interact with the knowledge-level and memorizing algorithm

Requirements

Implement a KnowledgeLevel model using Isar and freezed. The schema can be found on https://github.com/RoadTripMoustache/kana_to_kanji_api/issues/15

Implement an enum LearningMode with the following:

• review: will only focus on the already known (seen, practising and learned) resources
• learn: will review only today's element and then introduce new words

Implement a KnowledgeRepository that:

• can access the user to read/update LearningMode and newResourcesIntroduced
• can interact with the database to retrieve the next X elements to review
• can determine what the next X elements to review or learn based on (see Learning order system section)
• can update the knowledge level in bulk based on a list of KnowledgeUpdate (see Update Knowledge section)

Learning mode

Update the UI:

• to show a BottomSheetDialog every Y (for now: 15) new words learned on the same day asking to switch learning mode to review. The mode will be reset to learn the next day.
• to have an icon button on the AppBar of to easily switch from learning to review mode and vice-versa

Learning order system

The learning order system determines in which order we need to learn the resources. It's divided into two parts:

• levels: a list of resources to learn, it should not have more than 30 resources on it
• stages: a list of levels, it should not have more than 10 levels on it

The stages and levels will be built based on the JLPT. It will introduce resources from the same JLPT level and some resources from other JLPT levels.

Rules

• A level should not have more than 30 resources

• Maximum three (3) resources from a level are introduced at the same time

• New resources from the same level are introduced when:

  • 60% of the already seen resources (from the level) have a review gap of 3 days or more

• A level is considered finished when:

  • 100% of the resources on it have been seen
  • 60% of the resources have a review gap of 3 days or more

• A stage should not have more than 10 levels

• A stage is considered finished when:

  • 100% of the levels are finished
  • 80% of the resources in the levels have a review gap of 10 days or more

Determine the next element to review or learn

The method should:

• signature:
  • the number of resources to return, by default 30;
  • an optional List<ResourceUid> restrain to restrain the possible selection
• returns: List<KnowledgeUpdate>

In general, follow this:

1. retrieve from the database, the resource to review before tomorrow (KnowledgeLevel.next_review) limited to the learning order system
2. Learning mode:
   • LearningMode.learn: complete with new elements from either restrain or the learning level system
   • LearningMode.review:
     • if restrain is provided go to 3., otherwise complete with any resource to review before tomorrow (including the entire KnowledgeLevel table)
3. complete with resource ordered by additional_review_before_next_review ASC and next_review ASC, limited to restrain if provided

Flow diagram for the selection of the next elements to review or learn


Update KnowledgeLevel

Before updating the KnowledgeLevel.gap and dates, if the current day is review day (today = next_review excluding time):

• reset additional_review_before_next_review to 0
• last_review = today (time midnight) Otherwise, increase additional_review_before_next_review by 1.

To calculate the new KnowledgeLevel.gap use the following:

new_gap = gap + (gap * memorization_coefficient * mitigation_coefficient ^ (additional_review_before_next_review))

Update KnowledgeLevel.gap and next_review based on new_cap.

Coefficients:

• mitigation_coefficient: 0.3
• memorization_coefficient:
  • grade <= 1: 0
  • 1 < grade <= 2: 0.3
  • 2 < grade <= 3: 0.5
  • 3 < grade: 0.8

A resource knowledge level is considered:

• not seen: no KnowledgeLevel exist
• seen: KnowledgeLevel.gap >= 0
• practicing: KnowledgeLevel.gap >= 3
• learned: KnowledgeLevel.gap >= 60

Dependencies

Child of #160

Depends on:

• 135

• 167

• 216

• https://github.com/RoadTripMoustache/kana_to_kanji_api/issues/66
• https://github.com/RoadTripMoustache/kana_to_kanji_api/issues/77

Parent of:

• 224

• 225

• 229

• 230

• 226

• 227

• 228

• 231

• 232

• 233

• 271

• 281

Dev notes