Eve library

25.1.1.1 — Minerva Python Module Inventory

Guide

Revision 1

On this page

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/, coursecreation_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/, patchengine.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/, fileio*.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), coursegeneration.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.