@fenixforce/edition-voices 0.1.0

package/dist/teacher/corpus-importer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Corpus Importer — Types and pipeline interface for the Fenix Voices
+ * content import system.
+ *
+ * Defines the CorpusItem entity and the shared importer contract that
+ * CSV, JSON, and future importers implement.
+ */
+export type ContentType = "proverb" | "dialogue" | "vocabulary_list" | "grammar_explanation" | "article" | "roleplay" | "exercise_template" | "story" | "song_lyrics";
+export type CorpusSource = "ejiogbe" | "imported" | "scraped" | "synthetic";
+export type ReviewStatus = "approved" | "unreviewed" | "rejected";
+export type CorpusLevel = "pre-A1" | "A1" | "A2" | "B1" | "B2" | "C1" | "C2" | "unclassified";
+export interface CorpusItem {
+    id: string;
+    language: string;
+    contentType: ContentType;
+    level: CorpusLevel;
+    title?: string;
+    content: string;
+    translation?: string;
+    bridgeLanguage?: string;
+    tags: string[];
+    source: CorpusSource;
+    reviewStatus: ReviewStatus;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+export interface ImportResult {
+    imported: number;
+    skipped: number;
+    errors: string[];
+}
+export interface CorpusImporter {
+    /** Parse raw input and return validated CorpusItems. */
+    parse(raw: string): CorpusItem[];
+}
+export declare function isValidContentType(v: string): v is ContentType;
+export declare function isValidLevel(v: string): v is CorpusLevel;
+export declare function isValidLanguageCode(v: string): boolean;
+export declare function normalizeLanguageCode(v: string): string;
+/**
+ * Validates a partial CorpusItem object and returns an array of error
+ * messages. Empty array means valid.
+ */
+export declare function validateCorpusItem(item: Record<string, unknown>): string[];

package/dist/teacher/corpus-storage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Corpus Storage — PostgreSQL operations for the Fenix Voices corpus.
+ *
+ * Provides:
+ *   - Migration SQL for corpus_items table with pgvector embedding, GIN tags
+ *   - importBatch() — bulk insert with embedding generation
+ *   - search() — hybrid search (vector + full-text) with dual search fusion
+ *   - getRandomItems() — random selection for exercise variety
+ *   - tagContent() / classifyLevel() — content annotation
+ */
+import { Kysely } from "kysely";
+import type { CorpusItem, ImportResult } from "./corpus-importer.js";
+export type EmbedBatchFn = (texts: string[]) => Promise<(number[] | null)[]>;
+export declare function runCorpusMigration(db: Kysely<any>): Promise<string[]>;
+export declare function importBatch(db: Kysely<any>, items: CorpusItem[], embedFn?: EmbedBatchFn): Promise<ImportResult>;
+export interface CorpusSearchFilters {
+    language?: string;
+    level?: string;
+    contentType?: string;
+    tags?: string[];
+    reviewStatus?: string;
+}
+export interface CorpusSearchResult {
+    item: CorpusItem;
+    score: number;
+}
+export declare function search(db: Kysely<any>, query: string, queryEmbedding: number[] | null, filters?: CorpusSearchFilters, limit?: number, vectorWeight?: number, textWeight?: number): Promise<CorpusSearchResult[]>;
+export declare function getRandomItems(db: Kysely<any>, filters?: CorpusSearchFilters, count?: number): Promise<CorpusItem[]>;
+export declare function tagContent(db: Kysely<any>, id: string, tags: string[]): Promise<void>;
+export declare function classifyLevel(db: Kysely<any>, id: string, level: string): Promise<void>;
+export declare function getCorpusItem(db: Kysely<any>, id: string): Promise<CorpusItem | null>;

package/dist/teacher/curriculum/generator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Curriculum Generator — Generates curriculum templates via LLM
+ * when no template exists for a requested language.
+ */
+import { Kysely } from "kysely";
+import type { CurriculumTemplate } from "./schema.js";
+export type LLMGenerateObjectFn<T> = (prompt: string) => Promise<T>;
+export declare function buildGenerationPrompt(language: string, isoCode: string, corpusCount: number, corpusSample: string[]): string;
+export declare function generateTemplate(language: string, isoCode: string, corpusCount: number, corpusSample: string[], generateFn: LLMGenerateObjectFn<CurriculumTemplate>): Promise<CurriculumTemplate>;
+/**
+ * Generate a template and save it to the database.
+ */
+export declare function generateAndSaveTemplate(db: Kysely<any>, language: string, isoCode: string, corpusCount: number, corpusSample: string[], generateFn: LLMGenerateObjectFn<CurriculumTemplate>): Promise<CurriculumTemplate>;

package/dist/teacher/curriculum/loader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Curriculum Loader — Template management for loading, saving,
+ * and listing curriculum templates.
+ *
+ * Templates are loaded from disk (data/curricula/*.json) or from the
+ * curriculum_templates PostgreSQL table. Database takes precedence.
+ */
+import { Kysely } from "kysely";
+import type { CurriculumTemplate } from "./schema.js";
+export declare function runCurriculumMigration(db: Kysely<any>): Promise<string[]>;
+export declare function loadTemplateFromDisk(language: string, dir?: string): CurriculumTemplate | null;
+export declare function getTemplate(db: Kysely<any>, language: string, diskDir?: string): Promise<CurriculumTemplate | null>;
+export declare function saveTemplate(db: Kysely<any>, template: CurriculumTemplate): Promise<void>;
+export declare function listAvailableLanguages(db: Kysely<any>, diskDir?: string): Promise<string[]>;

package/dist/teacher/curriculum/progress-tracker.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Progress Tracker — Tracks learner advancement through a curriculum.
+ *
+ * Manages unit completion, prerequisite checking, and score-based
+ * advancement decisions.
+ */
+import { Kysely } from "kysely";
+import type { LearnerProgress } from "./schema.js";
+import type { CurriculumTemplate, CurriculumUnit } from "./schema.js";
+export declare function runProgressMigration(db: Kysely<any>): Promise<string[]>;
+export declare function getProgress(db: Kysely<any>, learnerId: string, language: string): Promise<LearnerProgress | null>;
+export declare function initProgress(db: Kysely<any>, learnerId: string, language: string, firstUnitId: string): Promise<LearnerProgress>;
+/**
+ * Check whether the learner should advance to the next unit based on
+ * their average score in the current unit.
+ */
+export declare function shouldAdvance(progress: LearnerProgress, threshold?: number): boolean;
+/**
+ * Check whether all prerequisite units for a given unit are completed.
+ */
+export declare function prerequisitesMet(unit: CurriculumUnit, completedUnits: string[]): boolean;
+/**
+ * Find the next unit the learner should move to, respecting prerequisites
+ * and CEFR level ordering.
+ */
+export declare function findNextUnit(template: CurriculumTemplate, completedUnits: string[]): CurriculumUnit | null;
+/**
+ * Mark the current unit as complete and advance to the next one.
+ * Returns null if the curriculum is complete or prerequisites block advancement.
+ */
+export declare function advanceUnit(db: Kysely<any>, learnerId: string, template: CurriculumTemplate): Promise<LearnerProgress | null>;
+/**
+ * Record a score for the current unit.
+ */
+export declare function recordUnitScore(db: Kysely<any>, learnerId: string, language: string, unitId: string, score: number): Promise<void>;

package/dist/teacher/curriculum/schema.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Curriculum Template Schema — Defines the structure for language
+ * curriculum templates and learner progress tracking.
+ */
+import type { CEFRLevel } from "../learner-model.js";
+export interface CurriculumTemplate {
+    language: string;
+    version: string;
+    author?: string;
+    units: CurriculumUnit[];
+}
+export interface CurriculumUnit {
+    id: string;
+    title: string;
+    level: CEFRLevel;
+    objectives: string[];
+    vocabularyTargets: string[];
+    grammarTargets: string[];
+    culturalContext?: string;
+    prerequisiteUnits: string[];
+    estimatedSessions: number;
+    exerciseTypeWeights: Record<string, number>;
+}
+export interface LearnerProgress {
+    learnerId: string;
+    templateLanguage: string;
+    completedUnits: string[];
+    currentUnitId: string;
+    currentSession: number;
+    unitScores: Record<string, number>;
+}
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+export declare function validateTemplate(obj: unknown): ValidationError[];

package/dist/teacher/exercises/builders/dialogue.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Dialogue Roleplay — Multi-turn conversation. Agent plays one role,
+ * learner plays the other. speechRequired when voice enabled.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const dialogueRoleplay: ExerciseBuilder;

package/dist/teacher/exercises/builders/dictation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Dictation — TTS plays phrase, learner types what they heard.
+ * audioRequired: true.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const dictation: ExerciseBuilder;

package/dist/teacher/exercises/builders/error-correction.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Error Correction — Show sentence with deliberate error, learner
+ * identifies and fixes it.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const errorCorrection: ExerciseBuilder;

package/dist/teacher/exercises/builders/fill-in-blank.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Fill in the Blank — Sentence with a gap. Masks a target word from corpus.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const fillInBlank: ExerciseBuilder;

package/dist/teacher/exercises/builders/listening.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Listening Comprehension — TTS renders a passage, learner answers
+ * comprehension questions. audioRequired: true.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const listeningComprehension: ExerciseBuilder;

package/dist/teacher/exercises/builders/pronunciation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pronunciation — TTS renders target phrase, learner speaks,
+ * STT transcribes for comparison. audioRequired + speechRequired.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const pronunciation: ExerciseBuilder;

package/dist/teacher/exercises/builders/reading.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reading Comprehension — Display passage, ask comprehension questions.
+ * Pulls from corpus articles/stories.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const readingComprehension: ExerciseBuilder;

package/dist/teacher/exercises/builders/sentence-construction.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sentence Construction — Give scrambled words, learner arranges
+ * into correct sentence.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const sentenceConstruction: ExerciseBuilder;

package/dist/teacher/exercises/builders/translation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Translation — Forward (native → target) and reverse (target → native).
+ * Uses parallel text from corpus when available.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const translationForward: ExerciseBuilder;
+export declare const translationReverse: ExerciseBuilder;

package/dist/teacher/exercises/builders/vocabulary-drill.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Vocabulary Drill — Match word to definition. 4 options, 1 correct.
+ */
+import type { ExerciseBuilder } from "../generator.js";
+export declare const vocabularyDrill: ExerciseBuilder;

package/dist/teacher/exercises/generator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Exercise Generator — Produces concrete practice activities from
+ * planned exercises in a lesson plan.
+ */
+import type { LearnerProfile } from "../learner-model.js";
+import type { PlannedExercise } from "../skills/plan-lesson.js";
+export type ExerciseType = "vocabulary_drill" | "fill_in_blank" | "translation_forward" | "translation_reverse" | "listening_comprehension" | "pronunciation" | "dialogue_roleplay" | "reading_comprehension" | "dictation" | "sentence_construction" | "error_correction";
+export interface Exercise {
+    id: string;
+    type: ExerciseType;
+    prompt: string;
+    expectedAnswer?: string;
+    acceptableAnswers?: string[];
+    hints: string[];
+    difficulty: number;
+    targetVocabulary?: string[];
+    targetGrammar?: string[];
+    audioRequired: boolean;
+    speechRequired: boolean;
+    metadata: Record<string, unknown>;
+}
+/** Content fetched from the corpus for building an exercise. */
+export interface CorpusContent {
+    text: string;
+    translation?: string;
+    language: string;
+    level: string;
+    tags: string[];
+}
+/** Builder function signature — each exercise type implements one. */
+export type ExerciseBuilder = (content: CorpusContent, planned: PlannedExercise, learner: LearnerProfile, distractors?: string[]) => Exercise;
+export type ContentQueryFn = (query: string, language: string, level: string) => Promise<CorpusContent[]>;
+export type DistractorFn = (language: string, level: string, exclude: string[], count: number) => Promise<string[]>;
+export type LLMFallbackFn = (type: string, language: string, level: string, targets: string[]) => Promise<CorpusContent>;
+export declare function resolveExerciseType(raw: string): ExerciseType;
+export declare function needsAudio(type: ExerciseType): boolean;
+export declare function needsSpeech(type: ExerciseType, voiceEnabled: boolean): boolean;
+export interface GenerateExerciseDeps {
+    queryContent: ContentQueryFn;
+    getDistractors?: DistractorFn;
+    llmFallback?: LLMFallbackFn;
+    builders: Map<ExerciseType, ExerciseBuilder>;
+}
+export declare function generateExercise(deps: GenerateExerciseDeps, planned: PlannedExercise, learner: LearnerProfile): Promise<Exercise>;
+export declare function createBaseExercise(type: ExerciseType, planned: PlannedExercise, learner: LearnerProfile): Omit<Exercise, "prompt" | "expectedAnswer">;

package/dist/teacher/exercises/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Exercise Builder Registry — Maps ExerciseType to builder functions.
+ */
+import type { ExerciseType, ExerciseBuilder } from "./generator.js";
+export { generateExercise, resolveExerciseType, needsAudio, needsSpeech, createBaseExercise } from "./generator.js";
+export type { Exercise, ExerciseType, ExerciseBuilder, CorpusContent, GenerateExerciseDeps } from "./generator.js";
+export declare const EXERCISE_BUILDERS: Map<ExerciseType, ExerciseBuilder>;

package/dist/teacher/importers/csv-importer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CSV Importer — Parses CSV datasets into CorpusItems.
+ *
+ * Supports:
+ *   - instruction/input/response column format
+ *   - Parallel text format (English + target language columns)
+ *   - Auto-detection of content type from column structure
+ *   - Custom column mapping
+ */
+import type { CorpusItem, ContentType, CorpusImporter } from "../corpus-importer.js";
+export declare function parseCSV(raw: string): Record<string, string>[];
+export interface CSVImportOptions {
+    language?: string;
+    bridgeLanguage?: string;
+    defaultContentType?: ContentType;
+    columnMap?: Record<string, string>;
+}
+export declare class CsvImporter implements CorpusImporter {
+    private opts;
+    constructor(opts?: CSVImportOptions);
+    parse(raw: string): CorpusItem[];
+}

package/dist/teacher/importers/json-importer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * JSON Importer — Parses JSON corpus files into validated CorpusItems.
+ *
+ * Accepts arrays of CorpusItem-compatible objects, validates required fields,
+ * normalizes language codes to ISO 639, and returns clean CorpusItems ready
+ * for batch embedding and insert.
+ */
+import type { CorpusItem, CorpusImporter } from "../corpus-importer.js";
+export declare class JsonImporter implements CorpusImporter {
+    parse(raw: string): CorpusItem[];
+}

package/dist/teacher/learner-model.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Learner Model — TypeScript interfaces for the Fenix Voices teacher layer.
+ *
+ * Defines the four core entities: LearnerProfile, VocabEntry,
+ * GrammarEntry, and SessionRecord.
+ */
+export type CEFRLevel = 'pre-A1' | 'A1' | 'A2' | 'B1' | 'B2' | 'C1' | 'C2';
+export type CorrectionStyle = 'gentle' | 'direct' | 'socratic';
+export type PracticeFrequency = 'daily' | 'every-other-day' | 'weekly' | 'on-demand';
+export interface LearnerPreferences {
+    sessionDuration: number;
+    exerciseTypes: string[];
+    voiceEnabled: boolean;
+    correctionStyle: CorrectionStyle;
+    practiceFrequency: PracticeFrequency;
+    timezone: string;
+    preferredPracticeTime?: string;
+}
+export interface LearnerStats {
+    totalSessions: number;
+    totalExercises: number;
+    currentStreak: number;
+    longestStreak: number;
+    lastSessionAt?: string;
+}
+export interface LearnerProfile {
+    id: string;
+    userId: string;
+    targetLanguage: string;
+    nativeLanguage: string;
+    bridgeLanguage?: string;
+    currentLevel: CEFRLevel;
+    goals: string[];
+    preferences: LearnerPreferences;
+    stats: LearnerStats;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface VocabEntry {
+    id: string;
+    learnerId: string;
+    word: string;
+    targetLanguage: string;
+    translation: string;
+    mastery: number;
+    nextReviewAt: string;
+    reviewCount: number;
+    lastReviewedAt?: string;
+    context?: string;
+}
+export interface GrammarEntry {
+    id: string;
+    learnerId: string;
+    concept: string;
+    targetLanguage: string;
+    mastery: number;
+    nextReviewAt: string;
+    reviewCount: number;
+    lastReviewedAt?: string;
+    notes?: string;
+}
+export interface SessionRecord {
+    id: string;
+    learnerId: string;
+    startedAt: string;
+    endedAt?: string;
+    unitId?: string;
+    exercisesCompleted: number;
+    averageScore: number;
+    newVocabulary: string[];
+    masteredItems: string[];
+    strugglingAreas: string[];
+    nextSessionFocus: string;
+}
+/** Compact learner stub surfaced to the agent context by default. */
+export interface LearnerStub {
+    learnerId: string;
+    targetLanguage: string;
+    currentLevel: CEFRLevel;
+    vocabCount: number;
+    recentFocus: string;
+    currentStreak: number;
+    lastSessionAt?: string;
+}

package/dist/teacher/learner-storage.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Learner Storage — PostgreSQL operations for the Fenix Voices teacher layer.
+ *
+ * Provides:
+ *   - Migration SQL for learner_profiles, vocab_entries, grammar_entries, session_records
+ *   - Full CRUD for all four tables
+ *   - getDueReviewItems() for spaced-repetition scheduling
+ *   - updateMastery() with SM-2 recalculation
+ *   - getProgressSummary() for dashboard aggregation
+ */
+import { Kysely } from "kysely";
+import type { LearnerProfile, VocabEntry, GrammarEntry, SessionRecord, LearnerStub } from "./learner-model.js";
+export declare function runLearnerMigration(db: Kysely<any>): Promise<string[]>;
+export declare function createLearnerProfile(db: Kysely<any>, profile: Omit<LearnerProfile, "id" | "createdAt" | "updatedAt">): Promise<LearnerProfile>;
+export declare function getLearnerProfile(db: Kysely<any>, id: string): Promise<LearnerProfile | null>;
+export declare function getLearnerProfileByUser(db: Kysely<any>, userId: string, targetLanguage: string): Promise<LearnerProfile | null>;
+export declare function updateLearnerProfile(db: Kysely<any>, id: string, updates: Partial<Pick<LearnerProfile, "currentLevel" | "goals" | "preferences" | "stats" | "bridgeLanguage">>): Promise<LearnerProfile | null>;
+export declare function deleteLearnerProfile(db: Kysely<any>, id: string): Promise<boolean>;
+export declare function createVocabEntry(db: Kysely<any>, entry: Omit<VocabEntry, "id">): Promise<VocabEntry>;
+export declare function getVocabEntry(db: Kysely<any>, id: string): Promise<VocabEntry | null>;
+export declare function deleteVocabEntry(db: Kysely<any>, id: string): Promise<boolean>;
+export declare function createGrammarEntry(db: Kysely<any>, entry: Omit<GrammarEntry, "id">): Promise<GrammarEntry>;
+export declare function getGrammarEntry(db: Kysely<any>, id: string): Promise<GrammarEntry | null>;
+export declare function deleteGrammarEntry(db: Kysely<any>, id: string): Promise<boolean>;
+export declare function createSessionRecord(db: Kysely<any>, record: Omit<SessionRecord, "id">): Promise<SessionRecord>;
+export declare function getSessionRecord(db: Kysely<any>, id: string): Promise<SessionRecord | null>;
+export declare function getSessionsByLearner(db: Kysely<any>, learnerId: string, limit?: number): Promise<SessionRecord[]>;
+export interface DueReviewItems {
+    vocab: VocabEntry[];
+    grammar: GrammarEntry[];
+}
+/**
+ * Returns vocab and grammar entries that are due for review
+ * (nextReviewAt <= now), ordered by next_review_at ascending.
+ */
+export declare function getDueReviewItems(db: Kysely<any>, learnerId: string, limit?: number): Promise<DueReviewItems>;
+/**
+ * Updates mastery for a vocab or grammar entry using SM-2 recalculation.
+ *
+ * @param table  — 'vocab_entries' or 'grammar_entries'
+ * @param entryId — The entry ID
+ * @param score  — Exercise score 0.0–1.0
+ */
+export declare function updateMastery(db: Kysely<any>, table: "vocab_entries" | "grammar_entries", entryId: string, score: number): Promise<void>;
+export interface ProgressSummary {
+    totalVocab: number;
+    masteredVocab: number;
+    totalGrammar: number;
+    masteredGrammar: number;
+    dueForReview: number;
+    totalSessions: number;
+    averageScore: number;
+    currentStreak: number;
+}
+export declare function getProgressSummary(db: Kysely<any>, learnerId: string): Promise<ProgressSummary>;
+/**
+ * Generates a compact learner stub for the agent context.
+ * This is the "progressive disclosure" entry point: the agent always sees the
+ * stub, and only fetches full profile/detail when it needs to plan a session.
+ */
+export declare function getLearnerStub(db: Kysely<any>, learnerId: string): Promise<LearnerStub | null>;

package/dist/teacher/level-classifier.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CEFR Level Classifier — Uses a utility LLM to classify corpus content
+ * into CEFR difficulty levels.
+ *
+ * Provides:
+ *   - classifyCEFRLevel() — single item classification
+ *   - batchClassify() — batch processing with cache
+ *   - enqueueClassification() — job queue integration
+ */
+import { Kysely } from "kysely";
+import type { CorpusLevel } from "./corpus-importer.js";
+export type LLMGenerateFn = (prompt: string) => Promise<string>;
+export declare function clearClassificationCache(): void;
+export declare function getCacheSize(): number;
+export declare function buildClassificationPrompt(content: string, language: string): string;
+export declare function parseLLMLevel(response: string): CorpusLevel;
+export declare function classifyCEFRLevel(content: string, language: string, generateFn: LLMGenerateFn): Promise<CorpusLevel>;
+export interface ClassifyJob {
+    id: string;
+    content: string;
+    language: string;
+}
+export interface ClassifyResult {
+    id: string;
+    level: CorpusLevel;
+    error?: string;
+}
+export declare function batchClassify(jobs: ClassifyJob[], generateFn: LLMGenerateFn): Promise<ClassifyResult[]>;
+export declare function enqueueClassification(db: Kysely<any>, itemIds: string[]): Promise<number>;
+/**
+ * Process a batch of enqueued classification jobs against the database.
+ * Updates each corpus item's level in place.
+ */
+export declare function processClassificationQueue(db: Kysely<any>, generateFn: LLMGenerateFn, batchSize?: number): Promise<ClassifyResult[]>;

package/dist/teacher/loop/message-builder.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Message Builder — Constructs MessageEnvelopes for the teaching loop.
+ *
+ * All messages route through the agent loop and channel router
+ * to the learner's preferred channel.
+ */
+import type { Exercise } from "../exercises/generator.js";
+import type { LearnerProfile } from "../learner-model.js";
+export interface MessageEnvelope {
+    channel: "scheduler";
+    learnerId: string;
+    type: "review" | "nudge" | "milestone";
+    subject: string;
+    body: string;
+    metadata: Record<string, unknown>;
+}
+export interface Milestone {
+    type: "vocabulary" | "streak" | "unit_completion";
+    value: number;
+}
+/**
+ * Format a review exercise for channel delivery.
+ */
+export declare function buildReviewMessage(exercise: Exercise, learner: LearnerProfile): MessageEnvelope;
+/**
+ * Build an encouraging nudge for inactive learners.
+ */
+export declare function buildNudgeMessage(learner: LearnerProfile, daysSinceLastSession: number): MessageEnvelope;
+/**
+ * Build a celebration message for reaching a milestone.
+ */
+export declare function buildMilestoneMessage(learner: LearnerProfile, milestone: Milestone): MessageEnvelope;

package/dist/teacher/loop/scheduler-integration.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Scheduler Integration — Registers teaching-loop cron jobs
+ * with the kernel's planned-tasks scheduler (Task 3.7).
+ *
+ * One cron job per active learner. Jobs are created, rescheduled,
+ * or removed in response to learner lifecycle events.
+ */
+import type { LearnerPreferences, PracticeFrequency } from "../learner-model.js";
+import type { TeachingLoopConfig, LoopOutcome } from "./teaching-loop.js";
+export interface CronJob {
+    id: string;
+    type: "teaching.loop";
+    learnerId: string;
+    schedule: string;
+    enabled: boolean;
+    createdAt: string;
+}
+export interface SchedulerDeps {
+    createJob: (job: Omit<CronJob, "id" | "createdAt">) => Promise<CronJob>;
+    updateJob: (jobId: string, updates: Partial<Pick<CronJob, "schedule" | "enabled">>) => Promise<CronJob>;
+    deleteJob: (jobId: string) => Promise<void>;
+    findJob: (learnerId: string, type: "teaching.loop") => Promise<CronJob | null>;
+    runLoop: (learnerId: string) => Promise<LoopOutcome>;
+}
+/**
+ * Convert learner practice frequency to a cron expression.
+ * Uses the config's defaultSchedule as fallback.
+ */
+export declare function frequencyToCron(frequency: PracticeFrequency, config?: TeachingLoopConfig): string;
+/**
+ * Register a cron job when a learner signs up.
+ */
+export declare function onLearnerCreated(deps: SchedulerDeps, learnerId: string, preferences: LearnerPreferences, config?: TeachingLoopConfig): Promise<CronJob | null>;
+/**
+ * Reschedule when a learner updates preferences.
+ */
+export declare function onPreferencesUpdated(deps: SchedulerDeps, learnerId: string, preferences: LearnerPreferences, config?: TeachingLoopConfig): Promise<CronJob | null>;
+/**
+ * Remove cron job when a learner disables the loop.
+ */
+export declare function onLoopDisabled(deps: SchedulerDeps, learnerId: string): Promise<void>;
+/**
+ * Execute a scheduled cron tick for a learner.
+ */
+export declare function onCronTick(deps: SchedulerDeps, learnerId: string): Promise<LoopOutcome>;