Source: oshun/minerva/minerva/models/ (20 files + schemas/) Analysis date:
2026-02-28 Purpose: Field-level detail for porting to @metis/models
TypeScript + Zod
Overview#
- Total models: 100+
- Total enums: 80+
- Total diff types: 35+
- Largest file:
actions.py (60KB, 35+ diff types)
- Lazy loading:
__getattr__ + _LazyDict for circular dep avoidance
Content Hierarchy#
text
Course
└─ Topic[]
└─ SubTopic[]
├─ Lesson[]
│ └─ Section[] (text, media, citations)
├─ Quiz (0-1)
│ └─ QuizQuestion[]
│ └─ Section[] (stems + options)
├─ ProjectAssignment[]
├─ DiagnosticAssessment[]
└─ StudyAidBundle (0-1)
├─ FlashcardSet → Flashcard[]
├─ DiscussionPrompt[]
├─ RealWorldApplication[]
└─ CollaborativeTask[]
ConceptGraph
├─ ConceptNode[]
└─ ConceptEdge[] (prerequisite | develops_into | related)
Presentation
└─ Slide[]
└─ ContainerElement
├─ TextElement
├─ DiagramElement
└─ ContainerElement (nested)
Core Structure Models#
Course#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| title |
string |
required |
min_length=1 |
| description |
string |
required |
min_length=1 |
| version |
int |
1 |
ge=0 |
| thumbnail |
string |
default URL |
|
| topics |
Topic[] |
[] |
|
| prerequisite_concepts |
string[] |
[] |
|
| concept_graph |
ConceptGraph? |
null |
|
| knowledge_graph |
KnowledgeGraph? |
null |
|
| glossary |
GlossaryTerm[] |
[] |
|
| metadata |
Record<string, any> |
{} |
|
| syllabus_content |
string? |
null |
transient, excluded from serialization |
Legacy aliases: course_name → title, course_id → id
Topic#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| title |
string |
required |
min_length=1 |
| description |
string |
required |
min_length=1 |
| difficulty_level |
"introductory" | "intermediate" | "advanced" |
|
|
| learning_objectives |
string[] |
[] |
|
| concept_prerequisites |
string[] |
[] |
|
| concept_node_ids |
string[] |
[] |
|
| other_details |
TopicOtherDetails |
{} |
|
| order |
int |
0 |
|
| sub_topics |
SubTopic[] |
[] |
|
SubTopic#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| title |
string |
required |
min_length=1 |
| description |
string |
required |
min_length=1 |
| order |
int |
0 |
|
| lessons |
Lesson[] |
[] |
|
| quiz |
Quiz? |
null |
|
| learning_objectives |
string[] |
[] |
|
| projects |
ProjectAssignment[] |
[] |
|
| diagnostics |
DiagnosticAssessment[] |
[] |
|
| study_aid_bundle |
StudyAidBundle? |
null |
|
| concept_node_ids |
string[] |
[] |
|
Lesson#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| title |
string |
required |
min_length=1 |
| order |
int |
0 |
|
| sections |
Section[] |
[] |
|
| learning_objectives |
string[] |
[] |
|
| difficulty_variants |
Record<string, string> |
{} |
|
| concept_node_ids |
string[] |
[] |
|
| prior_knowledge_check |
string? |
null |
|
| analogy |
string? |
null |
|
Section#
| Field |
Type |
Default |
Constraints |
| id |
string |
SHA256 hash |
auto-generated from content |
| type |
SectionType |
TEXT |
|
| text |
string |
"" |
markdown content |
| url |
string |
"" |
media URL |
| json_data |
any? |
null |
|
| citations |
string[] |
[] |
|
| order |
int |
0 |
|
| duration |
int? |
null |
|
| emotion_hints |
Record<string, string> |
{} |
TTS delivery guidance |
SectionType enum (17 values): TEXT, VIDEO, AUDIO, IMAGE, CODE, EXAMPLE,
APPLICATION, HISTORICAL_CONTEXT, LEARNING_ACTIVITY, DIAGRAM,
DIAGRAM_WITH_TRANSITIONS, ANIMATION_SEQUENCE, ANIMATION_SEQUENCE_DYNAMIC,
COMPLETE_ANIMATION_SEQUENCE, HTML_EMBEDDED_STANDALONE, HTML_EMBEDDED_SEQUENCE,
HOOK, WORKED_EXAMPLE, COMMON_MISTAKE, SUMMARY, PRACTICE
Assessment Models#
Quiz#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| text |
string |
required |
min_length=1, alias "title" |
| questions |
QuizQuestion[] |
[] |
|
| duration |
int? |
null |
|
| difficulty_level |
string? |
null |
|
| instruction |
string? |
null |
|
QuizQuestion#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| sections |
Section[] |
[] |
question stems |
| options |
Section[] |
[] |
answer choices |
| correct_option_id |
string |
"" |
alias "answer" |
| answer_explanation |
string? |
null |
|
| order |
int |
0 |
|
| marks |
int? |
null |
|
ProjectAssignment#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| title |
string |
required |
min_length=1 |
| description |
string |
required |
min_length=1 |
| context |
string |
"" |
localized context |
| learning_objective_ids |
string[] |
[] |
|
| deliverables |
string[] |
[] |
|
| milestones |
ProjectMilestone[] |
[] |
|
| evaluation_criteria |
string[] |
[] |
|
| collaboration_mode |
"individual" | "pair" | "team" |
|
|
| estimated_minutes |
int |
180 |
ge=30 |
DiagnosticAssessment#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| title |
string |
required |
min_length=1 |
| description |
string |
required |
min_length=1 |
| learning_objective_ids |
string[] |
[] |
|
| blueprint |
DiagnosticBlueprintEntry[] |
[] |
|
| follow_up_actions |
string[] |
[] |
|
| estimated_minutes |
int |
25 |
ge=5 |
Study Aid Models#
StudyAidBundle#
| Field |
Type |
Default |
Constraints |
| summary |
string |
required |
min_length=15 |
| flashcard_set |
FlashcardSet |
required |
|
| discussion_prompts |
DiscussionPrompt[] |
required |
min_length=1 |
| real_world_applications |
RealWorldApplication[] |
required |
min_length=1 |
| collaborative_tasks |
CollaborativeTask[] |
required |
min_length=1 |
| recommended_sequence |
string[] |
auto |
|
Flashcard#
| Field |
Type |
Default |
Constraints |
| prompt |
string |
required |
min_length=5 |
| answer |
string |
required |
min_length=5 |
| context |
string? |
null |
|
| tags |
string[] |
[] |
|
| difficulty |
"remember" | "understand" | "apply" | "analyze" |
|
|
DiscussionPrompt#
| Field |
Type |
Default |
Constraints |
| prompt |
string |
required |
min_length=10 |
| facilitation_notes |
string |
required |
min_length=10 |
| follow_up_questions |
string[] |
required |
min_length=1 |
| duration_minutes |
int |
15 |
ge=5, le=60 |
| collaboration_mode |
"individual" | "pairs" | "small_group" |
|
|
| learning_objective_ids |
string[] |
[] |
|
Concept Graph Models#
ConceptNode#
| Field |
Type |
Default |
Constraints |
| id |
string |
UUID |
auto-generated |
| name |
string |
required |
min_length=1 |
| description |
string |
required |
min_length=1 |
| review_priority |
int |
0 |
0-10 |
| suggested_review_interval_days |
int |
7 |
ge=0 |
ConceptEdge#
| Field |
Type |
Default |
Constraints |
| source_id |
string |
required |
|
| target_id |
string |
required |
|
| relationship |
RelationshipType |
required |
50+ NL variants auto-mapped |
RelationshipType: PREREQUISITE, DEVELOPS_INTO, RELATED (with 50+ natural
language mappings)
Presentation#
| Field |
Type |
Default |
| id |
string |
UUID prefix "presentation_" |
| slides |
Slide[] |
[] |
Slide#
| Field |
Type |
Default |
| id |
string |
UUID prefix "slide_" |
| container |
ContainerElement |
required |
| duration |
int |
4000 (ms) |
| transition_type |
TransitionType |
FADE |
| audio_url |
string? |
null |
ContainerElement / TextElement / DiagramElement#
Recursive DOM-like structure with to_html() serialization.
DiagramType: ANGLE, VENN, POLYGON, GRAPH AnimationType: INFINITE_PULSE,
INFINITE_GLOW, INFINITE_BOUNCE, INFINITE_WIGGLE, INFINITE_ROTATE
TransitionType: FADE, SLIDE, ZOOM, FLIP
Actions / Diff Types (Discriminated Unions)#
CourseAction (11 values)#
ADD_TOPIC, ADD_CONCEPT_NODE, ADD_CONCEPT_EDGE, ADD_GLOSSARY_TERM,
EDIT_COURSE_DETAILS, EDIT_TOPIC_DETAILS, LINK_ELEMENT_TO_CONCEPT,
DELETE_ELEMENT, MOVE_ELEMENT, MERGE_ELEMENTS, NO_ACTION_NEEDED
TopicAction (45 values)#
Full set of add/edit/refine/delete/move/merge/generate/patch actions for all
content types.
Key Diff Types#
- Structural: AddTopicDiff, AddSubTopicDiff, AddLessonDiff, AddSectionDiff
- Content: EditSectionContentDiff, RefineSectionContentDiff,
EditLessonTitleDiff
- Assessment: AddQuizToSubtopicDiff, AddQuizQuestionDiff,
RefineQuizQuestionDiff, AddProjectAssignmentDiff, AddDiagnosticAssessmentDiff,
AddStudyAidBundleDiff
- Organization: DeleteElementDiff, MoveElementDiff, MergeElementsDiff,
SplitElementDiff
- Media: GenerateDiagramForSectionDiff, PatchHtmlEmbeddedDiagramDiff,
UpdatePresentationDiff
- Concept: AddConceptNodeDiff, AddConceptEdgeDiff, LinkElementToConceptDiff
All use discriminated union on action field.
Findings / Quality Models#
LinterFinding#
| Field |
Type |
Constraints |
| finding_type |
string |
e.g. "PLACEHOLDER_TEXT_FOUND" |
| message |
string |
human-readable |
| description |
string? |
detailed explanation |
| target_ids |
string[] |
affected element IDs |
| topic_id |
string? |
parent topic |
| category |
FindingCategory |
13 values |
| severity |
"LOW" | "MEDIUM" | "HIGH" | "CRITICAL" |
|
| linter_name |
string? |
provenance |
FindingCategory: COURSE_STRUCTURE, CONTENT, ASSESSMENT, FACT_CHECKING,
ENGAGEMENT, STRUCTURE, LEARNING_OBJECTIVES, TECHNICAL_ACCURACY,
FACTUAL_ACCURACY, MULTI_MODAL_CONSISTENCY, READABILITY, CONTENT_QUALITY,
CURRICULUM_ALIGNMENT
Type Resolution Maps#
MODEL_NAME_TO_CLASS#
Maps string → model class: Course, Topic, SubTopic, Lesson, Section, Quiz,
QuizQuestion, ProjectAssignment, DiagnosticAssessment
ELEMENT_TYPE_TO_CLASS#
Maps ElementType enum → model class
VALID_PARENT_CHILD_MAP#
Defines content hierarchy constraints:
- Course → [Topic]
- Topic → [SubTopic]
- SubTopic → [Lesson, Quiz]
- Lesson → [Section]
- Quiz → [QuizQuestion]
- QuizQuestion → [Section]
ACTION_TO_EXPECTED_ID_TYPE_MAP#
Maps action names → expected parent/target ID types (30+ mappings)
Key Patterns for TypeScript Porting#
- Discriminated unions —
action field as discriminator for Diff types →
TypeScript union with type guards
- Zod validation — Field constraints (min_length, ge, le, literal types) →
Zod schemas
- UUID generation — Auto-generated IDs →
crypto.randomUUID()
- SHA256 content hashing — Section ID generation → Node.js crypto
- Legacy field migration — Validators that rename old fields → Zod
transform/preprocess
- Natural language enum mapping — 50+ relationship variants → lookup
table + fallback
- Recursive structures — Container/TextElement/DiagramElement → TypeScript
recursive types