deeptutor-calendar 1.7.0__py3-none-any.whl

deeptutor/api/routers/calendar.py

@@ -0,0 +1,183 @@
+"""Authenticated account calendar and workspace-local learning overlays."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from datetime import timedelta
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+from pydantic import ValidationError
+
+from deeptutor.services.calendar import models as m
+from deeptutor.services.calendar.layers import owner_key, read_layers
+from deeptutor.services.calendar.recurrence import parse_instant, zone
+from deeptutor.services.calendar.store import get_calendar_store
+from deeptutor.services.workspace.context import workspace_context
+
+from .task_board import board_workspace
+
+router = APIRouter()
+
+
+@contextmanager
+def errors():
+    try:
+        yield
+    except KeyError as exc:
+        raise HTTPException(404, "Calendar item not found.") from exc
+    except ValidationError as exc:
+        raise HTTPException(422, str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+
+def bounds(start, end, tz):
+    with errors():
+        first, last = parse_instant(start), parse_instant(end)
+        zone(tz)
+        if not first < last or last - first > timedelta(days=400):
+            raise ValueError("Choose a range between one second and 400 days.")
+        return first, last
+
+
+def validate_task(payload, request):
+    from deeptutor.services.task_board import get_task_board_store, workspace_board
+
+    if (
+        "task_workspace_id" in payload.model_fields_set
+        and "task_id" not in payload.model_fields_set
+    ):
+        raise HTTPException(400, "Change the task and its workspace together.")
+    if not payload.task_id:
+        return
+    workspace_id = board_workspace(request)
+    if payload.task_workspace_id not in (None, workspace_id):
+        raise HTTPException(404, "Task not found in this workspace.")
+    if not any(
+        c.id == payload.task_id and not c.archived
+        for c in workspace_board(get_task_board_store().read(), workspace_id).cards
+    ):
+        raise HTTPException(404, "Task not found in this workspace.")
+    payload.task_workspace_id = workspace_id
+
+
+@router.get("/calendars", response_model=m.CalendarList)
+def calendars():
+    return get_calendar_store().calendars()
+
+
+@router.post("/calendars", response_model=m.CalendarResponse, status_code=201)
+def create_calendar(payload: m.CreateCalendar):
+    return get_calendar_store().create_calendar(payload)
+
+
+@router.patch("/calendars/{id}", response_model=m.CalendarResponse)
+def update_calendar(id: str, payload: m.UpdateCalendar):
+    with errors():
+        return get_calendar_store().update_calendar(id, payload)
+
+
+@router.delete("/calendars/{id}", response_model=m.CalendarRevision)
+def delete_calendar(id: str):
+    with errors():
+        return get_calendar_store().delete_calendar(id)
+
+
+@router.get("/events", response_model=m.OccurrenceList)
+def events(start: str, end: str, tz: str = "UTC"):
+    first, last = bounds(start, end, tz)
+    with errors():
+        return get_calendar_store().occurrences(first, last, tz)
+
+
+@router.post("/events", response_model=m.CalendarEventResponse, status_code=201)
+def create_event(payload: m.EventInput, request: Request):
+    validate_task(payload, request)
+    with errors():
+        return get_calendar_store().create(payload)
+
+
+@router.patch("/events/{id}", response_model=m.CalendarRevision)
+def update_event(id: str, payload: m.EventPatchRequest, request: Request):
+    validate_task(payload.changes, request)
+    with errors():
+        return get_calendar_store().update(id, payload)
+
+
+@router.delete("/events/{id}")
+def delete_event(id: str, scope: m.Scope = "all", occurrence: str | None = None):
+    with errors():
+        return get_calendar_store().delete(id, scope, occurrence)
+
+
+@router.post("/undo/{token}", response_model=m.CalendarRevision)
+def undo(token: str):
+    with errors():
+        return get_calendar_store().restore(token)
+
+
+@router.get("/search", response_model=m.CalendarSearchResponse)
+def search(
+    q: str = Query(min_length=1, max_length=200), limit: int = Query(default=50, ge=1, le=100)
+):
+    with errors():
+        return get_calendar_store().search(q, limit)
+
+
+@router.get("/layers", response_model=m.CalendarLayers)
+def layers(request: Request, start: str, end: str, tz: str = "UTC"):
+    first, last = bounds(start, end, tz)
+    workspace_id = board_workspace(request)
+    with workspace_context(workspace_id):
+        return read_layers(workspace_id, first, last, tz)
+
+
+@router.delete("/automations/{job_id}", response_model=m.CalendarOk)
+def cancel_automation(job_id: str, request: Request):
+    from deeptutor.services.cron.service import get_cron_service
+
+    service = get_cron_service()
+    job = service.get_job(job_id)
+    if (
+        not job
+        or job.owner.key != owner_key()
+        or job.owner.kind != "chat"
+        or job.owner.workspace_id != board_workspace(request)
+    ):
+        raise HTTPException(404, "Automation not found.")
+    return {"ok": service.cancel_job(job_id, owner_key=owner_key())}
+
+
+@router.get("/stream")
+async def stream(request: Request):
+    store = await asyncio.to_thread(get_calendar_store)
+
+    async def changes():
+        revision = -1
+        tick = 0
+        while not await request.is_disconnected():
+            current = await asyncio.to_thread(store.revision)
+            if current != revision:
+                revision = current
+                yield f'id: {revision}\ndata: {{"revision":{revision}}}\n\n'
+            elif tick % 30 == 0:
+                yield ": heartbeat\n\n"
+            tick += 1
+            await asyncio.sleep(0.5)
+
+    return StreamingResponse(
+        changes(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache, no-transform",
+            "Content-Encoding": "identity",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.get("/task-blocks", response_model=dict[str, int])
+def task_blocks(request: Request):
+    return get_calendar_store().task_blocks(board_workspace(request))

deeptutor/services/calendar/__init__.py

@@ -0,0 +1 @@
+"""Account calendars, recurring events and workspace learning projections."""

deeptutor/services/calendar/layers.py

@@ -0,0 +1,142 @@
+"""Read-only projections of the selected workspace onto calendar days."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import math
+
+from .models import (
+    AutomationRun,
+    CalendarLayers,
+    FootprintDay,
+    FootprintSession,
+    ReviewDay,
+    ReviewPathCount,
+)
+from .recurrence import format_instant, zone
+
+
+def owner_key():
+    from deeptutor.multi_user.context import get_current_user
+    from deeptutor.services.cron.service import CronOwner
+
+    return CronOwner(kind="chat", user_id=get_current_user().id).key
+
+
+def read_layers(workspace_id, start, end, tzid):
+    from deeptutor.modules.catalog import module_enabled
+    from deeptutor.services.cron.service import compute_next_run, get_cron_service
+    from deeptutor.services.practice.storage import _DUE_AT_SQL, PracticeStore
+    from deeptutor.services.session import get_sqlite_session_store
+
+    tz = zone(tzid)
+    lo, hi = start.timestamp(), end.timestamp()
+
+    def day(ts):
+        return datetime.fromtimestamp(ts, tz).date().isoformat()
+
+    reviews, footprints = {}, {}
+
+    def review(ts):
+        key = day(ts)
+        return reviews.setdefault(key, ReviewDay(date=key))
+
+    def footprint(ts):
+        key = day(ts)
+        return footprints.setdefault(key, FootprintDay(date=key))
+
+    if module_enabled("mastery"):
+        from deeptutor.learning.policy import path_display_name
+        from deeptutor.learning.scheduler import SpacedRepetitionScheduler
+        from deeptutor.learning.storage import LearningStore
+
+        learning = LearningStore()
+        scheduler = SpacedRepetitionScheduler()
+        for progress, _topic, _count, _interaction in learning.list_topic_snapshots():
+            counts = {}
+            for task in scheduler.build_review_queue(progress):
+                if lo <= task.due_at < hi:
+                    key = day(task.due_at)
+                    counts[key] = counts.get(key, 0) + 1
+            for key, count in counts.items():
+                row = reviews.setdefault(key, ReviewDay(date=key))
+                row.mastery += count
+                row.paths.append(
+                    ReviewPathCount(
+                        id=progress.book_id, title=path_display_name(progress), count=count
+                    )
+                )
+        with learning._connect() as db:
+            for row in db.execute(
+                "SELECT timestamp FROM mastery_learning_evidence WHERE timestamp>=? AND timestamp<?",
+                (lo, hi),
+            ):
+                footprint(row[0]).mastery_evidence += 1
+
+    practice = PracticeStore(get_sqlite_session_store().db_path)
+    # The database is already workspace-scoped; match PracticeStore’s live-entry filter.
+    scope = "(n.session_id IS NULL OR s.deleted_at IS NULL)"
+    with practice.connect() as db:
+        # SQL fragments are local constants; both time bounds use parameters.
+        for row in db.execute(
+            f"SELECT {_DUE_AT_SQL} AS due FROM notebook_entries n LEFT JOIN sessions s ON s.id=n.session_id LEFT JOIN practice_review_state r ON r.entry_id=n.id WHERE {scope} AND {_DUE_AT_SQL}>=? AND {_DUE_AT_SQL}<?",  # nosec B608
+            (lo, hi),
+        ):
+            review(row[0]).practice += 1
+        for row in db.execute(
+            f"SELECT e.reviewed_at FROM practice_review_events e JOIN notebook_entries n ON n.id=e.entry_id LEFT JOIN sessions s ON s.id=n.session_id WHERE {scope} AND e.reviewed_at>=? AND e.reviewed_at<?",  # nosec B608
+            (lo, hi),
+        ):
+            footprint(row[0]).practice_reviews += 1
+        sessions_by_day = {}
+        for row in db.execute(
+            "SELECT m.created_at,s.id,s.title FROM messages m JOIN sessions s ON s.id=m.session_id WHERE s.deleted_at IS NULL AND m.role='user' AND m.created_at>=? AND m.created_at<?",
+            (lo, hi),
+        ):
+            key = day(row[0])
+            sessions_by_day.setdefault(key, {})[row[1]] = row[2] or ""
+        for key, sessions in sessions_by_day.items():
+            row = footprints.setdefault(key, FootprintDay(date=key))
+            row.session_count = len(sessions)
+            row.sessions = [
+                FootprintSession(id=id, title=title) for id, title in list(sessions.items())[:20]
+            ]
+
+    automations = []
+    for job in get_cron_service().list_jobs(owner_key()):
+        if job.owner.kind != "chat" or job.owner.workspace_id != workspace_id or not job.enabled:
+            continue
+        at = job.state.next_run_at_ms
+        if at is None:
+            continue
+        lower = max(int(lo * 1000), int(datetime.now(timezone.utc).timestamp() * 1000))
+        if at < lower:
+            if job.schedule.kind == "every":
+                step = job.schedule.every_seconds * 1000
+                at += max(0, math.ceil((lower - at) / step)) * step
+            else:
+                at = compute_next_run(job.schedule, lower - 1)
+        for _ in range(1000):
+            if at is None or at >= hi * 1000:
+                break
+            when = format_instant(datetime.fromtimestamp(at / 1000, timezone.utc))
+            automations.append(
+                AutomationRun(
+                    id=f"{job.id}:{at}",
+                    job_id=job.id,
+                    name=job.name,
+                    message=job.message,
+                    at=when,
+                    kind=job.schedule.kind,
+                    expr=job.schedule.expr,
+                    every_seconds=job.schedule.every_seconds,
+                    session_id=job.owner.session_id,
+                )
+            )
+            at = compute_next_run(job.schedule, at)
+    return CalendarLayers(
+        workspace_id=workspace_id,
+        reviews=sorted(reviews.values(), key=lambda r: r.date),
+        footprints=sorted(footprints.values(), key=lambda r: r.date),
+        automations=automations,
+    )

deeptutor/services/calendar/models.py

@@ -0,0 +1,311 @@
+"""Wire models for the account calendar.
+
+The encodings follow RFC 5545 so an ICS file maps onto them one to one:
+all-day events carry plain dates with an *exclusive* end date, timed events
+carry UTC instants on the wire and local wall time in ``tzid`` in storage.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import (
+    AfterValidator,
+    BaseModel,
+    ConfigDict,
+    Field,
+    StringConstraints,
+    field_validator,
+    model_validator,
+)
+
+from .recurrence import format_instant, format_rule, parse_date, parse_instant, parse_rule, zone
+
+CalendarColor = Annotated[str, StringConstraints(pattern=r"^#[0-9a-fA-F]{6}$")]
+CalendarName = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1, max_length=80)]
+EventTitle = Annotated[str, StringConstraints(strip_whitespace=True, max_length=200)]
+EventNotes = Annotated[str, StringConstraints(max_length=5000)]
+EventLocation = Annotated[str, StringConstraints(strip_whitespace=True, max_length=300)]
+Scope = Literal["this", "following", "all"]
+EventSource = Literal["user", "dito", "import"]
+
+# Minutes before the start. All-day events may also go negative, down to one
+# minute before the day ends: -540 reads "on the day at 09:00".
+MIN_REMINDER = -1439
+MAX_REMINDER = 40320  # four weeks
+MAX_REMINDERS = 5
+
+
+def _tzid(value: str) -> str:
+    zone(value)
+    return value
+
+
+def _rrule(value: str | None) -> str | None:
+    # Syntax only; UNTIL is normalised against the event's start in the store.
+    return None if value is None else format_rule(parse_rule(value))
+
+
+def _reminders(value: list[int]) -> list[int]:
+    unique = sorted(set(value))
+    if len(unique) > MAX_REMINDERS:
+        raise ValueError(f"At most {MAX_REMINDERS} reminders.")
+    if any(item < MIN_REMINDER or item > MAX_REMINDER for item in unique):
+        raise ValueError(f"Reminders must be between {MIN_REMINDER} and {MAX_REMINDER} minutes.")
+    return unique
+
+
+TimeZoneId = Annotated[str, StringConstraints(min_length=1, max_length=64), AfterValidator(_tzid)]
+RecurrenceRule = Annotated[str, StringConstraints(max_length=500), AfterValidator(_rrule)]
+Reminders = Annotated[list[int], Field(max_length=20), AfterValidator(_reminders)]
+Identifier = Annotated[str, StringConstraints(min_length=1, max_length=200)]
+
+
+def _reject_null(value: object) -> object:
+    if value is None:
+        raise ValueError("This field cannot be null.")
+    return value
+
+
+class CalendarEntry(BaseModel):
+    id: str
+    # Empty for the default calendar: the UI shows its localized name.
+    name: str
+    color: str
+    visible: bool
+    position: int
+    is_default: bool
+    created_at: str
+    updated_at: str
+
+
+class CreateCalendar(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: CalendarName
+    color: CalendarColor
+
+
+class UpdateCalendar(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: CalendarName | None = None
+    color: CalendarColor | None = None
+    visible: bool | None = None
+    position: int | None = Field(default=None, ge=0, le=100000)
+
+    @field_validator("name", "color", "visible", "position", mode="before")
+    @classmethod
+    def reject_null(cls, value: object) -> object:
+        return _reject_null(value)
+
+
+class EventInput(BaseModel):
+    """A new event, or the merged result of a patch before it is stored."""
+
+    model_config = ConfigDict(extra="forbid")
+    calendar_id: Identifier | None = None  # None: the default calendar
+    title: EventTitle = ""  # may be empty; the UI shows "Untitled"
+    notes: EventNotes = ""
+    location: EventLocation = ""
+    all_day: bool = False
+    # all_day: "YYYY-MM-DD" with an exclusive end; timed: instants with an
+    # offset or Z, normalised to "YYYY-MM-DDTHH:MM:SSZ".
+    start: str = Field(max_length=40)
+    end: str = Field(max_length=40)
+    tzid: TimeZoneId = "UTC"  # the browser's zone when the event was made
+    rrule: RecurrenceRule | None = None  # RFC 5545 RRULE value, no "RRULE:"
+    reminders: Reminders = Field(default_factory=list)
+    color: CalendarColor | None = None
+    task_id: Identifier | None = None  # a time block for a task card
+    task_workspace_id: str | None = Field(default=None, max_length=200)  # "" = General
+
+    @model_validator(mode="after")
+    def check_times(self) -> EventInput:
+        if self.all_day:
+            start, end = parse_date(self.start), parse_date(self.end)
+            self.start, self.end = start.isoformat(), end.isoformat()
+        else:
+            start, end = parse_instant(self.start), parse_instant(self.end)
+            self.start, self.end = format_instant(start), format_instant(end)
+        if end <= start:
+            raise ValueError("The end must be after the start.")
+        if not self.all_day and any(item < 0 for item in self.reminders):
+            raise ValueError("Only all-day events take reminders after the day starts.")
+        return self
+
+
+class EventPatch(BaseModel):
+    """Every field optional; explicit null clears rrule/color/task links only."""
+
+    model_config = ConfigDict(extra="forbid")
+    calendar_id: Identifier | None = None
+    title: EventTitle | None = None
+    notes: EventNotes | None = None
+    location: EventLocation | None = None
+    all_day: bool | None = None
+    start: str | None = Field(default=None, max_length=40)
+    end: str | None = Field(default=None, max_length=40)
+    tzid: TimeZoneId | None = None
+    rrule: RecurrenceRule | None = None
+    reminders: Reminders | None = None
+    color: CalendarColor | None = None
+    task_id: Identifier | None = None
+    task_workspace_id: str | None = Field(default=None, max_length=200)
+
+    @field_validator(
+        "calendar_id",
+        "title",
+        "notes",
+        "location",
+        "all_day",
+        "start",
+        "end",
+        "tzid",
+        "reminders",
+        mode="before",
+    )
+    @classmethod
+    def reject_null(cls, value: object) -> object:
+        return _reject_null(value)
+
+
+class EventPatchRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    changes: EventPatch
+    scope: Scope = "all"
+    # The occurrence key being edited. With it, ``changes.start``/``end`` are
+    # that occurrence's new times rather than the series' first instance.
+    occurrence: str | None = Field(default=None, max_length=40)
+
+
+class CalendarEvent(BaseModel):
+    """A stored master or override row."""
+
+    id: str
+    calendar_id: str
+    title: str
+    notes: str
+    location: str
+    all_day: bool
+    start: str
+    end: str
+    tzid: str
+    rrule: str | None
+    exdates: list[str]
+    reminders: list[int]
+    color: str | None
+    task_id: str | None
+    task_workspace_id: str | None
+    series_id: str | None  # override rows: the master's id
+    recurrence_id: str | None  # override rows: the occurrence key it replaces
+    source: EventSource = "user"
+    created_at: str
+    updated_at: str
+
+
+class Occurrence(BaseModel):
+    """One rendered instance of a stored event."""
+
+    id: str  # f"{event_id}:{occurrence}", unique per instance
+    event_id: str  # the row to PATCH/DELETE: master, override or single event
+    series_id: str | None  # the master when part of a recurring series
+    occurrence: str  # all-day: original start date; timed: original start in UTC
+    recurring: bool
+    calendar_id: str
+    title: str
+    notes: str
+    location: str
+    all_day: bool
+    start: str
+    end: str
+    tzid: str
+    rrule: str | None  # the series' rule
+    reminders: list[int]
+    color: str | None
+    task_id: str | None
+    task_workspace_id: str | None
+    source: EventSource = "user"
+
+    reminder_times: list[str] = Field(default_factory=list)
+
+
+class CalendarSearchHit(CalendarEvent):
+    # The next instance at or after now; a past single event keeps its start.
+    next_start: str | None = None
+
+
+class CalendarList(BaseModel):
+    calendars: list[CalendarEntry]
+    revision: int
+
+
+class CalendarResponse(BaseModel):
+    calendar: CalendarEntry
+    revision: int
+
+
+class CalendarRevision(BaseModel):
+    revision: int
+
+
+class OccurrenceList(BaseModel):
+    occurrences: list[Occurrence]
+    revision: int
+
+
+class CalendarEventResponse(BaseModel):
+    event: CalendarEvent
+    revision: int
+
+
+class CalendarSearchResponse(BaseModel):
+    events: list[CalendarSearchHit]
+
+
+class ReviewPathCount(BaseModel):
+    id: str
+    title: str
+    count: int
+
+
+class ReviewDay(BaseModel):
+    date: str
+    mastery: int = 0
+    practice: int = 0
+    paths: list[ReviewPathCount] = Field(default_factory=list)
+
+
+class AutomationRun(BaseModel):
+    id: str  # f"{job_id}:{at}"
+    job_id: str
+    name: str
+    message: str
+    at: str  # UTC instant
+    kind: Literal["at", "every", "cron"]
+    expr: str | None = None
+    every_seconds: int | None = None
+    session_id: str | None = None
+    enabled: bool = True
+
+
+class FootprintSession(BaseModel):
+    id: str
+    title: str
+
+
+class FootprintDay(BaseModel):
+    date: str
+    session_count: int = 0
+    sessions: list[FootprintSession] = Field(default_factory=list)
+    practice_reviews: int = 0
+    mastery_evidence: int = 0
+
+
+class CalendarLayers(BaseModel):
+    workspace_id: str
+    reviews: list[ReviewDay] = Field(default_factory=list)
+    automations: list[AutomationRun] = Field(default_factory=list)
+    footprints: list[FootprintDay] = Field(default_factory=list)
+
+
+class CalendarOk(BaseModel):
+    ok: bool = True