# 25.1.1.4 — Minerva Data Models Catalog

> 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

```
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
