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 —
MediaAgentAdapterandStoryboardAgentAdapterimported 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_warminganddistributed_cachemodules 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
CourseOrchestratorshould 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
- Prerequisite Knowledge Graph:
- 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:
BaseLinterabstract 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,Diagramtypes, animations - Study Aids:
Flashcard,FlashcardSet,StudyAidBundle,DiscussionPrompt - Concepts:
ConceptNode,ConceptEdge,ConceptGraph - Actions: 40+ diff types (AddTopicDiff, EditSectionDiff, etc.)
- Structure:
- Architecture: Lazy loading via
__getattr__(),_LazyDictfor 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
- LLM:
- 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:
- Deep Research Agent: web search, fact verification, pedagogical research, knowledge extraction
- Knowledge Graph (Neo4j): 50+ entity/relation types, educational schema
- Monitoring (15+ subsystems!): web change, document version, feed aggregation, freshness, coverage, notifications
- Integration: curriculum data APIs
- 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:
- Schema:
AdaptiveSchemaValidator,SemanticContentExtractor,ProviderSpecificOptimizer,TemplateEvolutionSystem - Math:
MathematicalContentValidator,ArithmeticExpression(uses SymPy) - Input:
InputValidator,SanitizationConfig - Content:
BookV2Validator,FactualAccuracyValidator,QuizExplanationValidator - Pipeline:
ValidationPipelineBuilder,create_quick_validation_pipeline(),create_production_validation_pipeline() - Cache:
ValidationCache,CachePolicy - Coordinator:
UnifiedValidationCoordinator,ValidationContext
- Schema:
- 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)#
content/— Empty (1-line docstring)content_standards/— Empty (__all__ = [])core/— Legacy shim (docstring only)data/— Empty (1-line docstring)collaboration/— Ends after docstringmoderation/— Empty initassessment_tools/— 1-line stubunified_orchestrator.py.backup— Dead code
Top 10 Technical Debt Patterns to NOT Carry Forward#
- Lazy loading via
__getattr__— Used pervasively to mask circular imports. Replace with proper dependency injection. - Unified orchestrator monolith — 30+ files for one system. Decompose into phases with clear boundaries.
- Research monitoring overcomplexity — 700+ exports, 15+ overlapping subsystems. Consolidate drastically.
- Broken/disabled features — L2 Redis cache, cache warming, distributed cache, MediaAgentAdapter, StoryboardAgentAdapter. Remove entirely.
- Try/except optional imports — Feature creep hiding behind ImportError. Use explicit feature flags or plugin architecture.
- 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.
- Duplicate systems — schemas/ vs models/, syllabus/ vs generation/, cache/ vs caching/, optimization/ vs performance/ vs refinement/. Pick one, delete the rest.
- Ghana hardcoding — Ghana-specific logic scattered throughout instead of being parameterized locale config.
- Over-engineering — autonomous_tour/ (tour with security scanning?), compliance_automation/ (5 regulatory frameworks), optimization/ (green computing mode?). Scope to actual needs.
- No dependency injection — Direct imports everywhere make testing and configuration difficult. Use DI containers.
Top 10 Feature Areas to Carry Forward#
- Multi-agent ReAct system — Core value prop. Clean agent abstractions with tool support.
- Course data model hierarchy — Well-organized Course → Topic → SubTopic → Lesson → Section.
- 20+ quality linters — Comprehensive content validation across domains (math, science, pedagogy, accessibility).
- Adaptive validation pipeline — Schema validation for LLM responses, mathematical verification, pipeline composition.
- Diff/patch system — ID-preserving structural modifications with preview and rollback.
- Multi-format document processing — BYOM system supporting 30+ formats with web integration.
- Multimedia production — Video specs, diagram rendering, presentation compilation, audio sync.
- Prerequisite knowledge graph — Concept mapping, gap detection, topological sequencing, learning path optimization.
- Research and RAG — Web research, fact checking, bias detection, source credibility, collaborative knowledge base.
- Adaptive learning — Learning style profiling (VARK, Felder-Silverman), difficulty variants, peer matching, confidence coaching.