8000 Count the daily goal in distinct cards, not answers by jmahmood · Pull Request #23 · jmahmood/CardBrick · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion cardbrick-py/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,8 @@ operation; it is deliberately not exposed in Parent Mode's on-device UI.

The day is a card goal chipped away in short sprints, not one sitting.
Per child profile: `daily_goal_cards` (default 150) is the day's goal
in card answers; each sprint is bounded by `session_card_limit`
in distinct cards (a card repeating a learning step counts once); each
sprint is bounded by `session_card_limit`
(default 20) and `session_time_minutes` (10, 0 = off), so the child
always knows how many sprints they still owe ("3 sprints to go today").
Doing sprints back-to-back — "going ahead" — burns the count down just
Expand Down
15 changes: 9 additions & 6 deletions cardbrick-py/cardbrick/service.py
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ def get_due_cards(self, profile=None, category_filter=None,
deck_filter=None, limits=None, bonus=False):
"""Build the queue for one sprint.

The day is a card goal (``daily_goal_cards`` answers) chipped
The day is a card goal (``daily_goal_cards`` distinct cards) chipped
away in short sprints; each call returns the next sprint's
worth, at most ``session_card_limit`` cards and never more than
what's left of the goal. Order: due review cards (most overdue
Expand Down Expand Up @@ -119,10 +119,10 @@ def get_due_cards(self, profile=None, category_filter=None,

now = self.now()
day_start = iso(local_day_start(now))
new_done, _review_done, _ = self.storage.daily_counts(day_start)
answers_done = self.storage.daily_answer_count(day_start)
new_done, review_done, _ = self.storage.daily_counts(day_start)
cards_done = new_done + review_done # distinct cards, not answers
remaining_new = max(limits["daily_new_cards"] - new_done, 0)
goal_left = max(limits["daily_goal_cards"] - answers_done, 0)
goal_left = max(limits["daily_goal_cards"] - cards_done, 0)
budget = limits["session_card_limit"] if bonus \
else min(goal_left, limits["session_card_limit"])

Expand Down Expand Up @@ -172,7 +172,8 @@ def sprint_status(self, profile=None, category_filter=None,
survive restarts, crashes, and undo.

Returns a dict:
cards_done answers logged today
cards_done distinct cards answered today (a card
repeating a learning step counts once)
goal daily_goal_cards in effect
cards_remaining what's left of the goal
sprints_planned ceil(goal / sprint size)
Expand All @@ -188,7 +189,9 @@ def sprint_status(self, profile=None, category_filter=None,
if profile.get(key) is not None:
limits[key] = profile[key]
now = self.now()
done = self.storage.daily_answer_count(iso(local_day_start(now)))
new_done, review_done, _ = self.storage.daily_counts(
iso(local_day_start(now)))
done = new_done + review_done
goal = limits["daily_goal_cards"]
sprint_size = max(limits["session_card_limit"], 1)
remaining = max(goal - done, 0)
Expand Down
12 changes: 0 additions & 12 deletions cardbrick-py/cardbrick/storage.py
Original file line number Diff line number Diff line change
Expand Up @@ -472,18 +472,6 @@ def daily_counts(self, day_start_iso):
(day_start_iso,))}
return len(new_ids), len(all_ids - new_ids), new_ids

def daily_answer_count(self, day_start_iso):
"""Total not-undone answers logged since the local day start.

Unlike daily_counts this counts every answer — including
learning-step repeats of the same card — which is the unit of
the daily goal ("150 cards a day").
"""
return self.conn.execute(
"""SELECT COUNT(*) AS n FROM review_log
WHERE undone = 0 AND reviewed_at >= ?""",
(day_start_iso,)).fetchone()["n"]

def daily_history(self, since_iso):
"""Raw (reviewed_at, was_new, card_id) tuples for progress views."""
return self.conn.execute(
Expand Down
2 changes: 1 addition & 1 deletion cardbrick-py/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ def build_parser():
help="View or edit the child profile")
p_profile.add_argument("--name", help="Child's name")
p_profile.add_argument("--daily-goal", type=int,
help="Daily goal in card answers; done in "
help="Daily goal in distinct cards; done in "
"sprints of --sprint-cards")
p_profile.add_argument("--daily-new", type=int,
help="New cards per day")
Expand Down
15 changes: 7 additions & 8 deletions cardbrick-py/tests/test_limits.py
Original file line number Diff line number Diff line change
Expand Up @@ -86,19 +86,18 @@ def test_daily_cap_counts_work_already_done_today(storage, service, clock):
assert len(new_ids) == 4


def test_goal_counts_every_answer_not_unique_cards(storage, service, clock):
# Two answers on the same card (a learning-step repeat) both count
# toward the goal: the contract is "N cards answered", not "N
# distinct cards".
def test_goal_counts_distinct_cards_not_answers(storage, service, clock):
# A learning-step repeat is the same card, so it consumes the goal
# once: the contract is "N distinct cards", and a hard card that
# comes back three times doesn't eat three cards' worth of goal.
seed_card(storage, service, 1)
seed_card(storage, service, 2, reps=1,
due=clock.now() - timedelta(days=1))
limits = _limits(daily_goal_cards=2, daily_new_cards=10)
service.answer_card(1, 1) # Again: the card comes back...
service.answer_card(1, 3) # ...and the repeat is a second answer.
# Card 2 is due, but the goal budget is already spent; per-unique-
# card accounting would have left room for it.
assert service.get_due_cards(limits=limits) == []
service.answer_card(1, 3) # ...but the repeat counts it only once.
queue = service.get_due_cards(limits=limits)
assert [row["id"] for row in queue] == [2] # room for one more card


def test_daily_budgets_reset_at_local_midnight(storage, service, clock):
Expand Down
12 changes: 6 additions & 6 deletions cardbrick-py/tests/test_study_ahead.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@
from conftest import seed_card

from cardbrick.scheduler import iso
from cardbrick.service import local_day_start
from cardbrick.session import StudySession
from cardbrick.storage import Storage

Expand Down Expand Up @@ -311,9 +310,10 @@ def test_migration_seeds_goal_from_old_caps(tmp_path):
storage.close()


def test_answers_before_day_start_do_not_count(storage, service, clock):
day_start = local_day_start(clock.now())
assert storage.daily_answer_count(iso(day_start)) == 0
def test_cards_done_counts_distinct_cards(storage, service, clock):
seed_card(storage, service, 1)
service.answer_card(1, 3)
assert storage.daily_answer_count(iso(day_start)) == 1
limits = _limits(daily_goal_cards=10, study_ahead_enabled=0)
assert service.sprint_status(limits=limits)["cards_done"] == 0
service.answer_card(1, 1) # Again: the card will repeat...
service.answer_card(1, 3) # ...but stays one card toward the goal
assert service.sprint_status(limits=limits)["cards_done"] == 1
13 changes: 7 additions & 6 deletions docs/STUDYING_AHEAD_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ goal** (say 150 cards) in **5–10 minute sprints** spread across the day.

Two numbers drive everything:

* `daily_goal_cards` — how many card answers the child should log today
(parent-set, e.g. 150);
* `daily_goal_cards` — how many distinct cards the child should answer
today (parent-set, e.g. 150);
* a **sprint** — one `StudySession`, already bounded by
`session_card_limit` (cards per sitting) and `session_time_minutes`
(5–10 min).
Expand All @@ -18,7 +18,8 @@ From these we derive, always from the append-only review log (never
in-memory counters, matching the house style):

```
cards_done_today = non-undone review-log entries since local midnight
cards_done_today = distinct cards in the non-undone review log since
local midnight (a learning-step repeat counts once)
cards_remaining = max(daily_goal_cards - cards_done_today, 0)
sprints_remaining = ceil(cards_remaining / session_card_limit)
sprints_planned = ceil(daily_goal_cards / session_card_limit)
Expand Down Expand Up @@ -59,8 +60,8 @@ dry before the goal is met.
`daily_review_cards` in the queue math (`get_due_cards`):

* `remaining_review = max(daily_goal_cards - cards_done_today, 0)` —
answers, not unique cards: learning-step repeats within a sprint count
toward the goal, which is correct for a "150 cards a day" contract.
distinct cards, not answers: a hard card repeating its learning steps
within a sprint counts toward "150 cards a day" once.
* `daily_new_cards` keeps its current meaning — it paces how fast new
material enters FSRS, which is orthogonal to the goal.
* `daily_review_cards` is retired from queue-building (column stays for
Expand Down Expand Up @@ -140,7 +141,7 @@ allowlists (`storage.py:538, :554`) so the profile CLI can set them:

| Field | Type | Default | Meaning |
|---|---|---|---|
| `daily_goal_cards` | INTEGER | 150 | Card answers per day; drives sprint count |
| `daily_goal_cards` | INTEGER | 150 | Distinct cards per day; drives sprint count |
| `study_ahead_days` | INTEGER | 1 | How far forward the ahead fill may reach |
| `study_ahead_enabled` | INTEGER (bool) | 1 | Allow ahead fill + bonus sprints |

Expand Down
Loading
0