Source:
oshun/minerva/minerva/{research,learning,database,cli}/Analysis date: 2026-02-28
1. Research Subsystem (60+ files, 39 directories)#
Architecture#
- Core:
DeepResearchAgentorchestrates web search, fact extraction, pedagogical analysis - Knowledge Graph: Entity/relationship extraction with Neo4j + Weaviate
- 8 Monitoring Systems: WebChangeMonitor, CoverageCompletenessTracker, FeedAggregator, DataFreshnessTracker, DocumentVersionMonitor, UpdateProcessor, NotificationService
Features to Keep#
- Multi-source web search (DuckDuckGo, Wikipedia, custom APIs)
- Knowledge graph with entity/relationship extraction
- Fact verification with credibility scoring
- Curriculum alignment mapping
- Notification system (email, webhook, in-app)
Debt to Discard#
- Neo4j client (migrate to PostgreSQL AGE)
- Weaviate client (migrate to pgvector)
- Over-parameterized monitoring (700+ exports)
- Duplicate alert handlers
2. Learning Subsystem (118 files, 57 directories)#
Architecture#
- Adaptive Engine (43KB): Cognitive load management + spaced repetition
- Learning Styles: VARK + Felder-Silverman dimensions
- Prerequisite Graph (18 files): Circular dependency detection, topological sequencing
- Difficulty Scaling: 5 difficulty levels with readability scoring
- Drag-Drop Activities: Multi-window synchronization
- Peer Matching: Collaborative learning pairing
- Multi-Armed Bandits: Content selection algorithms
Features to Keep#
- Prerequisite knowledge graphs with validation
- Adaptive learning with cognitive load theory
- VARK + Felder-Silverman assessment/adaptation
- Spaced repetition with forgetting curves
- Peer learning matching
- Drag-drop interactive activities
- Learning path optimization (topological ordering)
- Difficulty-based content variants
Debt to Discard#
- Tone adapter (partially implemented)
- Confidence coach (deprecated)
- Over-parameterized adaptive config
- Unused content selector variants
- Legacy bandit implementations
3. Database Subsystem (28 files, 5 directories)#
Supported Backends#
- PostgreSQL (primary) with pgvector + Apache AGE
- MongoDB (document storage)
- Redis (caching/queues)
Features to Keep#
- Multi-database abstraction layer
- Async connection pooling with metrics
- Repository pattern implementation
- Transaction support with rollback
- Bulk operations interface
- Vector embeddings (pgvector)
- Backup/restore with verification
- Sharding support
Debt to Discard#
- Neo4j bindings (use PostgreSQL AGE)
- Weaviate vector DB (use pgvector)
- Over-engineered fallback strategies
4. CLI Subsystem (57 files, 13 subdirectories)#
Command Hierarchy#
text
minerva-lite
├── batch ............. Batch course generation
├── run ............... Single course generation
│ └── resume ....... Resume paused run
├── status ............ Show run status
├── health ............ Service health check
├── research/* ........ Deep research workflows
├── monitor/* ......... Monitoring dashboards
├── documentation/* ... Documentation export
├── config/* .......... Configuration management
├── workflow/* ........ Workflow import/export
├── gpu/* ............. GPU infrastructure
├── infra/* ........... Docker/compose management
├── runpod/* .......... RunPod serverless
├── textbook/* ........ Textbook export
├── providers ......... LLM provider testing
├── validate .......... Configuration validation
└── tui ............... Text UI interface
Features to Keep#
- Multi-level command hierarchy
- Batch processing with resume
- Research command suite
- Health/status checks
- Configuration management
- Workflow import/export
- GPU management (RunPod)
Debt to Discard#
- Legacy wizard interface
- Unused output formatters
- Over-engineered progress tracking
5. Dependencies (117 Production)#
By Category#
| Category | Count | Key Packages |
|---|---|---|
| LLM/AI | 11 | litellm, anthropic, transformers, torch, peft |
| Database | 15 | psycopg2, asyncpg, sqlalchemy, redis, motor (mongo), boto3 |
| Web/Async | 7 | fastapi, aiohttp, websockets, httpx |
| CLI/Config | 5 | typer, pydantic, pyyaml |
| Research | 8 | networkx, sympy, ddgs, tavily, wikipedia |
| Text/Docs | 12 | textstat, nltk, spacy, pymupdf, tabula, python-docx |
| Multimedia | 8 | pillow, opencv, scikit-learn, google-apis |
| Security | 15 | bcrypt, cryptography, authlib, passlib, google-auth |
| Utilities | 14 | psutil, numba, lz4, chemistry, girth |
| Scheduling | 3 | croniter, ray, babel |
Heavy Dependencies (GPU/ML)#
- torch==2.6.0 — 2GB+ with CUDA, required for TTS/ML
- transformers — Hugging Face models
- mediapipe — Computer vision
- ray — Distributed computing
- opencv — Image processing
Overlaps with Oshun Shared Libraries#
- Database abstractions → @oshun/database
- LLM providers → @psyche/tavus-pipecat
- Web framework → @oshun/web-server
- Authentication → @oshun/auth
- Caching → @oshun/cache
- Storage (S3) → @oshun/storage