Eve library

25.1.1.4 — Minerva Data Models Catalog

Guide

Revision 1

On this page

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)


Rich Media Models#

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#

  1. Discriminated unions — action field as discriminator for Diff types → TypeScript union with type guards
  2. Zod validation — Field constraints (min_length, ge, le, literal types) → Zod schemas
  3. UUID generation — Auto-generated IDs → crypto.randomUUID()
  4. SHA256 content hashing — Section ID generation → Node.js crypto
  5. Legacy field migration — Validators that rename old fields → Zod transform/preprocess
  6. Natural language enum mapping — 50+ relationship variants → lookup table + fallback
  7. Recursive structures — Container/TextElement/DiagramElement → TypeScript recursive types