# ksaxena-233/lecturepacketengine architecture

> Architecture diagram of the GitHub repository ksaxena-233/lecturepacketengine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ksaxena-233/lecturepacketengine
- Repository: https://github.com/ksaxena-233/lecturepacketengine

## Overview

##### Project Type and Purpose
- This is an open-source Python tool (LecturePacketEngine) for AI-driven educational content generation.
- Core purpose: take a user prompt → generate structured lecture packets (PDFs, slides, videos) with AI text, LaTeX equations, images, and optionally adapt to cognitive state inputs (EEG).

##### File Structure Analysis
- Top-level modules:
- lecture_packet_engine.py – central orchestration class
- gemini_utils.py – wrapper for Google Gemini API
- pdf_generator.py – ReportLab-based PDF assembly
- manim_slides.py / revolutionary_slides.py / presentation.py – slide abstractions
- video_generator.py – video assembly pipeline
- cognitive_state_widget.py + eeg_* modules – sensor/ML feedback loop
- app.py – CLI/web entrypoint
- examples/ – usage scripts and demos
- requirements.txt – Python dependencies and external APIs

##### README Insights
- Three main feature domains:
a. AI-Powered Text & Equation Generation via Gemini
b. Smart Image Search (DuckDuckGo + PIL validation + retry/backoff)
c. Professional Output (PDF formatting, custom fonts, LaTeX, cover pages)
- Mentions ReportLab, Pillow, requests, duckduckgo_search, matplotlib, numpy.

##### Main Components
A. User Interface Layer
- app.py or CLI/Script (examples/basic_usage.py)
B. Core Engine
- LecturePacketEngine
C. External Services
- Google Gemini API (text/equation)
- DuckDuckGo Search API (images)
D. Processing Modules
- gemini_utils.py
- pdf_generator.py
- image_processor (PIL validation, resizing)
- slide_generators (manim_slides.py, presentation.py)
- video_generator.py
E. Adaptation / Feedback Module
- cognitive_state_widget.py
- eeg_dataset_processor.py → eeg_ml_pipeline.py → eeg_ml_classifier.py
F. Outputs
- Generated PDF (output/*.pdf)
- Slides (output/*.html or video)
- Video (output/*.mp4)

##### Relationships & Data Flow
1. UI → Engine: user prompt
2. Engine → Gemini API: request text + equations
3. Engine → DuckDuckGo: image queries → PIL validation → back to Engine
4. Engine → PDF Generator: assemble text, equations, images → PDF
5. Engine → Slide Generator(s): produce slide assets
6. Engine → Video Generator: combine slides, narrations (optional)
7. (Optional) Engine ↔ Cognitive Module: EEG data → ML pipeline → real-time feedback → adapt content
8. All outputs saved under output/

##### Architectural Patterns & Design Principles
- Modular “Pipeline” pattern: each stage (text, image, PDF, slides, video) is a pluggable module
- Single Responsibility: separate classes for API wrappers, generators, ML pipelines
- Retry/Backoff strategy for external calls (image search)
- Dependency Injection: Engine orchestrates modules via constructors

##### Technologies & Frameworks
- Python 3.9+
- Google Gemini API (via requests in gemini_utils.py)
- ReportLab (pdf_generator.py)
- PIL/Pillow (image validation, resizing)
- duckduckgo_search (image lookup)
- Manim (slide animations)
- matplotlib, numpy (figures)
- scikit-learn / custom ML for EEG (eeg_ml_classifier.py)

##### Summary
- The central role of LecturePacketEngine as orchestrator
- Pluggable modules for each content-generation stage
- External dependencies and retry logic
- Optional adaptive feedback via EEG modules
- Final outputs (PDF, slides, video)
By decomposing into these components and layering them clearly, even new contributors can grasp the architecture at a glance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI_App["app.py"]:::frontend
        UI_Example["basic_usage.py"]:::frontend
    end

    %% Core Engine
    subgraph "Core Engine"
        Engine["LecturePacketEngine"]:::core
    end

    %% External Services
    subgraph "External Services"
        GeminiAPI["Google Gemini API"]:::external
        DuckDuckGo["DuckDuckGo Search API"]:::external
    end

    %% Processing Modules
    subgraph "Processing Modules"
        GeminiUtil["gemini_utils.py"]:::processing
        PDFGen["pdf_generator.py"]:::processing
        SlideManim["manim_slides.py"]:::processing
        SlidePres["presentation.py"]:::processing
        SlideRev["revolutionary_slides.py"]:::processing
        VideoGen["video_generator.py"]:::processing
        ImgProc["Image Processor (PIL)"]:::processing
    end

    %% Feedback / Adaptation Module
    subgraph "Feedback / ML Adaptation"
        CogWidget["cognitive_state_widget.py"]:::feedback
        EEGPrep["eeg_dataset_processor.py"]:::feedback
        EEGPipe["eeg_ml_pipeline.py"]:::feedback
        EEGClass["eeg_ml_classifier.py"]:::feedback
    end

    %% Outputs
    subgraph "Outputs"
        OutPDF["Generated PDF"]:::output
        OutSlides["Generated Slides"]:::output
        OutVideo["Generated Video"]:::output
    end

    %% Connections
    UI_App -->|"prompt"| Engine
    UI_Example -->|"prompt"| Engine

    Engine -->|"request text/equations"| GeminiUtil
    GeminiUtil -->|"JSON response"| Engine
    Engine -->|"image query"| DuckDuckGo
    DuckDuckGo -->|"image bytes\n(retry/backoff)"| ImgProc
    ImgProc -->|"validated images"| Engine

    Engine -->|"content payload"| PDFGen
    PDFGen -->|"PDF file"| OutPDF

    Engine -->|"slide content"| SlideManim
    Engine -->|"slide content"| SlidePres
    Engine -->|"slide content"| SlideRev
    SlideManim -->|"slides asset"| OutSlides
    SlidePres -->|"slides asset"| OutSlides
    SlideRev -->|"slides asset"| OutSlides

    Engine -->|"slides+narration"| VideoGen
    VideoGen -->|"video file"| OutVideo

    Engine <-->|"EEG data / feedback"| CogWidget
    CogWidget -->|"raw EEG"| EEGPrep
    EEGPrep -->|"processed data"| EEGPipe
    EEGPipe -->|"predictions"| EEGClass
    EEGClass -->|"feedback signal"| Engine

    %% Click Events
    click UI_App "https://github.com/ksaxena-233/lecturepacketengine/blob/main/app.py"
    click UI_Example "https://github.com/ksaxena-233/lecturepacketengine/blob/main/examples/basic_usage.py"
    click Engine "https://github.com/ksaxena-233/lecturepacketengine/blob/main/lecture_packet_engine.py"
    click GeminiUtil "https://github.com/ksaxena-233/lecturepacketengine/blob/main/gemini_utils.py"
    click PDFGen "https://github.com/ksaxena-233/lecturepacketengine/blob/main/pdf_generator.py"
    click SlideManim "https://github.com/ksaxena-233/lecturepacketengine/blob/main/manim_slides.py"
    click SlidePres "https://github.com/ksaxena-233/lecturepacketengine/blob/main/presentation.py"
    click SlideRev "https://github.com/ksaxena-233/lecturepacketengine/blob/main/revolutionary_slides.py"
    click VideoGen "https://github.com/ksaxena-233/lecturepacketengine/blob/main/video_generator.py"
    click CogWidget "https://github.com/ksaxena-233/lecturepacketengine/blob/main/cognitive_state_widget.py"
    click EEGPrep "https://github.com/ksaxena-233/lecturepacketengine/blob/main/eeg_dataset_processor.py"
    click EEGPipe "https://github.com/ksaxena-233/lecturepacketengine/blob/main/eeg_ml_pipeline.py"
    click EEGClass "https://github.com/ksaxena-233/lecturepacketengine/blob/main/eeg_ml_classifier.py"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064;
    classDef core fill:#BBDEFB,stroke:#0D47A1;
    classDef external fill:#C8E6C9,stroke:#1B5E20;
    classDef processing fill:#FFE0B2,stroke:#E65100;
    classDef feedback fill:#E1BEE7,stroke:#4A148C;
    classDef output fill:#FFCCBC,stroke:#BF360C;
```
