Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(reading): accept video playback time in the reading viewport

jiangbianshu07cf021d345e
diff --git a/deeptutor/core/turn_request.py b/deeptutor/core/turn_request.py
index af1f95582..84f12ed3a 100644
--- a/deeptutor/core/turn_request.py
+++ b/deeptutor/core/turn_request.py
@@ -69,6 +69,8 @@ class ReadingViewport(BaseModel):
locator: int | None = Field(default=None, ge=0)
selection: str | None = None
+ # Playback position of a video material, reported by the reader on each turn.
+ time_seconds: float | None = Field(default=None, ge=0)
class TimedMediaViewport(BaseModel):
diff --git a/deeptutor/services/session/_turn_runtime_shared.py b/deeptutor/services/session/_turn_runtime_shared.py
index 1ea10c547..3250cabe9 100644
--- a/deeptutor/services/session/_turn_runtime_shared.py
+++ b/deeptutor/services/session/_turn_runtime_shared.py
@@ -8,6 +8,7 @@ import asyncio
from collections.abc import Sequence
from dataclasses import dataclass, field
import logging
+import math
import re
from typing import TYPE_CHECKING, Any, Literal
import unicodedata
@@ -624,10 +625,11 @@ def _reading_workspace_id(value: Any) -> str:
def _reading_viewport(value: Any) -> dict[str, Any]:
"""Normalize what the reader reports it is showing.
- Both fields are optional: a freshly opened document has no locator yet, and
- most turns carry no selection. Absent keys are omitted rather than zeroed so
- the capability's prompt block can distinguish "nothing selected" from an
- empty selection.
+ Every field is optional: a freshly opened document has no locator yet, most
+ turns carry no selection, and only video materials report a playback time.
+ Absent keys are omitted rather than zeroed so the capability's prompt block
+ can distinguish "nothing selected" from an empty selection, and "no media
+ time" from a video paused at 0:00.
"""
if not isinstance(value, dict):
return {}
@@ -641,6 +643,14 @@ def _reading_viewport(value: Any) -> dict[str, Any]:
selection = str(value.get("selection") or "").strip()
if selection:
viewport["selection"] = selection[:READING_SELECTION_MAX_CHARS]
+ raw_seconds = value.get("time_seconds")
+ if raw_seconds is not None and not isinstance(raw_seconds, bool):
+ try:
+ seconds = float(raw_seconds)
+ except (TypeError, ValueError):
+ seconds = -1.0
+ if math.isfinite(seconds) and seconds >= 0:
+ viewport["time_seconds"] = min(24 * 60 * 60, seconds)
return viewport
diff --git a/tests/reading/test_turn_wiring.py b/tests/reading/test_turn_wiring.py
index d770067fc..f0f248626 100644
--- a/tests/reading/test_turn_wiring.py
+++ b/tests/reading/test_turn_wiring.py
@@ -95,6 +95,52 @@ def test_selection_is_bounded_because_it_enters_the_prompt() -> None:
assert len(viewport["selection"]) == READING_SELECTION_MAX_CHARS
+def test_video_viewport_keeps_the_playback_time() -> None:
+ """A video question is grounded at the moment the learner paused on."""
+ assert _reading_viewport({"locator": 7, "time_seconds": 600.461}) == {
+ "locator": 7,
+ "time_seconds": 600.461,
+ }
+ # 0:00 is a real position, not an absent one.
+ assert _reading_viewport({"time_seconds": 0}) == {"time_seconds": 0.0}
+ assert _reading_viewport({"time_seconds": 10**9}) == {"time_seconds": 24 * 60 * 60}
+
+
[email protected]("value", [-1, "abc", float("nan"), float("inf"), True, None])
+def test_nonsense_playback_times_are_dropped(value: object) -> None:
+ assert _reading_viewport({"locator": 2, "time_seconds": value}) == {"locator": 2}
+
+
+def test_start_turn_accepts_the_video_viewport_the_reader_sends() -> None:
+ """The reader reports playback time on every video turn; rejecting it at
+ the protocol boundary left every question about a video unsent."""
+ from pydantic import ValidationError
+
+ from deeptutor.api.contracts.turn_protocol import StartTurnCommand
+
+ command = StartTurnCommand.model_validate(
+ {
+ "type": "start_turn",
+ "protocol_version": "2.0",
+ "content": "What does this part mean?",
+ "workspace_mode": "immersive_reading",
+ "reading_viewport": {"locator": 7, "time_seconds": 600.461},
+ }
+ )
+ assert command.reading_viewport is not None
+ assert command.reading_viewport.time_seconds == 600.461
+
+ with pytest.raises(ValidationError):
+ StartTurnCommand.model_validate(
+ {
+ "type": "start_turn",
+ "protocol_version": "2.0",
+ "content": "hi",
+ "reading_viewport": {"locator": 7, "unknown": 1},
+ }
+ )
+
+
def test_explicit_reading_references_are_normalized_at_the_turn_boundary() -> None:
assert _reading_references(
[
diff --git a/web/contracts/generated/api.ts b/web/contracts/generated/api.ts
index ed1073d60..be8bda337 100644
--- a/web/contracts/generated/api.ts
+++ b/web/contracts/generated/api.ts
@@ -15083,6 +15083,11 @@ export interface components {
* @default null
*/
readonly selection: string | null;
+ /**
+ * Time Seconds
+ * @default null
+ */
+ readonly time_seconds: number | null;
};
/** RebuildBookRequest */
readonly RebuildBookRequest: {
diff --git a/web/contracts/generated/turn-protocol.ts b/web/contracts/generated/turn-protocol.ts
index 08b0ccb61..2dcbe96be 100644
--- a/web/contracts/generated/turn-protocol.ts
+++ b/web/contracts/generated/turn-protocol.ts
@@ -73,6 +73,7 @@ export type Revision = number;
export type ReadingReferences = ReadingReference[];
export type Locator = number | null;
export type Selection = string | null;
+export type TimeSeconds = number | null;
export type ReadingWorkspaceId = string | null;
export type Regenerate = boolean;
export type RegeneratedFromMessageId = number | string | null;
@@ -85,7 +86,7 @@ export type Skills = string[];
export type SubagentConsultBudget = number | null;
export type SupersededTurnId = string | null;
export type TimedMediaId = string | null;
-export type TimeSeconds = number;
+export type TimeSeconds1 = number;
export type Tools = string[] | null;
export type Type1 = "message" | "start_turn";
export type WorkspaceId = string | null;
@@ -411,13 +412,14 @@ export interface ReadingReference {
export interface ReadingViewport {
locator?: Locator;
selection?: Selection;
+ time_seconds?: TimeSeconds;
}
/**
* This interface was referenced by `TurnProtocolDocument`'s JSON-Schema
* via the `definition` "TimedMediaViewport".
*/
export interface TimedMediaViewport {
- time_seconds: TimeSeconds;
+ time_seconds: TimeSeconds1;
}
/**
* This interface was referenced by `TurnProtocolDocument`'s JSON-Schema
diff --git a/web/contracts/schema/openapi.json b/web/contracts/schema/openapi.json
index 7a514cd92..d2601a70b 100644
--- a/web/contracts/schema/openapi.json
+++ b/web/contracts/schema/openapi.json
@@ -8401,6 +8401,19 @@
],
"default": null,
"title": "Selection"
+ },
+ "time_seconds": {
+ "anyOf": [
+ {
+ "minimum": 0,
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Time Seconds"
}
},
"title": "ReadingViewport",
diff --git a/web/contracts/schema/turn-protocol.json b/web/contracts/schema/turn-protocol.json
index 540b7abbf..2714636ca 100644
--- a/web/contracts/schema/turn-protocol.json
+++ b/web/contracts/schema/turn-protocol.json
@@ -509,6 +509,19 @@
],
"default": null,
"title": "Selection"
+ },
+ "time_seconds": {
+ "anyOf": [
+ {
+ "minimum": 0,
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Time Seconds"
}
},
"title": "ReadingViewport",