createStudySession

Builds a timed study agenda from your content for a given durationMinutes.

Two phases: (1) the model plans topic, goals, tips, block sequence, and a material allocation; (2) materials are generated via createLearningSet() from that allocation. Render with <StudySession />, or compose your own UI from blocks and materials (see Study session flow).

Usage

import { createStudySession } from "edu-sdk";

const session = await createStudySession({
  model: "google/gemini-3.6-flash",
  content,
  durationMinutes: 45,
  difficulty: "medium",
});

Options

content may be a string or FileContent (PDF / text / markdown bytes).

Goal seeding

1. If you pass goals, those seed the plan.
2. Else if learnerContext.focusAreas is set, those seed preferred goals.
3. Otherwise the model derives goals from the content.

When topic is provided, it seeds the plan topic; otherwise the model derives it from the content.

Personalization

When learnerContext is set:

• The plan biases time and active practice (quiz, practice problems, flashcards) toward weaker or focus topics, and less toward strong areas.
• The same learnerContext is forwarded into createLearningSet() so generated materials are personalized too.

See Personalization.

Returns

Promise<Artifact<StudySessionContent>>

{
  id: string;
  title: string;
  description?: string;
  metadata: {
    createdAt: string;
    model: string;
    difficulty: "easy" | "medium" | "hard";
  };
  content: {
    topic: string;
    goals: string[];
    totalDurationMinutes: number;
    tips: string[];
    blocks: StudySessionBlock[];
    materials: LearningSetContent;
  };
}

Blocks

Each block:

{
  id: string;
  type:
    | "read"
    | "notes"
    | "studyGuide"
    | "flashcards"
    | "quiz"
    | "practiceProblems"
    | "break"
    | "review";
  title: string;
  durationMinutes: number;
  instructions: string;
  materialKey?:
    | "quiz"
    | "flashcards"
    | "practiceProblems"
    | "notes"
    | "studyGuide";
}

Block durations are normalized to match durationMinutes. Gaps within ±5 minutes are adjusted on the last non-break block; larger mismatches throw InvalidInputError.

materialKey must only reference a material type that was allocated. The SDK validates that before generating materials.

Materials

materials is a LearningSetContent object (nested full artifacts). The model decides which types to include and in what quantity based on duration, difficulty, content, and optional learnerContext. If nothing is allocated, materials is {}.

Example

import { createStudySession } from "edu-sdk";

const session = await createStudySession({
  model: "google/gemini-3.6-flash",
  content: chapterText,
  durationMinutes: 60,
  topic: "Ohm's law",
  goals: ["Explain voltage, current, and resistance"],
  difficulty: "easy",
});

const { blocks, materials, tips } = session.content;
const quiz = materials.quiz; // Artifact<QuizQuestion[]> | undefined
// <Quiz questions={quiz!.content} />

Invalid input throws InvalidInputError (for example durationMinutes outside 5–240, empty content, or plan/allocation mismatches).

Next: <StudySession /> or Study session flow for wiring blocks to React.