@seal-sdk/playable

Executable learning-flow orchestration for the SEAL SDK.

@seal-sdk/playable connects Activity, Session, Interaction, Evidence, Assessment, Progress and Mastery into a learner-facing activity flow.

Applications normally access this capability through PlatformBuilder().build().playable.

Installation

For the recommended Platform composition:

npm install @seal-sdk/platform

For direct custom composition:

npm install @seal-sdk/playable

Quick start

import {
  PlatformBuilder,
} from "@seal-sdk/platform";

const seal =
  new PlatformBuilder().build();

const activity = {
  id: "activity-1",
  title: "Build the sentence",
  type: "sentence-construction",
  level: "sentence",
  pattern: "SVO",
  availableUnits: [
    "music",
    "Anna",
    "likes",
  ],
  expectedUnits: [
    "Anna",
    "likes",
    "music",
  ],
  skillIds: [
    "basic-svo-construction",
  ],
};

seal.activity.register(activity);

const session =
  await seal.playable.startActivity({
    learnerId: "student-1",
    activityId: activity.id,
  });

const result =
  await seal.playable.submitAnswer({
    sessionId: session.sessionId,
    submittedUnits: [
      "Anna",
      "likes",
      "music",
    ],
  });

console.log(result.correct);
console.log(result.score);
console.log(result.mastery);
console.log(result.recommendation);

For presentation and text rendering, use @seal-sdk/playable-ui.

PlayableLearningFlow

PlayableLearningFlow is the public orchestration contract.

It exposes:

• startActivity(input);
• submitAnswer(input);
• findActivityForSkill(skillId).

The Platform exposes an implementation through platform.playable.

Starting an activity

startActivity(input)

Starts a Playable session for a learner and activity.

const session =
  await seal.playable.startActivity({
    learnerId: "student-1",
    activityId: "activity-1",
  });

The returned PlayableSession contains:

• sessionId;
• learnerId;
• activityId.

Submitting an answer

submitAnswer(input)

Submits ordered units for an active Playable session.

const result =
  await seal.playable.submitAnswer({
    sessionId: session.sessionId,
    submittedUnits: [
      "Anna",
      "likes",
      "music",
    ],
  });

The flow:

1. creates a submit-answer Interaction;
2. captures Evidence;
3. assesses the submitted units;
4. records Assessment progress for every activity skill;
5. updates Mastery for the primary skill;
6. produces unit feedback and a recommendation.

The returned PlayableTurnResult contains:

• correct;
• numeric score;
• feedback;
• mastery;
• unitFeedback;
• correctAnswer;
• recommendation;
• optional nextActivity;
• optional nextSession.

Recommendations

A PlayableRecommendation contains an action, skillId and reason.

Current actions are:

• continue: the activity skill is mastered or proficient;
• review: the answer is partially correct, or correct while mastery is still developing;
• retry: the answer is incorrect with no partial score.

When review finds another incomplete activity for the same skill, the result can include nextActivity and a newly created nextSession.

When continuing, an incomplete activity referenced by the current activity's nextActivityId can be returned in the same way.

Finding an activity by skill

findActivityForSkill(skillId)

Returns the first registered activity whose skillIds contains the requested skill.

const activity =
  await seal.playable.findActivityForSkill(
    "basic-svo-construction",
  );

The result is undefined when no matching activity exists.

Direct composition

DefaultPlayableLearningFlow is the default implementation of PlayableLearningFlow.

Its constructor requires these engine contracts:

• Activity;
• Session;
• Evidence;
• Assessment;
• Progress;
• Mastery.

Most applications should use PlatformBuilder, which creates and connects these dependencies. Direct construction is intended for custom composition.

Errors

submitAnswer() throws a SealError when:

• the Playable session does not exist;
• the registered activity cannot be found;
• the activity does not define a skill.

Public types

The package exports:

• StartActivityInput;
• PlayableSession;
• SubmitPlayableAnswerInput;
• PlayableUnitFeedback;
• PlayableRecommendation;
• PlayableTurnResult;
• PlayableLearningFlow;
• DefaultPlayableLearningFlow.