Eve library

25.1.1.2 — Minerva Agents Functional Taxonomy

Guide

Revision 1

On this page

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)#

text
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)#

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

2. Content Refinement (Sequential)#

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

3. Tutoring (Adaptive)#

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

4. Research & Fact-Checking#

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

5. Diagram Generation Pipeline#

text
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