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#
- ReAct agent framework — Clean base with tool support, state, context window
- Multi-agent debate/consensus — CurriculumAgent → ModeratorAgent pattern
- Comprehensive evaluation — Rubric-based, persona-based, multi-dimensional
- IRT-based mastery tracking — Sophisticated learner modeling
- Affective/metacognitive modeling — Rare, high-value for edtech
- Query decomposition — Breaking complex research into sub-queries
- Fact verification with credibility — Source quality, not just content
- Diagram generation pipeline — Strategy → Data → Spec → Evaluate
- Lean mathematical verification — Formal proof checking
- Reasoning strategy plugins — CoT, ToT, Self-Consistency, Reflexion
- Learning style detection — VARK, Felder-Silverman
- Collaborative dialogue types — Socratic, Debate, Collaborative, Expert-Novice
Technical Debt to DISCARD#
- Monolithic agents — AITutorAgent (4,359), AssessmentAgent (2,292), ContentAgent (1,866) need decomposition
- Broken adapters — MediaAgentAdapter, StoryboardAgentAdapter imported but undefined
- Code duplication — CitationAnalyzer in 2 locations (1,285 lines each), FactCheckingAgent duplicates AdvancedResearch
- No agent registry — No centralized way to discover/instantiate agents
- Hardcoded constants — 100+ thresholds in AITutorAgent alone
- Synchronous communication — Protocol handlers are sync, need async event bus
- Opaque judge logic — ModeratorAgent's decision criteria not visible
- No plugin system — Agent strategies hardcoded, not pluggable
- Token estimation by chars — Should use actual tokenizer (tiktoken)
- No async event propagation — All agent-to-agent communication is synchronous