keystrike 1.1.0__py3-none-any.whl

keystrike/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"

keystrike/__main__.py

@@ -0,0 +1,9 @@
+from keystrike.cli import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

keystrike/app.py

@@ -0,0 +1,111 @@
+"""Composition root: wire all dependencies and return a ready-to-run KeystrikeApp."""
+
+from dataclasses import dataclass
+from random import Random
+
+from keystrike.application.build_lesson import BuildLesson
+from keystrike.application.learn_budget_use_cases import GetDailyLearnBudget
+from keystrike.application.prepare_practice import PreparePracticeSession
+from keystrike.application.session_use_cases import (
+    FinishSession,
+    RecordKeystroke,
+    StartSession,
+)
+from keystrike.application.settings_use_cases import CycleLayout, UpdateSettings
+from keystrike.application.stats_use_cases import GetHeatmap, GetHistory, RebuildAggregates
+from keystrike.application.sync_use_cases import GetSyncStatus, InitSync, PullSync, PushSync
+from keystrike.infrastructure.aggregates_cache import FileAggregatesCache
+from keystrike.infrastructure.clock import MonotonicClock
+from keystrike.infrastructure.id_gen import UlidGenerator
+from keystrike.infrastructure.languages import BundledLanguageProvider
+from keystrike.infrastructure.layout_repo import CompositeLayoutRepository
+from keystrike.infrastructure.paths import default_paths, ensure_dirs
+from keystrike.infrastructure.session_repo_jsonl import JsonlSessionRepository
+from keystrike.infrastructure.settings_repo_toml import TomlSettingsRepository
+from keystrike.infrastructure.sync_git import GitSyncGateway
+from keystrike.presentation.textual_app import KeystrikeApp
+
+
+@dataclass(frozen=True, slots=True)
+class SyncServices:
+    init: InitSync
+    pull: PullSync
+    push: PushSync
+    status: GetSyncStatus
+
+
+def build_sync() -> SyncServices:
+    paths = default_paths()
+    ensure_dirs(paths)
+    session_repo = JsonlSessionRepository(paths)
+    aggregates_cache = FileAggregatesCache(paths)
+    store = GitSyncGateway(paths)
+    rebuild = RebuildAggregates(repo=session_repo, cache=aggregates_cache)
+    return SyncServices(
+        init=InitSync(gateway=store),
+        pull=PullSync(gateway=store, rebuild=rebuild),
+        push=PushSync(gateway=store),
+        status=GetSyncStatus(gateway=store),
+    )
+
+
+def build() -> KeystrikeApp:
+    paths = default_paths()
+    ensure_dirs(paths)
+
+    clock = MonotonicClock()
+    id_gen = UlidGenerator()
+    session_repo = JsonlSessionRepository(paths)
+    settings_repo = TomlSettingsRepository(paths)
+    layout_repo = CompositeLayoutRepository(paths)
+    aggregates_cache = FileAggregatesCache(paths)
+    language_provider = BundledLanguageProvider()
+
+    start = StartSession(clock=clock, id_gen=id_gen)
+    record = RecordKeystroke(clock=clock, repo=session_repo)
+    finish = FinishSession(
+        clock=clock,
+        repo=session_repo,
+        aggregates_cache=aggregates_cache,
+        settings_repo=settings_repo,
+        layout_repo=layout_repo,
+    )
+    rebuild_aggregates = RebuildAggregates(repo=session_repo, cache=aggregates_cache)
+    get_heatmap = GetHeatmap(cache=aggregates_cache, settings_repo=settings_repo)
+    get_history = GetHistory(repo=session_repo)
+    get_daily_learn_budget = GetDailyLearnBudget(
+        clock=clock,
+        repo=session_repo,
+        settings_repo=settings_repo,
+    )
+    cycle_layout = CycleLayout(settings_repo=settings_repo, layout_repo=layout_repo)
+    update_settings = UpdateSettings(repo=settings_repo)
+    build_lesson = BuildLesson(
+        layout_repo=layout_repo,
+        aggregates_cache=aggregates_cache,
+        settings_repo=settings_repo,
+        language_provider=language_provider,
+        rng=Random(),
+    )
+    prepare_practice = PreparePracticeSession(
+        settings_repo=settings_repo,
+        layout_repo=layout_repo,
+        build_lesson=build_lesson,
+        get_daily_learn_budget=get_daily_learn_budget,
+    )
+
+    return KeystrikeApp(
+        clock=clock,
+        start=start,
+        record=record,
+        finish=finish,
+        settings_repo=settings_repo,
+        layout_repo=layout_repo,
+        prepare_practice=prepare_practice,
+        rebuild_aggregates=rebuild_aggregates,
+        get_heatmap=get_heatmap,
+        get_history=get_history,
+        cycle_layout=cycle_layout,
+        update_settings=update_settings,
+        get_daily_learn_budget=get_daily_learn_budget,
+    )

keystrike/application/build_lesson.py

@@ -0,0 +1,202 @@
+"""BuildLesson: the adaptive engine — figure out which keys are unlocked,
+pick a focus key, and generate practice text for them.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from random import Random
+
+from keystrike.domain.aggregate import transition_key
+from keystrike.domain.confidence import (
+    compute_unlocked,
+    confidence_of,
+    focus_key_from_transition,
+    practice_weight,
+    review_urgency,
+    select_focus,
+    select_focus_transition,
+    target_ms_per_char,
+    transition_confidence_of,
+    transition_practice_weight,
+)
+from keystrike.domain.generator import AdaptiveGenerator
+from keystrike.domain.learn_order import keyboard_order
+from keystrike.domain.models import (
+    KeyStats,
+    Layout,
+    LessonKey,
+    LessonState,
+    Settings,
+    TransitionStats,
+)
+from keystrike.domain.protocols import (
+    AggregatesCache,
+    LanguageProvider,
+    LayoutRepository,
+    SettingsRepository,
+)
+
+WORD_COUNT = 12
+_CONFIDENCE_GOOD = 1.0
+
+
+def _focus_reason(
+    focus: int,
+    stats: dict[int, KeyStats],
+    target: float,
+    now: float,
+) -> str | None:
+    key_stats = stats.get(focus)
+    urgency = review_urgency(key_stats.last_seen if key_stats else 0.0, now)
+    confidence = confidence_of(focus, stats, target)
+    if urgency > 0 and confidence >= _CONFIDENCE_GOOD:
+        return "review"
+    if confidence < _CONFIDENCE_GOOD:
+        return "weak"
+    return None
+
+
+def _focus_reason_transition(
+    prev_cp: int,
+    next_cp: int,
+    transitions: dict[str, TransitionStats],
+    target: float,
+    now: float,
+) -> str | None:
+    pair = chr(prev_cp) + chr(next_cp)
+    t_stats = transitions.get(transition_key(prev_cp, next_cp))
+    urgency = review_urgency(t_stats.last_seen if t_stats else 0.0, now)
+    confidence = transition_confidence_of(prev_cp, next_cp, transitions, target)
+    if urgency > 0 and confidence >= _CONFIDENCE_GOOD:
+        return f"{pair} review transition"
+    if confidence < _CONFIDENCE_GOOD:
+        return f"{pair} weak transition"
+    return None
+
+
+@dataclass(slots=True)
+class Lesson:
+    text: str
+    state: LessonState
+    urgency: dict[int, float]
+    focus_reason: str | None
+
+    @property
+    def focus_key(self) -> int:
+        return next(k.codepoint for k in self.state.keys if k.is_focus)
+
+    @property
+    def heatmap(self) -> dict[int, float]:
+        return {k.codepoint: k.confidence for k in self.state.keys}
+
+
+def _lesson_progress(
+    layout_name: str,
+    layout: Layout,
+    stats: dict[int, KeyStats],
+    settings: Settings,
+    now: float,
+    *,
+    transitions: dict[str, TransitionStats] | None = None,
+) -> tuple[tuple[int, ...], int, LessonState, tuple[int, int] | None]:
+    target = target_ms_per_char(settings.target_speed_cpm)
+    order = keyboard_order(layout)
+    unlocked = compute_unlocked(order, settings.alphabet_size, stats, target)
+    focus_bigram = (
+        select_focus_transition(unlocked, transitions, target, now)
+        if transitions else None
+    )
+    if focus_bigram is not None:
+        focus = focus_key_from_transition(*focus_bigram)
+    else:
+        focus = select_focus(unlocked, stats, target, now)
+
+    keys = tuple(
+        LessonKey(
+            codepoint=cp,
+            unlocked=True,
+            confidence=confidence_of(cp, stats, target),
+            is_focus=(cp == focus),
+        )
+        for cp in unlocked
+    )
+    state = LessonState(
+        layout=layout_name,
+        keys=keys,
+        alphabet_size=settings.alphabet_size,
+        target_speed_cpm=settings.target_speed_cpm,
+    )
+    return unlocked, focus, state, focus_bigram
+
+
+@dataclass(slots=True)
+class BuildLesson:
+    layout_repo: LayoutRepository
+    aggregates_cache: AggregatesCache
+    settings_repo: SettingsRepository
+    language_provider: LanguageProvider
+    rng: Random
+
+    def __call__(self, layout_name: str) -> Lesson:
+        settings = self.settings_repo.load()
+        layout = self.layout_repo.get(layout_name)
+        aggregates = self.aggregates_cache.get(layout_name)
+        stats = aggregates.keys if aggregates else {}
+        transitions = aggregates.transitions if aggregates else {}
+        now = time.time()
+        unlocked, focus, state, focus_bigram = _lesson_progress(
+            layout_name, layout, stats, settings, now, transitions=transitions,
+        )
+        target = target_ms_per_char(settings.target_speed_cpm)
+
+        table = self.language_provider.transitions(settings.lang)
+        generator = AdaptiveGenerator(table=table, rng=self.rng)
+        alphabet_chars = frozenset(chr(cp) for cp in unlocked)
+        char_weights = {
+            chr(k.codepoint): practice_weight(
+                k.confidence,
+                urgency=review_urgency(
+                    stats[k.codepoint].last_seen if k.codepoint in stats else 0.0, now,
+                ),
+            )
+            for k in state.keys
+        }
+        transition_weights = {
+            transition_key(prev, nxt): transition_practice_weight(
+                transition_confidence_of(prev, nxt, transitions, target),
+                urgency=review_urgency(
+                    transitions[transition_key(prev, nxt)].last_seen
+                    if transition_key(prev, nxt) in transitions else 0.0,
+                    now,
+                ),
+            )
+            for prev in unlocked
+            for nxt in unlocked
+        }
+        text = generator.generate_lesson(
+            alphabet_chars,
+            chr(focus),
+            word_count=WORD_COUNT,
+            char_weights=char_weights,
+            layout=layout,
+            transition_weights=transition_weights,
+            focus_bigram=focus_bigram,
+        )
+
+        urgency = {
+            cp: review_urgency(stats[cp].last_seen if cp in stats else 0.0, now)
+            for cp in unlocked
+        }
+        if focus_bigram is not None:
+            prev_cp, next_cp = focus_bigram
+            reason = _focus_reason_transition(prev_cp, next_cp, transitions, target, now)
+        else:
+            reason = _focus_reason(focus, stats, target, now)
+        return Lesson(
+            text=text,
+            state=state,
+            urgency=urgency,
+            focus_reason=reason,
+        )

keystrike/application/learn_budget_use_cases.py

@@ -0,0 +1,33 @@
+"""Use cases for the daily adaptive (learn) mode time budget."""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+from keystrike.domain.daily_learn import (
+    DailyLearnBudget,
+    compute_daily_learn_budget,
+    daily_learn_duration_ns,
+    session_local_date,
+)
+from keystrike.domain.protocols import Clock, SessionRepository, SettingsRepository
+
+
+@dataclass(slots=True)
+class GetDailyLearnBudget:
+    clock: Clock
+    repo: SessionRepository
+    settings_repo: SettingsRepository
+    tz: dt.tzinfo | None = None
+
+    def __call__(self, *, extra_ns: int = 0) -> DailyLearnBudget:
+        tz = self.tz or dt.datetime.now().astimezone().tzinfo or dt.UTC
+        today = session_local_date(self.clock.wall_epoch(), tz)
+        completed_ns = daily_learn_duration_ns(self.repo.iter_all_headers(), today, tz=tz)
+        limit_minutes = self.settings_repo.load().learn_daily_minutes
+        return compute_daily_learn_budget(
+            completed_ns=completed_ns,
+            limit_minutes=limit_minutes,
+            extra_ns=extra_ns,
+        )

keystrike/application/prepare_practice.py

@@ -0,0 +1,53 @@
+"""PreparePracticeSession: build SessionPrep for adaptive practice."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from keystrike.application.build_lesson import BuildLesson
+from keystrike.domain.enums import Mode
+from keystrike.domain.models import Layout
+from keystrike.domain.protocols import (
+    DailyLearnBudgetProvider,
+    LayoutRepository,
+    SettingsRepository,
+)
+
+PrepareNextSession = Callable[[], "SessionPrep | None"]
+
+
+@dataclass(frozen=True, slots=True)
+class SessionPrep:
+    target_text: str
+    layout: str
+    mode: Mode
+    focus_key: int | None
+    focus_reason: str | None
+    layout_obj: Layout | None
+    lesson_heatmap: dict[int, float] | None
+    lesson_urgency: dict[int, float] | None
+
+
+@dataclass(slots=True)
+class PreparePracticeSession:
+    settings_repo: SettingsRepository
+    layout_repo: LayoutRepository
+    build_lesson: BuildLesson
+    get_daily_learn_budget: DailyLearnBudgetProvider
+
+    def __call__(self) -> SessionPrep | None:
+        if self.get_daily_learn_budget().limit_reached:
+            return None
+        settings = self.settings_repo.load()
+        lesson = self.build_lesson(settings.layout)
+        return SessionPrep(
+            target_text=lesson.text,
+            layout=settings.layout,
+            mode=Mode.ADAPTIVE,
+            focus_key=lesson.focus_key,
+            focus_reason=lesson.focus_reason,
+            layout_obj=self.layout_repo.get(settings.layout),
+            lesson_heatmap=lesson.heatmap,
+            lesson_urgency=lesson.urgency,
+        )