# 25.1.1.2 — Minerva Agents Functional Taxonomy

> Source: `oshun/minerva/minerva/agents/` (120 files, ~48,000+ lines) Analysis
> date: 2026-02-28 Purpose: Categorize all agents, document capabilities,
> identify patterns for @metis/agents-types

---

## Overview

- **Total files:** 120 Python files across 5 subdirectories
- **Estimated LOC:** ~48,000+
- **Base framework:** `BaseAgent` (ABC) with ReAct loop pattern
- **Communication:** Multi-agent debate, blackboard architecture, message
  routing

---

## Agent Taxonomy

### Category 1: Orchestration & Coordination

| Agent               | Lines | Key Feature                                     |
| ------------------- | ----- | ----------------------------------------------- |
| CurriculumAgent     | 434   | Prerequisite-aware course structure planning    |
| ModeratorAgent      | 379   | Multi-agent debate synthesis and consensus      |
| CommunicationHub    | 1,164 | Central message router with conflict resolution |
| DialogueCoordinator | 520   | Multi-turn dialogue management                  |

### Category 2: Content Generation

| Agent                       | Lines | Key Feature                                 |
| --------------------------- | ----- | ------------------------------------------- |
| ContentAgent                | 1,866 | Pedagogical enrichment, scaffolding, media  |
| AssessmentAgent             | 2,292 | Quiz/assessment/rubric/study-aid generation |
| PedagogicalSectionGenerator | 426   | Section-level pedagogical templates         |

### Category 3: Quality Assurance

| Agent           | Lines | Key Feature                                      |
| --------------- | ----- | ------------------------------------------------ |
| CritiqueAgent   | 403   | Linter orchestration (programmatic + LLM)        |
| EvaluationAgent | 720   | Holistic rubric-based evaluation, bias detection |
| PersonaAgent    | —     | Stakeholder perspective evaluation               |

### Category 4: Tutoring & Adaptive Learning

| Agent                     | Lines | Key Feature                                      |
| ------------------------- | ----- | ------------------------------------------------ |
| AITutorAgent              | 4,359 | IRT mastery, affective modeling, personalization |
| AdaptiveLearningEngine    | 1,647 | ZPD-based difficulty adaptation                  |
| AffectiveStudentModel     | 796   | Emotional state tracking                         |
| LearningStyleApplicator   | 920   | VARK/Felder-Silverman detection                  |
| MetacognitiveScaffolder   | 604   | Meta-learning support                            |
| FormativeFeedbackEnhancer | 640   | Feedback generation                              |
| DynamicModeSelector       | 581   | Interaction mode selection                       |
| MultiTurnContextManager   | 852   | Conversation memory                              |

### Category 5: Research & Fact-Checking

| Agent                      | Lines  | Key Feature                     |
| -------------------------- | ------ | ------------------------------- |
| AdvancedResearchAgent      | 1,500+ | Query decomposition, web search |
| FactCheckingAgent          | ~400   | Web-based claim verification    |
| QueryDecomposer            | —      | Complex query breakdown         |
| CitationAnalyzer           | 1,285  | Source quality assessment       |
| ContradictionDetector      | —      | Conflicting claim resolution    |
| TemporalConsistencyChecker | —      | Timeline validation             |
| StatisticalValidator       | —      | Statistical claim checking      |
| CrossLanguageResearcher    | —      | Multi-lingual research          |

### Category 6: Multimedia & Diagrams

| Agent                         | Lines | Key Feature                            |
| ----------------------------- | ----- | -------------------------------------- |
| DiagramStrategistAgent        | 326   | Context-aware diagram planning         |
| DiagramDataAgent              | 507   | Data extraction/generation for visuals |
| DiagramSpecAuthorAgent        | 522   | Diagram specification writing          |
| DiagramEvaluationAgent        | ~200  | Overall diagram quality                |
| DiagramAccessibilityEvalAgent | ~200  | WCAG compliance checking               |
| DiagramConsistencyEvalAgent   | ~200  | Visual/data consistency                |
| DiagramPedagogyEvalAgent      | ~200  | Learning effectiveness                 |
| DiagramPlanningAgent          | —     | Pipeline orchestration                 |
| StoryboardAgent               | —     | Animated storyboard sequencing         |
| MultimodalAgent               | 1,221 | GPU-based media (images, audio, video) |

### Category 7: Reasoning & Verification

| Agent                   | Lines | Key Feature                         |
| ----------------------- | ----- | ----------------------------------- |
| ReasoningAgent          | 369   | Pluggable reasoning strategies      |
| LeanVerificationAgent   | 1,516 | Mathematical proof verification     |
| ChainOfThoughtStrategy  | —     | Step-by-step reasoning              |
| TreeOfThoughtsStrategy  | 490   | Multi-path exploration with pruning |
| SelfConsistencyStrategy | —     | Vote-based consensus                |
| ReflexionStrategy       | —     | Self-correction                     |

---

## Base Framework

### BaseAgent (1,379 lines)

```
AgentConfig
  model, max_retries, timeout, temperature, max_tokens
  enable_tools, persona, custom_params
  context_window_size, reserved_output_tokens, truncation_strategy

AgentState (thread-safe)
  status: PENDING | IN_PROGRESS | COMPLETED | FAILED
  execution_count, error_count, checkpoint_version

AgentResult
  reasoning, confidence, metadata
  thoughts, actions, observations (ReAct trace)
  errors, warnings

ContextWindowManager
  token estimation, truncation: sliding_window | keep_recent | summarize
```

**Key methods:** `invoke_tool()`, `execute_with_timeout()`,
`execute_with_retry()`, `save_state()`, `load_state()`, `cleanup()`

### ReActAgent (342 lines, extends BaseAgent)

Template method pattern: `_reason()` → `_act()` → `_observe()` → repeat →
`_extract_diff()`

---

## Multi-Agent Communication Flows

### 1. Curriculum Planning (Debate Pattern)

```
User Input → CurriculumAgent ×N (different personas)
  → Plan 1, Plan 2, ... Plan N
  → ModeratorAgent (aggregates + judges)
  → Winning Consensus Plan
```

### 2. Content Refinement (Sequential)

```
Course → CritiqueAgent (finds issues)
  → ContentAgent (refines based on findings)
  → EvaluationAgent (holistic check)
  → CritiqueAgent (re-evaluate)
  → [iterate until passing]
```

### 3. Tutoring (Adaptive)

```
Student Query → AITutorAgent
  ├→ Student Model (affect, metacognition, style)
  ├→ DynamicModeSelector (pick interaction mode)
  ├→ IRT Calculations (mastery estimation)
  └→ Personalized Response + Feedback Enhancement
```

### 4. Research & Fact-Checking

```
Content Claims → AdvancedResearchAgent
  ├→ QueryDecomposer → sub-queries
  ├→ FactChecker → verify each claim
  ├→ CitationAnalyzer → evaluate sources
  ├→ ContradictionDetector → find conflicts
  └→ TemporalConsistencyChecker → validate timeline
```

### 5. Diagram Generation Pipeline

```
Learning Objective → DiagramStrategist (plan)
  → DiagramData (extract data) → DiagramSpecAuthor (write spec)
  → DiagramPlanning (sequence) → Storyboard (animate)
  → [Evaluation Suite] (assess quality)
```

---

## Communication Protocol

- **AgentCommunicationHub:** Central message router
- **MultiAgentDebate:** Debate orchestration with fairness
- **AgentConflictResolver:** Conflict resolution strategies
- **AgentNegotiator:** Agent negotiation framework
- **AgentLoadBalancer:** Workload distribution
- **AgentTrustSystem:** Reputation tracking
- **BlackboardArchitecture:** Shared knowledge base

**Message types:** REQUEST, RESPONSE, PROPOSAL, NEGOTIATION, CONFLICT,
RESOLUTION

---

## Features to KEEP

1. **ReAct agent framework** — Clean base with tool support, state, context
   window
2. **Multi-agent debate/consensus** — CurriculumAgent → ModeratorAgent pattern
3. **Comprehensive evaluation** — Rubric-based, persona-based, multi-dimensional
4. **IRT-based mastery tracking** — Sophisticated learner modeling
5. **Affective/metacognitive modeling** — Rare, high-value for edtech
6. **Query decomposition** — Breaking complex research into sub-queries
7. **Fact verification with credibility** — Source quality, not just content
8. **Diagram generation pipeline** — Strategy → Data → Spec → Evaluate
9. **Lean mathematical verification** — Formal proof checking
10. **Reasoning strategy plugins** — CoT, ToT, Self-Consistency, Reflexion
11. **Learning style detection** — VARK, Felder-Silverman
12. **Collaborative dialogue types** — Socratic, Debate, Collaborative,
    Expert-Novice

## Technical Debt to DISCARD

1. **Monolithic agents** — AITutorAgent (4,359), AssessmentAgent (2,292),
   ContentAgent (1,866) need decomposition
2. **Broken adapters** — MediaAgentAdapter, StoryboardAgentAdapter imported but
   undefined
3. **Code duplication** — CitationAnalyzer in 2 locations (1,285 lines each),
   FactCheckingAgent duplicates AdvancedResearch
4. **No agent registry** — No centralized way to discover/instantiate agents
5. **Hardcoded constants** — 100+ thresholds in AITutorAgent alone
6. **Synchronous communication** — Protocol handlers are sync, need async event
   bus
7. **Opaque judge logic** — ModeratorAgent's decision criteria not visible
8. **No plugin system** — Agent strategies hardcoded, not pluggable
9. **Token estimation by chars** — Should use actual tokenizer (tiktoken)
10. **No async event propagation** — All agent-to-agent communication is
    synchronous
