# 25.1.1.7-10 — Research, Learning, Database, CLI Analysis

> Source: `oshun/minerva/minerva/{research,learning,database,cli}/` Analysis
> date: 2026-02-28

---

## 1. Research Subsystem (60+ files, 39 directories)

### Architecture

- **Core:** `DeepResearchAgent` orchestrates 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

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