lyihub/mad-professor-public

<explanation>

1. Project Type and Purpose

- This is a full‑stack, desktop Python application (mad‑professor) built with PyQt6 as the UI and a modular “core engine” for AI‑driven academic paper processing and Q&A.

- Purpose: import PDF papers, extract/translate/structure content, build a vector index (RAG), and let users interact with a “mad professor” AI via text or voice (TTS and STT).

2. File Structure Analysis

Top‑level components:

- Core modules: AI_manager.py, AI_professor_UI.py, AI_professor_chat.py, data_manager.py, pipeline.py, rag_retriever.py, TTS_manager.py, voice_input.py, threads.py

- Processor folder: PDF→Markdown, tiling, translation, extra info, RAG index builder

- UI folder: PyQt6 widgets (chat_widget, markdown_view, sidebar, upload_widget)

- Prompt templates: various .txt for character, translation, summarization

- Config/paths, model download script, assets (CSS, images), font files

- Data directories (data/ for incoming PDFs, output/ for processed results)

3. README Insights

- Frontend: PyQt6 desktop UI (split pane: paper view + chat pane)

- Core engine:

• PDF processing pipeline (magic‑pdf, custom processors)

• RAG retriever (FAISS vector DB)

• AI chat logic (LLM calls via DeepSeek API, “mad professor” personality)

- Interaction: Whisper‑powered STT, MiniMax TTS, emotion mapping

- Dependencies: MinerU, RealtimeSTT, PyTorch/CUDA, FAISS‑GPU

4. Designing the System Diagram

a. Main Components (each as a box):

- UI Layer (PyQt6)

• Sidebar & Upload Widget

• Markdown Paper Viewer

• Chat/Message Bubbles

• Voice Input Button

- Application Orchestrator

• main.py → initializes UI & threads

• threads.py → manages async tasks

- Core Engine

• AI_manager (chat coordinator)

• data_manager (paper metadata & storage)

• pipeline (dispatches PDF→processors)

• rag_retriever (vector search)

• TTS_manager (audio out)

• voice_input (audio in, STT forwarding)

- Processor Subsystem (pipeline stages)

• pdf_processor → md_processor → tiling_processor → translate_processor → extra_info_processor → rag_processor → json_processor → md_restore_processor

- Data Storage

• Local file store (data/, output/)

• Vector DB (FAISS index files)

- External Services

• DeepSeek LLM API

• MiniMax TTS API

• Whisper/ReaI‑timeSTT (online or local)

b. Relationships & Data Flow (use directed arrows):

1. UI upload action → pipeline → processor subsystem → data_manager writes output & builds FAISS

2. UI “ask question” → AI_manager

→ rag_retriever retrieves relevant chunks

→ AI_manager calls DeepSeek API with prompt + chunks

→ AI_manager returns text answer → UI

→ TTS_manager converts answer → audio output

3. UI voice input → voice_input (STT via Whisper) → text → AI_manager

4. data_manager supplies paper content (JSON/Markdown) to UI

c. Architectural Patterns & Principles

- Modular pipeline: each processor is a self‑contained stage

- MVC‑style separation: UI ↔ Core engine ↔ Data storage

- Concurrency: threads for non‑blocking processing, STT, TTS

- RAG pattern: vector embedding + retrieval for context‑aware QA

d. Key Technologies & Libraries

- Python 3.10+, PyQt6 for UI

- magic‑pdf / custom PDF→MD pipeline

- FAISS‑GPU for vector indexing

- PyTorch/CUDA for embeddings & STT models

- External APIs: DeepSeek (LLM), MiniMax (TTS), Whisper/ReaI‑timeSTT (STT)

5. Tailoring Diagram to This Project

- Emphasize the split between:

• Frontend (PyQt6 widgets)

• Backend core engine modules

• Processor pipeline stages

• Local storage (papers, indices)

• External service integrations (LLM, TTS, STT)

- Highlight the flow from PDF import → processing → index build → interactive QA/voice

6. Diagramming Guidelines for the Principal Engineer

- Use clear boxes with labels for each component/module

- Connect with directional arrows showing request/response or data flow

- Color‑code by layer:

• UI (blue)

• Core engine (green)

• Processors (orange)

• Storage (gray)

• External services (purple)

- Use distinct shapes (rounded for UI, rectangles for services, cylinders for storage)

- Annotate each arrow with the type of data or call (e.g., “PDF file,” “vector query,” “LLM prompt/response,” “audio stream”)

7. Final Tips

- Be exhaustive: represent each processor module as its own block if detail is needed

- Show concurrency points: mark where threads spawn tasks

- Capture the “RAG loop” explicitly: pipeline → vector index → retrieval → LLM

- Keep the diagram legible—group related processors under one “Processing Pipeline” container if space is tight

By following these steps and structuring your diagram with clear labels, directional arrows, color coding, and shape differentiation, you’ll produce a precise, maintainable system architecture diagram tailored to the mad‑professor project.