# 25.1.1.1 — Minerva Python Module Inventory

> Source: `oshun/minerva/minerva/` (188 entries) Analysis date: 2026-02-28
> Purpose: Catalog every module, identify features to keep, flag technical debt
> to discard

---

## Module Classification Summary

| Category                | Modules                                                                                                                                          | Status                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| **Core Generation**     | generation/, generators/, course/, course*creation_assistant/, course_generator.py, enhanced_course_generator.py, course_generation*\*.py        | Active, high-value         |
| **Orchestration**       | orchestration/, unified_orchestrator\*.py (30+ files), typed_orchestrator.py                                                                     | Active but massive debt    |
| **Agents**              | agents/                                                                                                                                          | Active, core feature       |
| **Models & Schemas**    | models/, schemas/, model_utils.py                                                                                                                | Active, foundational       |
| **Validation**          | validation/, schema_validator.py                                                                                                                 | Active, comprehensive      |
| **Linters**             | linters/                                                                                                                                         | Active, 20+ linters        |
| **Diff/Patch**          | diff/, patch*engine.py, dict_to_diff_converter.py, rich_media*\*.py                                                                              | Active, critical           |
| **Multimedia**          | multimedia/, video/, diagram\*.py, storyboard/, audio/                                                                                           | Active, core feature       |
| **Research**            | research/, rag/, concept_graph/, knowledge/                                                                                                      | Active but over-engineered |
| **Learning**            | learning/, tutor/, assessment/, assessment_tools/                                                                                                | Active, key feature        |
| **LLM**                 | llm/, llm_utils.py, llm_operation_manager.py, providers/, prompts/                                                                               | Active, core               |
| **Infrastructure**      | database/, cache/, caching/, io/, file*io*\*.py, settings.py, config/                                                                            | Active, mixed quality      |
| **API**                 | api/                                                                                                                                             | Active, needs redesign     |
| **CLI/TUI**             | cli/, tui/                                                                                                                                       | Active                     |
| **Monitoring**          | monitoring/, monitoring\_\*.py, observability/, metrics/, tracking/, progress/                                                                   | Over-engineered            |
| **Optimization**        | optimization/, performance/, refinement/                                                                                                         | Feature creep              |
| **Compliance**          | compliance/, compliance_automation/                                                                                                              | Aspirational               |
| **Export/IO**           | export/, output/, book_exporter\*.py, io/                                                                                                        | Active                     |
| **Syllabus**            | syllabus/, syllabus\_\*.py, guidance/                                                                                                            | Active, Ghana-heavy        |
| **Document Processing** | document_processing/, byom/                                                                                                                      | Active, valuable           |
| **VLM**                 | vlm/                                                                                                                                             | Mostly stubs               |
| **Misc/Dead**           | content/, content_standards/, core/, data/, collaboration/, demo/                                                                                | Empty stubs                |
| **DevOps**              | devops/, devops_cli.py, dependency_health/                                                                                                       | Dev tooling                |
| **Security**            | security/, moderation/                                                                                                                           | Minimal                    |
| **Version**             | version_control/, version_manager.py, version_menu.py                                                                                            | Active                     |
| **Other**               | diversity/, visualization/, interaction.py, resources/, retry/, templates/, test_profiles.py, tools/, typings/, exceptions.py, run_tracking\*.py | Mixed                      |

---

## Detailed Module Analysis

### A — Accessibility

**`accessibility/`** — WCAG 2.1 AA compliance layer

- **Key exports:** `AccessibilityEngine`, `ARIAManager`, `ScreenReaderSupport`,
  `KeyboardNavigation`, `VisualAccessibility`, `ColorContrastChecker`,
  `CaptionGenerator`, `AudioAccessibility`, `CognitiveAccessibility`
- **Keep:** Full WCAG 2.1 AA framework, multi-modal accessibility (screen
  readers, captions, keyboard nav), semantic HTML/ARIA support, educational
  content-specific patterns
- **Debt:** Heavy side effects on import, coupling between features, no
  lazy-module loading

### A — Administration

**`administration/`** — System admin dashboard

- **Key exports:** `SystemAdministrationDashboard`, `UserManagementSystem`,
  `SystemHealthMonitor`, `ConfigurationManager`, `SecurityAuditLogger`,
  `ContentModerationSystem`, `SystemAnalyticsEngine`
- **Keep:** RBAC implementation, real-time health monitoring, audit logging
  (SOC2/GDPR/HIPAA patterns), role-based access
- **Debt:** Many features marked TODO, hard-coded alert thresholds,
  over-architected moderation, missing DI patterns

### A — Agents

**`agents/`** — Multi-agent ReAct system (75+ files)

- **Key exports:** `BaseAgent`, `CurriculumAgent`, `ContentAgent`,
  `AssessmentAgent`, `EvaluationAgent`, `CritiqueAgent`, `FactCheckingAgent`,
  `ModeratorAgent`, `LeanVerificationAgent`, `CollaborativeDialogue`
- **Keep:** ReAct agent pattern with tool support, modular agent design, Lean
  proof verification, collaborative dialogue system
- **Debt:** CRITICAL — `MediaAgentAdapter` and `StoryboardAgentAdapter` imported
  but undefined (broken refactor), no centralized agent registry, no explicit
  tool definitions, weak error handling/recovery

### A — Analysis

**`analysis/`** — Content analysis (concept extraction, readability, sentiment,
topics)

- **Key exports:** `ConceptExtractor`, `ConceptAnalyzer`, `ConceptGraphBuilder`,
  `KnowledgeGraph`, `ReadabilityAnalyzer`, `SentimentAnalyzer`,
  `ThemeExtractor`, `TopicModeler`
- **Keep:** Multi-strategy concept extraction, educational readability metrics,
  multilingual support, BERTopic/LDA modeling, knowledge graph building
- **Debt:** Many extractors are stubs, inconsistent error handling, no
  validation of extracted concepts

### A — Analytics

**`analytics/`** — Learning analytics (minimal)

- **Key exports:** `StudentRiskModel`, `RuleBasedRiskModel`,
  `StudentRiskPrediction`, `ModelArtifact`
- **Keep:** Rule-based risk model (interpretable, no ML deps), predictive
  student risk detection
- **Debt:** Only ~30 lines of imports, actual implementations delegated
  elsewhere, missing evaluation metrics

### A — API

**`api/`** — REST API layer

- **Key exports:** `AuthenticationManager`, `JWTManager`, `OAuthManager`,
  `SAMLManager`, `AuthorizationManager`, `RateLimitMiddleware`,
  `ValidationMiddleware`, `MonitoringMiddleware`, `CORSMiddleware`,
  `SecurityMiddleware`, `CourseModel`, `UserModel`, `APIResponse`
- **Keep:** Comprehensive auth framework (JWT, OAuth2, SAML), well-designed
  middleware stack, RFC 7807 error responses, RBAC integration
- **Debt:** Lazy loading via `__getattr__` masks import issues, no API
  versioning, no GraphQL, middleware stacking order undocumented

### A — Assessment / Assessment Tools

**`assessment/`** — Assessment and quiz system **`assessment_tools/`** —
Lightweight facade (1 line)

- **Keep:** Bloom's taxonomy integration, IRT (Item Response Theory), rubric
  types, peer review, adaptive testing
- **Debt:** `assessment_tools/` is an empty stub

### A — Attribution

**`attribution/`** — Source tracking and provenance

- **Key exports:** `ContextAttributionManager`, `SourceTracker`,
  `AttributionChain`, `SourceMetadata`, `UsageContext`
- **Keep:** Provenance tracking, context management
- **Debt:** Minimal implementation

### A — Audio

**`audio/`** — Audio processing

- **Keep:** TTS integration patterns, audio asset management
- **Debt:** Limited scope

### A — Audit

**`audit/`** — Simple audit logging

- **Key exports:** `record()`, `list_events()`, `purge_older_than()`
- **Keep:** Event recording pattern
- **Debt:** Too simple, needs enhancement

### A — Autonomous Tour

**`autonomous_tour/`** — Product tour with security scanning, ROI modeling

- **Key exports:** `AiExplanationGenerator`, `IndustryNarrativeCustomization`,
  `RealTimeDataAnalysis`, `RoiBusinessValue`, `TourSecurityScanner`
- **Keep:** None (over-engineered for a tour feature)
- **Debt:** Entire module is over-engineered, poor naming, unrelated concerns
  mixed

### B — Background

**`background/`** — Background job scheduling (pgcron, pgmq)

- **Key exports:** adapters, factory, jobs modules
- **Keep:** PostgreSQL queue integration patterns
- **Debt:** Old job queue patterns

### B — Batch Config

**`batch_config.py`** — Batch course processing configuration

- **Key exports:** `BatchConfig`, `CourseConfig`, `BatchProgress`,
  `CourseProgress`
- **Keep:** Comprehensive batch orchestration, YAML/JSON/Python config,
  round-robin processing, time budgets
- **Debt:** Over-parameterized (100+ options), needs simplification

### B — Book Exporter

**`book_exporter.py`**, **`book_exporter_models.py`** — Course → book.json
conversion

- **Keep:** Clean recursive conversion pipeline (Course → Topic → SubTopic →
  Lesson → Section)
- **Debt:** Assumes specific internal model structure, fragile

### B — BYOM (Bring Your Own Materials)

**`byom/`** — Multi-format document ingestion (30+ formats)

- **Key exports:** `DocumentParser`, `TextExtractor`, `MetadataExtractor`,
  `ContentProcessor`, `DocumentParserFacade`, `WebContentIntegrator`,
  `RSSFeedIntegrator`, `WikipediaProcessor`
- **Keep:** Multi-format processing, web scraping, citation management
- **Debt:** Over-engineered extractors, optional web integration via
  ImportError, metadata extraction incomplete

### C — Cache / Caching

**`cache/`** — LRU/TTL embedding cache + semantic cache **`caching/`** —
Enterprise multi-level caching (L1 memory, L2 Redis, L3 CDN)

- **Key exports (caching):** `CacheManager`, `MemoryCache`, `TTLCache`,
  `LRUCache`, `LFUCache`, `CacheInvalidationManager`, `CloudFrontIntegration`,
  `CloudflareIntegration`, `FastlyIntegration`
- **Keep:** Multi-level strategy, invalidation patterns (tag/time/event),
  predictive caching
- **Debt:** BROKEN — `cache_warming` and `distributed_cache` modules removed
  (reference non-existent `_core`), L2 Redis disabled, over-configured (195
  config keys), cache coherency incomplete

### C — CLI

**`cli/`** — Command-line interface (1,100+ lines)

- **Key commands:** batch, run, run-enhanced, run-resume, status, health,
  providers, validate, tui
- **Keep:** Well-structured subcommand system, batch orchestration,
  configuration management
- **Debt:** Massive **init**.py (bad modularity), fallback batch config parsing,
  lazy loading via `__getattr__`

### C — Collaboration

**`collaboration/`** — AI-human collaboration (NOT IMPLEMENTED)

- **Status:** Module ends after docstring. Complete stub.
- **Debt:** Delete entirely

### C — Common

**`common/`** — Shared utilities and base classes

- **Key exports:** `BaseAgent`, `BaseConnector`, `BaseLinter`, `BaseOptimizer`,
  `Course`, `Assessment`, `User`, text processing/validation/error handling
  utilities
- **Keep:** Reusable base patterns, data model foundations
- **Debt:** Traversal functions likely unused, heavy ABCs make testing harder

### C — Compliance / Compliance Automation

**`compliance/`** — Policy and regulatory monitoring (minimal, 4 files)
**`compliance_automation/`** — FERPA, SOC2, COPPA, GDPR, HIPAA (20+ files)

- **Keep:** Compliance patterns as reference
- **Debt:** Largely unimplemented (`compliance/`), too broad without focus
  (`compliance_automation/`)

### C — Concept Graph

**`concept_graph/`** — Concept extraction, prerequisite detection, ordering

- **Key exports:** `ConceptGraphBuilder`, `ConceptGraphService`,
  `ConceptOrderingEngine`, `ConceptGraphIntegrationService`
- **Keep:** Concept-based learning sequence validation
- **Debt:** Integration hooks suggest incomplete refactor

### C — Config

**`config/`** — Multi-region configuration with country profiles

- **Key exports:** `CountryProfile`, `get_country_profile()`,
  `list_available_countries()`
- **Keep:** Clean country/locale abstraction
- **Debt:** Minimal, needs expansion for non-Ghana locales

### C — Content / Content Standards

**`content/`** — EMPTY (1-line docstring) **`content_standards/`** — EMPTY
(`__all__ = []`)

- **Debt:** Both are stubs. Delete entirely.

### C — Core

**`core/`** — Legacy import compatibility shims (docstring only)

- **Debt:** Legacy cruft. Delete entirely.

### C — Course

**`course/`** — Course orchestration facade

- **Key exports:** `CourseGenerator`, `generate_or_load_course` (from
  orchestrator)
- **Keep:** Clean facade pattern
- **Debt:** Lazy loading masks circular deps, deprecation warning for
  `CourseOrchestrator` should be removed (break cleanly)

### C — Course Creation Assistant

**`course_creation_assistant/`** — Rapid course building and quality assessment

- **Key exports:** `RapidCourseBuilder`, `ContentAggregator`, `QualityAssessor`
- **Keep:** Template-based course generation, content aggregation
- **Debt:** Research components orthogonal to course creation, over-engineered,
  citation manager tightly coupled

### C — Course Generation Files

**`course_generation_ghana.py`** — Ghana curriculum
**`course_generation_math_specs.py`** — Math domain specifics
**`course_generation_syllabus.py`** — Syllabus-based generation
**`course_generation_topics.py`** — Topic-based generation

- **Keep:** Localization patterns, math domain specs
- **Debt:** Scattered across files, high duplication, should be consolidated
  into region/domain abstraction

### C — Course Generators

**`course_generator.py`** (48 lines) — Legacy facade
**`enhanced_course_generator.py`** (439 lines) — Advanced with parallel
workflows

- **Keep:** Parallel workflow strategies
- **Debt:** Two entry points, no upgrade path, legacy wrapper

### C — Coverage Gate

**`coverage_gate.py`** — Test coverage enforcement for CI/CD

### C — Curriculum

**`curriculum/`** — Curriculum management (likely sparse)

### D — Dashboard

**`dashboard/`** — User/admin dashboard with real-time monitoring

- **Key exports:** `SystemMonitor`, `JobTracker`, `RealTimeUpdateManager`
- **Keep:** Real-time monitoring architecture
- **Debt:** WebSocket handling untested, no backpressure/throttling,
  over-designed admin controls

### D — Data

**`data/`** — EMPTY (1-line docstring)

- **Debt:** Stub. Delete entirely.

### D — Database

**`database/`** — Multi-database infrastructure (PostgreSQL, MongoDB, Redis)

- **Key exports:** Connection pooling, transactions, repository pattern,
  sharding support, backup/restore
- **Keep:** Connection pool manager, repository pattern, transactional
  operations
- **Debt:** Overly complex, sharding logic incomplete, backup operations
  under-tested

### D — Demo

**`demo/`** — Tutorial/demo infrastructure

- **Debt:** Lightweight stubs, minimal value

### D — Dependency Health

**`dependency_health/`** — Dependency monitoring, alerting, impact analysis

- **Keep:** Dependency monitoring framework
- **Debt:** Scattered tooling

### D — DevOps

**`devops/`**, **`devops_cli.py`** — CI/CD alignment, TDD compliance

- **Keep:** TDD compliance checker, DR drill scheduler
- **Debt:** Tools scattered, TDD checker may be too strict

### D — Diagram Files

**`diagram/`**, **`diagram_generator.py`**, **`diagram_types.py`**,
**`diagram_styles.py`**, **`diagram_accessibility.py`**,
**`diagram_intelligence.py`**

- **Keep:** Diagram asset management, S3 support, diagram generation
- **Debt:** Files scattered across 6+ locations (poor organization), should be
  consolidated

### D — Diff

**`diff/`** — Diff validation and application for course modifications

- **Key exports:** `DiffValidator`, `ProgrammaticDiffApplier`, ID preservation,
  structural validation, action handlers, preview generation
- **Keep:** ID preservation during diffs, structural validation, action
  handlers, preview generation
- **Debt:** Lazy loading via `__getattr__`, multiple validation passes
  inefficient, preview generation expensive

### D — Dict to Diff Converter

**`dict_to_diff_converter.py`** — Convert Python dicts to diff objects

### D — Diversity

**`diversity/`**, **`enhanced_diversity_manager.py`**,
**`finding_diversity_manager.py`**

- **Key exports:** `EnhancedDiversityManager`, `CategoryQuota`
- **Keep:** Quota-based diversity enforcement
- **Debt:** Minimal module, separate enhanced version creates duplication

### D — Document Processing

**`document_processing/`** — Multi-format document parsing, OCR (30+ formats)

- **Key exports:** `DocumentProcessor`, `DocumentAnalyzer`,
  `EnhancedDocumentProcessor`, format handlers (PDF, Office, Archive, Ebook,
  Web, Markup, Science, Multimedia, Source Code)
- **Keep:** Multi-format support, OCR, structure extraction, deduplication
- **Debt:** Too many handler types (should be plugin system),
  Parser/Analyzer/Processor redundancy

### E — Embeddings

**`embeddings/`** — Embedding operations (minimal)

### E — Exceptions

**`exceptions.py`** — Custom exception hierarchy

- **Key exports:** `MinervaError`, `ConnectorError`, `ValidationError`,
  `ConfigurationError`, `DatabaseError`, `LLMParsingError`,
  `ContentGenerationError`, `RetryableError`, `NonRetryableError`
- **Keep:** Comprehensive exception hierarchy, RFC 7807 compatibility, PEP 3134
  chaining
- **Debt:** Re-exports from `common.exceptions` (redundancy), too many exception
  types

### E — Experiments

**`experiments/`** — ML experimentation framework

### E — Export

**`export/`** — Content export

### F — File IO Files

**`file_io_diagram.py`**, **`file_io_json.py`**, **`file_io_s3.py`**,
**`file_io_state.py`**, **`file_io_utils.py`**

- **Keep:** Modular file I/O, S3 support
- **Debt:** Extracted from monolithic file (incomplete refactor), should be in
  dedicated I/O module

### F — Flow

**`flow/`** — Control flow, checkpoints, recovery, quality gates (mostly stubs)

### G — Generation

**`generation/`** — Course, syllabus, and export pipeline generation

- **Key exports:** `CompleteCourseGenerator`, `EnhancedCourseGenerator`,
  `SyllabusProcessor`, `SyllabusCourseBuilder`, `TopicCreator`,
  `GhanaSyllabusProcessor`, `SyllabusResearchAgent`
- **Keep:** Modular generation pipeline, syllabus parsing with anomaly
  detection, research agent for pedagogical analysis, lesson scaffolding
- **Debt:** Multiple overlapping generators, mixed responsibilities in
  SyllabusProcessor, Ghana-specific code hardcoded

### G — Generators

**`generators/`** — Lightweight artifact generators

- **Key exports:** `DiagramGenerator`, `QuizUtilities`
- **Keep:** Reusable quiz templates
- **Debt:** Very thin, could merge with generation/

### G — Guidance

**`guidance/`** — Syllabus-based educational guidance

- **Key exports:** `MasterGuidelines`, `SyllabusProfiles`, `SyllabusAdapters`,
  `SyllabusValidation`, `SyllabusReview`, `SyllabusAudit`, `SyllabusSnapshot`
- **Keep:** Profile-based content adaptation, standards compliance,
  snapshot/versioning
- **Debt:** Unclear separation of concerns, tight coupling to syllabus format,
  review vs audit overlap

### I — Integration / Integrations

**`integration/`** — Complex subsystem integration (E2E workflows, distributed
state) **`integrations/`** — Third-party connectors (ChatterboxTTS, MinIO,
MongoDB, Neo4j, STT, Weaviate)

- **Keep (integration):** Distributed state conflict resolution, asset pipeline
  coordination, multimodal synchronization
- **Keep (integrations):** Modular provider pattern for each service
- **Debt:** MASSIVE overcomplexity — too many layers, fragmented across two
  directories, 4 files for multimodal correlation alone

### I — Interaction

**`interaction.py`** — Drag-and-drop interaction management for quizzes

- **Key exports:** `MultiTouchManager`, `DragItem`, `DropZone`, `DropResult`,
  `ContainerRule`
- **Keep:** Clean frozen dataclasses, constraint validation, immutable state
- **Debt:** Very niche, `update_drag()` is minimal stub

### I — IO

**`io/`** — File I/O utilities

- **Key exports:** `save_json_file()`, `load_json_file()`,
  `atomic_write_json()`, `save_diagram_file()`, `upload_course_dir_to_s3()`,
  `save_intermediate_state()`, `create_output_path()`, `is_safe_path()`
- **Keep:** Atomic JSON writes, debounced S3 uploads, state checkpointing, safe
  path handling
- **Debt:** Mixed concerns (JSON + diagrams + S3 + state), should use repository
  pattern

### K — Knowledge

**`knowledge/`** — Knowledge base, prerequisites, learning objectives

- **Keep:** Knowledge graph relationships, prerequisite analysis

### L — Learning

**`learning/`** — Comprehensive adaptive learning system

- **Key subsystems:**
  - Prerequisite Knowledge Graph: `PrerequisiteKnowledgeGraph`,
    `PrerequisiteMapper`, `KnowledgeGapAnalyzer`, `LearningPathOptimizer`,
    `TopologicalLearningSequencer`
  - Drag-Drop Activities: `DragDropLearningActivity`,
    `DragDropApplicationManager`, `DragDropWindowSyncManager`
  - Learning Style Adaptation (optional): `LearningStyleAdaptationSystem`,
    `FelderSilvermanAnalyzer`, `VARKStyleAnalyzer`, `MultiModalContentGenerator`
  - Peer Learning (optional): `PeerLearningSuggestionEngine`,
    `CommonErrorAnalyzer`, `PeerMatchingAlgorithm`
  - Difficulty Variants (optional): `DifficultyVariantGenerator`
  - Confidence/Tone (optional): `ConfidenceCoach`, `ToneAdjuster`
- **Keep:** Prerequisite graph system (sophisticated), knowledge gap detection,
  drag-drop tracking, learning style profiling, peer matching
- **Debt:** Multiple "optional" systems via try/except (feature creep), unclear
  which are production vs experimental, overlapping concerns

### L — Linters

**`linters/`** — 20+ specialized quality linters

- **Key linters:** `ClarityLinter`, `TitleQualityLinter`, `TopicDepthLinter`,
  `FactCheckingLinter`, `MathematicalAccuracyLinter`, `ChemistryAccuracyLinter`,
  `PhysicsAccuracyLinter`, `ScientificConsistencyLinter`, `PrerequisiteLinter`,
  `ConceptGraphLinter`, `QuizAnswerAccuracyLinter`, `QuizFeedbackQualityLinter`,
  `MediaAudioDescriptionLinter`, `MediaCaptionLanguageLinter`,
  `MediaTimestampAlignmentLinter`, `GhanaPolicyComplianceLinter`,
  `PlagiarismLicenseLinter`, `WcagAccessibilityLinter`, `GraphSchemaLinter`,
  `DiagramDataQualityLinter`
- **Architecture:** `BaseLinter` abstract interface, lazy loading via
  `__getattr__`
- **Keep:** Comprehensive quality checks, clear categorization by domain, lazy
  loading strategy (good for plugins)
- **Debt:** Ghana-specific linter hardcoded, no priority/severity system, no
  composition/chaining

### L — LLM

**`llm/`** — LLM optimization and batching (sparse exports) **`llm_utils.py`** —
Schema validation, budget tracking, response repair
**`llm_operation_manager.py`** — Timeout and progress management

- **Keep (llm_utils):** Budget tracking, ephemeral scratchpad, schema
  validation, circuit breaker pattern
- **Keep (llm_operation_manager):** Configurable timeouts, priority queue,
  operation tracking
- **Debt:** Lazy loading suggests circular imports, budget tracker minimal, no
  actual circuit breaker implementation shown

### L — LMS

**`lms/`**, **`lms_roster_grades.py`** — LMS integration, roster/grade
management

- **Key exports:** `Student`, `Principal`, `InMemoryRosterGrades`,
  `RosterGradesService`
- **Keep:** Clean permission model, immutable records, role-based access
- **Debt:** In-memory only, hardcoded permission checks, no grade calculation

### L — LO Coverage Planner

**`lo_coverage_planner.py`** — Learning objective coverage mapping

### L — Logging

**`logging_json.py`**, **`logging_utils.py`** — Structured logging utilities

### M — Metrics

**`metrics/`** — Performance, cost, and coverage metrics

- **Key modules:** `runtime.py`, `cost_reporting.py`, `coverage.py`,
  `batch_dashboard.py`, `aggregation.py`, `quality_regression.py`,
  `generation_profile.py`
- **Keep:** Cost tracking, coverage analytics, batch dashboards, quality trend
  analysis
- **Debt:** Isolated files without unified interface, cost reporting likely
  hardcoded to OpenAI

### M — Models

**`models/`** — Comprehensive data model hierarchy

- **Key data classes:**
  - Structure: `Course`, `Topic`, `SubTopic`, `Lesson`, `Section`
  - Assessment: `Quiz`, `QuizQuestion`, `ProjectAssignment`,
    `DiagnosticAssessment`
  - Rich Media: `Presentation`, `Slide`, `Diagram` types, animations
  - Study Aids: `Flashcard`, `FlashcardSet`, `StudyAidBundle`,
    `DiscussionPrompt`
  - Concepts: `ConceptNode`, `ConceptEdge`, `ConceptGraph`
  - Actions: 40+ diff types (AddTopicDiff, EditSectionDiff, etc.)
- **Architecture:** Lazy loading via `__getattr__()`, `_LazyDict` for dynamic
  registry, maps for type resolution
- **Keep:** Well-organized hierarchy, comprehensive diff types, type validation
  maps
- **Debt:** Lazy loading (circular deps), too many diff types (feature creep),
  no version migration

### M — Model Utils

**`model_utils.py`** — Pydantic model utilities

- **Key exports:** `collect_all_ids()`, `validate_id_preservation()`,
  `find_element_by_id()`, `find_duplicate_ids()`, `count_content_stats()`
- **Keep:** ID preservation validation, duplicate detection, model traversal
- **Debt:** Thin wrappers, lazy loading for circular imports

### M — Moderation

**`moderation/`** — Content safety (EMPTY in **init**)

- **Debt:** Stub. Delete.

### M — Monitoring

**`monitoring/`**, **`monitoring_resource_monitor.py`**, **`monitoring_rss.py`**

- **Key modules:** resource monitor, anomaly detection, performance metrics,
  cache manager, memory optimization, diagram profiler, load testing
- **Keep:** Resource monitoring, anomaly detection, performance profiling
- **Debt:** Scattered across many files, unclear integration, specialized
  diagram profiler too specific

### M — Multimedia

**`multimedia/`** — Presentation and diagram rendering with validation

- **Key exports:** `DiagramRenderer`, `PresentationRenderer`,
  `MultimediaAssetValidator`, `AudioValidator`, `DiagramValidator`,
  `PresentationValidator`, `AssetQualityMetrics`, `ValidationResult`
- **Keep:** Pluggable validator architecture, asset quality metrics,
  rendering/validation separation
- **Debt:** Only rendering/validation (no generation), deprecation warning
  suggests refactoring in progress

### O — Observability

**`observability/`** — Monitoring, tracing, observability infrastructure

### O — Optimization

**`optimization/`** — Resource optimization (LLM, CPU, memory, networking)

- **Key subsystems:**
  - LLM: `LLMBatchManager`, `CostAwareRouter`, `TokenOptimizer`,
    `ModelUsageTracker`
  - Quota: `QuotaManager`, `RateLimiter`, `ThrottleManager`
  - Resource: `ResourcePool`, `ObjectPool`, `ResourceManager`
  - Memory: `MemoryOptimizer`, `MemoryProfiler`
  - CPU: `CPUOptimizer`, `AlgorithmProfiler`, `TaskScheduler`
- **Keep:** Quota/rate limiting, resource pooling, cost-aware routing
- **Debt:** EXTREME feature creep (15+ optimization types), "green computing
  mode" and "carbon tracking" (premature), disabled energy optimization (dead
  code)

### O — Orchestration

**`orchestration/`** — Multi-agent workflow orchestration

- **Key exports:** `OrchestrationFacade`, `MultiAgentOrchestrator`,
  `AgentCoordinationEngine`, `WorkflowExecutor`, `AgentMemorySystem`,
  `WorkflowRegistry`, `WorkflowVisualization`, `DeterministicTestHarness`
- **Keep:** Clean facade, workflow visualization, test harness, performance
  tracking
- **Debt:** Multiple orchestrator levels unclear, test harness suggests
  production instability

### O — Output

**`output/`** — Result formatting and export

### P — Patch Engine

**`patch_engine.py`** — Apply structural modifications to courses

- **Key exports:** `canonicalize()`, `apply_patch()` (AddSection,
  UpdateSectionMeta, SetAudioUrl, PatchDiagram)
- **Keep:** Canonicalization for minimal diffs, type-safe patch application,
  deep copy (no side effects)
- **Debt:** Only 4 patch types, no rollback/undo, no transactions

### P — Performance

**`performance/`** — Performance optimization and profiling

- **Key modules:** batch_prompt_builder, intelligent_refinement_enhanced,
  scheduler, opportunities, intelligent_orchestrator
- **Keep:** Batch optimization, scheduler, opportunity detection
- **Debt:** Heavy overlap with orchestration/ and optimization/, vague
  "intelligent" naming

### P — Progress

**`progress/`** — Learning progress tracking

### P — Prompts

**`prompts/`** — LLM prompt management and templates

### P — Providers

**`providers/`** — LLM provider abstraction

- **Key exports:** `LLMProvider`, `CodexProvider`, `LLMProviderFactory`,
  `LLMRequest`, `LLMResponse`, `CodexModel`, `SubscriptionUsage`
- **Keep:** Clean provider interface, factory pattern, subscription awareness
- **Debt:** Codex CLI very specific, no cost tracking at provider level, no
  registration mechanism

### Q — Quiz Generator

**`quiz_generator.py`** — Quiz utilities with Bloom's taxonomy

- **Key exports:** `QuizUtilities`, `ACTION_VERBS`, `MISCONCEPTION_TEMPLATES`
- **Keep:** Action verb categorization, misconception-based feedback
- **Debt:** Very minimal, no actual generation (just utilities), Ghana context
  limited

### R — RAG

**`rag/`** — RAG 2.0 with collaborative KB, citation, bias detection

- **Key exports:** `EnhancedRAGSystem`, `CollaborativeKnowledgeBase`,
  `ContextAttribution`, `KnowledgeQualityAssessor`,
  `FactCheckTransparencyReporter`, `BiasDetector`, `SourceReliability`
- **Keep:** Collaborative knowledge base, bias detection (critical for edtech),
  fact-check transparency, source credibility
- **Debt:** Experimental system, bias detection likely incomplete, no
  integration with verification linters

### R — Reasoning

**`reasoning/`** — Mathematical and logical problem-solving (PAL)

- **Key exports:** `PALSolver`, `MathematicalProblem`, `MathExecutor`,
  `CodeValidator`, `ProgramSolution`, `SolutionExplanation`
- **Keep:** Program-aided reasoning, code validation, mathematical problem
  specification
- **Debt:** Limited to math, code execution security unclear, no symbolic math

### R — Refinement

**`refinement/`** — Content refinement with opportunity detection

- **Keep:** Intelligent refinement loop, opportunity prioritization
- **Debt:** Overlap with content agents, no rollback if refinement worsens
  quality

### R — Repository

**`repository.py`** — Data persistence abstraction

- **Key exports:** `CourseRepository` (file system + MongoDB)
- **Keep:** Dual backend support, clean repository pattern
- **Debt:** Only CourseRepository, MongoDB hardcoded, manual timestamp
  versioning

### R — Research

**`research/`** — MASSIVE deep research system (5 subsystems)

- **Key subsystems:**
  1. Deep Research Agent: web search, fact verification, pedagogical research,
     knowledge extraction
  2. Knowledge Graph (Neo4j): 50+ entity/relation types, educational schema
  3. Monitoring (15+ subsystems!): web change, document version, feed
     aggregation, freshness, coverage, notifications
  4. Integration: curriculum data APIs
  5. Metadata: session tracking, search history
- **Keep:** Web research, knowledge graph extraction, change detection, coverage
  analysis, notifications
- **Debt:** MASSIVE overcomplexity — 700+ exports from monitoring alone,
  overlapping subsystems, rigid Neo4j schema (50+ hardcoded entity types)

### R — Run Tracking

**`run_tracking.py`**, **`run_tracking_agents.py`**,
**`run_tracking_lifecycle.py`**, **`run_tracking_models.py`**,
**`run_tracking_storage.py`**, **`run_tracking_helpers.py`**

- **Keep:** Run ID management, state snapshots, resumable runs
- **Debt:** Scattered across 6 files

### S — Schema Validator

**`schema_validator.py`** — Runtime validation of Course structure

- **Key exports:** `validate_against_reference()`, `_walk()`
- **Keep:** Content richness validation, reference spec validation
- **Debt:** Only validates Section types, hardcoded richness requirements

### S — Schemas

**`schemas/`** — Data schema definitions (content, diagrams, patches, rendering,
upgrades)

- **Keep:** Schema separation, patch schema, rendering schema, upgrade/migration
- **Debt:** Unclear relationship to models/ (potential duplication)

### S — Security

**`security/`** — Security controls (minimal)

### S — Service Discovery

**`service_discovery/`** — Service registration (minimal)

### S — Settings

**`settings.py`** — Centralized Pydantic BaseSettings configuration

- **Keep:** Environment variable binding, type-safe config, validation,
  documentation
- **Debt:** Scattered timeout config, many undocumented settings, no dev/prod
  profiles, feature flags as boolean strings

### S — Storyboard

**`storyboard/`**, **`storyboard_guardrails.py`** — Multimedia storyboard
generation

- **Keep:** Scene-by-scene planning, narrative flow validation, timing
  synchronization

### S — Syllabus

**`syllabus/`**, **`syllabus_processor.py`**, **`syllabus_targets.py`**

- **Keep:** Comprehensive syllabus parsing, curriculum mapping, auditing,
  profile-based adaptation
- **Debt:** Duplicate functionality between generation/ and syllabus/, heavy
  Ghana curriculum hardcoding

### T — Templates / Test Profiles

**`templates/`** — Content templates **`test_profiles.py`** — Test data fixtures

### T — Tools

**`tools/`** — Development utilities

- **Key tools:** batch_analyzer, cli_validate_docs, file_refactorer,
  python_interpreter_tool, web_search_tool
- **Keep:** File analysis tools, validation utilities
- **Debt:** .backup.py file (dead code), python interpreter is security risk

### T — Tracking / TUI / Tutor

**`tracking/`** — Operation tracking **`tui/`** — Terminal UI **`tutor/`** —
Tutoring system and learner interaction

### T — Typed Orchestrator

**`typed_orchestrator.py`** — Type-safe patch application

- **Key exports:** `apply_typed_patch_plan()`
- **Keep:** Type-safe patch API
- **Debt:** Extremely thin, should be in patch_engine.py

### T — Typings

**`typings/`** — Type hints and protocol definitions

### U — Unified Orchestrator (30+ files!)

**`unified_orchestrator.py`** + 28 `unified_orchestrator_*.py` files +
`unified_config.py` + `.py.backup`

- **Files:** baseline_state, catchup, completion, compliance, compliance_state,
  concept, concurrency, config, course_utils, environment, exception_wrappers,
  finalization, load_existing, memory, mode, multimedia, multimedia_state,
  output, postprocessing, preflight, processing, results, resume, rounds_state,
  settings, setup, state_handlers, tracker, types, utils
- **Keep:** End-to-end orchestration, state management, resumable runs,
  multi-round refinement, compliance tracking, multimedia coordination
- **Debt:** CRITICAL — 30+ files for single system, main file likely 3000+
  lines, multiple overlapping state files, backup file present, no clear module
  boundary, massive duplication

### V — Validation

**`validation/`** — Multi-layered content validation

- **Key subsystems:**
  1. Schema: `AdaptiveSchemaValidator`, `SemanticContentExtractor`,
     `ProviderSpecificOptimizer`, `TemplateEvolutionSystem`
  2. Math: `MathematicalContentValidator`, `ArithmeticExpression` (uses SymPy)
  3. Input: `InputValidator`, `SanitizationConfig`
  4. Content: `BookV2Validator`, `FactualAccuracyValidator`,
     `QuizExplanationValidator`
  5. Pipeline: `ValidationPipelineBuilder`,
     `create_quick_validation_pipeline()`,
     `create_production_validation_pipeline()`
  6. Cache: `ValidationCache`, `CachePolicy`
  7. Coordinator: `UnifiedValidationCoordinator`, `ValidationContext`
- **Keep:** Adaptive schema handling (excellent for LLM responses), math
  validation (rare/valuable), pipeline builder, validation caching
- **Debt:** Multiple validation systems unclear which are production, pipeline
  builder may be over-engineered

### V — Verification

**`verification/`** — Result verification and quality assessment

### V — Version Control

**`version_control/`**, **`version_manager.py`**, **`version_menu.py`**

- **Keep:** Version history, diff generation, rollback
- **Debt:** Unclear integration with run tracking

### V — Video

**`video/`** — Educational video specification

- **Key exports:** `VideoSpec`, `Scene`, `Shot`, `VisualElement`, `VisualLayer`,
  `AudioTrack`, `CameraMotion`, `AnimationSpec`, `TransitionSpec`, `Resolution`,
  `Position`
- **Keep:** Structured video specification, scene-shot hierarchy, audio sync,
  animation specs
- **Debt:** Only models (no generation/rendering), no integration with
  multimedia/

### V — Visualization

**`visualization/`** — Course structure visualization

### V — VLM

**`vlm/`** — Vision-language model integration

- **Key exports (lightweight):** `VLMProcessor`, `VLMProvider`, `VLMResponse`,
  `ImageAnalyzer`, `VisualContentGenerator`, `DiagramInterpreter`,
  `EducationalImageClassifier`, `AccessibilityGenerator`
- **Key exports (heavy, optional):** `EducationalVLMFineTuner`,
  `EducationalDataset`, `VLMEvaluationSuite`
- **Keep:** Accessibility alt-text generation, diagram interpretation, image
  classification, clean lightweight/heavy separation
- **Debt:** Fine-tuning system is incomplete stub, no actual VLM integration
  shown, all features are facades

---

## Modules to DELETE Entirely (Empty Stubs)

1. `content/` — Empty (1-line docstring)
2. `content_standards/` — Empty (`__all__ = []`)
3. `core/` — Legacy shim (docstring only)
4. `data/` — Empty (1-line docstring)
5. `collaboration/` — Ends after docstring
6. `moderation/` — Empty **init**
7. `assessment_tools/` — 1-line stub
8. `unified_orchestrator.py.backup` — Dead code

---

## Top 10 Technical Debt Patterns to NOT Carry Forward

1. **Lazy loading via `__getattr__`** — Used pervasively to mask circular
   imports. Replace with proper dependency injection.
2. **Unified orchestrator monolith** — 30+ files for one system. Decompose into
   phases with clear boundaries.
3. **Research monitoring overcomplexity** — 700+ exports, 15+ overlapping
   subsystems. Consolidate drastically.
4. **Broken/disabled features** — L2 Redis cache, cache warming, distributed
   cache, MediaAgentAdapter, StoryboardAgentAdapter. Remove entirely.
5. **Try/except optional imports** — Feature creep hiding behind ImportError.
   Use explicit feature flags or plugin architecture.
6. **Scattered file organization** — diagram*\*.py (6 locations), file_io*_.py
   (5 files), course*generation*_.py (4 files), run_tracking\*.py (6 files).
   Consolidate into proper packages.
7. **Duplicate systems** — schemas/ vs models/, syllabus/ vs generation/, cache/
   vs caching/, optimization/ vs performance/ vs refinement/. Pick one, delete
   the rest.
8. **Ghana hardcoding** — Ghana-specific logic scattered throughout instead of
   being parameterized locale config.
9. **Over-engineering** — autonomous_tour/ (tour with security scanning?),
   compliance_automation/ (5 regulatory frameworks), optimization/ (green
   computing mode?). Scope to actual needs.
10. **No dependency injection** — Direct imports everywhere make testing and
    configuration difficult. Use DI containers.

---

## Top 10 Feature Areas to Carry Forward

1. **Multi-agent ReAct system** — Core value prop. Clean agent abstractions with
   tool support.
2. **Course data model hierarchy** — Well-organized Course → Topic → SubTopic →
   Lesson → Section.
3. **20+ quality linters** — Comprehensive content validation across domains
   (math, science, pedagogy, accessibility).
4. **Adaptive validation pipeline** — Schema validation for LLM responses,
   mathematical verification, pipeline composition.
5. **Diff/patch system** — ID-preserving structural modifications with preview
   and rollback.
6. **Multi-format document processing** — BYOM system supporting 30+ formats
   with web integration.
7. **Multimedia production** — Video specs, diagram rendering, presentation
   compilation, audio sync.
8. **Prerequisite knowledge graph** — Concept mapping, gap detection,
   topological sequencing, learning path optimization.
9. **Research and RAG** — Web research, fact checking, bias detection, source
   credibility, collaborative knowledge base.
10. **Adaptive learning** — Learning style profiling (VARK, Felder-Silverman),
    difficulty variants, peer matching, confidence coaching.
