# DIY Transcriptomics — AI Architecture, Vector RAG & RLHF Guide A technical reference detailing the multimodal artificial intelligence ecosystem, vector retrieval-augmented generation (RAG), and reinforcement learning pipelines powering DIY Transcriptomics. --- ## 1. Dual-Model Architecture & Routing The platform employs a hybrid tiered model strategy using Google's frontier Gemini family: ```mermaid flowchart TD UserQuery["Student Interaction"] --> TaskRouter{"Task Classification"} TaskRouter -- "Real-Time Chat / Tutor / Code Q&A" --> FlashLite["Gemini 3.5 Flash-Lite
(SSE Streaming, <500ms TTFB)"] TaskRouter -- "Multimodal Vision / Complex Merge / Repo Audit" --> Flash37["Gemini 3.7 Flash
(Multimodal Vision & Deep Reasoning)"] FlashLite --> StreamOutput["Token-by-Token Streaming Markdown"] Flash37 --> StructuredOutput["Rubric Scores, JSON Specs, & Merged Reports"] ``` ### Models & Roles 1. **Google Gemini 3.5 Flash-Lite:** * **Primary Function:** High-speed conversational tutoring, real-time code error troubleshooting, and inline code annotations. * **Streaming:** Server-Sent Events (SSE) streaming with sub-second time-to-first-byte (<500ms TTFB). Includes automatic fallback to standard callable endpoints if the network stream is interrupted. 2. **Google Gemini 3.7 Flash:** * **Primary Function:** Multimodal scientific figure evaluation, GitHub repository code auditing, and collaborative report synthesis. * **Characteristics:** High reasoning capability, robust adherence to strict JSON schemas, and exceptional visual detail analysis for high-resolution scatterplots, heatmaps, and PCA graphics. --- ## 2. Cross-Curriculum Vector RAG Engine The AI assistant is grounded in the course's exact transcripts, R scripts, slide decks, and assigned readings to prevent hallucinations and provide precise curriculum citations. ```mermaid flowchart LR subgraph Ingestion ["1. Document Ingestion"] VTT["Vimeo Transcripts"] --> Chunker["Sliding Window Chunker
(300 words, 50-word overlap)"] Scripts["R Step Scripts"] --> Chunker PDFs["Course Readings"] --> Chunker end subgraph Embedding ["2. Vector Embedding"] Chunker --> EmbedAPI["gemini-embedding-001
(768 Dimensions)"] EmbedAPI --> FirestoreVec["Firestore Collection:
/course_knowledge_embeddings"] end subgraph Retrieval ["3. Hybrid Search"] StudentQ["Student Question"] --> QEmbed["Embed Question"] QEmbed --> FindNearest{"Firestore
findNearest()"} FindNearest -- Success --> TopChunks["Top K Relevant Chunks"] FindNearest -- Failover --> CosineFallback["In-Memory Cosine
Similarity Fallback"] CosineFallback --> TopChunks end TopChunks --> Synthesis["Gemini 3.5 Flash-Lite Context Synthesis"] ``` ### Key Technical Specifications * **Embedding Model:** `gemini-embedding-001` (768 dimensions). * **Chunking Geometry:** ~300 words per chunk with a 50-word sliding overlap, ensuring that semantic boundaries (such as code chunks and explanations) are never cleaved in half. * **Dual Retrieval Engine:** 1. *Native Firestore Vector Search:* Uses Firestore's `findNearest` vector index for ultra-low latency cosine similarity retrieval directly within the database tier. 2. *In-Memory Cosine Fallback:* If the database vector index is temporarily warming or unavailable, an in-memory cosine fallback dynamically computes dot products against cached chunk vectors to guarantee zero downtime for students. * **Hyperlinked Citations:** Every retrieved citation dynamically injects clickable Markdown links to referenced lectures (e.g. `[Lecture 4: Alignment & Mapping](/project/lecture-04.html)`) and direct PDF paths under `/Reading/files/` (e.g. `[Kallisto.pdf](/Reading/files/Kallisto.pdf)`). --- ## 3. Socratic Debugging Mode (Tutor Mode) The Lecture and Lab Companion widgets feature an optional **Tutor Mode** toggle (indicated by a 🎓 badge and subtle cream chat bubbles) that transforms the AI into a pedagogical guide. ### Pedagogical Loop 1. **Detection:** Identifies the conceptual root of the student's error without providing code. 2. **Observation:** Prompts the student to inspect specific outputs (e.g. *"What does `dim(counts)` return?"* or *"Look closely at line 14: what type of data structure does `read_tsv` produce?"*). 3. **Scaffolding:** Supplies progressive hints based on the student's follow-up responses. 4. **"Reveal Answer" Safety Valve:** A prominent **Reveal Direct Answer** button automatically unlocks after 2–3 Socratic exchanges to ensure students never remain permanently blocked. --- ## 4. Lab Critic: Multimodal Figure & Repository AI The Lab Critic provides instantaneous, rubric-aligned scientific feedback to students before final submission. ### Figure Critic (Multimodal Vision) * **Input:** High-resolution PNG or PDF figures submitted by the student. * **Scoring Rubric (1–5 scale):** * *Clarity:* Visual contrast, legible typography, uncrowded labels. * *Consistency:* Adherence to course color palettes and plotting paradigms. * *Labels:* Complete axis titles with physical units, informative legends, clear titles. * *Story:* Clear biological interpretation and highlighted discoveries. * **Granular JSON Reference Rules:** Instructors configure specific rubrics in the Admin panel: * *Global Specs:* Universal checks (e.g. `{"require_gene_symbols": true}`). * *Pattern Matching:* Matches student drafts against instructor-supplied "Ideal Pattern" or "Anti-Pattern" reference figures. * **Peer Benchmarking:** Compares individual report card scores against anonymous class averages. ### Repository Critic (Code & Reproducibility) * **Input:** Public GitHub repository URL. * **Scoring Rubric (1–5 scale):** Documentation (`README.md`), Reproducibility (relative file paths, environment configs), Code Style (tidyverse formatting, comments), and Completeness. --- ## 5. Report Studio & Multimodal AI Merge During collaborative table exercises, table members contribute individual scripts and figures. The **Report Studio** provides an interactive Markdown review workspace (inspired by Plannotator): * **Multimodal AI Merge:** Uses **Gemini 3.7 Flash** to synthesize table-mates' individual R scripts and figures into a cohesive unified report draft. * **Role-Based Review (RBAC):** * *👑 Table Coordinator:* Edit access, syntax tools, cloud autosave, and sole authority to **Finalize & Submit**. * *👥 Table Members:* Read-only inspection with full peer annotation privileges. * **Inline Text Annotations (``):** Selecting preview text spawns a `[ 💬 Annotate Selection ]` popover that highlights passages in amber and alerts table-mates. * **Word-Level Myers Diff Engine:** Myers/LCS token-level visual diff comparing the immutable baseline AI draft against the human-edited final report (`+green additions` / `-red deletions`). --- ## 6. Triple-Loop Learning Architecture (RLHF) The system automatically collects human feedback to create proprietary training datasets for future model fine-tuning (SFT) and alignment: ```mermaid flowchart TD subgraph Loop1 ["Loop 1: Ask DIY Signals"] StudentRating["Student & Instructor 👍/👎 Feedback"] --> Log1["ai_activity_logs (query_feedback)"] end subgraph Loop2 ["Loop 2: Group Report Edits"] AIDraft["AI Draft Baseline"] --> DiffEngine["Report Studio Word Diff"] HumanFinal["Human Final Report"] --> DiffEngine PeerComments["Peer Inline Comments"] --> DiffEngine DiffEngine --> Log2["ai_activity_logs (table_merge_training)"] end subgraph Loop3 ["Loop 3: Instructor Calibration"] AIScores["AI-Generated Figure Scores"] --> InstructorOverride["Instructor Manual Score Override"] InstructorOverride --> Log3["ai_activity_logs (critic_calibration)"] end Log1 --> SFT["Supervised Fine-Tuning & Prompt Calibration Hub"] Log2 --> SFT Log3 --> SFT ``` 1. **Loop 1 (Assistant Quality):** Captures student and instructor ratings on "Ask DIY" responses to flag knowledge gaps or confusing explanations. 2. **Loop 2 (Scientific Synthesis):** Performs shadow logging of AI baseline drafts vs. human-edited final reports in the Report Studio, recording exact token diffs and peer comments to study where AI drafts fail scientific rigor. 3. **Loop 3 (Figure Grading):** Records instructor manual overrides of AI-generated figure scores, building ground-truth calibration sets for grading models. --- *Associated Guides:* [`docs/COURSE_MAINTENANCE_AND_CONTENT_GUIDE.md`](/docs/COURSE_MAINTENANCE_AND_CONTENT_GUIDE.html), [`docs/INSTRUCTOR_ADMIN_GUIDE.md`](/docs/INSTRUCTOR_ADMIN_GUIDE.html), [`docs/FIREBASE_BACKEND_SCHEMA.md`](/docs/FIREBASE_BACKEND_SCHEMA.html)