DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
import { apiFetch, apiUrl } from "@/lib/api";
export type VideoProvider = "youtube" | "invidious";
export interface TranscriptCue {
start: number;
end: number;
text: string;
}
export type VideoMark = VideoLearningMark;
export type SuggestedVideoMark = VideoMarkSuggestion;
export interface TimedSegment extends TranscriptCue {
locator: number;
}
export type VideoPlayback =
| {
provider: "youtube";
kind: "youtube_iframe";
video_id: string;
start_seconds: number;
}
| {
provider: "invidious";
kind: "html5";
format_id: string;
mime_type: string;
stream_url: string;
subtitles_url: string;
start_seconds: number;
};
export interface TimedMediaMaterial {
version: number;
type: "timed_media";
material_id: string;
source: {
provider: "youtube";
video_id: string;
url: string;
entry_time_seconds: number;
};
metadata: {
title: string;
author: string;
duration_seconds: number;
thumbnail_url?: string;
};
transcript: {
status: "ready" | "unavailable";
reason: string;
language: string;
source: string;
cues: TranscriptCue[];
};
segments: TimedSegment[];
learning: { last_position: number; marks?: VideoLearningMark[] };
playback: VideoPlayback;
}
export type VideoMarkKind = "key_point" | "question" | "review";
export type VideoMarkAuthor = "user" | "assistant";
export type VideoMarkSource = "immersive";
export interface VideoLearningMark {
mark_id: string;
kind: VideoMarkKind;
start_seconds: number;
end_seconds: number;
start_locator: number;
end_locator: number;
quote: string;
note: string;
author: VideoMarkAuthor;
source?: VideoMarkSource;
metadata?: Record<string, unknown>;
created_at: string;
updated_at: string;
reviewed_at?: string;
}
export interface VideoMarkSuggestion {
kind: VideoMarkKind;
start_seconds: number;
end_seconds: number;
start_locator: number;
end_locator: number;
quote: string;
note: string;
author: VideoMarkAuthor;
}
export interface VideoNote {
notebook_id: string;
note_id: string;
material_id: string;
body: string;
time_seconds: number;
locator: number;
quote: string;
created_at: number;
updated_at: number;
}
export interface VideoLearningSettings {
version: 1;
default_provider: VideoProvider;
youtube: { transcript_provider: "youtube_transcript_api" | "none" };
invidious: { api_base_url: string; public_base_url: string };
}
async function unwrap<T>(response: Response): Promise<T> {
if (!response.ok) {
throw await responseError(response);
}
return (await response.json()) as T;
}
async function responseError(response: Response): Promise<Error> {
const payload = await response.json().catch(() => ({}));
const detail = (payload as { detail?: unknown })?.detail;
const message =
typeof detail === "string"
? detail
: typeof (detail as { message?: unknown } | undefined)?.message ===
"string"
? (detail as { message: string }).message
: null;
return new Error(message || `Request failed (${response.status})`);
}
async function unwrapText(response: Response): Promise<string> {
if (!response.ok) {
throw await responseError(response);
}
return response.text();
}
export async function listVideoNotes(materialId: string): Promise<VideoNote[]> {
return unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/notes`,
),
{ cache: "no-store" },
),
);
}
export async function createVideoNote(
materialId: string,
body: string,
timeSeconds: number,
): Promise<VideoNote> {
return unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/notes`,
),
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ body, time_seconds: timeSeconds }),
},
),
);
}
export async function exportVideoNotes(materialId: string): Promise<string> {
return unwrapText(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/notes.md`,
),
{ cache: "no-store" },
),
);
}
export async function updateVideoNote(
materialId: string,
noteId: string,
body: string,
): Promise<VideoNote> {
return unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/notes/${encodeURIComponent(noteId)}`,
),
{
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ body }),
},
),
);
}
export async function deleteVideoNote(
materialId: string,
noteId: string,
): Promise<void> {
await unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/notes/${encodeURIComponent(noteId)}`,
),
{ method: "DELETE" },
),
);
}
export async function resolveVideo(
url: string,
language = "",
providerOverride?: VideoProvider,
): Promise<TimedMediaMaterial> {
return unwrap(
await apiFetch(apiUrl("/api/video-learning/materials/resolve"), {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
url,
language,
...(providerOverride ? { provider_override: providerOverride } : {}),
}),
}),
);
}
export async function getVideoMaterial(
materialId: string,
): Promise<TimedMediaMaterial> {
return unwrap(
await apiFetch(
apiUrl(`/api/video-learning/materials/${encodeURIComponent(materialId)}`),
{
cache: "no-store",
},
),
);
}
export async function refreshInvidiousTranscript(
materialId: string,
): Promise<TimedMediaMaterial> {
return unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/transcript/refresh`,
),
{ method: "POST" },
),
);
}
export async function saveVideoProgress(
materialId: string,
timeSeconds: number,
durationSeconds: number,
): Promise<void> {
await unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/progress`,
),
{
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
time_seconds: Math.max(0, timeSeconds),
duration_seconds: Math.max(0, durationSeconds),
}),
},
),
);
}
export async function listVideoMarks(
materialId: string,
): Promise<VideoLearningMark[]> {
return unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/marks`,
),
{ cache: "no-store" },
),
);
}
export async function createVideoMark(
materialId: string,
payload: {
kind: VideoMarkKind;
start_seconds: number;
end_seconds?: number | null;
start_locator?: number;
end_locator?: number;
quote?: string;
note?: string;
},
): Promise<VideoLearningMark> {
return unwrap(
await apiFetch(
apiUrl(`/api/video-learning/materials/${encodeURIComponent(materialId)}/marks`),
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload),
},
),
);
}
export async function updateVideoMark(
materialId: string,
markId: string,
payload: Partial<{ reviewed: boolean; note: string }>,
): Promise<VideoLearningMark> {
return unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/marks/${encodeURIComponent(markId)}`,
),
{
method: "PATCH",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload),
},
),
);
}
export async function deleteVideoMark(
materialId: string,
markId: string,
): Promise<void> {
await unwrap(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/marks/${encodeURIComponent(markId)}`,
),
{ method: "DELETE" },
),
);
}
export async function suggestVideoMarks(
materialId: string,
timeSeconds = 0,
): Promise<VideoMarkSuggestion[]> {
const payload = await unwrap<{ suggestions: VideoMarkSuggestion[] }>(
await apiFetch(
apiUrl(
`/api/video-learning/materials/${encodeURIComponent(materialId)}/mark-suggestions`,
),
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ time_seconds: timeSeconds }),
},
),
);
return payload.suggestions || [];
}
export async function getVideoLearningSettings(): Promise<VideoLearningSettings> {
return unwrap(
await apiFetch(apiUrl("/api/settings/video-learning"), {
cache: "no-store",
}),
);
}
export async function saveVideoLearningSettings(
settings: VideoLearningSettings,
): Promise<VideoLearningSettings> {
return unwrap(
await apiFetch(apiUrl("/api/settings/video-learning"), {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(settings),
}),
);
}
export async function testInvidious(
settings: VideoLearningSettings,
): Promise<{ ok: boolean; message: string }> {
return unwrap(
await apiFetch(apiUrl("/api/settings/video-learning/test-invidious"), {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(settings),
}),
);
}
export interface InvidiousAccountStatus {
connected: boolean;
needs_reauthorization?: boolean;
}
export interface InvidiousVideo {
videoId: string;
title: string;
author: string;
lengthSeconds: number;
videoThumbnails?: { url: string }[];
}
export interface InvidiousPlaylist {
playlistId: string;
title: string;
videoCount: number;
videos?: InvidiousVideo[];
}
export interface InvidiousCatalog {
videos?: InvidiousVideo[];
}
export async function invidiousAccount(
action: "status" | "authorize" | "disconnect",
) {
return unwrap<InvidiousAccountStatus & { authorize_url?: string }>(
await apiFetch(`/api/video-learning/invidious/account/${action}`, {
method: action === "status" ? "GET" : "POST",
cache: "no-store",
}),
);
}
export async function browseInvidious(
kind: string,
query: string,
page: number,
playlistId: string,
signal: AbortSignal,
) {
const params = new URLSearchParams({
q: query,
page: String(page),
playlist_id: playlistId,
});
return unwrap<InvidiousVideo[] | InvidiousPlaylist[] | InvidiousCatalog>(
await apiFetch(`/api/video-learning/invidious/browse/${kind}?${params}`, {
signal,
cache: "no-store",
}),
);
}