diff --git a/README.md b/README.md
index 156e2dc..8ce47b8 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@
| Feature | Description |
|---------|-------------|
+| ๐ง **AI Learning Assistant** | Personalized curriculum recommendations, semantic search, milestone roadmaps & interactive tutoring |
| ๐ค **AI Tutor** | Google Gemini-powered chatbot for instant answers |
| ๐ **Progress Tracking** | LocalStorage-backed topic completion with visual progress bar |
| ๐ฎ **Interactive Simulations** | Motion, Projectile, NLM, Ray Optics, Chemical Bonding, Thermodynamics |
@@ -99,15 +100,54 @@ LearnSphere_2/
---
+## ๐ง AI Learning Assistant & Structured Content Engine
+
+LearnSphere includes a personalized AI Learning Assistant that analyzes a learner's background, timeline, and goals (e.g. *"I know basic JavaScript and want to become a React developer in 3 months"*), dynamically searches our structured curriculum database, and generates customized milestone roadmaps.
+
+### ๐ The End-to-End Flow
+```
+Create Structured Content โ Store in SQLite DB โ AI Semantic Retrieval โ User Query Understanding โ Personalized Roadmap & Next Step
+```
+
+### ๐ Structured Content Catalog (8 Technical Tracks)
+1. **JavaScript**: Modern JavaScript: Core to Advanced ES6+ (Beginner to Intermediate)
+2. **React**: Modern Frontend Engineering & State Architecture (Intermediate)
+3. **Node.js**: Scalable Backend Architecture & Express APIs (Intermediate)
+4. **Python**: Python Programming & Algorithmic Problem Solving (Beginner)
+5. **Java**: Object-Oriented Engineering & Spring Boot Microservices (Intermediate)
+6. **SQL**: Relational Database Architecture, CTEs & Index Optimization (Beginner)
+7. **Machine Learning**: Foundations & Applied Scikit-Learn Pipelines (Intermediate)
+8. **Full Stack Web Development**: MERN & Modern Web Architecture Capstone (Advanced)
+
+Each course contains detailed prerequisites, topics covered, estimated hours, curriculum sequence modules, resource types (labs, videos, projects, quizzes), and hands-on capstone projects.
+
+### ๐ ๏ธ Architecture & Capabilities
+- **Backend API**: FastAPI with Pydantic validation, CORS, error handling, and OpenAPI documentation (`/docs`).
+- **Storage**: SQLite database (`backend/data/learnsphere_assistant.db`) storing courses, queries, and conversational chat history.
+- **AI & Semantic Search**:
+ - TF-IDF vectorizer + Cosine Similarity scoring over course documents.
+ - Automatic prerequisite dependency chaining and progression ordering.
+ - Google Gemini integration (`gemini-2.5-flash` / `gemini-1.5-flash`) via `google-genai`.
+ - Deterministic semantic fallback engine ensuring 100% functionality offline and without an API key.
+- **Frontend Interface**:
+ - `assistant.html`: Fully responsive UI with dark/light mode support.
+ - Visual milestone timeline, why-recommended explanation, and immediate next step callout.
+ - Interactive follow-up conversational assistant.
+ - Structured content catalog explorer with live search and filtering.
+ - Past guidance history drawer.
+
+---
+
## ๐ฅ๏ธ Tech Stack
| Layer | Technology |
|-------|-----------|
-| Frontend | HTML5, CSS3, Vanilla JavaScript |
-| Backend (AI Tutor) | Python 3, Flask, flask-cors |
-| AI Engine | Google Gemini 1.5 Pro (via `google-generativeai`) |
-| Data Persistence | Browser localStorage (progress, theme, auth) |
-| CI/CD | GitHub Actions (HTML validation, secret scanning) |
+| Frontend | HTML5, CSS3, Vanilla JavaScript, Vite |
+| Backend (AI Assistant) | Python 3, FastAPI, Uvicorn, Pydantic, Scikit-learn |
+| Backend (Auth Server) | Node.js, Express, SQLite |
+| AI Engine | Google Gemini (`google-genai`) + TF-IDF Semantic Retrieval Fallback |
+| Database | SQLite (`learnsphere_assistant.db` & `learnsphere.db`) |
+| Testing | Vitest (51 tests) & Pytest (11 tests) |
---
diff --git a/assistant.css b/assistant.css
new file mode 100644
index 0000000..7286511
--- /dev/null
+++ b/assistant.css
@@ -0,0 +1,1432 @@
+/* assistant.css โ LearnSphere AI Learning Assistant */
+
+.assistant-container {
+ max-width: 1200px;
+ margin: 0 auto;
+ padding: 30px 20px 80px 20px;
+}
+
+/* Hero Section */
+.assistant-hero {
+ text-align: center;
+ margin-bottom: 36px;
+}
+
+.ai-badge {
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+ background: rgba(56, 189, 248, 0.12);
+ border: 1px solid rgba(56, 189, 248, 0.3);
+ color: var(--accent-color);
+ padding: 6px 16px;
+ border-radius: 9999px;
+ font-size: 0.85rem;
+ font-weight: 600;
+ letter-spacing: 0.5px;
+ text-transform: uppercase;
+ margin-bottom: 16px;
+}
+
+.assistant-hero h1 {
+ font-size: 2.5rem;
+ font-weight: 800;
+ margin-bottom: 12px;
+ background: linear-gradient(135deg, #ffffff 30%, var(--accent-color) 100%);
+ -webkit-background-clip: text;
+ -webkit-text-fill-color: transparent;
+}
+
+[data-theme="light"] .assistant-hero h1 {
+ background: linear-gradient(135deg, #0f172a 30%, #0284c7 100%);
+ -webkit-background-clip: text;
+ -webkit-text-fill-color: transparent;
+}
+
+.assistant-hero p {
+ color: var(--text-muted);
+ font-size: 1.1rem;
+ max-width: 680px;
+ margin: 0 auto;
+ line-height: 1.6;
+}
+
+/* Tab Navigation */
+.view-tabs {
+ display: flex;
+ justify-content: center;
+ gap: 12px;
+ margin-bottom: 30px;
+}
+
+.tab-btn {
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ color: var(--text-muted);
+ padding: 10px 22px;
+ border-radius: 30px;
+ font-weight: 600;
+ font-size: 0.95rem;
+ cursor: pointer;
+ transition: all 0.25s ease;
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+}
+
+.tab-btn:hover {
+ color: var(--text-color);
+ border-color: var(--accent-color);
+}
+
+.tab-btn.active {
+ background: var(--accent-color);
+ color: #0b0f19;
+ border-color: var(--accent-color);
+ font-weight: 700;
+ box-shadow: 0 4px 14px rgba(56, 189, 248, 0.35);
+}
+
+/* Prompt Card */
+.prompt-card {
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ border-radius: 20px;
+ padding: 28px;
+ box-shadow: var(--card-shadow);
+ backdrop-filter: blur(12px);
+ margin-bottom: 36px;
+ position: relative;
+ overflow: hidden;
+}
+
+.prompt-card::before {
+ content: "";
+ position: absolute;
+ top: 0;
+ left: 0;
+ right: 0;
+ height: 3px;
+ background: linear-gradient(90deg, #0284c7, #38bdf8, #818cf8);
+}
+
+.prompt-label {
+ display: block;
+ font-weight: 700;
+ font-size: 1rem;
+ color: var(--text-color);
+ margin-bottom: 10px;
+}
+
+.prompt-textarea {
+ width: 100%;
+ min-height: 110px;
+ background: rgba(15, 23, 42, 0.6);
+ border: 1px solid var(--border-color);
+ border-radius: 14px;
+ padding: 16px;
+ color: var(--text-color);
+ font-family: inherit;
+ font-size: 1rem;
+ line-height: 1.5;
+ resize: vertical;
+ transition: border-color 0.2s, box-shadow 0.2s;
+ box-sizing: border-box;
+}
+
+[data-theme="light"] .prompt-textarea {
+ background: rgba(255, 255, 255, 0.9);
+}
+
+.prompt-textarea:focus {
+ outline: none;
+ border-color: var(--accent-color);
+ box-shadow: 0 0 0 3px rgba(56, 189, 248, 0.2);
+}
+
+/* Quick Suggestion Chips */
+.quick-prompts-label {
+ font-size: 0.85rem;
+ color: var(--text-muted);
+ margin-top: 14px;
+ margin-bottom: 8px;
+ font-weight: 600;
+ display: flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.chips-wrapper {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 8px;
+ margin-bottom: 20px;
+}
+
+.chip-btn {
+ background: rgba(255, 255, 255, 0.05);
+ border: 1px solid rgba(255, 255, 255, 0.1);
+ color: var(--text-muted);
+ font-size: 0.85rem;
+ padding: 6px 12px;
+ border-radius: 20px;
+ cursor: pointer;
+ transition: all 0.2s;
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+}
+
+[data-theme="light"] .chip-btn {
+ background: rgba(0, 0, 0, 0.04);
+ border-color: rgba(0, 0, 0, 0.1);
+}
+
+.chip-btn:hover {
+ background: rgba(56, 189, 248, 0.15);
+ border-color: var(--accent-color);
+ color: var(--accent-color);
+ transform: translateY(-1px);
+}
+
+/* Refinement Options Row */
+.options-row {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+ gap: 16px;
+ margin-bottom: 22px;
+ padding-top: 16px;
+ border-top: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.option-group label {
+ display: block;
+ font-size: 0.82rem;
+ font-weight: 600;
+ color: var(--text-muted);
+ margin-bottom: 6px;
+ text-transform: uppercase;
+ letter-spacing: 0.5px;
+}
+
+.option-select {
+ width: 100%;
+ padding: 9px 12px;
+ border-radius: 10px;
+ background: rgba(15, 23, 42, 0.6);
+ border: 1px solid var(--border-color);
+ color: var(--text-color);
+ font-size: 0.9rem;
+ cursor: pointer;
+}
+
+[data-theme="light"] .option-select {
+ background: rgba(255, 255, 255, 0.9);
+}
+
+.option-select:focus {
+ outline: none;
+ border-color: var(--accent-color);
+}
+
+.submit-row {
+ display: flex;
+ justify-content: flex-end;
+ align-items: center;
+ gap: 16px;
+}
+
+.generate-btn {
+ background: linear-gradient(135deg, #0284c7, #38bdf8);
+ color: #ffffff;
+ border: none;
+ padding: 12px 28px;
+ border-radius: 12px;
+ font-size: 1rem;
+ font-weight: 700;
+ cursor: pointer;
+ transition: all 0.25s ease;
+ display: inline-flex;
+ align-items: center;
+ gap: 10px;
+ box-shadow: 0 4px 15px rgba(2, 132, 199, 0.4);
+}
+
+.generate-btn:hover:not(:disabled) {
+ background: linear-gradient(135deg, #0369a1, #0284c7);
+ transform: translateY(-2px);
+ box-shadow: 0 6px 20px rgba(2, 132, 199, 0.5);
+}
+
+.generate-btn:disabled {
+ opacity: 0.6;
+ cursor: not-allowed;
+ transform: none;
+}
+
+/* Loading State */
+.loading-box {
+ display: none;
+ text-align: center;
+ padding: 60px 24px;
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ border-radius: 20px;
+ box-shadow: var(--card-shadow);
+}
+
+/* Modern Dual-Ring AI Spinner */
+.loading-spinner-wrapper {
+ position: relative;
+ width: 68px;
+ height: 68px;
+ margin: 0 auto 24px auto;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+}
+
+.spinner-outer-ring {
+ position: absolute;
+ inset: 0;
+ border-radius: 50%;
+ border: 3.5px solid rgba(56, 189, 248, 0.15);
+ border-top: 3.5px solid var(--accent-color);
+ border-right: 3.5px solid #818cf8;
+ -webkit-animation: spinClockwise 1s linear infinite !important;
+ animation: spinClockwise 1s linear infinite !important;
+ box-shadow: 0 0 16px rgba(56, 189, 248, 0.3);
+}
+
+.spinner-inner-ring {
+ position: absolute;
+ inset: 8px;
+ border-radius: 50%;
+ border: 3px solid rgba(129, 140, 248, 0.1);
+ border-top: 3px solid #38bdf8;
+ border-bottom: 3px solid #818cf8;
+ -webkit-animation: spinCounter 0.75s linear infinite !important;
+ animation: spinCounter 0.75s linear infinite !important;
+}
+
+.spinner-center-icon {
+ font-size: 1.35rem;
+ color: var(--accent-color);
+ -webkit-animation: pulseGlowIcon 1.5s ease-in-out infinite !important;
+ animation: pulseGlowIcon 1.5s ease-in-out infinite !important;
+}
+
+/* Fallback .spinner */
+.spinner {
+ width: 52px;
+ height: 52px;
+ border: 4px solid rgba(56, 189, 248, 0.2);
+ border-top: 4px solid var(--accent-color);
+ border-right: 4px solid #818cf8;
+ border-radius: 50%;
+ -webkit-animation: spinClockwise 0.9s linear infinite !important;
+ animation: spinClockwise 0.9s linear infinite !important;
+ margin: 0 auto 20px auto;
+ box-shadow: 0 0 16px rgba(56, 189, 248, 0.25);
+}
+
+@-webkit-keyframes spinClockwise {
+ 0% {
+ -webkit-transform: rotate(0deg);
+ transform: rotate(0deg);
+ }
+ 100% {
+ -webkit-transform: rotate(360deg);
+ transform: rotate(360deg);
+ }
+}
+
+@keyframes spinClockwise {
+ 0% {
+ -webkit-transform: rotate(0deg);
+ transform: rotate(0deg);
+ }
+ 100% {
+ -webkit-transform: rotate(360deg);
+ transform: rotate(360deg);
+ }
+}
+
+@-webkit-keyframes spinCounter {
+ 0% {
+ -webkit-transform: rotate(0deg);
+ transform: rotate(0deg);
+ }
+ 100% {
+ -webkit-transform: rotate(-360deg);
+ transform: rotate(-360deg);
+ }
+}
+
+@keyframes spinCounter {
+ 0% {
+ -webkit-transform: rotate(0deg);
+ transform: rotate(0deg);
+ }
+ 100% {
+ -webkit-transform: rotate(-360deg);
+ transform: rotate(-360deg);
+ }
+}
+
+@-webkit-keyframes pulseGlowIcon {
+ 0%, 100% {
+ opacity: 0.65;
+ -webkit-transform: scale(0.92);
+ transform: scale(0.92);
+ }
+ 50% {
+ opacity: 1;
+ -webkit-transform: scale(1.12);
+ transform: scale(1.12);
+ }
+}
+
+@keyframes pulseGlowIcon {
+ 0%, 100% {
+ opacity: 0.65;
+ transform: scale(0.92);
+ }
+ 50% {
+ opacity: 1;
+ transform: scale(1.12);
+ }
+}
+
+/* Ensure spinners always rotate even if user has reduced-motion active */
+@media (prefers-reduced-motion: reduce) {
+ .spinner-outer-ring,
+ .spinner-inner-ring,
+ .spinner-center-icon,
+ .spinner,
+ .fa-spin {
+ animation-duration: 1.2s !important;
+ animation-iteration-count: infinite !important;
+ -webkit-animation-iteration-count: infinite !important;
+ }
+}
+
+html[data-reduced-motion="true"] .spinner-outer-ring,
+html[data-reduced-motion="true"] .spinner-inner-ring,
+html[data-reduced-motion="true"] .spinner-center-icon,
+html[data-reduced-motion="true"] .spinner,
+html[data-reduced-motion="true"] .fa-spin {
+ animation-duration: 1.2s !important;
+ animation-iteration-count: infinite !important;
+ -webkit-animation-iteration-count: infinite !important;
+}
+
+.loading-box h3 {
+ font-size: 1.3rem;
+ margin-bottom: 8px;
+ color: var(--text-color);
+}
+
+.loading-ticker {
+ color: var(--text-muted);
+ font-size: 0.95rem;
+ min-height: 24px;
+}
+
+/* Error State */
+.error-box {
+ display: none;
+ background: rgba(239, 68, 68, 0.1);
+ border: 1px solid rgba(239, 68, 68, 0.3);
+ color: #f87171;
+ padding: 20px;
+ border-radius: 14px;
+ margin-bottom: 24px;
+ text-align: center;
+}
+
+.error-box button {
+ background: #ef4444;
+ color: #fff;
+ border: none;
+ padding: 6px 16px;
+ border-radius: 8px;
+ cursor: pointer;
+ margin-top: 10px;
+ font-weight: 600;
+}
+
+/* Recommendation Results Section */
+.results-wrapper {
+ display: none;
+ animation: fadeIn 0.4s ease;
+}
+
+@keyframes fadeIn {
+ from { opacity: 0; transform: translateY(10px); }
+ to { opacity: 1; transform: translateY(0); }
+}
+
+/* Learner Profile Banner */
+.profile-pill-strip {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
+ margin-bottom: 24px;
+}
+
+.profile-pill {
+ background: rgba(255, 255, 255, 0.05);
+ border: 1px solid var(--border-color);
+ padding: 8px 16px;
+ border-radius: 30px;
+ font-size: 0.88rem;
+ color: var(--text-color);
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+}
+
+.profile-pill strong {
+ color: var(--accent-color);
+}
+
+/* Summary Card */
+.overview-card {
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ border-radius: 18px;
+ padding: 26px;
+ margin-bottom: 24px;
+ box-shadow: var(--card-shadow);
+}
+
+.overview-card h2 {
+ font-size: 1.4rem;
+ color: var(--text-color);
+ margin-bottom: 12px;
+ display: flex;
+ align-items: center;
+ gap: 10px;
+}
+
+.overview-card p {
+ color: var(--text-muted);
+ line-height: 1.65;
+ font-size: 1rem;
+ margin-bottom: 14px;
+}
+
+.rationale-callout {
+ background: rgba(56, 189, 248, 0.07);
+ border-left: 4px solid var(--accent-color);
+ padding: 14px 18px;
+ border-radius: 0 10px 10px 0;
+ color: var(--text-color);
+ font-size: 0.95rem;
+ line-height: 1.55;
+ margin-top: 14px;
+}
+
+/* Immediate Next Step Card */
+.next-step-card {
+ background: linear-gradient(135deg, rgba(2, 132, 199, 0.15), rgba(56, 189, 248, 0.05));
+ border: 1px solid rgba(56, 189, 248, 0.35);
+ border-radius: 18px;
+ padding: 24px;
+ margin-bottom: 30px;
+ display: flex;
+ align-items: flex-start;
+ gap: 20px;
+}
+
+.next-step-icon {
+ font-size: 2rem;
+ color: var(--accent-color);
+ background: rgba(56, 189, 248, 0.15);
+ width: 56px;
+ height: 56px;
+ border-radius: 14px;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ flex-shrink: 0;
+}
+
+.next-step-content h3 {
+ font-size: 1.15rem;
+ color: var(--text-color);
+ margin-bottom: 6px;
+ font-weight: 700;
+}
+
+.next-step-content p {
+ color: var(--text-muted);
+ font-size: 0.98rem;
+ line-height: 1.55;
+ margin: 0;
+}
+
+/* Learning Sequence Roadmap */
+.section-heading {
+ font-size: 1.5rem;
+ font-weight: 700;
+ color: var(--text-color);
+ margin-bottom: 20px;
+ display: flex;
+ align-items: center;
+ gap: 10px;
+}
+
+.roadmap-timeline {
+ position: relative;
+ padding-left: 36px;
+ margin-bottom: 40px;
+}
+
+.roadmap-timeline::before {
+ content: "";
+ position: absolute;
+ left: 14px;
+ top: 10px;
+ bottom: 20px;
+ width: 3px;
+ background: linear-gradient(180deg, var(--accent-color), #818cf8);
+ border-radius: 2px;
+}
+
+.timeline-phase {
+ position: relative;
+ margin-bottom: 28px;
+}
+
+.phase-node {
+ position: absolute;
+ left: -36px;
+ top: 4px;
+ width: 28px;
+ height: 28px;
+ border-radius: 50%;
+ background: #0284c7;
+ border: 3px solid #0b0f19;
+ color: #fff;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ font-weight: 700;
+ font-size: 0.8rem;
+ box-shadow: 0 0 10px rgba(56, 189, 248, 0.5);
+}
+
+.phase-card {
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ border-radius: 14px;
+ padding: 20px;
+ box-shadow: var(--card-shadow);
+ transition: transform 0.2s, border-color 0.2s;
+}
+
+.phase-card:hover {
+ border-color: var(--accent-color);
+ transform: translateX(4px);
+}
+
+.phase-header {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ flex-wrap: wrap;
+ gap: 10px;
+ margin-bottom: 10px;
+}
+
+.phase-title {
+ font-size: 1.15rem;
+ font-weight: 700;
+ color: var(--text-color);
+}
+
+.phase-duration {
+ background: rgba(255, 255, 255, 0.08);
+ padding: 4px 10px;
+ border-radius: 20px;
+ font-size: 0.82rem;
+ font-weight: 600;
+ color: var(--accent-color);
+}
+
+.phase-details {
+ color: var(--text-muted);
+ font-size: 0.92rem;
+ line-height: 1.5;
+ margin-bottom: 12px;
+}
+
+.phase-project {
+ background: rgba(16, 185, 129, 0.1);
+ border: 1px solid rgba(16, 185, 129, 0.25);
+ color: #10b981;
+ padding: 8px 12px;
+ border-radius: 8px;
+ font-size: 0.86rem;
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+ font-weight: 600;
+}
+
+/* Recommended Courses Grid */
+.courses-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(360px, 1fr));
+ gap: 24px;
+ margin-bottom: 40px;
+}
+
+.course-card {
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ border-radius: 18px;
+ padding: 24px;
+ box-shadow: var(--card-shadow);
+ display: flex;
+ flex-direction: column;
+ justify-content: space-between;
+ transition: transform 0.25s, border-color 0.25s;
+ position: relative;
+ overflow: hidden;
+}
+
+.course-card:hover {
+ transform: translateY(-4px);
+ border-color: var(--accent-color);
+}
+
+.course-top-badges {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ margin-bottom: 12px;
+}
+
+.badge-topic {
+ font-size: 0.8rem;
+ font-weight: 700;
+ text-transform: uppercase;
+ color: var(--accent-color);
+}
+
+.badge-diff {
+ font-size: 0.75rem;
+ font-weight: 700;
+ padding: 3px 8px;
+ border-radius: 6px;
+ text-transform: uppercase;
+}
+
+.diff-beginner { background: rgba(16, 185, 129, 0.15); color: #10b981; }
+.diff-intermediate { background: rgba(245, 158, 11, 0.15); color: #f59e0b; }
+.diff-advanced { background: rgba(239, 68, 68, 0.15); color: #ef4444; }
+
+.course-card h3 {
+ font-size: 1.25rem;
+ color: var(--text-color);
+ margin-bottom: 10px;
+ font-weight: 700;
+}
+
+.course-card p {
+ color: var(--text-muted);
+ font-size: 0.92rem;
+ line-height: 1.5;
+ margin-bottom: 16px;
+}
+
+.course-meta {
+ display: flex;
+ gap: 14px;
+ font-size: 0.84rem;
+ color: var(--text-muted);
+ margin-bottom: 14px;
+}
+
+.course-resource-pills {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 6px;
+ margin-bottom: 18px;
+}
+
+.res-pill {
+ background: rgba(255, 255, 255, 0.05);
+ border: 1px solid rgba(255, 255, 255, 0.08);
+ font-size: 0.75rem;
+ padding: 3px 8px;
+ border-radius: 4px;
+ color: var(--text-muted);
+}
+
+.modules-toggle {
+ background: transparent;
+ border: 1px solid var(--border-color);
+ color: var(--text-color);
+ padding: 8px 14px;
+ border-radius: 8px;
+ cursor: pointer;
+ font-size: 0.85rem;
+ font-weight: 600;
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ width: 100%;
+ margin-bottom: 12px;
+}
+
+.modules-accordion {
+ display: none;
+ background: rgba(15, 23, 42, 0.4);
+ border-radius: 8px;
+ padding: 12px;
+ margin-bottom: 14px;
+ font-size: 0.85rem;
+}
+
+[data-theme="light"] .modules-accordion {
+ background: rgba(0, 0, 0, 0.03);
+}
+
+.module-item {
+ padding: 6px 0;
+ border-bottom: 1px solid rgba(255, 255, 255, 0.05);
+}
+
+.module-item:last-child {
+ border-bottom: none;
+}
+
+.module-item-title {
+ font-weight: 600;
+ color: var(--text-color);
+}
+
+.module-item-project {
+ color: var(--text-muted);
+ font-size: 0.8rem;
+ margin-top: 2px;
+}
+
+.capstone-box {
+ background: rgba(56, 189, 248, 0.06);
+ border: 1px dashed rgba(56, 189, 248, 0.3);
+ border-radius: 8px;
+ padding: 10px 12px;
+ font-size: 0.84rem;
+ color: var(--text-color);
+ margin-bottom: 16px;
+}
+
+.capstone-box strong {
+ color: var(--accent-color);
+}
+
+/* Follow-up Interactive Chat */
+.assistant-chat-section {
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ border-radius: 20px;
+ padding: 26px;
+ box-shadow: var(--card-shadow);
+ margin-top: 40px;
+}
+
+.chat-messages-container {
+ max-height: 380px;
+ overflow-y: auto;
+ padding: 14px;
+ background: rgba(15, 23, 42, 0.4);
+ border-radius: 14px;
+ margin-bottom: 16px;
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+}
+
+[data-theme="light"] .chat-messages-container {
+ background: rgba(0, 0, 0, 0.03);
+}
+
+.chat-bubble {
+ max-width: 80%;
+ padding: 12px 16px;
+ border-radius: 14px;
+ line-height: 1.5;
+ font-size: 0.95rem;
+}
+
+.chat-bubble.user {
+ align-self: flex-end;
+ background: #0284c7;
+ color: #fff;
+ border-bottom-right-radius: 4px;
+}
+
+.chat-bubble.assistant {
+ align-self: flex-start;
+ background: rgba(255, 255, 255, 0.08);
+ color: var(--text-color);
+ border-bottom-left-radius: 4px;
+ border: 1px solid rgba(255, 255, 255, 0.05);
+}
+
+[data-theme="light"] .chat-bubble.assistant {
+ background: #ffffff;
+ border-color: rgba(0, 0, 0, 0.08);
+ box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05);
+}
+
+.chat-input-wrapper {
+ display: flex;
+ gap: 10px;
+}
+
+.chat-input {
+ flex: 1;
+ background: rgba(15, 23, 42, 0.6);
+ border: 1px solid var(--border-color);
+ color: var(--text-color);
+ padding: 12px 16px;
+ border-radius: 12px;
+ font-size: 0.95rem;
+}
+
+[data-theme="light"] .chat-input {
+ background: #ffffff;
+}
+
+.chat-input:focus {
+ outline: none;
+ border-color: var(--accent-color);
+}
+
+.chat-send-btn {
+ background: var(--accent-color);
+ color: #0b0f19;
+ border: none;
+ padding: 0 22px;
+ border-radius: 12px;
+ font-weight: 700;
+ cursor: pointer;
+ transition: all 0.2s;
+}
+
+.chat-send-btn:hover {
+ background: #0284c7;
+ color: #ffffff;
+}
+
+/* Catalog View Section */
+.catalog-section {
+ display: none;
+}
+
+.catalog-filters {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
+ margin-bottom: 24px;
+ align-items: center;
+}
+
+.catalog-search-input {
+ flex: 1;
+ min-width: 240px;
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ color: var(--text-color);
+ padding: 10px 16px;
+ border-radius: 10px;
+ font-size: 0.95rem;
+}
+
+.catalog-search-input:focus {
+ outline: none;
+ border-color: var(--accent-color);
+}
+
+/* History Modal or Drawer */
+.history-item {
+ background: rgba(255, 255, 255, 0.03);
+ border: 1px solid rgba(255, 255, 255, 0.08);
+ border-radius: 12px;
+ padding: 14px 18px;
+ margin-bottom: 12px;
+ cursor: pointer;
+ transition: all 0.2s;
+}
+
+.history-item:hover {
+ border-color: var(--accent-color);
+ background: rgba(56, 189, 248, 0.05);
+}
+
+.history-query {
+ font-weight: 600;
+ color: var(--text-color);
+ margin-bottom: 4px;
+}
+
+.history-meta {
+ font-size: 0.8rem;
+ color: var(--text-muted);
+}
+
+/* Empty State */
+.empty-state {
+ text-align: center;
+ padding: 60px 20px;
+ color: var(--text-muted);
+}
+
+.empty-state i {
+ font-size: 3rem;
+ color: var(--accent-color);
+ margin-bottom: 16px;
+ opacity: 0.7;
+}
+
+.empty-state h3 {
+ color: var(--text-color);
+ font-size: 1.3rem;
+ margin-bottom: 8px;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+ .assistant-hero h1 {
+ font-size: 1.9rem;
+ }
+ .options-row {
+ grid-template-columns: 1fr;
+ }
+ .courses-grid {
+ grid-template-columns: 1fr;
+ }
+ .next-step-card {
+ flex-direction: column;
+ }
+ .roadmap-timeline {
+ padding-left: 28px;
+ }
+ .phase-node {
+ left: -28px;
+ }
+}
+
+/* โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+ DAG Graph & Visual Roadmap Enhancements
+ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ */
+
+/* Structured Takeaways Cards Grid (Replaces monolithic paragraphs) */
+.takeaways-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+ gap: 16px;
+ margin-top: 18px;
+}
+
+.takeaway-card {
+ background: rgba(15, 23, 42, 0.45);
+ border: 1px solid rgba(255, 255, 255, 0.08);
+ border-radius: 14px;
+ padding: 18px;
+ transition: transform 0.2s, border-color 0.2s;
+ display: flex;
+ flex-direction: column;
+}
+
+[data-theme="light"] .takeaway-card {
+ background: rgba(255, 255, 255, 0.9);
+ border-color: rgba(0, 0, 0, 0.08);
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.04);
+}
+
+.takeaway-card:hover {
+ transform: translateY(-2px);
+ border-color: var(--accent-color);
+}
+
+.takeaway-header {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ margin-bottom: 8px;
+}
+
+.takeaway-icon-box {
+ width: 36px;
+ height: 36px;
+ border-radius: 10px;
+ background: rgba(56, 189, 248, 0.15);
+ color: var(--accent-color);
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ font-size: 1rem;
+ flex-shrink: 0;
+}
+
+.takeaway-title {
+ font-size: 0.95rem;
+ font-weight: 700;
+ color: var(--text-color);
+}
+
+.takeaway-desc {
+ color: var(--text-muted);
+ font-size: 0.88rem;
+ line-height: 1.5;
+ margin: 0;
+}
+
+/* Interactive Next Step Card */
+.next-step-detailed {
+ display: flex;
+ flex-direction: column;
+ gap: 14px;
+ margin-top: 10px;
+}
+
+.next-step-badge-row {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ gap: 10px;
+}
+
+.next-step-badge {
+ background: rgba(56, 189, 248, 0.2);
+ border: 1px solid rgba(56, 189, 248, 0.4);
+ color: var(--accent-color);
+ padding: 4px 12px;
+ border-radius: 20px;
+ font-size: 0.8rem;
+ font-weight: 700;
+ text-transform: uppercase;
+}
+
+.next-step-checklist {
+ list-style: none;
+ padding: 0;
+ margin: 0;
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+
+.next-step-item {
+ display: flex;
+ align-items: flex-start;
+ gap: 10px;
+ font-size: 0.92rem;
+ color: var(--text-color);
+ line-height: 1.45;
+}
+
+.next-step-item i {
+ color: #10b981;
+ margin-top: 3px;
+}
+
+/* DAG Roadmap Flow Container */
+.dag-view-toggle {
+ display: inline-flex;
+ background: rgba(15, 23, 42, 0.6);
+ border: 1px solid var(--border-color);
+ border-radius: 30px;
+ padding: 4px;
+ margin-bottom: 24px;
+}
+
+[data-theme="light"] .dag-view-toggle {
+ background: rgba(0, 0, 0, 0.05);
+}
+
+.dag-view-btn {
+ background: transparent;
+ border: none;
+ color: var(--text-muted);
+ padding: 8px 18px;
+ border-radius: 20px;
+ font-size: 0.85rem;
+ font-weight: 600;
+ cursor: pointer;
+ transition: all 0.2s;
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.dag-view-btn.active {
+ background: var(--accent-color);
+ color: #0b0f19;
+ font-weight: 700;
+ box-shadow: 0 2px 8px rgba(56, 189, 248, 0.3);
+}
+
+/* DAG Visual Tree Layout */
+.dag-flow-tree {
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ position: relative;
+ max-width: 900px;
+ margin: 0 auto;
+}
+
+.dag-node-wrapper {
+ width: 100%;
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ position: relative;
+}
+
+.dag-node-card {
+ width: 100%;
+ background: var(--card-bg);
+ border: 1px solid var(--card-border);
+ border-radius: 16px;
+ padding: 22px;
+ box-shadow: var(--card-shadow);
+ position: relative;
+ transition: all 0.25s ease;
+ backdrop-filter: blur(10px);
+}
+
+.dag-node-card:hover {
+ border-color: var(--accent-color);
+ transform: translateY(-2px);
+ box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);
+}
+
+.dag-node-card.active-node {
+ border-color: var(--accent-color);
+ box-shadow: 0 0 20px rgba(56, 189, 248, 0.25);
+ background: linear-gradient(135deg, rgba(30, 41, 59, 0.9), rgba(15, 23, 42, 0.9));
+}
+
+.dag-node-card.completed-node {
+ border-color: rgba(16, 185, 129, 0.5);
+ background: rgba(16, 185, 129, 0.04);
+}
+
+.dag-node-card.completed-node .dag-node-step {
+ background: #10b981;
+}
+
+/* Node Top Bar */
+.dag-node-top {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ flex-wrap: wrap;
+ gap: 8px;
+ margin-bottom: 12px;
+}
+
+.dag-node-left {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+}
+
+.dag-node-step {
+ background: #0284c7;
+ color: #fff;
+ font-size: 0.75rem;
+ font-weight: 800;
+ padding: 3px 10px;
+ border-radius: 20px;
+ letter-spacing: 0.5px;
+ text-transform: uppercase;
+}
+
+.dag-category-pill {
+ font-size: 0.75rem;
+ font-weight: 700;
+ padding: 3px 10px;
+ border-radius: 6px;
+ text-transform: uppercase;
+}
+
+.cat-gateway { background: rgba(56, 189, 248, 0.15); color: #38bdf8; }
+.cat-core { background: rgba(99, 102, 241, 0.15); color: #818cf8; }
+.cat-pattern { background: rgba(236, 72, 153, 0.15); color: #f472b6; }
+.cat-framework { background: rgba(245, 158, 11, 0.15); color: #f59e0b; }
+.cat-capstone { background: rgba(16, 185, 129, 0.15); color: #10b981; }
+
+.dag-status-indicator {
+ font-size: 0.8rem;
+ font-weight: 600;
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.status-in-progress {
+ color: #38bdf8;
+ animation: pulseGlow 1.8s infinite;
+}
+
+.status-completed {
+ color: #10b981;
+}
+
+.status-locked {
+ color: var(--text-muted);
+}
+
+@keyframes pulseGlow {
+ 0%, 100% { opacity: 1; transform: scale(1); }
+ 50% { opacity: 0.7; transform: scale(0.98); }
+}
+
+/* Node Content */
+.dag-node-title {
+ font-size: 1.2rem;
+ font-weight: 700;
+ color: var(--text-color);
+ margin-bottom: 4px;
+}
+
+.dag-node-course-sub {
+ font-size: 0.84rem;
+ color: var(--accent-color);
+ margin-bottom: 12px;
+ display: flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.dag-node-chips {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 6px;
+ margin-bottom: 14px;
+}
+
+.dag-topic-tag {
+ background: rgba(255, 255, 255, 0.05);
+ border: 1px solid rgba(255, 255, 255, 0.08);
+ font-size: 0.78rem;
+ padding: 3px 10px;
+ border-radius: 6px;
+ color: var(--text-muted);
+}
+
+[data-theme="light"] .dag-topic-tag {
+ background: rgba(0, 0, 0, 0.04);
+ border-color: rgba(0, 0, 0, 0.08);
+}
+
+.dag-project-box {
+ background: rgba(16, 185, 129, 0.08);
+ border: 1px dashed rgba(16, 185, 129, 0.3);
+ border-radius: 8px;
+ padding: 10px 14px;
+ font-size: 0.85rem;
+ color: #10b981;
+ margin-bottom: 14px;
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ font-weight: 600;
+}
+
+.dag-node-footer {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ flex-wrap: wrap;
+ gap: 10px;
+ padding-top: 12px;
+ border-top: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.dag-hours-pill {
+ font-size: 0.82rem;
+ color: var(--text-muted);
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.dag-toggle-complete-btn {
+ background: transparent;
+ border: 1px solid var(--border-color);
+ color: var(--text-color);
+ padding: 6px 14px;
+ border-radius: 8px;
+ font-size: 0.82rem;
+ font-weight: 600;
+ cursor: pointer;
+ transition: all 0.2s;
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.dag-toggle-complete-btn:hover {
+ border-color: #10b981;
+ color: #10b981;
+}
+
+.dag-toggle-complete-btn.is-done {
+ background: #10b981;
+ border-color: #10b981;
+ color: #ffffff;
+}
+
+/* Connector Line Between DAG Nodes */
+.dag-connector {
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ justify-content: center;
+ height: 48px;
+ position: relative;
+}
+
+.dag-connector-line {
+ width: 3px;
+ height: 32px;
+ background: linear-gradient(180deg, var(--accent-color), #818cf8);
+ border-radius: 2px;
+}
+
+.dag-connector-arrow {
+ color: #818cf8;
+ font-size: 0.9rem;
+ margin-top: -6px;
+}
+
+.dag-connector-label {
+ position: absolute;
+ right: calc(50% + 12px);
+ background: rgba(15, 23, 42, 0.8);
+ border: 1px solid rgba(255, 255, 255, 0.1);
+ color: var(--text-muted);
+ font-size: 0.72rem;
+ padding: 2px 8px;
+ border-radius: 10px;
+ white-space: nowrap;
+ text-transform: uppercase;
+ letter-spacing: 0.5px;
+}
+
+[data-theme="light"] .dag-connector-label {
+ background: #ffffff;
+ border-color: rgba(0, 0, 0, 0.1);
+}
+
diff --git a/assistant.html b/assistant.html
new file mode 100644
index 0000000..7931a09
--- /dev/null
+++ b/assistant.html
@@ -0,0 +1,370 @@
+
+
+
+ AI Learning Assistant โ LearnSphere
+
+
+
+
+
+
+ Your Personalized Learning Assistant
+
+ Describe your technical ambition, current background, and timeframe.
+ Our AI searches LearnSphere's structured content library to build your custom milestone roadmap.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ โก Basic JS to React Developer (3 Months)
+
+
+ ๐ Beginner to Machine Learning with Python (4 Months)
+
+
+ ๐ Frontend to Full-Stack Node & SQL (6 Weeks)
+
+
+ โ Java OOP & Spring Boot Microservices (8 Weeks)
+
+
+ ๐๏ธ SQL Database Architecture & Optimization (1 Month)
+
+
+
+
+
+
+ Current Skill Level
+
+ Auto-detect from description
+ Beginner (Starting from scratch)
+ Intermediate (Know fundamentals)
+ Advanced (Experienced developer)
+
+
+
+
+ Target Timeframe
+
+ 3 Months
+ 6 Weeks
+ 4 Months
+ 6 Months
+ Self-Paced (Flexible)
+
+
+
+
+ Weekly Commitment
+
+ ~6 hours/week (Part-time)
+ ~4 hours/week (Light)
+ ~10 hours/week (Standard)
+ ~15 hours/week (Accelerated)
+ ~25 hours/week (Intensive)
+
+
+
+
+ Tip: Press Ctrl+Enter to submit
+
+
+
+
+
+
+
+
+
+ Crafting Your Custom Learning Path
+ Analyzing your career ambition and skill profile...
+
+
+
+
+
+ Unable to generate recommendation.
+ Try Again
+
+
+
+
+ No Roadmap Generated Yet
+ Type your learning goals above or select one of the quick-start templates to see personalized recommendations in action.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Your Immediate Next Step for Today
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Technical topics are connected in a Directed Acyclic Graph (DAG) dependency sequence. Each node represents an actionable curriculum milestone with lessons, hours, and code deliverables.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Ask Follow-up Questions About Your Roadmap
+
+
+ Have questions about study pacing, interview preparation, or specific code exercises? Ask below:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Explore all 8 technical tracks created for LearnSphere. Click any course to have the AI build a custom roadmap around it!
+
+
+
+
+ All Topics
+ JavaScript
+ React
+ Node.js
+ Python
+ Java
+ SQL
+ Machine Learning
+ Full Stack
+
+
+
+ All Difficulties
+ Beginner
+ Intermediate
+ Advanced
+
+
+
+
+
+
+
+
+
+
+
+ Review your previous guidance sessions stored in the LearnSphere database. Click any session to reload its plan.
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/assistant.js b/assistant.js
new file mode 100644
index 0000000..723ec38
--- /dev/null
+++ b/assistant.js
@@ -0,0 +1,868 @@
+/**
+ * assistant.js โ LearnSphere AI Learning Assistant Client Controller
+ */
+
+(function () {
+ "use strict";
+
+ // API Base URL (proxied by Vite during dev or uses port 5000 directly)
+ const API_BASE = window.location.origin;
+
+ // DOM Elements
+ const promptInput = document.getElementById("goalPrompt");
+ const levelSelect = document.getElementById("learnerLevel");
+ const timeframeSelect = document.getElementById("targetTimeframe");
+ const hoursSelect = document.getElementById("weeklyHours");
+ const generateBtn = document.getElementById("generateBtn");
+
+ const loadingBox = document.getElementById("loadingBox");
+ const loadingTicker = document.getElementById("loadingTicker");
+ const errorBox = document.getElementById("errorBox");
+ const errorMessage = document.getElementById("errorMessage");
+ const emptyState = document.getElementById("emptyState");
+ const resultsWrapper = document.getElementById("resultsWrapper");
+
+ // Results Sub-containers
+ const profilePillsContainer = document.getElementById("profilePillsContainer");
+ const summaryText = document.getElementById("summaryText");
+ const whyRecommendedText = document.getElementById("whyRecommendedText");
+ const takeawaysGrid = document.getElementById("takeawaysGrid");
+ const nextStepDetailed = document.getElementById("nextStepDetailed");
+ const immediateNextStepText = document.getElementById("immediateNextStepText");
+ const dagFlowTree = document.getElementById("dagFlowTree");
+ const roadmapTimeline = document.getElementById("roadmapTimeline");
+ const dagToggleTree = document.getElementById("dagToggleTree");
+ const dagToggleTimeline = document.getElementById("dagToggleTimeline");
+ const recommendedCoursesGrid = document.getElementById("recommendedCoursesGrid");
+ const alternativePathsContainer = document.getElementById("alternativePathsContainer");
+
+ // Chat Elements
+ const chatContainer = document.getElementById("chatMessages");
+ const chatInput = document.getElementById("chatInput");
+ const chatSendBtn = document.getElementById("chatSendBtn");
+ const suggestedChipsContainer = document.getElementById("suggestedChips");
+
+ // Tab buttons & Views
+ const tabRoadmap = document.getElementById("tabRoadmap");
+ const tabCatalog = document.getElementById("tabCatalog");
+ const tabHistory = document.getElementById("tabHistory");
+ const assistantMainView = document.getElementById("assistantMainView");
+ const catalogView = document.getElementById("catalogView");
+ const historyView = document.getElementById("historyView");
+
+ // Catalog elements
+ const catalogSearchInput = document.getElementById("catalogSearch");
+ const catalogTopicFilter = document.getElementById("catalogTopicFilter");
+ const catalogDiffFilter = document.getElementById("catalogDiffFilter");
+ const allCoursesGrid = document.getElementById("allCoursesGrid");
+ const historyList = document.getElementById("historyList");
+
+ let currentSessionId = "sess-" + Math.random().toString(36).substring(2, 9);
+ let currentQueryId = null;
+ let allCoursesData = [];
+
+ // Loading Step Ticker Messages
+ const tickerSteps = [
+ "Analyzing your career ambition and skill profile...",
+ "Querying LearnSphere's structured content database...",
+ "Identifying prerequisite bridges and knowledge gaps...",
+ "Computing semantic relevance and course progression...",
+ "Synthesizing your personalized roadmap and immediate next step..."
+ ];
+ let tickerInterval = null;
+
+ // --- Tab Switching ---
+ function switchTab(activeTab) {
+ [tabRoadmap, tabCatalog, tabHistory].forEach(t => t && t.classList.remove("active"));
+ if (assistantMainView) assistantMainView.style.display = "none";
+ if (catalogView) catalogView.style.display = "none";
+ if (historyView) historyView.style.display = "none";
+
+ if (activeTab === "roadmap") {
+ if (tabRoadmap) tabRoadmap.classList.add("active");
+ if (assistantMainView) assistantMainView.style.display = "block";
+ } else if (activeTab === "catalog") {
+ if (tabCatalog) tabCatalog.classList.add("active");
+ if (catalogView) catalogView.style.display = "block";
+ loadCatalogContent();
+ } else if (activeTab === "history") {
+ if (tabHistory) tabHistory.classList.add("active");
+ if (historyView) historyView.style.display = "block";
+ loadHistoryData();
+ }
+ }
+
+ if (tabRoadmap) tabRoadmap.addEventListener("click", () => switchTab("roadmap"));
+ if (tabCatalog) tabCatalog.addEventListener("click", () => switchTab("catalog"));
+ if (tabHistory) tabHistory.addEventListener("click", () => switchTab("history"));
+
+ // --- DAG Graph vs Timeline Switcher ---
+ if (dagToggleTree && dagToggleTimeline && dagFlowTree && roadmapTimeline) {
+ dagToggleTree.addEventListener("click", () => {
+ dagToggleTree.classList.add("active");
+ dagToggleTimeline.classList.remove("active");
+ dagFlowTree.style.display = "flex";
+ roadmapTimeline.style.display = "none";
+ });
+
+ dagToggleTimeline.addEventListener("click", () => {
+ dagToggleTimeline.classList.add("active");
+ dagToggleTree.classList.remove("active");
+ dagFlowTree.style.display = "none";
+ roadmapTimeline.style.display = "block";
+ });
+ }
+
+ // --- Preset Prompt Chips ---
+ document.querySelectorAll(".chip-btn").forEach(btn => {
+ btn.addEventListener("click", () => {
+ const promptText = btn.getAttribute("data-prompt");
+ if (promptText && promptInput) {
+ promptInput.value = promptText;
+ promptInput.focus();
+ // Auto submit for rapid demo evaluation
+ submitGoalRequest();
+ }
+ });
+ });
+
+ // --- Start / Stop Loading ---
+ function startLoading() {
+ if (emptyState) emptyState.style.display = "none";
+ if (resultsWrapper) resultsWrapper.style.display = "none";
+ if (errorBox) errorBox.style.display = "none";
+ if (loadingBox) {
+ loadingBox.style.display = "block";
+ loadingBox.scrollIntoView({ behavior: "smooth", block: "center" });
+ }
+ if (generateBtn) {
+ generateBtn.disabled = true;
+ generateBtn.innerHTML = `${escapeHtml(p.target_role || "Developer")}
+ ${escapeHtml(p.current_level || "Beginner")}
+ ${escapeHtml(p.timeframe || "3 months")} (~${p.weekly_commitment_hours || 6} hrs/wk)
+ `;
+ }
+
+ // 2. Summary & Structured Takeaways
+ if (summaryText) summaryText.innerHTML = formatMarkdown(data.summary || "");
+ if (whyRecommendedText) whyRecommendedText.innerHTML = formatMarkdown(data.why_recommended || "");
+ renderTakeawaysGrid(data);
+
+ // 3. Immediate Next Step
+ renderNextStepDetailed(data);
+
+ // 4. Interactive DAG Graph Roadmap
+ renderDAGTree(data);
+
+ // 5. Learning Sequence / Roadmap Timeline (Alternative View)
+ if (roadmapTimeline) {
+ roadmapTimeline.innerHTML = "";
+ const seq = data.learning_sequence || [];
+ seq.forEach((phase, idx) => {
+ const phaseEl = document.createElement("div");
+ phaseEl.className = "timeline-phase";
+ phaseEl.innerHTML = `
+ ${phase.phase_number || (idx + 1)}
+
+
+
${escapeHtml(phase.weekly_focus || "")}
+
+
+ ${phase.actionable_project ? `
+
+
+ ` : ""}
+
${escapeHtml(r)} `).join("");
+ const topicsChips = (c.topics_covered || []).slice(0, 5).map(t => `
+
${escapeHtml(m.title)} (${escapeHtml(m.duration)})
+
+
+
+ ${escapeHtml(c.difficulty)}
+
+
${escapeHtml(c.title)}
+
+
+
${escapeHtml(c.description)}
+
+
+
+
+ ${escapeHtml(c.why_relevant)}
+
+
+
Resource Formats:
+
${resourceBadges}
+
+
Key Topics Covered:
+
${topicsChips}
+
+
+
+
${modulesList}
+
+ ${c.capstone_project && c.capstone_project.title ? `
+
+
+ ` : ""}
+
+
+
+
+ `;
+
+ // Toggle modules accordion
+ const toggleBtn = card.querySelector(".modules-toggle");
+ const accordion = card.querySelector(".modules-accordion");
+ const arrow = card.querySelector(".toggle-arrow");
+ toggleBtn.addEventListener("click", () => {
+ const isOpen = accordion.style.display === "block";
+ accordion.style.display = isOpen ? "none" : "block";
+ arrow.style.transform = isOpen ? "rotate(0deg)" : "rotate(180deg)";
+ });
+
+ // Start course action
+ const startBtn = card.querySelector(".start-course-btn");
+ startBtn.addEventListener("click", () => {
+ alert(`Starting course: ${c.title}! Modules and interactive practice labs are now active in your learner queue.`);
+ });
+
+ recommendedCoursesGrid.appendChild(card);
+ });
+
+ // 6. Alternative Pathways
+ if (alternativePathsContainer) {
+ const alts = data.alternative_paths || [];
+ if (alts.length > 0) {
+ alternativePathsContainer.innerHTML = alts.map(a => `
+
+
${escapeHtml(pt.description || "")}
+
+
+
${formatMarkdown(data.why_recommended)}
+
+ ${escapeHtml(actionTitle)}
+
+
+ ${escapeHtml(course)} ${escapeHtml(estTime)}
+ ${deliverable ? `
+
+
+
${escapeHtml(deliverable)}
+
No roadmap nodes available.
`;
+ return;
+ }
+
+ const totalNodes = nodes.length;
+
+ // Top progress bar header
+ const progressHeader = document.createElement("div");
+ progressHeader.className = "dag-progress-header";
+ progressHeader.style.cssText = "width:100%; max-width:820px; background:var(--card-bg); border:1px solid var(--card-border); border-radius:14px; padding:16px 22px; margin-bottom:28px; display:flex; justify-content:space-between; align-items:center; flex-wrap:wrap; gap:14px; box-shadow:var(--card-shadow);";
+
+ progressHeader.innerHTML = `
+
+
+
+
+
DAG Curriculum Mastery Track
+
0 of ${totalNodes} milestones completed (0%)
+
+
${escapeHtml(node.title)}
+ ${node.course_title ? `
` : ""}
+ ${node.summary ? `${escapeHtml(node.summary)}
` : ""}
+
+ ${skillsHtml ? `
+ Skills Acquired:
+ ${skillsHtml}
+ ` : ""}
+
+ ${node.hands_on_project ? `
+
+
+
+ Hands-on Project:
+ ${escapeHtml(node.hands_on_project)}
+
+
Mark Complete `;
+ card.style.borderColor = "";
+ card.style.background = "";
+ if (statusEl) {
+ statusEl.className = `dag-status-indicator ${isFirst ? "status-in-progress" : ""}`;
+ statusEl.innerHTML = `${initialStatus} `;
+ }
+ } else {
+ completedSet.add(nodeId);
+ btn.classList.add("is-done");
+ btn.innerHTML = `Milestone Completed! `;
+ card.style.borderColor = "rgba(16, 185, 129, 0.5)";
+ card.style.background = "linear-gradient(135deg, var(--card-bg) 80%, rgba(16, 185, 129, 0.08))";
+ if (statusEl) {
+ statusEl.className = "dag-status-indicator status-completed";
+ statusEl.innerHTML = `Completed `;
+ }
+ }
+ updateProgress();
+ });
+
+ dagFlowTree.appendChild(card);
+
+ // Render connector to next milestone if not the final node
+ if (idx < totalNodes - 1) {
+ const connector = document.createElement("div");
+ connector.className = "dag-connector";
+ connector.innerHTML = `
+ unlocks milestone #${idx + 2}
+
+
+ `;
+ dagFlowTree.appendChild(connector);
+ }
+ });
+ }
+
+ // --- Interactive Follow-up Chat ---
+ function initChatWithGreeting(data) {
+ if (!chatContainer) return;
+ chatContainer.innerHTML = `
+
+ Hello! I have created your personalized ${escapeHtml(data.learner_profile.target_role || "learning")} roadmap.
+ You can ask me anything about your pace, how to prepare for interviews, or how to tackle specific modules!
+
+ `;
+ }
+
+ async function sendChatMessage() {
+ const msg = chatInput ? chatInput.value.trim() : "";
+ if (!msg) return;
+
+ // Append user bubble
+ appendChatBubble("user", msg);
+ if (chatInput) chatInput.value = "";
+
+ // Typing indicator
+ const typingEl = document.createElement("div");
+ typingEl.className = "chat-bubble assistant";
+ typingEl.id = "chatTypingIndicator";
+ typingEl.innerHTML = `${escapeHtml(p)}
+ `).join("");
+
+ suggestedChipsContainer.querySelectorAll(".chat-suggestion-chip").forEach(btn => {
+ btn.addEventListener("click", () => {
+ const nextMsg = btn.getAttribute("data-msg");
+ if (chatInput) chatInput.value = nextMsg;
+ sendChatMessage();
+ });
+ });
+ }
+ } catch (err) {
+ const typing = document.getElementById("chatTypingIndicator");
+ if (typing) typing.remove();
+ appendChatBubble("assistant", "Sorry, I encountered an issue replying. Please try again!");
+ }
+ }
+
+ function appendChatBubble(role, text) {
+ if (!chatContainer) return;
+ const bubble = document.createElement("div");
+ bubble.className = `chat-bubble ${role}`;
+ bubble.innerHTML = formatMarkdown(text);
+ chatContainer.appendChild(bubble);
+ chatContainer.scrollTop = chatContainer.scrollHeight;
+ }
+
+ if (chatSendBtn) chatSendBtn.addEventListener("click", sendChatMessage);
+ if (chatInput) {
+ chatInput.addEventListener("keydown", (e) => {
+ if (e.key === "Enter") {
+ e.preventDefault();
+ sendChatMessage();
+ }
+ });
+ }
+
+ // --- Content Catalog Explorer ---
+ async function loadCatalogContent() {
+ if (!allCoursesGrid) return;
+ allCoursesGrid.innerHTML = `Loading content catalog...
`;
+
+ try {
+ const res = await fetch(`${API_BASE}/api/ai/content`);
+ const data = await res.json();
+ allCoursesData = data.courses || [];
+ renderCatalogList(allCoursesData);
+ } catch (err) {
+ allCoursesGrid.innerHTML = `Failed to load catalog. Please ensure the backend server is running.
`;
+ }
+ }
+
+ function renderCatalogList(courses) {
+ if (!allCoursesGrid) return;
+ allCoursesGrid.innerHTML = "";
+
+ if (courses.length === 0) {
+ allCoursesGrid.innerHTML = `No courses found matching your filter criteria.
`;
+ return;
+ }
+
+ courses.forEach(c => {
+ const card = document.createElement("div");
+ card.className = "course-card";
+ const diffClass = c.difficulty.toLowerCase() === "beginner" ? "diff-beginner"
+ : (c.difficulty.toLowerCase() === "intermediate" ? "diff-intermediate" : "diff-advanced");
+
+ card.innerHTML = `
+
+
+ ${escapeHtml(c.topic)}
+ ${escapeHtml(c.difficulty)}
+
+
${escapeHtml(c.title)}
+
+
+
${escapeHtml(c.description)}
+
+ Prerequisites: ${(c.prerequisites || []).join(", ") || "None"}
+
+
+
+ `;
+
+ card.querySelector(".plan-with-course-btn").addEventListener("click", () => {
+ switchTab("roadmap");
+ if (promptInput) {
+ promptInput.value = `I want to master ${c.topic} and build real-world projects with ${c.title}.`;
+ submitGoalRequest();
+ }
+ });
+
+ allCoursesGrid.appendChild(card);
+ });
+ }
+
+ // Filter listeners for Catalog
+ function filterCatalog() {
+ const query = (catalogSearchInput ? catalogSearchInput.value : "").toLowerCase();
+ const topic = catalogTopicFilter ? catalogTopicFilter.value.toLowerCase() : "all";
+ const diff = catalogDiffFilter ? catalogDiffFilter.value.toLowerCase() : "all";
+
+ const filtered = allCoursesData.filter(c => {
+ const matchesQuery = !query || c.title.toLowerCase().includes(query) || c.description.toLowerCase().includes(query) || (c.topics_covered || []).some(t => t.toLowerCase().includes(query));
+ const matchesTopic = topic === "all" || c.topic.toLowerCase() === topic;
+ const matchesDiff = diff === "all" || c.difficulty.toLowerCase() === diff;
+ return matchesQuery && matchesTopic && matchesDiff;
+ });
+
+ renderCatalogList(filtered);
+ }
+
+ if (catalogSearchInput) catalogSearchInput.addEventListener("input", filterCatalog);
+ if (catalogTopicFilter) catalogTopicFilter.addEventListener("change", filterCatalog);
+ if (catalogDiffFilter) catalogDiffFilter.addEventListener("change", filterCatalog);
+
+ // --- Load History Data ---
+ async function loadHistoryData() {
+ if (!historyList) return;
+ historyList.innerHTML = `Loading history...
`;
+
+ try {
+ const res = await fetch(`${API_BASE}/api/ai/history?limit=10`);
+ const data = await res.json();
+ const queries = data.history || [];
+
+ if (queries.length === 0) {
+ historyList.innerHTML = `No past recommendations found yet. Try asking the assistant!
`;
+ return;
+ }
+
+ historyList.innerHTML = "";
+ queries.forEach(q => {
+ const item = document.createElement("div");
+ item.className = "history-item";
+ const dateStr = q.created_at ? new Date(q.created_at).toLocaleString() : "";
+ item.innerHTML = `
+
+ Role: ${escapeHtml(q.parsed_target_role || "Developer")} | Level: ${escapeHtml(q.parsed_current_level || "Beginner")} | ${dateStr}
+ `;
+ item.addEventListener("click", () => {
+ switchTab("roadmap");
+ if (promptInput) {
+ promptInput.value = q.query_text;
+ submitGoalRequest();
+ }
+ });
+ historyList.appendChild(item);
+ });
+ } catch (err) {
+ historyList.innerHTML = `Failed to load history.
`;
+ }
+ }
+
+ // --- Utility Helpers ---
+ function escapeHtml(str) {
+ if (!str) return "";
+ return String(str)
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+ .replace(/"/g, """)
+ .replace(/'/g, "'");
+ }
+
+ function formatMarkdown(str) {
+ if (!str) return "";
+ let formatted = escapeHtml(str);
+ // Bold: **text**
+ formatted = formatted.replace(/\*\*(.*?)\*\*/g, "$1 ");
+ // Italic: *text*
+ formatted = formatted.replace(/\*(.*?)\*/g, "$1 ");
+ // Line breaks
+ formatted = formatted.replace(/\n\n/g, "").replace(/\n/g, "
${formatted}
`;
+ }
+
+})();
diff --git a/backend/__init__.py b/backend/__init__.py
new file mode 100644
index 0000000..33a2781
--- /dev/null
+++ b/backend/__init__.py
@@ -0,0 +1 @@
+# LearnSphere AI Backend Package
diff --git a/backend/ai_engine.py b/backend/ai_engine.py
new file mode 100644
index 0000000..c230fee
--- /dev/null
+++ b/backend/ai_engine.py
@@ -0,0 +1,852 @@
+import json
+import os
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import List, Dict, Any, Optional, Tuple
+
+from dotenv import load_dotenv
+
+from backend.database import (
+ get_all_courses,
+ get_course_by_id,
+ save_user_query,
+ save_chat_message,
+ get_chat_history,
+)
+from backend.models import (
+ GoalRequest,
+ RecommendationResponse,
+ ParsedProfile,
+ RecommendedCourse,
+ LearningPhase,
+ ChatRequest,
+ ChatResponse,
+ DAGNode,
+ DAGEdge,
+ DAGGraph,
+ KeyTakeaway,
+ NextStepDetails,
+)
+
+load_dotenv()
+
+# Check for Gemini API key
+GEMINI_API_KEY = os.environ.get("GEMINI_API_KEY")
+GEMINI_MODEL = os.environ.get("GEMINI_MODEL", "gemini-2.5-flash")
+gemini_client = None
+
+if GEMINI_API_KEY and GEMINI_API_KEY != "your_gemini_api_key_here":
+ try:
+ from google import genai
+ gemini_client = genai.Client(api_key=GEMINI_API_KEY)
+ print(f"[AI ENGINE] Successfully initialized Google Gemini Client with model {GEMINI_MODEL}")
+ except Exception as e:
+ print(f"[AI ENGINE] Could not initialize Google GenAI: {e}. Using deterministic semantic engine.")
+
+
+# --- Semantic Similarity / TF-IDF Vectorizer helper ---
+def compute_semantic_relevance(query: str, courses: List[Dict[str, Any]]) -> List[Tuple[Dict[str, Any], float]]:
+ """
+ Computes semantic similarity scores between the user query and the course catalog
+ using TF-IDF term-frequency and keyword domain matching.
+ """
+ try:
+ from sklearn.feature_extraction.text import TfidfVectorizer
+ from sklearn.metrics.pairwise import cosine_similarity
+
+ # Build document corpus for each course
+ docs = []
+ for c in courses:
+ doc = (
+ f"{c['title']} {c['topic']} {c['difficulty']} "
+ f"{c['description']} {' '.join(c.get('topics_covered', []))} "
+ f"{' '.join(c.get('target_roles', []))} {' '.join(c.get('key_skills_acquired', []))}"
+ )
+ docs.append(doc)
+
+ vectorizer = TfidfVectorizer(stop_words="english", ngram_range=(1, 2))
+ tfidf_matrix = vectorizer.fit_transform(docs)
+ query_vec = vectorizer.transform([query])
+ sim_scores = cosine_similarity(query_vec, tfidf_matrix)[0]
+
+ scored = []
+ for idx, course in enumerate(courses):
+ base_score = float(sim_scores[idx])
+
+ # Heuristic domain boosts
+ query_lower = query.lower()
+ topic_lower = course["topic"].lower()
+ title_lower = course["title"].lower()
+
+ bonus = 0.0
+ # Java vs JavaScript boundary check
+ clean_query = query_lower.replace("javascript", " ") if "javascript" in query_lower else query_lower
+ if course["id"] == "course-java-springboot":
+ if re.search(r"\bjava\b", clean_query):
+ bonus += 0.40
+ else:
+ if re.search(rf"\b{re.escape(topic_lower)}\b", query_lower):
+ bonus += 0.40
+
+ if any(term in query_lower for term in [course["slug"]]):
+ bonus += 0.25
+
+ # Role matching bonus
+ for role in course.get("target_roles", []):
+ if re.search(rf"\b{re.escape(role.lower())}\b", query_lower):
+ bonus += 0.35
+
+ final_score = min(0.99, base_score + bonus)
+ scored.append((course, final_score))
+
+ scored.sort(key=lambda x: x[1], reverse=True)
+ return scored
+ except Exception as e:
+ print(f"[AI ENGINE] Fallback in TF-IDF calculation: {e}")
+ # Fallback keyword scoring
+ query_tokens = set(re.findall(r"\w+", query.lower()))
+ scored = []
+ for c in courses:
+ text = f"{c['title']} {c['topic']} {c['description']} {' '.join(c.get('topics_covered', []))}".lower()
+ words = set(re.findall(r"\w+", text))
+ common = len(query_tokens.intersection(words))
+ score = common / max(1, len(query_tokens))
+ scored.append((c, score))
+ scored.sort(key=lambda x: x[1], reverse=True)
+ return scored
+
+
+def parse_learner_profile(query: str, explicit_level: Optional[str] = None, explicit_timeframe: Optional[str] = None) -> ParsedProfile:
+ """
+ Extracts current level, target role, timeframe, and weekly study hours from natural language query.
+ """
+ q = query.lower()
+
+ # Determine Current Level
+ detected_level = "Beginner"
+ if explicit_level and explicit_level.lower() != "auto":
+ detected_level = explicit_level.capitalize()
+ else:
+ if any(term in q for term in ["advanced", "experienced", "production", "senior", "lead developer"]):
+ detected_level = "Advanced"
+ elif any(term in q for term in ["intermediate", "know basic", "knows basic", "some experience", "have built", "familiar with", "worked with"]):
+ detected_level = "Intermediate"
+ elif any(term in q for term in ["beginner", "starting out", "scratch", "new to", "no experience", "zero"]):
+ detected_level = "Beginner"
+
+ # Determine Target Role / Ambition
+ target_role = "Software Developer"
+ if any(k in q for k in ["react developer", "frontend developer", "frontend engineer", "front end", "react"]):
+ target_role = "React Frontend Developer"
+ elif any(k in q for k in ["full stack", "fullstack", "mern", "web developer"]):
+ target_role = "Full Stack Web Developer"
+ elif any(k in q for k in ["node", "backend", "api developer", "backend engineer"]):
+ target_role = "Backend Node.js Engineer"
+ elif any(k in q for k in ["machine learning", "ml engineer", "data scientist", "ai engineer"]):
+ target_role = "Machine Learning Engineer"
+ elif any(k in q for k in ["python developer", "data analyst", "python"]):
+ target_role = "Python Software Engineer"
+ elif re.search(r"\bjava\b", q.replace("javascript", " ")):
+ target_role = "Java Enterprise Backend Engineer"
+ elif any(k in q for k in ["sql", "database administrator", "dba", "data engineer"]):
+ target_role = "Database & SQL Specialist"
+
+ # Determine Timeframe
+ timeframe = explicit_timeframe if explicit_timeframe else "3 months"
+ match = re.search(r"(\d+)\s*(months?|weeks?|years?|days?)", q)
+ if match:
+ timeframe = f"{match.group(1)} {match.group(2)}"
+
+ # Determine Weekly hours
+ weekly_hours = 6
+ hour_match = re.search(r"(\d+)\s*(hours|hrs|hr)\s*(per|\/|a)?\s*week", q)
+ if hour_match:
+ weekly_hours = int(hour_match.group(1))
+
+ # Identify primary skills needed
+ skills = []
+ if "react" in q or "frontend" in target_role.lower():
+ skills.extend(["Modern JavaScript ES6+", "React Hooks", "State Management", "Component Composition", "REST API Integration"])
+ if "node" in q or "backend" in target_role.lower():
+ skills.extend(["Node.js Runtime", "Express APIs", "JWT Authentication", "Database Architecture"])
+ if "python" in q:
+ skills.extend(["Python OOP", "Data Structures", "Scripting", "Packaging"])
+ if "machine learning" in q or "data scientist" in target_role.lower():
+ skills.extend(["NumPy & Pandas", "Scikit-Learn", "Model Training", "Model Evaluation", "FastAPI Serving"])
+ if re.search(r"\bjava\b", q.replace("javascript", " ")):
+ skills.extend(["Core Java & JVM", "OOP Principles", "Java Collections", "Spring Boot 3 REST"])
+ if "sql" in q or "database" in q:
+ skills.extend(["Relational Schema Design", "Complex Joins", "Aggregations & Window Functions", "Query Optimization"])
+
+ if not skills:
+ skills = ["Foundational Syntax", "Data Structures", "Building Applied Projects", "Version Control"]
+
+ # Prerequisites to bridge
+ bridges = []
+ if "react" in q and ("basic javascript" in q or "beginner" in detected_level.lower()):
+ bridges.append("Solidify Asynchronous JavaScript (Promises, async/await, Array methods) before React")
+ if "machine learning" in q and "python" not in q:
+ bridges.append("Ensure Python programming fundamentals are solid before mathematical modeling")
+ if "full stack" in q:
+ bridges.append("Review Frontend React and Backend Express independently before combining")
+
+ return ParsedProfile(
+ current_level=detected_level,
+ target_role=target_role,
+ timeframe=timeframe,
+ weekly_commitment_hours=weekly_hours,
+ primary_skills_needed=skills,
+ prerequisites_to_bridge=bridges,
+ )
+
+
+def build_dag_graph(ordered_courses: List[Dict[str, Any]], profile: ParsedProfile) -> DAGGraph:
+ """
+ Constructs a Directed Acyclic Graph (DAG) representing the complete technical
+ skill dependency tree across all recommended modules and courses.
+ """
+ nodes: List[DAGNode] = []
+ edges: List[DAGEdge] = []
+
+ level = 0
+ prev_node_id = None
+
+ for c_idx, course in enumerate(ordered_courses):
+ phase_num = c_idx + 1
+ modules = course.get("learning_sequence", [])
+ total_mods = len(modules)
+
+ for m_idx, mod in enumerate(modules):
+ node_id = f"dag-{course['slug']}-m{m_idx+1}"
+
+ # Categorize the node cleanly
+ category = "Core Architecture"
+ if level == 0 and (course.get("difficulty", "").lower() == "beginner" or m_idx == 0):
+ category = "Foundational Gateway"
+ elif m_idx == total_mods - 1:
+ category = "Capstone Milestone"
+ elif any(k in mod.get("title", "").lower() for k in ["spring", "react", "express", "fastapi"]):
+ category = "Enterprise Framework"
+ elif any(k in mod.get("title", "").lower() for k in ["stream", "jpa", "auth", "advanced", "tuning", "window"]):
+ category = "Advanced Pattern"
+
+ # Parse hours from duration string (e.g., "1 week (6 hours)" -> 6)
+ hours = 6
+ h_match = re.search(r"(\d+)\s*(hours|hrs)", mod.get("duration", ""))
+ if h_match:
+ hours = int(h_match.group(1))
+
+ status = "in_progress" if level == 0 else "pending"
+ prereqs = [prev_node_id] if prev_node_id else []
+
+ node = DAGNode(
+ id=node_id,
+ title=mod.get("title", f"Module {m_idx+1}"),
+ level=level,
+ phase=phase_num,
+ category=category,
+ estimated_hours=hours,
+ duration_label=mod.get("duration", "1 week"),
+ course_id=course["id"],
+ course_title=course["title"],
+ prerequisites=prereqs,
+ key_topics=mod.get("topics", []),
+ hands_on_project=mod.get("hands_on_project"),
+ status=status
+ )
+ nodes.append(node)
+
+ if prev_node_id:
+ edges.append(DAGEdge(
+ from_node=prev_node_id,
+ to_node=node_id,
+ label="unlocks"
+ ))
+
+ prev_node_id = node_id
+ level += 1
+
+ return DAGGraph(nodes=nodes, edges=edges)
+
+
+def build_why_recommended_points(ordered_courses: List[Dict[str, Any]], profile: ParsedProfile) -> List[KeyTakeaway]:
+ points = []
+
+ # 1. Target Role Fit
+ points.append(KeyTakeaway(
+ title="Target Role Alignment",
+ description=f"Curated specifically for becoming a {profile.target_role}. Bridges your current level ({profile.current_level}) directly to production enterprise competence without unrelated topics.",
+ icon="fa-bullseye"
+ ))
+
+ # 2. Pacing & Feasibility
+ total_hours = sum(c.get("total_hours", 0) for c in ordered_courses)
+ weeks = max(2, round(total_hours / max(4, profile.weekly_commitment_hours)))
+ points.append(KeyTakeaway(
+ title="Pacing & Schedule Feasibility",
+ description=f"At your committed pace of ~{profile.weekly_commitment_hours} hrs/week, you will complete {total_hours} total curriculum hours across ~{weeks} weeks, fitting your {profile.timeframe} target.",
+ icon="fa-clock"
+ ))
+
+ # 3. Prerequisite Bridge
+ first_c = ordered_courses[0]
+ points.append(KeyTakeaway(
+ title="Grounded Prerequisite Bridge",
+ description=f"Solidifies foundational syntax and design patterns in '{first_c['title']}' before introducing framework complexity, avoiding common junior knowledge gaps.",
+ icon="fa-bridge"
+ ))
+
+ # 4. Capstone Portfolio Impact
+ last_c = ordered_courses[-1]
+ capstone_name = last_c.get("capstone_project", {}).get("title", "Production Microservice")
+ points.append(KeyTakeaway(
+ title="Verifiable Portfolio Artifact",
+ description=f"Culminates with delivering '{capstone_name}', a resume-ready project featuring persistence, testing, and clean code that recruiters look for in technical interviews.",
+ icon="fa-trophy"
+ ))
+
+ return points
+
+
+def build_next_step_details(first_course: Dict[str, Any], profile: ParsedProfile) -> NextStepDetails:
+ first_module = first_course.get("learning_sequence", [{}])[0]
+ return NextStepDetails(
+ course_title=first_course["title"],
+ module_title=first_module.get("title", "Module 1"),
+ action_item=first_module.get("summary", "Master the foundational environment and code syntax"),
+ hands_on_project=first_module.get("hands_on_project", "Build initial interactive practice exercise"),
+ estimated_time=first_module.get("duration", "Week 1 (6 hours)")
+ )
+
+
+def generate_heuristic_recommendation(
+ goal_req: GoalRequest,
+ courses: List[Dict[str, Any]],
+ scored_courses: List[Tuple[Dict[str, Any], float]],
+ profile: ParsedProfile,
+) -> RecommendationResponse:
+ """
+ Deterministic rule-based & semantic engine that selects courses,
+ orders them by dependency sequence, and generates tailored guidance.
+ """
+ query_id = f"ls-query-{uuid.uuid4().hex[:8]}"
+ query_lower = goal_req.query.lower()
+
+ # Filter top relevant courses (threshold score > 0.08 or top 3)
+ relevant_scored = [sc for sc in scored_courses if sc[1] > 0.08]
+ if not relevant_scored:
+ relevant_scored = scored_courses[:3]
+
+ selected_courses_map = {}
+ for c, score in relevant_scored[:4]:
+ selected_courses_map[c["id"]] = (c, score)
+
+ # Prerequisite chaining logic:
+ # 1. If React is selected and user knows only "basic javascript" or is beginner:
+ if "course-react-engineering" in selected_courses_map:
+ if ("basic" in query_lower or "beginner" in profile.current_level.lower()) and "course-js-core" not in selected_courses_map:
+ js_course = get_course_by_id("course-js-core")
+ if js_course:
+ selected_courses_map["course-js-core"] = (js_course, 0.85)
+
+ # 2. If Machine Learning is selected and user is beginner or hasn't mastered Python:
+ if "course-ml-foundations" in selected_courses_map:
+ if "course-python-mastery" not in selected_courses_map:
+ py_course = get_course_by_id("course-python-mastery")
+ if py_course:
+ selected_courses_map["course-python-mastery"] = (py_course, 0.88)
+
+ # 3. If Full-stack is requested, ensure backend and frontend courses are present
+ if "fullstack" in query_lower or "full stack" in query_lower:
+ for cid in ["course-react-engineering", "course-nodejs-backend", "course-sql-database"]:
+ if cid not in selected_courses_map:
+ c = get_course_by_id(cid)
+ if c:
+ selected_courses_map[cid] = (c, 0.75)
+
+ # Order courses logically:
+ # Order hierarchy: Beginner foundations -> Intermediate core -> Specialized -> Capstone
+ difficulty_order = {"Beginner": 1, "Intermediate": 2, "Advanced": 3}
+ topic_prereq_order = {
+ "JavaScript": 1,
+ "Python": 1,
+ "SQL": 2,
+ "React": 3,
+ "Node.js": 3,
+ "Java": 3,
+ "Machine Learning": 4,
+ "Full Stack Web Development": 5,
+ }
+
+ ordered_courses_tuples = list(selected_courses_map.values())
+ ordered_courses_tuples.sort(
+ key=lambda item: (
+ difficulty_order.get(item[0]["difficulty"], 2),
+ topic_prereq_order.get(item[0]["topic"], 3),
+ )
+ )
+
+ ordered_raw_courses = [item[0] for item in ordered_courses_tuples]
+
+ # Build RecommendedCourse models
+ rec_models = []
+ for c, score in ordered_courses_tuples:
+ # Generate custom why_relevant
+ why_rel = f"Directly aligns with your target of becoming a {profile.target_role}."
+ if c["topic"] == "JavaScript" and "react" in query_lower:
+ why_rel = "Bridges your basic JavaScript understanding to modern ES6+ patterns, closures, and async/await needed to write idiomatic React."
+ elif c["topic"] == "React":
+ why_rel = "Provides the core component, hooks, and routing architecture required for modern frontend engineering."
+ elif c["topic"] == "Python" and "machine learning" in query_lower:
+ why_rel = "Establishes data structure, algorithm, and scripting competence required before tackling ML algorithms."
+ elif c["topic"] == "Node.js":
+ why_rel = "Teaches server-side REST architecture and authentication to make your applications full-stack."
+ elif c["topic"] == "SQL":
+ why_rel = "Essential for designing normalized databases, writing analytical queries, and connecting data backends."
+ elif c["topic"] == "Machine Learning":
+ why_rel = "Guides you through hands-on Scikit-Learn pipelines, feature engineering, and model deployment."
+ elif c["topic"] == "Java":
+ why_rel = "Covers core object-oriented principles, JVM memory architecture, and Spring Boot 3 microservice persistence."
+
+ rec_models.append(
+ RecommendedCourse(
+ id=c["id"],
+ title=c["title"],
+ topic=c["topic"],
+ slug=c["slug"],
+ difficulty=c["difficulty"],
+ estimated_duration=c["estimated_duration"],
+ total_hours=c["total_hours"],
+ resource_types=c.get("resource_types", []),
+ relevance_score=round(score, 2),
+ why_relevant=why_rel,
+ topics_covered=c.get("topics_covered", []),
+ learning_sequence=c.get("learning_sequence", []),
+ key_skills_acquired=c.get("key_skills_acquired", []),
+ capstone_project=c.get("capstone_project", {}),
+ )
+ )
+
+ # Generate Learning Sequence Phases
+ learning_sequence = []
+ total_weeks = 0.0
+
+ for idx, c in enumerate(ordered_raw_courses):
+ phase_num = idx + 1
+ est_weeks = max(2.0, round(c["total_hours"] / max(4, profile.weekly_commitment_hours), 1))
+ total_weeks += est_weeks
+
+ phase_title = f"Phase {phase_num}: Master {c['title']}"
+ weekly_focus = f"Dedicate ~{profile.weekly_commitment_hours} hours/week exploring {c['topic']} concepts and coding exercises."
+ milestone_goal = f"Complete all modules and successfully deliver the capstone project: {c['capstone_project'].get('title', 'Course Project')}."
+ actionable_project = c["capstone_project"].get("title", f"{c['topic']} Applied Project")
+
+ learning_sequence.append(
+ LearningPhase(
+ phase_number=phase_num,
+ phase_title=phase_title,
+ course_id=c["id"],
+ course_title=c["title"],
+ duration_weeks=est_weeks,
+ weekly_focus=weekly_focus,
+ milestone_goal=milestone_goal,
+ actionable_project=actionable_project,
+ )
+ )
+
+ # Formulate customized concise summary (no giant monolithic paragraphs!)
+ summary = (
+ f"Customized milestone path to advance from **{profile.current_level}** to a proficient **{profile.target_role}** "
+ f"within **{profile.timeframe}**. Structured into progressive phases at ~**{profile.weekly_commitment_hours} hours/week** "
+ f"balancing foundational logic with hands-on capstone engineering."
+ )
+
+ why_recommended = (
+ f"This sequence systematically prevents knowledge gaps by building solid architecture before high-level frameworks. "
+ f"Every phase delivers an interactive milestone project to prove competency."
+ )
+
+ # Structured points & next step details
+ why_points = build_why_recommended_points(ordered_raw_courses, profile)
+ next_step_details = build_next_step_details(ordered_raw_courses[0], profile)
+
+ # Immediate next step string
+ first_course = ordered_raw_courses[0]
+ first_module = first_course.get("learning_sequence", [{}])[0]
+ immediate_next_step = (
+ f"Begin today with **{first_course['title']}** โ Start with **{first_module.get('title', 'Module 1')}**: "
+ f"{first_module.get('summary', 'Review core syntax and foundational logic')}. "
+ f"Hands-on goal for this week: *{first_module.get('hands_on_project', 'Complete initial practice exercise')}*."
+ )
+
+ # Build the full DAG dependency graph!
+ dag_graph = build_dag_graph(ordered_raw_courses, profile)
+
+ alternatives = [
+ "Increase study time to 12-15 hours/week to complete the roadmap in half the time.",
+ "Add an interactive Git & GitHub version control module to your workflow for portfolio sharing.",
+ "Team up with a peer in the LearnSphere Community channel for weekly code reviews."
+ ]
+
+ now_iso = datetime.now(timezone.utc).isoformat()
+
+ # Save to database
+ save_user_query(
+ query_id=query_id,
+ query_text=goal_req.query,
+ parsed_current_level=profile.current_level,
+ parsed_target_role=profile.target_role,
+ parsed_timeframe=profile.timeframe,
+ recommended_courses=[rc.model_dump() for rc in rec_models],
+ learning_sequence=[lp.model_dump() for lp in learning_sequence],
+ why_relevant=why_recommended,
+ immediate_next_step=immediate_next_step,
+ summary=summary,
+ user_id=goal_req.user_id,
+ )
+
+ return RecommendationResponse(
+ success=True,
+ query_id=query_id,
+ learner_profile=profile,
+ summary=summary,
+ why_recommended=why_recommended,
+ why_recommended_points=why_points,
+ immediate_next_step=immediate_next_step,
+ next_step_details=next_step_details,
+ learning_sequence=learning_sequence,
+ dag_graph=dag_graph,
+ recommended_courses=rec_models,
+ alternative_paths=alternatives,
+ created_at=now_iso,
+ )
+
+
+def generate_gemini_recommendation(
+ goal_req: GoalRequest,
+ courses: List[Dict[str, Any]],
+ scored_courses: List[Tuple[Dict[str, Any], float]],
+ profile: ParsedProfile,
+) -> Optional[RecommendationResponse]:
+ """
+ Uses Gemini LLM to synthesize rich, grounded natural language reasoning
+ based on the retrieved LearnSphere catalog.
+ """
+ if not gemini_client:
+ return None
+
+ # Retrieve candidate courses
+ candidate_courses = [item[0] for item in scored_courses[:5]]
+ catalog_summary = []
+ for c in candidate_courses:
+ catalog_summary.append({
+ "id": c["id"],
+ "title": c["title"],
+ "topic": c["topic"],
+ "difficulty": c["difficulty"],
+ "description": c["description"],
+ "prerequisites": c["prerequisites"],
+ "estimated_duration": c["estimated_duration"],
+ "total_hours": c["total_hours"],
+ "topics_covered": c["topics_covered"],
+ "capstone_project": c["capstone_project"],
+ })
+
+ prompt = f"""You are the official AI Learning Assistant for LearnSphere.
+A learner has described their learning goal and background:
+"{goal_req.query}"
+
+Learner Profile Details:
+- Detected Current Level: {profile.current_level}
+- Target Ambition: {profile.target_role}
+- Desired Timeframe: {profile.timeframe}
+- Weekly Commitment: {profile.weekly_commitment_hours} hours/week
+
+Below is the verified LearnSphere structured content catalog available:
+{json.dumps(catalog_summary, indent=2)}
+
+TASK:
+1. Select the best 1 to 4 courses from the LearnSphere catalog that bridge the learner's current level to their goal.
+2. Formulate a logical, sequential learning path with phases.
+3. Keep text concise and actionable (NO long monolithic paragraphs).
+4. Provide structured "why_recommended_points" with 3 to 4 distinct key takeaway cards (Target Alignment, Pacing Feasibility, Prerequisite Bridge, Portfolio Deliverable).
+5. Provide structured "next_step_details" with course_title, module_title, action_item, hands_on_project, estimated_time.
+
+You MUST respond strictly with valid JSON conforming to this exact structure:
+{{
+ "summary": "Concise 2-3 sentence overview of this milestone path",
+ "why_recommended": "Brief 2-sentence overall rationale summary",
+ "why_recommended_points": [
+ {{
+ "title": "Target Role Alignment",
+ "description": "Short explanation of how this path maps to their ambition",
+ "icon": "fa-bullseye"
+ }},
+ {{
+ "title": "Pacing & Feasibility",
+ "description": "Short explanation of weekly hours and timeline feasibility",
+ "icon": "fa-clock"
+ }},
+ {{
+ "title": "Prerequisite Bridge",
+ "description": "Short explanation of foundational skills solidified first",
+ "icon": "fa-bridge"
+ }},
+ {{
+ "title": "Portfolio Deliverable",
+ "description": "Short explanation of the capstone project built",
+ "icon": "fa-trophy"
+ }}
+ ],
+ "immediate_next_step": "Precise instruction of which course, module, and hands-on lab to start today",
+ "next_step_details": {{
+ "course_title": "Course Title",
+ "module_title": "Module 1: ...",
+ "action_item": "Specific action to do today",
+ "hands_on_project": "Hands-on coding exercise for this week",
+ "estimated_time": "Week 1 (6 hours)"
+ }},
+ "recommended_course_ids": ["course-java-springboot"],
+ "learning_sequence": [
+ {{
+ "phase_number": 1,
+ "phase_title": "Phase 1: ...",
+ "course_id": "course-java-springboot",
+ "course_title": "...",
+ "duration_weeks": 4.0,
+ "weekly_focus": "...",
+ "milestone_goal": "...",
+ "actionable_project": "..."
+ }}
+ ],
+ "alternative_paths": [
+ "Optional suggestion 1",
+ "Optional suggestion 2"
+ ]
+}}
+Only return the raw JSON object, no markdown code fence and no extra commentary.
+"""
+
+ try:
+ response = gemini_client.models.generate_content(
+ model=GEMINI_MODEL,
+ contents=prompt,
+ )
+ raw_text = (response.text or "").strip()
+ # Remove markdown fence if present
+ raw_text = re.sub(r"^```(json)?\s*", "", raw_text)
+ raw_text = re.sub(r"\s*```$", "", raw_text)
+
+ parsed = json.loads(raw_text)
+
+ query_id = f"ls-query-{uuid.uuid4().hex[:8]}"
+
+ rec_course_ids = parsed.get("recommended_course_ids", [])
+ rec_models = []
+ raw_courses = []
+ for cid in rec_course_ids:
+ c = get_course_by_id(cid)
+ if c:
+ raw_courses.append(c)
+ rec_models.append(
+ RecommendedCourse(
+ id=c["id"],
+ title=c["title"],
+ topic=c["topic"],
+ slug=c["slug"],
+ difficulty=c["difficulty"],
+ estimated_duration=c["estimated_duration"],
+ total_hours=c["total_hours"],
+ resource_types=c.get("resource_types", []),
+ relevance_score=0.95,
+ why_relevant=f"Selected by AI as a core milestone for {profile.target_role}.",
+ topics_covered=c.get("topics_covered", []),
+ learning_sequence=c.get("learning_sequence", []),
+ key_skills_acquired=c.get("key_skills_acquired", []),
+ capstone_project=c.get("capstone_project", {}),
+ )
+ )
+
+ if not rec_models:
+ # If Gemini returned invalid IDs, fallback to heuristic
+ return None
+
+ phases = []
+ for p in parsed.get("learning_sequence", []):
+ phases.append(LearningPhase(**p))
+
+ # Build DAG Graph from verified courses
+ dag_graph = build_dag_graph(raw_courses, profile)
+
+ # Parse why_recommended_points
+ why_points = []
+ raw_points = parsed.get("why_recommended_points", [])
+ if isinstance(raw_points, list) and len(raw_points) > 0:
+ for pt in raw_points:
+ try:
+ why_points.append(KeyTakeaway(
+ title=pt.get("title", "Key Takeaway"),
+ description=pt.get("description", ""),
+ icon=pt.get("icon", "fa-check")
+ ))
+ except Exception:
+ pass
+ if not why_points:
+ why_points = build_why_recommended_points(raw_courses, profile)
+
+ # Parse next_step_details
+ raw_next = parsed.get("next_step_details", {})
+ if isinstance(raw_next, dict) and "course_title" in raw_next:
+ try:
+ next_step_details = NextStepDetails(
+ course_title=raw_next.get("course_title", raw_courses[0]["title"]),
+ module_title=raw_next.get("module_title", "Module 1"),
+ action_item=raw_next.get("action_item", "Start initial foundational lab"),
+ hands_on_project=raw_next.get("hands_on_project", "Build starter exercise"),
+ estimated_time=raw_next.get("estimated_time", "Week 1 (6 hours)")
+ )
+ except Exception:
+ next_step_details = build_next_step_details(raw_courses[0], profile)
+ else:
+ next_step_details = build_next_step_details(raw_courses[0], profile)
+
+ now_iso = datetime.now(timezone.utc).isoformat()
+
+ # Save to database
+ save_user_query(
+ query_id=query_id,
+ query_text=goal_req.query,
+ parsed_current_level=profile.current_level,
+ parsed_target_role=profile.target_role,
+ parsed_timeframe=profile.timeframe,
+ recommended_courses=[rc.model_dump() for rc in rec_models],
+ learning_sequence=[lp.model_dump() for lp in phases],
+ why_relevant=parsed.get("why_recommended", ""),
+ immediate_next_step=parsed.get("immediate_next_step", ""),
+ summary=parsed.get("summary", ""),
+ user_id=goal_req.user_id,
+ )
+
+ return RecommendationResponse(
+ success=True,
+ query_id=query_id,
+ learner_profile=profile,
+ summary=parsed.get("summary", ""),
+ why_recommended=parsed.get("why_recommended", ""),
+ why_recommended_points=why_points,
+ immediate_next_step=parsed.get("immediate_next_step", ""),
+ next_step_details=next_step_details,
+ learning_sequence=phases,
+ dag_graph=dag_graph,
+ recommended_courses=rec_models,
+ alternative_paths=parsed.get("alternative_paths", []),
+ created_at=now_iso,
+ )
+ except Exception as e:
+ print(f"[AI ENGINE] Gemini generation error: {e}. Falling back to deterministic engine.")
+ return None
+
+
+def get_personalized_recommendation(goal_req: GoalRequest) -> RecommendationResponse:
+ """
+ Main entry point for generating personalized recommendations:
+ 1. Loads structured courses from SQLite.
+ 2. Computes semantic relevance vector scores.
+ 3. Parses learner profile.
+ 4. Tries Gemini LLM with grounded catalog; falls back to deterministic heuristic engine.
+ """
+ courses = get_all_courses()
+ scored_courses = compute_semantic_relevance(goal_req.query, courses)
+ profile = parse_learner_profile(goal_req.query, goal_req.current_level, goal_req.target_timeframe)
+
+ # Attempt Gemini generation if client is configured
+ if gemini_client:
+ llm_response = generate_gemini_recommendation(goal_req, courses, scored_courses, profile)
+ if llm_response:
+ return llm_response
+
+ # Fallback to rule-based & semantic progression engine
+ return generate_heuristic_recommendation(goal_req, courses, scored_courses, profile)
+
+
+def handle_followup_chat(chat_req: ChatRequest) -> ChatResponse:
+ """
+ Handles conversational follow-up questions from the learner regarding their plan.
+ """
+ session_id = chat_req.session_id or f"sess-{uuid.uuid4().hex[:8]}"
+ msg_id = f"msg-{uuid.uuid4().hex[:8]}"
+
+ # Save user message
+ save_chat_message(session_id, "user", chat_req.message, msg_id, chat_req.context_query_id)
+ history = get_chat_history(session_id, limit=8)
+
+ all_courses = get_all_courses()
+ catalog_brief = ", ".join([f"{c['title']} ({c['topic']}, {c['difficulty']})" for c in all_courses])
+
+ if gemini_client:
+ try:
+ history_prompt = "\n".join([f"{h['role'].upper()}: {h['message']}" for h in history])
+ prompt = (
+ f"You are the LearnSphere AI Learning Assistant.\n"
+ f"Available LearnSphere Courses: {catalog_brief}\n\n"
+ f"Conversation History:\n{history_prompt}\n\n"
+ f"Respond to the learner's latest question with helpful, encouraging, and concrete advice grounded in LearnSphere's courses.\n"
+ f"Be concise, practical, and clear."
+ )
+ response = gemini_client.models.generate_content(
+ model=GEMINI_MODEL,
+ contents=prompt,
+ )
+ reply = (response.text or "").strip()
+ except Exception as e:
+ print(f"[AI ENGINE] Chat LLM error: {e}")
+ reply = generate_heuristic_chat_reply(chat_req.message)
+ else:
+ reply = generate_heuristic_chat_reply(chat_req.message)
+
+ # Save assistant message
+ asst_msg_id = f"msg-{uuid.uuid4().hex[:8]}"
+ save_chat_message(session_id, "assistant", reply, asst_msg_id, chat_req.context_query_id)
+
+ suggested = [
+ "How many hours per week should I dedicate to labs?",
+ "What projects will best showcase my skills to employers?",
+ "Can I skip straight to the intermediate course?"
+ ]
+
+ return ChatResponse(session_id=session_id, reply=reply, suggested_prompts=suggested)
+
+
+def generate_heuristic_chat_reply(message: str) -> str:
+ """
+ Rule-based intelligent chat response when LLM is unavailable.
+ """
+ m = message.lower()
+ if any(k in m for k in ["hours", "time", "pace", "schedule", "busy", "part-time"]):
+ return (
+ "If your schedule is tight, we recommend breaking your study time into 45-minute daily focus sessions "
+ "rather than long weekend marathons. Dedicating 5โ7 hours across 4โ5 days yields significantly higher retention "
+ "and allows your subconscious mind to absorb programming patterns between sessions."
+ )
+ elif any(k in m for k in ["skip", "prerequisite", "direct", "fast"]):
+ return (
+ "While you can jump directly into intermediate topics like React or Spring Boot, learners who brush up on core foundations "
+ "(such as ES6+ closures, async/await, or Java Streams) solve debugging issues 3x faster. We recommend reviewing the first module's "
+ "interactive quiz firstโif you score 85%+, feel free to skip ahead!"
+ )
+ elif any(k in m for k in ["project", "portfolio", "resume", "job", "hire"]):
+ return (
+ "The capstone projects in each course are specifically designed for your portfolio! For example, the E-Commerce Storefront in React "
+ "and the Loan Prediction API in Machine Learning demonstrate real-world architecture, error handling, and deployability that recruiters look for."
+ )
+ elif any(k in m for k in ["stuck", "error", "difficult", "hard", "help"]):
+ return (
+ "Getting stuck is a natural part of coding! Try breaking down the problem: log each intermediate variable, "
+ "check MDN or official documentation, and re-read the module cheatsheet. You can also paste specific error messages here for guidance."
+ )
+ else:
+ return (
+ "Great question! LearnSphere's structured content provides step-by-step guidance, interactive labs, and practical capstone projects. "
+ "Focus on completing each module's hands-on exercise before moving to the next. What specific topic or milestone would you like to explore next?"
+ )
diff --git a/backend/database.py b/backend/database.py
new file mode 100644
index 0000000..6d05749
--- /dev/null
+++ b/backend/database.py
@@ -0,0 +1,324 @@
+import json
+import os
+import sqlite3
+import datetime
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+DB_DIR = Path(__file__).resolve().parent / "data"
+DB_DIR.mkdir(parents=True, exist_ok=True)
+DB_PATH = DB_DIR / "learnsphere_assistant.db"
+SEED_FILE = Path(__file__).resolve().parent / "seed_data.json"
+
+
+def get_db_connection() -> sqlite3.Connection:
+ conn = sqlite3.connect(str(DB_PATH))
+ conn.row_factory = sqlite3.Row
+ return conn
+
+
+def init_db():
+ conn = get_db_connection()
+ cursor = conn.cursor()
+
+ cursor.execute("""
+ CREATE TABLE IF NOT EXISTS learning_content (
+ id TEXT PRIMARY KEY,
+ title TEXT NOT NULL,
+ topic TEXT NOT NULL,
+ slug TEXT NOT NULL UNIQUE,
+ difficulty TEXT NOT NULL,
+ description TEXT NOT NULL,
+ prerequisites TEXT NOT NULL,
+ estimated_duration TEXT NOT NULL,
+ total_hours INTEGER NOT NULL,
+ resource_types TEXT NOT NULL,
+ target_roles TEXT NOT NULL,
+ topics_covered TEXT NOT NULL,
+ learning_sequence TEXT NOT NULL,
+ key_skills_acquired TEXT NOT NULL,
+ capstone_project TEXT NOT NULL,
+ created_at TEXT NOT NULL
+ );
+ """)
+
+ cursor.execute("""
+ CREATE INDEX IF NOT EXISTS ix_learning_content_topic ON learning_content(topic);
+ """)
+ cursor.execute("""
+ CREATE INDEX IF NOT EXISTS ix_learning_content_difficulty ON learning_content(difficulty);
+ """)
+
+ cursor.execute("""
+ CREATE TABLE IF NOT EXISTS user_queries (
+ id TEXT PRIMARY KEY,
+ user_id TEXT,
+ query_text TEXT NOT NULL,
+ parsed_current_level TEXT,
+ parsed_target_role TEXT,
+ parsed_timeframe TEXT,
+ recommended_courses TEXT NOT NULL,
+ learning_sequence TEXT NOT NULL,
+ why_relevant TEXT NOT NULL,
+ immediate_next_step TEXT NOT NULL,
+ summary TEXT,
+ created_at TEXT NOT NULL
+ );
+ """)
+ cursor.execute("""
+ CREATE INDEX IF NOT EXISTS ix_user_queries_created_at ON user_queries(created_at DESC);
+ """)
+
+ cursor.execute("""
+ CREATE TABLE IF NOT EXISTS chat_interactions (
+ id TEXT PRIMARY KEY,
+ session_id TEXT NOT NULL,
+ role TEXT NOT NULL,
+ message TEXT NOT NULL,
+ context_query_id TEXT,
+ created_at TEXT NOT NULL
+ );
+ """)
+ cursor.execute("""
+ CREATE INDEX IF NOT EXISTS ix_chat_session ON chat_interactions(session_id);
+ """)
+
+ conn.commit()
+ conn.close()
+
+ # Seed content if table is empty or update if updated
+ seed_database_if_needed()
+
+
+def seed_database_if_needed(force: bool = False):
+ if not SEED_FILE.exists():
+ return
+
+ conn = get_db_connection()
+ cursor = conn.cursor()
+
+ cursor.execute("SELECT COUNT(*) FROM learning_content")
+ count = cursor.fetchone()[0]
+
+ if count > 0 and not force:
+ conn.close()
+ return
+
+ with open(SEED_FILE, "r", encoding="utf-8") as f:
+ courses = json.load(f)
+
+ now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+ for c in courses:
+ cursor.execute("""
+ INSERT INTO learning_content (
+ id, title, topic, slug, difficulty, description, prerequisites,
+ estimated_duration, total_hours, resource_types, target_roles,
+ topics_covered, learning_sequence, key_skills_acquired,
+ capstone_project, created_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT(id) DO UPDATE SET
+ title=excluded.title,
+ topic=excluded.topic,
+ slug=excluded.slug,
+ difficulty=excluded.difficulty,
+ description=excluded.description,
+ prerequisites=excluded.prerequisites,
+ estimated_duration=excluded.estimated_duration,
+ total_hours=excluded.total_hours,
+ resource_types=excluded.resource_types,
+ target_roles=excluded.target_roles,
+ topics_covered=excluded.topics_covered,
+ learning_sequence=excluded.learning_sequence,
+ key_skills_acquired=excluded.key_skills_acquired,
+ capstone_project=excluded.capstone_project
+ """, (
+ c["id"],
+ c["title"],
+ c["topic"],
+ c["slug"],
+ c["difficulty"],
+ c["description"],
+ json.dumps(c.get("prerequisites", [])),
+ c["estimated_duration"],
+ c.get("total_hours", 0),
+ json.dumps(c.get("resource_types", [])),
+ json.dumps(c.get("target_roles", [])),
+ json.dumps(c.get("topics_covered", [])),
+ json.dumps(c.get("learning_sequence", [])),
+ json.dumps(c.get("key_skills_acquired", [])),
+ json.dumps(c.get("capstone_project", {})),
+ now
+ ))
+
+ conn.commit()
+ conn.close()
+
+
+def get_all_courses(topic: Optional[str] = None, difficulty: Optional[str] = None) -> List[Dict[str, Any]]:
+ conn = get_db_connection()
+ cursor = conn.cursor()
+
+ query = "SELECT * FROM learning_content WHERE 1=1"
+ params = []
+
+ if topic and topic.lower() != "all":
+ query += " AND LOWER(topic) = LOWER(?)"
+ params.append(topic)
+ if difficulty and difficulty.lower() != "all":
+ query += " AND LOWER(difficulty) = LOWER(?)"
+ params.append(difficulty)
+
+ query += " ORDER BY total_hours ASC"
+ cursor.execute(query, params)
+ rows = cursor.fetchall()
+ conn.close()
+
+ results = []
+ for r in rows:
+ results.append({
+ "id": r["id"],
+ "title": r["title"],
+ "topic": r["topic"],
+ "slug": r["slug"],
+ "difficulty": r["difficulty"],
+ "description": r["description"],
+ "prerequisites": json.loads(r["prerequisites"]),
+ "estimated_duration": r["estimated_duration"],
+ "total_hours": r["total_hours"],
+ "resource_types": json.loads(r["resource_types"]),
+ "target_roles": json.loads(r["target_roles"]),
+ "topics_covered": json.loads(r["topics_covered"]),
+ "learning_sequence": json.loads(r["learning_sequence"]),
+ "key_skills_acquired": json.loads(r["key_skills_acquired"]),
+ "capstone_project": json.loads(r["capstone_project"]),
+ "created_at": r["created_at"],
+ })
+ return results
+
+
+def get_course_by_id(course_id: str) -> Optional[Dict[str, Any]]:
+ conn = get_db_connection()
+ cursor = conn.cursor()
+ cursor.execute("SELECT * FROM learning_content WHERE id = ? OR slug = ?", (course_id, course_id))
+ r = cursor.fetchone()
+ conn.close()
+
+ if not r:
+ return None
+
+ return {
+ "id": r["id"],
+ "title": r["title"],
+ "topic": r["topic"],
+ "slug": r["slug"],
+ "difficulty": r["difficulty"],
+ "description": r["description"],
+ "prerequisites": json.loads(r["prerequisites"]),
+ "estimated_duration": r["estimated_duration"],
+ "total_hours": r["total_hours"],
+ "resource_types": json.loads(r["resource_types"]),
+ "target_roles": json.loads(r["target_roles"]),
+ "topics_covered": json.loads(r["topics_covered"]),
+ "learning_sequence": json.loads(r["learning_sequence"]),
+ "key_skills_acquired": json.loads(r["key_skills_acquired"]),
+ "capstone_project": json.loads(r["capstone_project"]),
+ "created_at": r["created_at"],
+ }
+
+
+def save_user_query(
+ query_id: str,
+ query_text: str,
+ parsed_current_level: str,
+ parsed_target_role: str,
+ parsed_timeframe: str,
+ recommended_courses: List[Any],
+ learning_sequence: List[Any],
+ why_relevant: str,
+ immediate_next_step: str,
+ summary: str = "",
+ user_id: Optional[str] = None
+):
+ conn = get_db_connection()
+ cursor = conn.cursor()
+ now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+ cursor.execute("""
+ INSERT INTO user_queries (
+ id, user_id, query_text, parsed_current_level, parsed_target_role,
+ parsed_timeframe, recommended_courses, learning_sequence, why_relevant,
+ immediate_next_step, summary, created_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ """, (
+ query_id,
+ user_id,
+ query_text,
+ parsed_current_level,
+ parsed_target_role,
+ parsed_timeframe,
+ json.dumps(recommended_courses),
+ json.dumps(learning_sequence),
+ why_relevant,
+ immediate_next_step,
+ summary,
+ now
+ ))
+ conn.commit()
+ conn.close()
+
+
+def get_recent_queries(limit: int = 10) -> List[Dict[str, Any]]:
+ conn = get_db_connection()
+ cursor = conn.cursor()
+ cursor.execute("""
+ SELECT * FROM user_queries ORDER BY created_at DESC LIMIT ?
+ """, (limit,))
+ rows = cursor.fetchall()
+ conn.close()
+
+ results = []
+ for r in rows:
+ results.append({
+ "id": r["id"],
+ "user_id": r["user_id"],
+ "query_text": r["query_text"],
+ "parsed_current_level": r["parsed_current_level"],
+ "parsed_target_role": r["parsed_target_role"],
+ "parsed_timeframe": r["parsed_timeframe"],
+ "recommended_courses": json.loads(r["recommended_courses"]),
+ "learning_sequence": json.loads(r["learning_sequence"]),
+ "why_relevant": r["why_relevant"],
+ "immediate_next_step": r["immediate_next_step"],
+ "summary": r["summary"],
+ "created_at": r["created_at"],
+ })
+ return results
+
+
+def save_chat_message(session_id: str, role: str, message: str, message_id: str, context_query_id: Optional[str] = None):
+ conn = get_db_connection()
+ cursor = conn.cursor()
+ now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+ cursor.execute("""
+ INSERT INTO chat_interactions (id, session_id, role, message, context_query_id, created_at)
+ VALUES (?, ?, ?, ?, ?, ?)
+ """, (message_id, session_id, role, message, context_query_id, now))
+ conn.commit()
+ conn.close()
+
+
+def get_chat_history(session_id: str, limit: int = 20) -> List[Dict[str, Any]]:
+ conn = get_db_connection()
+ cursor = conn.cursor()
+ cursor.execute("""
+ SELECT role, message, created_at FROM chat_interactions
+ WHERE session_id = ?
+ ORDER BY created_at ASC
+ LIMIT ?
+ """, (session_id, limit))
+ rows = cursor.fetchall()
+ conn.close()
+
+ return [{"role": r["role"], "message": r["message"], "created_at": r["created_at"]} for r in rows]
diff --git a/backend/main.py b/backend/main.py
new file mode 100644
index 0000000..726bfc0
--- /dev/null
+++ b/backend/main.py
@@ -0,0 +1,126 @@
+import html
+import os
+import uvicorn
+from contextlib import asynccontextmanager
+from typing import Optional, Dict, Any
+
+from fastapi import FastAPI, Request, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from backend.database import init_db
+from backend.routes import router as ai_router
+from backend.ai_engine import gemini_client, GEMINI_MODEL
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+ # Initialize SQLite database and seed structured content
+ print("[SERVER] Initializing LearnSphere AI Learning Assistant database...")
+ init_db()
+ print("[SERVER] Database initialized and content verified.")
+ yield
+
+
+app = FastAPI(
+ title="LearnSphere AI Learning Assistant API",
+ description="Backend API powering personalized curriculum recommendations, semantic content retrieval, and AI tutoring for LearnSphere.",
+ version="2.0.0",
+ lifespan=lifespan,
+)
+
+# Enable CORS for frontend Vite dev server (port 5173), production URLs, and local requests
+app.add_middleware(
+ CORSMiddleware,
+ allow_origins=["*"],
+ allow_credentials=True,
+ allow_methods=["*"],
+ allow_headers=["*"],
+)
+
+# Mount AI Learning Assistant routes
+app.include_router(ai_router)
+
+
+# Health check
+@app.get("/health")
+def health():
+ return {
+ "status": "ok",
+ "service": "learnsphere-ai-assistant",
+ "version": "2.0.0",
+ "ai_provider": "google-gemini" if gemini_client else "deterministic-semantic-engine",
+ }
+
+
+# Legacy /chat compatibility for home.html & review.html AI Tutor
+class LegacyChatRequest(BaseModel):
+ message: str
+
+
+@app.post("/chat")
+def legacy_chat(payload: LegacyChatRequest):
+ user_input = payload.message.strip()
+ if not user_input:
+ raise HTTPException(status_code=400, detail="Message cannot be empty.")
+
+ if gemini_client:
+ try:
+ guardrails = (
+ "You are an encouraging educational tutor for LearnSphere. "
+ "Help the student with concepts in programming, computer science, mathematics, or science. "
+ "Keep responses concise, clear, and actionable."
+ )
+ response = gemini_client.models.generate_content(
+ model=GEMINI_MODEL,
+ contents=f"{guardrails}\n\nUser: {user_input}",
+ )
+ raw = (response.text or "").strip()
+ safe_text = html.escape(raw).replace("\n", "