Add LaunchPadAI undergraduate internship advisor panel.

Rebrand the CCAI MuscleGrowthAI template into LaunchPadAI with five career advisors, launchpad_config.yaml, and HF/Docker deploy wiring.

Co-authored-by: Cursor <cursoragent@cursor.com>

.dockerignore

@@ -0,0 +1,20 @@
+**/node_modules
+**/venv
+**/.venv
+**/__pycache__
+**/chromadb_storage
+**/chroma_data
+**/chroma_db
+.git
+.gitignore
+.env
+**/.env
+.vscode
+.cursor
+**/.idea
+**/.DS_Store
+**/Thumbs.db
+docker-compose.yml
+Dockerfile
+.dockerignore
+*.md

.gitattributes

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/propose_release.yml

@@ -0,0 +1,29 @@
+name: Propose Stable Release
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        type: choice
+        description: Release Type
+        options:
+          - patch
+          - minor
+          - major
+jobs:
+  update_version:
+    uses: neongeckocom/.github/.github/workflows/propose_semver_release.yml@master
+    with:
+      branch: dev
+      release_type: ${{ inputs.release_type }}
+      update_changelog: True
+      version_file: "multi_llm_chatbot_backend/app/version.py"
+  pull_changes:
+    uses: neongeckocom/.github/.github/workflows/pull_master.yml@master
+    needs: update_version
+    with:
+      pr_reviewer: neonreviewers
+      pr_assignee: ${{ github.actor }}
+      pr_draft: false
+      pr_title: ${{ needs.update_version.outputs.version }}
+      pr_body: ${{ needs.update_version.outputs.changelog }}
+      destination: main

.github/workflows/publish_release.yml

@@ -0,0 +1,31 @@
+# On every push to `main` (which happens when a release PR produced by
+# Propose Stable Release is merged), read the current version and create a
+# matching GitHub release.  Docker image publishing is intentionally left
+# out for now and can be added separately.
+
+name: Publish GitHub Release
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  tag_release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Get Version
+        run: |
+          VERSION=$(python multi_llm_chatbot_backend/app/version.py)
+          echo "VERSION=${VERSION}" >> $GITHUB_ENV
+      - uses: ncipollo/release-action@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ env.VERSION }}
+          generateReleaseNotes: true

.github/workflows/publish_test_build.yml

@@ -0,0 +1,24 @@
+# Bumps the alpha suffix on every push to `dev` (except when the only
+# change is to the version file itself, to prevent a publish loop).  A
+# GitHub prerelease is cut for each alpha so artifacts are easy to find.
+# This project is not distributed via PyPI, so `publish_pypi` is disabled.
+
+name: Publish Alpha Build
+on:
+  push:
+    branches:
+      - dev
+    paths-ignore:
+      - 'multi_llm_chatbot_backend/app/version.py'
+      - 'CHANGELOG.md'
+
+jobs:
+  publish_alpha_release:
+    uses: neongeckocom/.github/.github/workflows/publish_alpha_release.yml@master
+    secrets: inherit
+    with:
+      version_file: "multi_llm_chatbot_backend/app/version.py"
+      setup_py: "multi_llm_chatbot_backend/app/version.py"
+      publish_prerelease: true
+      publish_pypi: false
+      update_changelog: true

.github/workflows/unit_tests.yml

@@ -0,0 +1,37 @@
+name: Run Unit Tests
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  unit_tests:
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        working-directory: multi_llm_chatbot_backend
+        run: |
+          pip install wheel
+          pip install -r requirements.txt -r test_requirements.txt
+
+      - name: Run unit tests
+        working-directory: multi_llm_chatbot_backend
+        run: |
+          pytest app/tests/unit/ --junitxml=test-results/results.xml
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-py${{ matrix.python-version }}
+          path: multi_llm_chatbot_backend/test-results/

.gitignore

@@ -0,0 +1,27 @@
+# main
+.env
+gcp_build.txt
+
+# backend
+multi_llm_chatbot_backend/.env
+multi_llm_chatbot_backend/chroma_db/
+multi_llm_chatbot_backend/chromadb_storage/
+multi_llm_chatbot_backend/.dockerignore
+multi_llm_chatbot_backend/.env.deploy
+multi_llm_chatbot_backend/Dockerfile
+
+
+
+# frontend
+phd-advisor-frontend/.env.production
+phd-advisor-frontend/.firebase/
+phd-advisor-frontend/.firebaserc
+phd-advisor-frontend/firebase.json
+
+# Ignore all __pycache__ folders
+**/__pycache__/
+
+
+# Python virtual environments
+**/venv/
+.venv/

CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+## [2.0.1a3](https://github.com/NeonGeckoCom/CCAI-Demo/tree/2.0.1a3) (2026-05-21)
+
+[Full Changelog](https://github.com/NeonGeckoCom/CCAI-Demo/compare/2.0.1a2...2.0.1a3)
+
+**Merged pull requests:**
+
+- Add Onboarding tour [\#48](https://github.com/NeonGeckoCom/CCAI-Demo/pull/48) ([NeonRyan](https://github.com/NeonRyan))
+
+## [2.0.1a2](https://github.com/NeonGeckoCom/CCAI-Demo/tree/2.0.1a2) (2026-05-19)
+
+[Full Changelog](https://github.com/NeonGeckoCom/CCAI-Demo/compare/33862e61789b40734f952d1ae06b03c86dff49af...2.0.1a2)
+
+**Implemented enhancements:**
+
+- \[FEAT\] Clear User Data [\#52](https://github.com/NeonGeckoCom/CCAI-Demo/issues/52)
+- \[FEAT\] Support tools [\#34](https://github.com/NeonGeckoCom/CCAI-Demo/issues/34)
+- \[FEAT\] Add endpoint and UI for User Account updates [\#26](https://github.com/NeonGeckoCom/CCAI-Demo/issues/26)
+- \[FEAT\] Support advisor avatar images [\#25](https://github.com/NeonGeckoCom/CCAI-Demo/issues/25)
+- \[FEAT\] Configurable User Guide [\#24](https://github.com/NeonGeckoCom/CCAI-Demo/issues/24)
+- \[FEAT\] Support vLLM endpoints [\#22](https://github.com/NeonGeckoCom/CCAI-Demo/issues/22)
+- \[FEAT\] Improved persona configuration handling [\#8](https://github.com/NeonGeckoCom/CCAI-Demo/issues/8)
+- \[FEAT\] Implement automatic color picker for personas [\#7](https://github.com/NeonGeckoCom/CCAI-Demo/issues/7)
+- \[FEAT\] Validate configured icons [\#6](https://github.com/NeonGeckoCom/CCAI-Demo/issues/6)
+- \[FEAT\] Improved Checks for "Clarification Needed" [\#5](https://github.com/NeonGeckoCom/CCAI-Demo/issues/5)
+- \[FEAT\] Versioning and release automation [\#4](https://github.com/NeonGeckoCom/CCAI-Demo/issues/4)
+
+**Fixed bugs:**
+
+- \[BUG\] Deleting a chat in the UI causes an empty chat to be created [\#45](https://github.com/NeonGeckoCom/CCAI-Demo/issues/45)
+- \[BUG\] User inputs are sometimes repeated [\#42](https://github.com/NeonGeckoCom/CCAI-Demo/issues/42)
+- \[BUG\] Improved method for LLM JSON Generation [\#13](https://github.com/NeonGeckoCom/CCAI-Demo/issues/13)
+
+**Closed issues:**
+
+- Pin the requirements.txt to stable versions [\#37](https://github.com/NeonGeckoCom/CCAI-Demo/issues/37)
+
+**Merged pull requests:**
+
+- feat/Added front end support for settings page [\#60](https://github.com/NeonGeckoCom/CCAI-Demo/pull/60) ([NeonRyan](https://github.com/NeonRyan))
+- Clear User Data [\#58](https://github.com/NeonGeckoCom/CCAI-Demo/pull/58) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Feat/improve clarification check [\#57](https://github.com/NeonGeckoCom/CCAI-Demo/pull/57) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- UI Improvements [\#56](https://github.com/NeonGeckoCom/CCAI-Demo/pull/56) ([NeonRyan](https://github.com/NeonRyan))
+- Fix bug around chat deletion [\#54](https://github.com/NeonGeckoCom/CCAI-Demo/pull/54) ([NeonRyan](https://github.com/NeonRyan))
+- Add User Guide [\#53](https://github.com/NeonGeckoCom/CCAI-Demo/pull/53) ([NeonRyan](https://github.com/NeonRyan))
+- Add versioning automation [\#47](https://github.com/NeonGeckoCom/CCAI-Demo/pull/47) ([NeonDaniel](https://github.com/NeonDaniel))
+- Fix/dup first message [\#44](https://github.com/NeonGeckoCom/CCAI-Demo/pull/44) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Feat/persona avatars [\#43](https://github.com/NeonGeckoCom/CCAI-Demo/pull/43) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Feat/account management [\#41](https://github.com/NeonGeckoCom/CCAI-Demo/pull/41) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Fix/json output [\#40](https://github.com/NeonGeckoCom/CCAI-Demo/pull/40) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Feat/advisor tools [\#38](https://github.com/NeonGeckoCom/CCAI-Demo/pull/38) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Feat/vllm endpoints [\#36](https://github.com/NeonGeckoCom/CCAI-Demo/pull/36) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Refactor/unittests [\#33](https://github.com/NeonGeckoCom/CCAI-Demo/pull/33) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Support Voice Interaction [\#32](https://github.com/NeonGeckoCom/CCAI-Demo/pull/32) ([NeonDaniel](https://github.com/NeonDaniel))
+- Fix/structured json output [\#30](https://github.com/NeonGeckoCom/CCAI-Demo/pull/30) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Feat/auto persona colors [\#23](https://github.com/NeonGeckoCom/CCAI-Demo/pull/23) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Feat/validate lucide icons [\#21](https://github.com/NeonGeckoCom/CCAI-Demo/pull/21) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Initial setup of GitHub Actions workflow [\#20](https://github.com/NeonGeckoCom/CCAI-Demo/pull/20) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Refactor chat UI layout [\#19](https://github.com/NeonGeckoCom/CCAI-Demo/pull/19) ([NeonDaniel](https://github.com/NeonDaniel))
+- Stream LLM Responses [\#18](https://github.com/NeonGeckoCom/CCAI-Demo/pull/18) ([NeonDaniel](https://github.com/NeonDaniel))
+- Feat/improve persona config [\#16](https://github.com/NeonGeckoCom/CCAI-Demo/pull/16) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Add Neon AI Branding [\#15](https://github.com/NeonGeckoCom/CCAI-Demo/pull/15) ([NeonDaniel](https://github.com/NeonDaniel))
+- Docs/update readme repo URL [\#14](https://github.com/NeonGeckoCom/CCAI-Demo/pull/14) ([NeonCharlie-24](https://github.com/NeonCharlie-24))
+- Improve backend logic around user input parsing [\#12](https://github.com/NeonGeckoCom/CCAI-Demo/pull/12) ([NeonDaniel](https://github.com/NeonDaniel))
+- Fix Home navigation to prevent logging out [\#11](https://github.com/NeonGeckoCom/CCAI-Demo/pull/11) ([NeonDaniel](https://github.com/NeonDaniel))
+- Add configuration for Undergrad Advisor Panel [\#10](https://github.com/NeonGeckoCom/CCAI-Demo/pull/10) ([NeonDaniel](https://github.com/NeonDaniel))
+- Add configuration support [\#3](https://github.com/NeonGeckoCom/CCAI-Demo/pull/3) ([NeonDaniel](https://github.com/NeonDaniel))
+- Docker optimization by Cursor [\#2](https://github.com/NeonGeckoCom/CCAI-Demo/pull/2) ([NeonDaniel](https://github.com/NeonDaniel))
+- Implement Docker deployment [\#1](https://github.com/NeonGeckoCom/CCAI-Demo/pull/1) ([NeonDaniel](https://github.com/NeonDaniel))
+
+
+
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

Dockerfile

@@ -0,0 +1,76 @@
+# syntax=docker/dockerfile:1.7
+# ---------------------------------------------------------------------------
+# LaunchPadAI Panel — single-container HuggingFace Spaces image.
+#
+# Mirrors the structural choices used by the working HF Spaces deployments
+# CCAI-Vibe-Demo and CU-Student-AIProject-Helper:
+#   * multi-stage Node frontend build → Python+SPA bundle
+#   * non-root user uid 1000, port 7860 (HF Spaces convention)
+#   * persistence on the HF Storage Bucket mount at /data (SQLite shim)
+#   * REACT_APP_API_URL is set to the empty string at build time so the SPA
+#     issues relative URLs and shares the FastAPI origin
+#
+# Build context: repo root (this file).
+# ---------------------------------------------------------------------------
+
+# ---- 1. Frontend build (CRA) ----------------------------------------------
+FROM node:20-bookworm AS frontend-build
+WORKDIR /app/frontend
+
+COPY phd-advisor-frontend/package.json phd-advisor-frontend/package-lock.json* ./
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci
+
+COPY phd-advisor-frontend/ ./
+
+# Empty REACT_APP_API_URL → CRA inlines '' so every fetch() hits the same
+# origin as the SPA (the FastAPI server below).
+ENV REACT_APP_API_URL=""
+RUN npm run build
+
+# ---- 2. Python runtime + SPA bundle ---------------------------------------
+FROM python:3.12-slim-bookworm
+
+# ffmpeg is required by the /api/voice/transcribe endpoint
+# (browser WebM/Opus → WAV for Whisper). Kept on the runtime image only,
+# not on the build image, so we don't pay the apt cost during incremental
+# code rebuilds.
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ffmpeg && \
+    rm -rf /var/lib/apt/lists/*
+
+# HF Spaces runs the container as uid 1000 and expects the app to do the
+# same; with a non-root user we cannot bind privileged ports, but :7860 is
+# fine.
+RUN useradd -m -u 1000 user && mkdir -p /home/user/data && chown user:user /home/user/data
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    CORS_ORIGINS=* \
+    DATA_DIR=/home/user/data \
+    CONFIG_PATH=/home/user/app/launchpad_config.yaml
+
+WORKDIR $HOME/app
+
+# ---- Python deps (cached unless requirements.txt changes) -----------------
+COPY --chown=user multi_llm_chatbot_backend/requirements.txt ./
+RUN --mount=type=cache,target=/home/user/.cache/pip,uid=1000,gid=1000 \
+    pip install --no-cache-dir --user -r requirements.txt
+
+# ---- Backend source -------------------------------------------------------
+COPY --chown=user multi_llm_chatbot_backend/ ./
+
+# ---- Top-level configuration files (config.yaml + persona definitions) ----
+COPY --chown=user launchpad_config.yaml ./launchpad_config.yaml
+COPY --chown=user personas/ ./personas/
+
+# ---- Frontend bundle ------------------------------------------------------
+# main.py mounts $HOME/app/static at "/" so the SPA is served same-origin
+# with the API.
+COPY --chown=user --from=frontend-build /app/frontend/build ./static
+
+ENV PYTHONPATH=$HOME/app
+
+EXPOSE 7860
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,98 @@
+---
+title: LaunchPadAI
+emoji: 🚀
+colorFrom: green
+colorTo: blue
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
+# LaunchPadAI Panel
+
+An AI undergraduate internship and early-career assistant built on Neon AI's
+Collaborative Conversational AI (CCAI) framework. Ask about Handshake/LinkedIn
+search, resume polish, interview prep, application cadence, and networking —
+and get diverse perspectives from a panel of five career AI advisors.
+
+This repository is a **complete, deployable application** — the CCAI
+multi-advisor stack (FastAPI backend + React frontend) wired to the
+LaunchPadAI configuration in [`launchpad_config.yaml`](launchpad_config.yaml)
+and the personas in [`personas/career_advisors/`](personas/career_advisors).
+
+## Advisors
+
+1. **Internship Search Strategist** — roles, platforms, target lists
+2. **Resume Optimizer** — ATS, bullets, skills match
+3. **Interview Coach** — prep, presence, company research
+4. **Application Scheduler** — cadence, deadlines, tracking
+5. **Career Path Mentor** — networking, pivot, full-time transition
+
+## Hugging Face Spaces deployment
+
+This Space ships as a single Docker image built from the repository-root
+[`Dockerfile`](Dockerfile). The container:
+
+1. Builds the React frontend (CRA) at image-build time with `REACT_APP_API_URL=""`
+   so every `fetch` issues a relative URL.
+2. Serves the bundled SPA from FastAPI at `/`, with the API on `/api/...`,
+   `/auth/...`, etc. — all on the same `:7860` origin.
+3. Persists user data (auth, profiles, chat sessions) in **SQLite via
+   `aiosqlite`** at `${DATA_DIR}/launchpad_panel.db`. Mount a Hugging Face
+   Storage Bucket at `/data` to make the database survive Space rebuilds.
+   There is **no MongoDB** and no third-party data plane.
+
+### Required Space secrets
+
+| Secret | Purpose |
+|--------|---------|
+| `JWT_SECRET_KEY` | Signs auth tokens. Set this to a long random string. |
+| `OPENAI_API_KEY` | Powers the default OpenAI provider (`gpt-5.4-mini`). |
+| `GEMINI_API_KEY` | Optional — only if you switch `llm.provider` back to `gemini`. |
+
+Set these under **Settings → Variables and secrets** on the Space.
+
+## Local deployment
+
+### Option A — Docker
+
+```bash
+# From the repo root, create a .env with at least:
+#   JWT_SECRET_KEY=some-long-random-string
+#   OPENAI_API_KEY=your-openai-key
+docker compose up --build
+```
+
+Open <http://localhost:7860>. Override the host port with `LAUNCHPAD_HOST_PORT` if
+7860 is taken.
+
+### Option B — Native (no Docker)
+
+**Backend** (terminal 1):
+
+```bash
+cd multi_llm_chatbot_backend
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+CONFIG_PATH=../launchpad_config.yaml uvicorn app.main:app --reload --port 8000
+```
+
+**Frontend** (terminal 2):
+
+```bash
+cd phd-advisor-frontend
+npm install
+REACT_APP_API_URL=http://localhost:8000 npm start
+```
+
+Open <http://localhost:3000> — you should see **LaunchPadAI** with five career advisors.
+
+## Configuration
+
+App UI, login fields, chat examples, orchestrator keywords, and LLM/RAG
+settings live in [`launchpad_config.yaml`](launchpad_config.yaml). The five
+advisor YAMLs in `personas/career_advisors/` load automatically. Point the app at a
+different config with `CONFIG_PATH`.
+
+The workshop draft that generated this panel is saved as
+[`advisor-panel-draft.json`](advisor-panel-draft.json).

advisor-panel-draft.json

@@ -0,0 +1,111 @@
+{
+  "authorName": "Kennedy Johnson",
+  "panelName": "Undergraduate Internship Search",
+  "purpose": "Help undergraduate students locate, apply for, and land internships in a competitive market — and pivot to entry-level full-time roles when appropriate.",
+  "advisors": [
+    {
+      "name": "Internship Search Strategist",
+      "role": "Roles, Platforms & Target Lists"
+    },
+    {
+      "name": "Resume Optimizer",
+      "role": "ATS, Bullets & Skills Match"
+    },
+    {
+      "name": "Interview Coach",
+      "role": "Prep, Presence & Company Research"
+    },
+    {
+      "name": "Application Scheduler",
+      "role": "Cadence, Deadlines & Tracking"
+    },
+    {
+      "name": "Career Path Mentor",
+      "role": "Networking, Pivot & Full-Time Transition"
+    }
+  ],
+  "visionApplicationPurpose": "Help undergraduate students locate, apply for, and land internships in a competitive market — and pivot to entry-level full-time roles when appropriate.",
+  "visionTargetAudience": "Undergraduate students, especially juniors (3rd year) seeking internships. Seniors (4th year+) are guided toward internships or full-time entry-level jobs.",
+  "visionKeyOutcomes": "Personalized daily/weekly application schedules; where to apply (Handshake, LinkedIn, company sites); interview tips and likely questions; resume feedback and revision based on experience and skills.",
+  "appTitle": "LaunchPadAI",
+  "appSubtitle": "AI mentor for internships to full-time jobs",
+  "primaryBrandColor": "#0F766E",
+  "logoIcon": "Rocket",
+  "footerText": "© 2026 Kennedy Johnson. All rights reserved.",
+  "headlinePrefix": "Undergraduate Internship Navigation",
+  "headlineHighlight": "AI Undergrad Job Finder",
+  "homepageDescription": "Receive a personalized plan to find and land an internship as a third-year undergrad, or pivot to an entry-level full-time job as a fourth-year student and beyond.",
+  "featuresSectionTitle": "AI Career Toolkit",
+  "featureCards": [
+    {
+      "title": "AI Internship Search",
+      "icon": "Search",
+      "description": "A personalized plan to match multiple internships a day, plus resume review and interview tips to build your career foundation."
+    },
+    {
+      "title": "Resume Optimizer",
+      "icon": "FilePenLine",
+      "description": "Feedback, edits, and tweaks so your resume stands out to ATS systems and recruiting teams."
+    },
+    {
+      "title": "AI Interview Helper",
+      "icon": "MessagesSquare",
+      "description": "Near-perfect answers, company research tips, and guidance on presence and body language for virtual or in-person interviews."
+    }
+  ],
+  "loginPageSubtitle": "Sign in to land your internship and entry-level job today!",
+  "signupPageSubtitle": "Create an account to start the first day of your career!",
+  "userInfoRows": [
+    {
+      "infoBoxLabel": "Academic Standing",
+      "dropdownChoices": "Sophomore (2nd year), Junior (3rd year — internships), Senior (4th year — FT / entry-level), Graduate / recent grad"
+    }
+  ],
+  "examplePromptCards": [
+    {
+      "title": "Career Layout",
+      "icon": "CalendarRange",
+      "prompts": [
+        "How many internships should I apply to each day?",
+        "How do I stand out in an interview?",
+        "Where can I find entry-level jobs that build real skills?"
+      ]
+    },
+    {
+      "title": "Search & Apply",
+      "icon": "Search",
+      "prompts": [
+        "Build a Handshake and LinkedIn search plan for business analytics internships.",
+        "What companies should a Leeds undergrad target this semester?",
+        "How do I track applications without getting overwhelmed?"
+      ]
+    },
+    {
+      "title": "Resume & Materials",
+      "icon": "FilePenLine",
+      "prompts": [
+        "Rewrite my resume bullets for an internship in marketing analytics.",
+        "What keywords should I add for ATS screening?",
+        "Review my experience section for a junior-year candidate."
+      ]
+    },
+    {
+      "title": "Interview & Network",
+      "icon": "MessagesSquare",
+      "prompts": [
+        "Give me 10 behavioral interview questions for a finance internship.",
+        "How should I research a company the night before?",
+        "Draft a LinkedIn outreach message to an alumni in my field."
+      ]
+    }
+  ],
+  "chatInputPlaceholder": "Ask about application cadence, Handshake/LinkedIn search, resume edits, or interview prep...",
+  "sharedBasePrompt": "base_prompt: |\n  **Formatting (Compact Markdown v1):**\n  - Use GitHub-Flavored Markdown.\n  - Output exactly three sections in this order:\n    - `### Thought` -- one sentence that reflects on the user's situation from YOUR perspective.\n    - `### What to do` -- exactly 3 bullets, one line each, with practical actions.\n    - `### Next step` -- one imperative sentence telling the user what to do now.\n  - Use `###` for headings and `-` for bullets.\n  - Insert one blank line between sections.\n  - Keep each section unique and non-repetitive.",
+  "includedPersonaIds": [
+    "internship_search_strategist",
+    "resume_optimizer",
+    "interview_coach",
+    "application_scheduler",
+    "career_path_mentor"
+  ]
+}

docker-compose.yml

@@ -0,0 +1,33 @@
+# ---------------------------------------------------------------------------
+# Local-dev wrapper around the single-container HuggingFace Spaces image.
+#
+# Override LAUNCHPAD_HOST_PORT via .env (or shell) if 7860 conflicts; the
+# in-container port is fixed at 7860 to mirror HF Spaces.
+# ---------------------------------------------------------------------------
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: launchpad-panel:dev
+    ports:
+      - "${LAUNCHPAD_HOST_PORT:-7860}:7860"
+    environment:
+      JWT_SECRET_KEY: ${JWT_SECRET_KEY:-CHANGEME-by-overriding-in-dot-env-file}
+      GEMINI_API_KEY: ${GEMINI_API_KEY:-}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+      VLLM_API_KEY: ${VLLM_API_KEY:-}
+      VLLM_API_USERNAME: ${VLLM_API_USERNAME:-}
+      GEMINI_MODEL: ${GEMINI_MODEL:-gemini-2.5-flash}
+      CONFIG_PATH: ${CONFIG_PATH:-/home/user/app/launchpad_config.yaml}
+      # Same-origin in single-container; only relevant for cross-origin dev.
+      CORS_ORIGINS: ${CORS_ORIGINS:-*}
+      # SQLite + ChromaDB persistence both land here. The named volume below
+      # mirrors the HF Storage Bucket mount so user data survives rebuilds.
+      DATA_DIR: /data
+    volumes:
+      - launchpad_data:/data
+
+volumes:
+  launchpad_data:

docs/nutrition_tools.md

@@ -0,0 +1,35 @@
+# Nutrition calculation tools (MuscleGrowthAI)
+
+Deterministic fitness/nutrition math for advisor responses. LLM personas receive pre-computed values instead of doing arithmetic themselves.
+
+## Tools in use
+
+| Source | Cost | Status | Purpose |
+|--------|------|--------|---------|
+| **Local Python formulas** | Free | **Active** | lbs↔kg, protein g/kg (1.6–2.2), meal splits |
+| **USDA FoodData Central** | Free (API key) | Planned | Food nutrient lookup by name/barcode |
+| **Open Food Facts** | Free (no key) | Planned | Product/barcode nutrient data |
+
+## Core formulas (local)
+
+- **Weight:** `kg = lbs × 0.45359237`
+- **Protein (hypertrophy):** `protein_g_min = round(weight_kg × 1.6)`, `protein_g_mid = round(weight_kg × 1.9)`, `protein_g_max = round(weight_kg × 2.2)`
+- **Meal split:** even distribution with remainder assigned to first meals
+
+Example: **230 lb** → **104.33 kg** → **167–230 g protein/day**; midpoint at **1.9 g/kg** ≈ **~198 g/day** (4 meals ≈ 50/50/49/49 g at the midpoint).
+
+## How calculations reach advisors
+
+1. **Context injection (primary):** When chat history mentions protein and a body weight is present, `compute_protein_advisory_context()` runs in `_build_enhanced_context_for_persona()` and adds a `PRE-COMPUTED NUTRITION VALUES` JSON block to each persona system prompt.
+2. **LLM tool calling (optional):** `calculate_protein_target` is registered in `app/tools/nutrition_calculator.py` and enabled via `muscle_growth_config.yaml` → `tools.nutrition_calculator.enabled: true`. The orchestrator may call it for direct tool responses when appropriate.
+
+## Files
+
+- `multi_llm_chatbot_backend/app/tools/nutrition_calculator.py` — formulas + tool definition
+- `multi_llm_chatbot_backend/app/core/improved_orchestrator.py` — injects computed context into persona prompts
+- `muscle_growth_config.yaml` — enables `nutrition_calculator` tool
+
+## USDA / Open Food Facts (later)
+
+- USDA: register at [https://fdc.nal.usda.gov/api-key-signup](https://fdc.nal.usda.gov/api-key-signup), set `USDA_API_KEY` env var.
+- Open Food Facts: `https://world.openfoodfacts.org/api/v2/product/{barcode}` — no key required.

launchpad_config.yaml

@@ -0,0 +1,202 @@
+# ============================================================================
+# LaunchPadAI — Application Configuration
+# Generated from advisor-panel-draft (Undergraduate Internship Search) by Kennedy Johnson
+# Modeled on MuscleGrowthAI / CCAI multi-advisor panel pattern
+# ============================================================================
+
+app:
+  title: "LaunchPadAI"
+  subtitle: "AI mentor for internships to full-time jobs"
+  primary_color: "#0F766E"
+  logo_icon: "Rocket"
+  footer_text: "© 2026 Kennedy Johnson. All rights reserved."
+  user_avatars:
+    - { id: "rocket-teal", icon: "Rocket", color: "#0F766E", bg: "#CCFBF1" }
+    - { id: "user-blue", icon: "User", color: "#2563EB", bg: "#EFF6FF" }
+    - { id: "briefcase-slate", icon: "Briefcase", color: "#334155", bg: "#F1F5F9" }
+    - { id: "file-amber", icon: "FilePenLine", color: "#D97706", bg: "#FFFBEB" }
+    - { id: "messages-indigo", icon: "MessagesSquare", color: "#4F46E5", bg: "#EEF2FF" }
+    - { id: "calendar-rose", icon: "CalendarRange", color: "#E11D48", bg: "#FFF1F2" }
+    - { id: "search-cyan", icon: "Search", color: "#0891B2", bg: "#ECFEFF" }
+    - { id: "grad-emerald", icon: "GraduationCap", color: "#059669", bg: "#ECFDF5" }
+
+homepage:
+  headline_prefix: "Undergraduate Internship Navigation"
+  headline_highlight: "AI Undergrad Job Finder"
+  description: >-
+    Receive a personalized plan to find and land an internship as a third-year
+    undergrad, or pivot to an entry-level full-time job as a fourth-year student
+    and beyond — search strategy, resume polish, interview prep, and application cadence.
+  features_title: "AI Career Toolkit"
+  features:
+    - title: "AI Internship Search"
+      description: "A personalized plan to match multiple internships a day, plus resume review and interview tips to build your career foundation."
+      icon: "Search"
+    - title: "Resume Optimizer"
+      description: "Feedback, edits, and tweaks so your resume stands out to ATS systems and recruiting teams."
+      icon: "FilePenLine"
+    - title: "AI Interview Helper"
+      description: "Near-perfect answers, company research tips, and guidance on presence for virtual or in-person interviews."
+      icon: "MessagesSquare"
+
+login:
+  subtitle: "Sign in to land your internship and entry-level job today!"
+  signup_subtitle: "Create an account to start the first day of your career!"
+  knowledge_levels:
+    - { value: "", label: "Select your academic standing" }
+    - { value: "sophomore", label: "Sophomore (2nd year)" }
+    - { value: "junior", label: "Junior (3rd year — internships)" }
+    - { value: "senior", label: "Senior (4th year — FT / entry-level)" }
+    - { value: "grad", label: "Graduate / recent grad" }
+  timezones:
+    - { value: "", label: "Select timezone (optional)" }
+    - { value: "America/New_York", label: "Eastern (US)" }
+    - { value: "America/Chicago", label: "Central (US)" }
+    - { value: "America/Denver", label: "Mountain (US)" }
+    - { value: "America/Los_Angeles", label: "Pacific (US)" }
+    - { value: "America/Anchorage", label: "Alaska (US)" }
+    - { value: "Pacific/Honolulu", label: "Hawaii (US)" }
+    - { value: "UTC", label: "UTC" }
+  academic_stages:
+    - { value: "", label: "Select your academic standing" }
+    - { value: "sophomore", label: "Sophomore (2nd year)" }
+    - { value: "junior", label: "Junior (3rd year — internships)" }
+    - { value: "senior", label: "Senior (4th year — FT / entry-level)" }
+    - { value: "grad", label: "Graduate / recent grad" }
+
+chat_page:
+  placeholder: "Ask about application cadence, Handshake/LinkedIn search, resume edits, or interview prep..."
+  examples:
+    - title: "Career Layout"
+      icon: "CalendarRange"
+      color: "#0F766E"
+      bg_color: "#CCFBF1"
+      suggestions:
+        - "How many internships should I apply to each day?"
+        - "How do I stand out in an interview?"
+        - "Where can I find entry-level jobs that build real skills?"
+    - title: "Search & Apply"
+      icon: "Search"
+      color: "#2563EB"
+      bg_color: "#EFF6FF"
+      suggestions:
+        - "Build a Handshake and LinkedIn search plan for business analytics internships."
+        - "What companies should a Leeds undergrad target this semester?"
+        - "How do I track applications without getting overwhelmed?"
+    - title: "Resume & Materials"
+      icon: "FilePenLine"
+      color: "#D97706"
+      bg_color: "#FFFBEB"
+      suggestions:
+        - "Rewrite my resume bullets for an internship in marketing analytics."
+        - "What keywords should I add for ATS screening?"
+        - "Review my experience section for a junior-year candidate."
+    - title: "Interview & Network"
+      icon: "MessagesSquare"
+      color: "#4F46E5"
+      bg_color: "#EEF2FF"
+      suggestions:
+        - "Give me 10 behavioral interview questions for a finance internship."
+        - "How should I research a company the night before?"
+        - "Draft a LinkedIn outreach message to an alumni in my field."
+
+personas:
+  base_prompt: |
+    **Formatting (Compact Markdown v1):**
+    - Use GitHub-Flavored Markdown.
+    - Output exactly three sections in this order:
+      - `### Thought` — one sentence that reflects on the user's situation from YOUR perspective.
+      - `### What to do` — exactly 3 bullets, one line each, with practical actions.
+      - `### Next step` — one imperative sentence telling the user what to do now.
+    - Use `###` for headings and `-` for bullets.
+    - Insert one blank line between sections.
+    - Keep each section unique and non-repetitive.
+    - Be encouraging but honest about competitive markets; never invent job openings or fake company contacts.
+    - Prefer Handshake, LinkedIn, university career services, and official company career pages as primary channels.
+  personas_dir: "personas/career_advisors"
+
+orchestrator:
+  min_words_without_keywords: 6
+  conversation_history_token_threshold: 4000
+  specific_keywords:
+    - "internship"
+    - "intern"
+    - "job"
+    - "career"
+    - "resume"
+    - "cv"
+    - "cover letter"
+    - "handshake"
+    - "linkedin"
+    - "interview"
+    - "behavioral"
+    - "recruiter"
+    - "ats"
+    - "apply"
+    - "application"
+    - "networking"
+    - "alumni"
+    - "offer"
+    - "full-time"
+    - "entry-level"
+    - "sophomore"
+    - "junior"
+    - "senior"
+    - "leeds"
+    - "undergrad"
+    - "deadline"
+    - "portfolio"
+  clarification_questions:
+    - "What is your academic standing (sophomore, junior, senior) and target start term?"
+    - "Which majors, industries, or role types are you targeting?"
+    - "Are you optimizing for internships, full-time entry-level, or both?"
+    - "How many hours per week can you realistically spend on applications?"
+  clarification_suggestions:
+    - "Ask for a weekly Handshake and LinkedIn search plan"
+    - "Upload your resume for ATS-focused edits"
+    - "Request behavioral interview practice for your target role"
+    - "Get a daily application cadence with tracking tips"
+
+auth:
+  algorithm: "HS256"
+  token_expiry_minutes: 43200
+
+mongodb:
+  database_name: "launchpad_advisor"
+
+llm:
+  provider: "openai"
+  gemini:
+    model: "gemini-2.5-flash"
+  ollama:
+    model: "llama3.2:1b"
+  vllm:
+    api_url: ""
+    api_key: ""
+    api_username: "guest"
+    model_id: ""
+    neon_persona_orchestrator: "vanilla"
+    neon_persona_advisors: "vanilla"
+  openai:
+    # Key comes from the OPENAI_API_KEY env var / HF Space secret (never committed).
+    api_key: ""
+    model: "gpt-5.4-mini"
+    orchestrator_reasoning_effort: "low"
+    persona_reasoning_effort: "none"
+  resilient:
+    race_timeout_seconds: 60
+
+rag:
+  embedding_model: "all-MiniLM-L6-v2"
+  chroma_collection: "launchpad_documents"
+
+tools:
+  current_datetime:
+    enabled: true
+    default_timezone: "America/Denver"
+  nutrition_calculator:
+    enabled: false
+
+voice:
+  stt_endpoint: "https://whisper.neonaiservices.com"
+  tts_endpoint: "https://coqui.neonaiservices.com"

multi_llm_chatbot_backend/.env.example

@@ -0,0 +1,24 @@
+# Copy this file to `.env` (same directory) for a native, non-Docker local run.
+# The backend auto-loads it on startup.
+
+# Path to the app config, relative to this backend directory.
+CONFIG_PATH=../launchpad_config.yaml
+
+# Where the SQLite database + uploaded docs live. Any writable folder works;
+# on a native run this replaces the container's /data mount.
+DATA_DIR=./local_data
+
+# Signs auth tokens — set to a long random string.
+JWT_SECRET_KEY=change-me-to-a-long-random-string
+
+# Default provider is OpenAI GPT-5.4-mini (see launchpad_config.yaml -> llm.provider).
+# Set your OpenAI API key here (get one from Clary, or use your own).
+OPENAI_API_KEY=
+
+# Optional alternatives:
+# GEMINI_API_KEY=   # only if you switch llm.provider back to "gemini"
+VLLM_API_KEY=
+
+# Frontend origins allowed to call this backend during native dev
+# (CRA dev server defaults to port 3000).
+CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

multi_llm_chatbot_backend/README.md

@@ -0,0 +1,178 @@
+# Multi-LLM Chatbot Backend
+
+A modular, extensible FastAPI backend for building an AI-powered research advisor chatbot that supports:
+- Multiple AI personas with configurable tone and behavior
+- Dynamic switching between Gemini (cloud) and Ollama (local) LLMs
+- Chat session persistence and context memory
+- Document upload, chunking, and retrieval using RAG
+- Rich export features (PDF, DOCX, TXT)
+- User authentication and JWT-based access control
+
+---
+
+## Backend Architecture
+
+```text
+User Input
+   ↓
+/chat-stream → Orchestrator
+     ↓            ↙         ↘
+  SessionManager   ContextManager   RAGManager
+         ↓              ↓             ↓
+     MongoDB        Token Trimming   ChromaDB
+         ↓              ↓             ↓
+        Persisted Chat & Doc Context → LLM (Gemini/Ollama)
+```
+
+---
+
+## Features
+
+- Persona-based multi-agent conversation (`Theorist`, `Pragmatist`, etc.)
+- Provider switching (Gemini ↔ Ollama)
+- Context-aware response routing + top-K advisor selection
+- PDF, DOCX, and TXT file upload and semantic retrieval
+- Developer tools: debug personas, test RAG, export sessions
+- Secure authentication and session scoping
+
+---
+
+## Setup Instructions
+
+### 1. Clone and Configure Environment
+
+```bash
+git clone https://github.com/yourorg/multi-llm-chatbot-backend
+cd multi-llm-chatbot-backend
+cp .env.example .env  # already provided
+```
+
+### 2. Python Environment Setup
+
+```bash
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+
+pip install -r requirements.txt
+```
+
+### 3. Run the Server
+
+```bash
+uvicorn app.main:app --reload
+```
+
+> Server will be available at: `http://localhost:8000`
+
+---
+
+## FastAPI Routing & Modules
+
+| Folder | Description |
+|--------|-------------|
+| [`app/api`](./api_README.md) | REST API endpoints for chat, auth, RAG, exports |
+| [`app/core`](./core_README.md) | Main orchestration, context windows, database logic |
+| [`app/llm`](./llm_README.md) | Gemini + Ollama LLM wrappers |
+| [`app/models`](./models_README.md) | Persona and user schemas |
+| [`app/utils`](./utils_README.md) | File parsing, summaries, exports, vector helpers |
+
+---
+
+## Key Files
+
+### `main.py`
+
+- Loads env vars, sets up FastAPI instance with CORS and routers
+- Calls `connect_to_mongo()` on startup and `close_mongo_connection()` on shutdown
+- Imports and registers all routers (`auth`, `chat_sessions`, etc.)
+
+### `.env` (Sample Vars)
+
+```ini
+# MongoDB
+MONGODB_CONNECTION_STRING=mongodb://localhost:27017
+MONGODB_DATABASE_NAME=neon_ai_backend
+
+# Gemini API Key and model
+GEMINI_API_KEY=...  # Replace with real key
+GEMINI_MODEL=gemini-2.0-flash
+
+# Default provider
+DEFAULT_PROVIDER=gemini
+```
+
+### `requirements.txt`
+
+Includes:
+- **FastAPI**, **Uvicorn**: API framework and server
+- **httpx**: Async LLM request handler
+- **motor**, **pymongo**: MongoDB async access
+- **chromadb**, **sentence-transformers**: Vector database + embeddings
+- **PyPDF2**, **docx2txt**, **reportlab**: Document parsing and PDF generation
+- **passlib**, **python-jose**: Auth and security
+
+---
+
+## Persona Design & Context Handling
+
+- Personas defined in `app/models/default_personas.py`
+- Rich system prompts, styles, and epistemologies
+- Responses routed through `ImprovedChatOrchestrator`
+- Context trimmed and weighted via `ContextManager`
+
+---
+
+## Switching LLM Providers
+
+You can hot-swap models via API:
+
+```http
+POST /switch-provider
+{ "provider": "gemini" } | { "provider": "ollama" }
+```
+
+> Also supported: `/switch-model`, `/current-model`, `/current-provider`
+
+---
+
+## Document Upload + RAG
+
+- Upload PDFs, DOCX, or TXT to sessions
+- Text is extracted → chunked → embedded → stored in ChromaDB
+- Queried during conversation by persona-aware `EnhancedRAGManager`
+
+---
+
+## Export Options
+
+| Format | Export Endpoint |
+|--------|------------------|
+| PDF | `/export-chat?format=pdf` |
+| DOCX | `/export-chat?format=docx` |
+| TXT | `/export-chat?format=txt` |
+| Summary | `/chat-summary?format=pdf` |
+
+---
+
+## Developer & Debug Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `/debug/personas` | See registered advisors and prompts |
+| `/debug/ranked-personas` | View top-K advisors for context |
+| `/debug/rag-status` | Run sample search to test document index |
+
+---
+
+## Status & Roadmap
+
+- [x] Multi-LLM backend ready (Gemini + Ollama)
+- [x] Document RAG + export system
+- [x] Session-aware persona routing
+- [x] JWT Auth + MongoDB user handling
+- [ ] UI enhancements and persona memory
+- [ ] Persona fine-tuning support (future)
+
+---
+
+For questions, contributions, or deployment help — feel free to reach out!

multi_llm_chatbot_backend/app/api/README.md

@@ -0,0 +1,175 @@
+# `app/api` – REST API Layer for Multi-LLM Chatbot
+
+This module defines the complete FastAPI-based HTTP interface for all backend features, including chat, session management, RAG operations, provider switching, and document interaction.
+
+Each file in this directory defines route groups (`APIRouter`) to modularize functionality.
+
+---
+
+## API Directory Layout
+
+| File | Purpose |
+|------|---------|
+| `auth.py` | Handles user authentication (login, signup, token validation) |
+| `chat.py` | Core routes for LLM-backed chat, reply-to-advisor, and multi-turn flow |
+| `chat_sessions.py` | Stores user conversations and provides access to saved history |
+| `debug.py` | Developer tools: debug personas, RAG tests, ranking advisor responses |
+| `documents.py` | Upload, parse, index, and query documents via RAG |
+| `provider.py` | Switch between Gemini and Ollama providers |
+| `root.py` | Root `/` endpoint for heartbeat and versioning |
+| `sessions.py` | Tracks and resets session-specific in-memory context |
+| `utils.py` | Helpers used by multiple routers (e.g. session ID management) |
+
+---
+
+## `auth.py` – User Authentication API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/signup` | `POST` | Register a new user |
+| `/login` | `POST` | Authenticate user and return access token |
+| `/me` | `GET` | Return current logged-in user |
+| `/healthcheck` | `GET` | Ping endpoint to check login status |
+
+Uses JWT-based Bearer token auth via FastAPI dependencies.
+
+---
+
+## `chat.py` – Chat Interaction
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/chat-stream` | `POST` | Stream advisor responses as newline-delimited JSON |
+| `/reply-to-advisor` | `POST` | Ask a question to a specific advisor/persona |
+
+These routes handle:
+- Message routing via `ImprovedChatOrchestrator`
+- Persona-wise response generation
+- Embedding document-aware context
+- Returning consistent message structure
+
+---
+
+## `chat_sessions.py` – Persistent Storage of Conversations
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/chat-sessions` | `GET` | List all saved chat sessions |
+| `/chat-sessions/{id}` | `GET` | Retrieve specific chat session |
+| `/chat-sessions/{id}` | `DELETE` | Soft-delete a chat session |
+| `/chat-sessions/save` | `POST` | Save in-memory session to MongoDB |
+
+Saves message history, metadata, and uploaded files.
+
+---
+
+## `debug.py` – Developer Tools
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/debug/personas` | `GET` | List current personas, prompts, keywords |
+| `/debug/ranked-personas` | `GET` | Return top advisors for current session |
+| `/debug/rag-status` | `GET` | Run sample RAG query + return health info |
+
+Provides insight into:
+- Persona prompt preview
+- RAG test queries and indexed documents
+- Session size + truncation status
+
+---
+
+## `documents.py` – Document Upload and RAG
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/upload-document` | `POST` | Upload and parse a document for semantic search |
+| `/search-documents` | `POST` | RAG search using text query and persona context |
+| `/document-stats` | `GET` | Overview of documents uploaded to session |
+| `/uploaded-files` | `GET` | Return list of uploaded file names |
+| `/document-insights/{filename}` | `GET` | Get detailed metadata for a document |
+| `/export-chat` | `GET` | Export current or stored chat session (PDF, TXT, DOCX) |
+| `/chat-summary` | `GET` | Export summary generated by LLM (multi-format) |
+
+Supports file parsing (`PDF`, `DOCX`, `TXT`), chunking, embedding, and export.
+
+---
+
+## `provider.py` – LLM Provider Control
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/current-provider` | `GET` | Return currently active provider and model |
+| `/switch-provider` | `POST` | Dynamically switch between `gemini` and `ollama` |
+| `/current-model` | `GET` | Get currently loaded model name |
+| `/switch-model` | `POST` | Alias for switching based on model name |
+
+Changes are propagated by:
+- Creating new LLM client
+- Re-registering all personas
+
+---
+
+## `sessions.py` – In-Memory Session Management
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/context` | `GET` | Return current session context (messages, documents, stats) |
+| `/reset-session` | `POST` | Reset in-memory session or specific chat context |
+| `/session-stats` | `GET` | Return stats like message count, file size, timestamps |
+| `/active-sessions` | `GET` | Return list of all active in-memory sessions |
+| `/cleanup-sessions` | `POST` | Manually trigger expired session cleanup |
+
+Supports ephemeral sessions and reusable chat contexts (e.g. for documents).
+
+---
+
+## `utils.py` – Route-Level Utilities
+
+Defines shared helper:
+
+- `get_or_create_session_for_request(request)`  
+- `get_or_create_session_for_request_async(request)`  
+
+These parse session cookies or generate new session IDs, crucial for maintaining separation across:
+- In-memory ephemeral sessions
+- Document-linked long-term sessions
+
+---
+
+## `root.py` – API Healthcheck
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | `GET` | Return version + feature list |
+
+Simple heartbeat endpoint used for readiness probes and sanity checks.
+
+---
+
+## Auth Flow Integration
+
+Most routes use:
+
+```python
+Depends(get_current_active_user)
+```
+
+This ensures only logged-in users can:
+- Upload and retrieve files
+- Export summaries
+- Save or delete chat sessions
+
+JWT tokens are passed via the `Authorization: Bearer ...` header.
+
+---
+
+## High-Level Flow
+
+```text
+Frontend → /chat-stream → orchestrator → personas → RAG + LLM → response[]
+        ↘ /upload-document → extractor → RAG chunks → indexed
+        ↘ /context or /reset-session → session_manager
+        ↘ /export-chat or /chat-summary → utils + formatter
+```
+
+---

multi_llm_chatbot_backend/app/api/old_routes.py

@@ -0,0 +1,1001 @@
+import os
+from fastapi import APIRouter, Body, HTTPException, Header, UploadFile, File, Request
+from fastapi import Query
+from typing import Optional, List
+import httpx
+from app.llm.llm_client import LLMClient
+from app.llm.improved_gemini_client import ImprovedGeminiClient
+from app.llm.improved_ollama_client import ImprovedOllamaClient
+from app.models.persona import Persona
+from app.core.improved_orchestrator import ImprovedChatOrchestrator
+from app.core.session_manager import get_session_manager
+from app.core.rag_manager import get_rag_manager
+from app.models.default_personas import get_default_personas
+from app.utils.document_extractor import extract_text_from_file
+from app.utils.file_limits import is_within_upload_limit
+from pydantic import BaseModel
+
+from fastapi.responses import StreamingResponse
+from fastapi import Query
+from app.utils.file_export import export_chat_as_file
+
+from app.utils.chat_summary import generate_summary_from_messages, parse_summary_to_blocks
+from app.utils.file_export import prepare_export_response, generate_pdf_file_from_blocks
+from app.version import __version__
+
+import hashlib
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# Provider management (same as before)
+current_provider = "gemini"
+available_providers = ["ollama", "gemini"]
+
+def create_llm_client(provider: str = None) -> LLMClient:
+    """Create LLM client based on provider"""
+    if provider is None:
+        provider = current_provider
+        
+    if provider == "gemini":
+        try:
+            return ImprovedGeminiClient(model_name=os.getenv("GEMINI_MODEL"))
+        except ValueError as e:
+            logger.warning(f"Gemini API key not found, falling back to Ollama: {e}")
+            return ImprovedOllamaClient(model_name="llama3.2:1b")
+    elif provider == "ollama":
+        return ImprovedOllamaClient(model_name="llama3.2:1b")
+    else:
+        raise ValueError(f"Unknown provider: {provider}")
+
+# Initialize with default provider
+llm = create_llm_client()
+chat_orchestrator = ImprovedChatOrchestrator()
+session_manager = get_session_manager()
+
+# Initialize personas
+DEFAULT_PERSONAS = get_default_personas(llm)
+for persona in DEFAULT_PERSONAS:
+    chat_orchestrator.register_persona(persona)
+
+# Keep all the same data models as before
+class UserInput(BaseModel):
+    user_input: str
+
+class PersonaInput(BaseModel):
+    id: str
+    name: str
+    system_prompt: str
+
+class ChatMessage(BaseModel):
+    user_input: str
+    session_id: Optional[str] = None
+    response_length: Optional[str] = "medium"
+
+class ReplyToAdvisor(BaseModel):
+    user_input: str
+    advisor_id: str
+    original_message_id: Optional[str] = None
+
+class ProviderSwitch(BaseModel):
+    provider: str
+
+# ==============================================================
+# SESSION MANAGEMENT COMPATIBILITY LAYER
+# ==============================================================
+
+def get_or_create_session_for_request(request: Request, 
+                                    session_id_override: Optional[str] = None) -> str:
+    """
+    Get or create session for request using multiple strategies:
+    1. Use provided session_id if given
+    2. Use X-Session-ID header if present  
+    3. Use client IP as fallback for backward compatibility
+    4. Create new session if nothing available
+    
+    This allows the old stateless API to work with session management
+    """
+    # Strategy 1: Explicit session ID (for new clients)
+    if session_id_override:
+        return session_id_override
+    
+    # Strategy 2: Check for session header (optional for frontend)
+    session_header = request.headers.get("X-Session-ID")
+    if session_header:
+        return session_header
+    
+    # Strategy 3: Use client IP for backward compatibility
+    # This gives each client IP their own persistent session
+    client_ip = request.client.host if request.client else "unknown"
+    ip_session_id = f"ip_{client_ip}"
+    
+    # Get or create session for this IP
+    session = session_manager.get_session(ip_session_id)
+    return session.session_id
+
+
+
+# Helper functions (same as before)
+def _is_valid_response(response: str, persona_id: str) -> bool:
+    """Validate response quality"""
+    if len(response) < 2 or len(response) > 5000:
+        return False
+    
+    confusion_indicators = [
+        f"Thank you, Dr. {persona_id.title()}",
+        "Assistant:",
+        f"Dr. {persona_id.title()}",
+        "Assistant:",
+        f"Dr. {persona_id.title()} Advisor:",
+        "excellent discussion, Assistant"
+    ]
+    
+    return not any(indicator in response for indicator in confusion_indicators)
+
+def _get_persona_fallback(persona_id: str) -> str:
+    """Get persona-specific fallback responses"""
+    fallbacks = {
+        "methodologist": "Focus on ensuring your methodology aligns with your research question. What specific method are you considering?",
+        "theorist": "Consider the theoretical framework underlying your approach. What assumptions guide your thinking?",
+        "pragmatist": "Let's break this down into actionable steps. What's the most important thing you need to decide today?"
+    }
+    return fallbacks.get(persona_id, "I'd be happy to help. Could you provide more details?")
+
+# Provider management endpoints (EXACTLY THE SAME)
+@router.get("/current-provider")
+async def get_current_provider():
+    return {
+        "current_provider": current_provider,
+        "available_providers": available_providers,
+        "model_info": {
+            "name": llm.model_name if hasattr(llm, 'model_name') else "gemini-2.0-flash",
+            "provider": current_provider
+        }
+    }
+
+@router.post("/switch-provider")
+async def switch_provider(provider_data: ProviderSwitch):
+    global current_provider, llm
+    
+    if provider_data.provider not in available_providers:
+        raise HTTPException(
+            status_code=400, 
+            detail=f"Unknown provider: {provider_data.provider}. Available: {available_providers}"
+        )
+    
+    try:
+        current_provider = provider_data.provider
+        new_llm = create_llm_client(current_provider)
+        llm = new_llm
+        
+        new_personas = get_default_personas(new_llm)
+        chat_orchestrator.personas.clear()
+        for persona in new_personas:
+            chat_orchestrator.register_persona(persona)
+        
+        return {
+            "message": f"Successfully switched to {current_provider}",
+            "current_provider": current_provider,
+            "model_info": {
+                "name": new_llm.model_name if hasattr(new_llm, 'model_name') else "gemini-2.0-flash",
+                "provider": current_provider
+            }
+        }
+        
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to switch to {provider_data.provider}: {str(e)}"
+        )
+
+# Main chat endpoint
+@router.post("/chat-sequential")
+async def chat_sequential_enhanced(message: ChatMessage, request: Request):
+    """
+    Enhanced sequential chat with intelligent persona ordering.
+    Returns responses in the order determined by LLM-based relevance ranking.
+    """
+    try:
+        # Get or create session
+        session_id = get_or_create_session_for_request(request, message.session_id)
+        
+        # Add user message to session first (needed for persona ranking)
+        session = session_manager.get_session(session_id)
+        session.append_message("user", message.user_input)
+        
+        # Get intelligently ordered personas based on context
+        top_personas = await chat_orchestrator.get_top_personas(
+            session_id=session_id, 
+            k=3  # Get top 3 most relevant personas
+        )
+        
+        logger.info(f"Intelligent persona order for session {session_id}: {top_personas}")
+        
+        # Generate responses from personas in the intelligent order
+        responses = []
+        
+        for persona_id in top_personas:
+            try:
+                # Generate response from this persona
+                persona_result = await chat_orchestrator.chat_with_persona(
+                    user_input=message.user_input,
+                    persona_id=persona_id,
+                    session_id=session_id,
+                    response_length=message.response_length or "medium"
+                )
+                
+                
+                if "persona_name" in persona_result and "response" in persona_result:
+                    responses.append({
+                        "persona": persona_result["persona_name"],
+                        "persona_id": persona_result["persona_id"],
+                        "response": persona_result["response"]
+                    })
+                elif persona_result.get("type") == "single_persona_response" and "persona" in persona_result:
+                    persona_data = persona_result["persona"]
+                    responses.append({
+                        "persona": persona_data["persona_name"],
+                        "persona_id": persona_data["persona_id"],
+                        "response": persona_data["response"]
+                    })
+                else:
+                    # Fallback response
+                    responses.append({
+                        "persona": chat_orchestrator.personas[persona_id].name,
+                        "persona_id": persona_id,
+                        "response": "I'm having trouble processing your question right now. Please try again."
+                    })
+                    
+            except Exception as e:
+                logger.error(f"Error generating response for persona {persona_id}: {str(e)}")
+                # Error fallback
+                responses.append({
+                    "persona": chat_orchestrator.personas[persona_id].name,
+                    "persona_id": persona_id,
+                    "response": "I encountered an error while processing your question. Please try again."
+                })
+        
+        #  response format
+        return {
+            "type": "sequential_responses",
+            "responses": responses
+        }
+
+    except Exception as e:
+        logger.error(f"Error in enhanced sequential chat: {str(e)}")
+        return {
+            "type": "error", 
+            "responses": [{
+                "persona": "System",
+                "response": "I'm having trouble processing your request. Could you please try again?"
+            }]
+        }
+
+@router.post("/chat/{persona_id}")
+async def chat_with_specific_advisor(persona_id: str, input: UserInput, request: Request):
+    """Chat with a specific advisor - SAME INTERFACE"""
+    try:
+        if persona_id not in chat_orchestrator.personas:
+            raise HTTPException(status_code=404, detail=f"Persona '{persona_id}' not found")
+
+        # Get session using compatibility layer
+        session_id = get_or_create_session_for_request(request)
+        
+        # Use new orchestrator
+        result = await chat_orchestrator.chat_with_persona(
+            user_input=input.user_input,
+            persona_id=persona_id,
+            session_id=session_id
+        )
+        
+        # FIX: Handle the actual response structure from orchestrator
+        if result.get("type") == "single_persona_response" and "persona" in result:
+            # New expected structure
+            persona_data = result["persona"]
+            return {
+                "persona": persona_data["persona_name"],
+                "persona_id": persona_data["persona_id"],
+                "response": persona_data["response"]
+            }
+        elif "persona_id" in result and "response" in result:
+            # Current actual structure from orchestrator
+            return {
+                "persona": result["persona_name"],
+                "persona_id": result["persona_id"],
+                "response": result["response"]
+            }
+        elif result.get("type") == "error" or "error" in result:
+            # Error handling
+            return {
+                "persona": "System",
+                "response": result.get("error", "I'm having trouble generating a response right now. Please try again.")
+            }
+        else:
+            # Fallback
+            return {
+                "persona": "System",
+                "response": "I'm having trouble generating a response right now. Please try again."
+            }
+            
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in chat_with_specific_advisor: {e}")
+        return {
+            "persona": "System",
+            "response": "I'm having trouble generating a response right now. Please try again."
+        }
+
+# Reply to advisor endpoint (SAME INTERFACE)
+@router.post("/reply-to-advisor")
+async def reply_to_advisor(reply: ReplyToAdvisor, request: Request):
+    """Reply to a specific advisor - SAME INTERFACE"""
+    try:
+        if reply.advisor_id not in chat_orchestrator.personas:
+            raise HTTPException(status_code=404, detail=f"Advisor '{reply.advisor_id}' not found")
+
+        # Get session using compatibility layer
+        session_id = get_or_create_session_for_request(request)
+        
+        # Use new orchestrator
+        result = await chat_orchestrator.chat_with_persona(
+            user_input=reply.user_input,
+            persona_id=reply.advisor_id,
+            session_id=session_id
+        )
+        
+        if result["type"] == "single_persona_response":
+            persona_data = result["persona"]
+            return {
+                "type": "advisor_reply",
+                "persona": persona_data["persona_name"],
+                "persona_id": persona_data["persona_id"],
+                "response": persona_data["response"],
+                "original_message_id": reply.original_message_id
+            }
+        else:
+            return {
+                "type": "error",
+                "persona": "System",
+                "response": result.get("message", "I'm having trouble generating a reply right now. Please try again.")
+            }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in reply_to_advisor: {e}")
+        return {
+            "type": "error",
+            "persona": "System",
+            "response": "I'm having trouble generating a reply right now. Please try again."
+        }
+
+@router.post("/upload-document")
+async def upload_document(file: UploadFile = File(...), request: Request = None):
+    """
+    Enhanced document upload with better metadata tracking and user feedback
+    """
+    try:
+        # Get or create session
+        session_id = get_or_create_session_for_request(request)
+        session = session_manager.get_session(session_id)
+        
+        # Validate file
+        MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
+        if file.size and file.size > MAX_FILE_SIZE:
+            raise HTTPException(status_code=413, detail="File size exceeds 10MB limit")
+
+        
+        # Read and validate file content
+        file_bytes = await file.read()
+        content = extract_text_from_file(file_bytes, file.content_type)
+        if not content.strip():
+            raise HTTPException(status_code=400, detail="Document is empty or unreadable.")
+
+        # Get enhanced RAG manager
+        rag_manager = get_rag_manager()
+        
+        # Determine file type for metadata
+        file_type_map = {
+            "application/pdf": "pdf",
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx", 
+            "text/plain": "txt"
+        }
+        file_type = file_type_map.get(file.content_type, "unknown")
+        
+        # Add document to enhanced vector database
+        rag_result = rag_manager.add_document(
+            content=content,
+            filename=file.filename,
+            session_id=session_id,
+            file_type=file_type
+        )
+        
+        if not rag_result["success"]:
+            raise HTTPException(
+                status_code=500, 
+                detail=f"Failed to process document: {rag_result.get('error', 'Unknown error')}"
+            )
+        
+        # Update session tracking
+        session.uploaded_files.append(file.filename)
+        session.total_upload_size += len(file_bytes)
+        
+        # Add enhanced document reference to session messages
+        doc_metadata = rag_result.get("document_metadata", {})
+        doc_title = doc_metadata.get("title", file.filename)
+        
+        session.append_message(
+            "system", 
+            f"Document uploaded: '{doc_title}' ({file.filename}) - "
+            f"{rag_result['chunks_created']} sections processed, "
+            f"~{rag_result['total_tokens']} tokens analyzed. "
+            f"You can now ask questions about this document by referencing it by name."
+        )
+
+        return {
+            "message": f"Document '{file.filename}' uploaded and processed successfully.",
+            "filename": file.filename,
+            "document_title": doc_title,
+            "chunks_created": rag_result['chunks_created'],
+            "total_tokens": rag_result['total_tokens'],
+            "file_type": file_type,
+            "can_reference_by_name": True,
+            "suggestions": [
+                f"Try asking: 'What methodology does my {file.filename} propose?'",
+                f"Or: 'What are the key findings in {doc_title}?'",
+                f"Or: 'Compare the approach in my document with current best practices'"
+            ]
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error processing document upload: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Error processing document: {str(e)}")
+
+    
+@router.get("/export-chat")
+async def export_chat(request: Request, format: str = Query(..., regex="^(txt|pdf|docx)$")):
+    """
+    Export the current chat context in the requested format.
+    """
+    try:
+        session_id = get_or_create_session_for_request(request)
+        session = session_manager.get_session(session_id)
+
+        if not session.messages:
+            return {"error": "No messages in this session."}
+
+        return prepare_export_response(session.messages, format)
+
+    except Exception as e:
+        logger.error(f"Error exporting chat: {str(e)}")
+        return {"error": "Failed to export chat.", "detail": str(e)}
+    
+    
+@router.get("/chat-summary")
+async def chat_summary(
+    request: Request,
+    format: str = Query("text", regex="^(txt|pdf|docx)$")
+):
+    """
+    Generate and return a summary of the current session chat.
+    Can return as plain txt, PDF, or DOCX.
+    """
+    try:
+        session_id = get_or_create_session_for_request(request)
+        session = session_manager.get_session(session_id)
+
+        if not session.messages:
+            return {"error": "No messages in this session."}
+
+        llm = next(iter(chat_orchestrator.personas.values())).llm
+        summary_text = await generate_summary_from_messages(session.messages, llm)
+
+        if format == "txt":
+            return prepare_export_response(summary_text, "txt", filename_prefix="chat_summary")
+
+        elif format == "docx":
+            return prepare_export_response(summary_text, "docx", filename_prefix="chat_summary")
+
+        elif format == "pdf":
+            # Parse and render using block formatting
+            blocks = [{"type": "heading", "text": "Chat Summary"}] + parse_summary_to_blocks(summary_text)
+
+            file_stream = generate_pdf_file_from_blocks(blocks)
+            return StreamingResponse(
+                file_stream,
+                media_type="application/pdf",
+                headers={"Content-Disposition": "attachment; filename=chat_summary.pdf"}
+            )
+
+    except Exception as e:
+        logger.error(f"Error in chat-summary endpoint: {str(e)}")
+        return {"error": "Summary generation failed", "detail": str(e)}
+
+
+
+
+# Add new endpoint to get document statistics
+@router.get("/document-stats")
+async def get_document_stats(request: Request):
+    """Get statistics about uploaded documents in vector database"""
+    try:
+        session_id = get_or_create_session_for_request(request)
+        rag_manager = get_rag_manager()
+        
+        stats = rag_manager.get_document_stats(session_id)
+        return stats
+        
+    except Exception as e:
+        logger.error(f"Error getting document stats: {str(e)}")
+        return {"total_chunks": 0, "total_documents": 0, "documents": []}
+
+# Get uploaded files (SAME INTERFACE)
+@router.get("/uploaded-files")
+async def get_uploaded_filenames(request: Request):
+    """Get uploaded files - SAME INTERFACE"""
+    try:
+        session_id = get_or_create_session_for_request(request)
+        session = session_manager.get_session(session_id)
+        return {"files": session.uploaded_files}
+    except Exception as e:
+        logger.error(f"Error getting uploaded files: {str(e)}")
+        return {"files": []}
+
+# Context endpoint (SAME INTERFACE)
+@router.get("/context")
+async def get_context(request: Request):
+    """Get context - ENHANCED with RAG information"""
+    try:
+        session_id = get_or_create_session_for_request(request)
+        session = session_manager.get_session(session_id)
+
+        # Get RAG statistics
+        rag_stats = session.get_rag_stats()
+        
+        return {
+            "messages": session.messages,
+            "rag_info": {
+                "total_documents": rag_stats.get("total_documents", 0),
+                "total_chunks": rag_stats.get("total_chunks", 0),
+                "documents": rag_stats.get("documents", [])
+            }
+        }
+    except Exception as e:
+        logger.error(f"Error getting context: {str(e)}")
+        return {"messages": [], "rag_info": {"total_documents": 0, "total_chunks": 0}}
+
+@router.post("/reset-session")
+async def reset_session(request: Request):
+    """Reset session - ENHANCED with RAG cleanup"""
+    try:
+        session_id = get_or_create_session_for_request(request)
+        
+        # Use the enhanced reset that clears both conversation and vector DB
+        success = session_manager.reset_session_completely(session_id)
+        
+        if success:
+            return {"status": "reset", "message": "Session and all documents reset successfully"}
+        else:
+            return {"status": "error", "message": "Failed to reset session"}
+    except Exception as e:
+        logger.error(f"Error resetting session: {e}")
+        return {"status": "error", "message": "Failed to reset session"}
+
+
+# Legacy model endpoints (SAME INTERFACE)
+@router.post("/switch-model")
+async def switch_model(model_name: str = Body(...)):
+    """Legacy model switching - SAME INTERFACE"""
+    if "gemini" in model_name.lower():
+        return await switch_provider(ProviderSwitch(provider="gemini"))
+    else:
+        return await switch_provider(ProviderSwitch(provider="ollama"))
+
+@router.get("/current-model")
+async def get_current_model():
+    """Legacy model info - SAME INTERFACE"""
+    model_name = llm.model_name if hasattr(llm, 'model_name') else "gemini-2.0-flash"
+    return {
+        "model": model_name,
+        "provider": current_provider
+    }
+
+@router.post("/search-documents")
+async def search_documents(request: Request, query: str = Body(..., embed=True), persona: str = Body("", embed=True)):
+    """
+    Search uploaded documents using RAG
+    
+    This endpoint allows direct document search for debugging/testing
+    """
+    try:
+        session_id = get_or_create_session_for_request(request)
+        rag_manager = get_rag_manager()
+        
+        # Get persona context for search enhancement
+        persona_contexts = {
+            "methodologist": "methodology research design analysis",
+            "theorist": "theory theoretical framework conceptual",
+            "pragmatist": "practical application implementation"
+        }
+        persona_context = persona_contexts.get(persona, "")
+        
+        # Search documents
+        results = rag_manager.search_documents(
+            query=query,
+            session_id=session_id,
+            persona_context=persona_context,
+            n_results=5
+        )
+        
+        return {
+            "query": query,
+            "persona_filter": persona,
+            "results_count": len(results),
+            "results": results
+        }
+        
+    except Exception as e:
+        logger.error(f"Error searching documents: {str(e)}")
+        return {"query": query, "results_count": 0, "results": [], "error": str(e)}
+
+@router.get("/session-stats")
+async def get_session_stats(request: Request):
+    """Get comprehensive session statistics including RAG data"""
+    try:
+        session_id = get_or_create_session_for_request(request)
+        stats = session_manager.get_session_stats(session_id)
+        return stats
+    except Exception as e:
+        logger.error(f"Error getting session stats: {str(e)}")
+        return {"error": str(e)}
+
+
+@router.get("/debug/personas")
+async def debug_personas(request: Request):
+    """Debug personas - ENHANCED with RAG information"""
+    try:
+        session_id = get_or_create_session_for_request(request)
+        session = session_manager.get_session(session_id)
+        
+        # Get RAG statistics
+        rag_manager = get_rag_manager()
+        rag_stats = rag_manager.get_document_stats(session_id)
+        
+        return {
+            "personas": {
+                pid: {
+                    "name": persona.name,
+                    "prompt": persona.system_prompt[:100] + "...",
+                    "retrieval_keywords": chat_orchestrator._get_persona_context_keywords(pid)
+                } for pid, persona in chat_orchestrator.personas.items()
+            },
+            "session_info": {
+                "context_length": len(session.messages),
+                "uploaded_files": session.uploaded_files,
+                "rag_stats": rag_stats
+            },
+            "current_provider": current_provider,
+            "rag_enabled": True
+        }
+    except Exception as e:
+        logger.error(f"Error in debug endpoint: {str(e)}")
+        return {
+            "personas": {},
+            "session_info": {"context_length": 0},
+            "current_provider": current_provider,
+            "rag_enabled": False,
+            "error": str(e)
+        }
+
+@router.get("/debug/ranked-personas")
+async def get_ranked_personas(request: Request, k: int = Query(3, ge=1, le=10)):
+    """
+    Debug endpoint: Get top-k ranked personas based on current session context.
+    Uses LLM to rank based on latest conversation messages.
+    """
+    try:
+        session_id = get_or_create_session_for_request(request)
+        
+        # Call the ranking method
+        top_personas = await chat_orchestrator.get_top_personas(session_id=session_id, k=k)
+        
+        # Include some metadata for debug purposes
+        return {
+            "ranked_personas": top_personas,
+            "available_personas": list(chat_orchestrator.personas.keys()),
+            "session_id": session_id
+        }
+    except Exception as e:
+        logger.error(f"Error in /debug/ranked-personas: {e}")
+        return {
+            "ranked_personas": [],
+            "error": str(e)
+        }
+
+
+@router.post("/chat/{persona_id}")
+async def chat_with_specific_persona(persona_id: str, message: ChatMessage, request: Request):
+    """
+    Chat with a specific persona - Enhanced with RAG debugging
+    
+    This endpoint helps debug RAG integration by testing individual personas
+    """
+    try:
+        session_id = get_or_create_session_for_request(request, message.session_id)
+        
+        # Validate persona exists
+        if persona_id not in chat_orchestrator.personas:
+            available_personas = list(chat_orchestrator.personas.keys())
+            raise HTTPException(
+                status_code=400, 
+                detail=f"Persona '{persona_id}' not found. Available: {available_personas}"
+            )
+        
+        # Use the enhanced orchestrator method
+        result = await chat_orchestrator.chat_with_persona(
+            user_input=message.user_input,
+            persona_id=persona_id,
+            session_id=session_id,
+            response_length=message.response_length or "medium"
+        )
+        
+        # Fix: Handle the response structure properly
+        if result.get("type") == "single_persona_response" and "persona" in result:
+            persona_data = result["persona"]
+            
+            # Add debugging information
+            result["debug_info"] = {
+                "persona_id": persona_id,
+                "session_id": session_id,
+                "query_length": len(message.user_input),
+                "rag_manager_available": True,
+                "used_documents": persona_data.get("used_documents", False),
+                "chunks_used": persona_data.get("document_chunks_used", 0)
+            }
+        
+        return result
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in individual persona chat: {str(e)}")
+        return {
+            "type": "error",
+            "message": f"Error chatting with {persona_id}: {str(e)}",
+            "persona_id": persona_id
+        }
+    
+@router.get("/debug/enhanced-personas")
+async def debug_enhanced_personas(request: Request):
+    """
+    Enhanced debug endpoint with document context information
+    """
+    try:
+        session_id = get_or_create_session_for_request(request)
+        session = session_manager.get_session(session_id)
+        
+        # Get enhanced RAG statistics
+        rag_manager = get_rag_manager()
+        rag_stats = rag_manager.get_document_stats(session_id)
+        
+        # Analyze document awareness capabilities
+        document_analysis = {}
+        if rag_stats.get("documents"):
+            for doc in rag_stats["documents"]:
+                document_analysis[doc["filename"]] = {
+                    "chunks_available": doc["chunks"],
+                    "estimated_tokens": doc["estimated_tokens"],
+                    "sections_identified": doc["sections"],
+                    "content_types_detected": {
+                        "has_methodology": doc.get("has_methodology", False),
+                        "has_theory": doc.get("has_theory", False),
+                        "has_references": doc.get("has_references", False)
+                    }
+                }
+        
+        return {
+            "personas": {
+                pid: {
+                    "name": persona.name,
+                    "expertise_area": persona.name.split(" - ")[1] if " - " in persona.name else "General",
+                    "prompt_quality": "enhanced" if len(persona.system_prompt) > 500 else "basic",
+                    "document_handling_enabled": "document awareness" in persona.system_prompt.lower(),
+                    "retrieval_keywords": chat_orchestrator._get_enhanced_persona_context_keywords(pid)[:100] + "...",
+                    "temperature": getattr(persona, 'temperature', 5)
+                } for pid, persona in chat_orchestrator.personas.items()
+            },
+            "session_info": {
+                "context_length": len(session.messages),
+                "uploaded_files": session.uploaded_files,
+                "rag_stats": rag_stats,
+                "document_analysis": document_analysis
+            },
+            "system_capabilities": {
+                "document_name_recognition": True,
+                "cross_document_analysis": True,
+                "persona_specialized_retrieval": True,
+                "enhanced_attribution": True,
+                "query_document_detection": True
+            },
+            "current_provider": current_provider,
+            "rag_enabled": True,
+            "enhancement_level": "advanced"
+        }
+    except Exception as e:
+        logger.error(f"Error in enhanced debug endpoint: {str(e)}")
+        return {
+            "error": str(e),
+            "enhancement_level": "error",
+            "rag_enabled": False
+        }
+
+@router.get("/document-insights/{filename}")
+async def get_document_insights(filename: str, request: Request):
+    """
+    NEW ENDPOINT: Get insights about a specific uploaded document
+    """
+    try:
+        session_id = get_or_create_session_for_request(request)
+        rag_manager = get_rag_manager()
+        
+        # Get document statistics
+        stats = rag_manager.get_document_stats(session_id)
+        
+        # Find the specific document
+        document_info = None
+        for doc in stats.get("documents", []):
+            if doc["filename"] == filename:
+                document_info = doc
+                break
+        
+        if not document_info:
+            raise HTTPException(status_code=404, detail=f"Document {filename} not found")
+        
+        # Get a sample of content from this document
+        results = rag_manager.collection.get(
+            where={"session_id": session_id, "filename": filename},
+            limit=3,
+            include=["documents", "metadatas"]
+        )
+        
+        sample_sections = []
+        if results["documents"]:
+            for doc, metadata in zip(results["documents"], results["metadatas"]):
+                sample_sections.append({
+                    "section": metadata.get("document_section", "unknown"),
+                    "content_preview": doc[:200] + "..." if len(doc) > 200 else doc,
+                    "keywords": metadata.get("keywords", "")
+                })
+        
+        return {
+            "filename": filename,
+            "document_title": document_info.get("title", filename),
+            "file_type": document_info.get("file_type", "unknown"),
+            "statistics": {
+                "total_chunks": document_info["chunks"],
+                "estimated_tokens": document_info["estimated_tokens"],
+                "sections_identified": document_info["sections"]
+            },
+            "content_analysis": {
+                "has_methodology": document_info.get("has_methodology", False),
+                "has_theory": document_info.get("has_theory", False), 
+                "has_references": document_info.get("has_references", False)
+            },
+            "sample_sections": sample_sections,
+            "suggested_queries": [
+                f"What methodology does my {filename} propose?",
+                f"What are the key theoretical concepts in {filename}?",
+                f"What are the main findings in my {document_info.get('title', filename)}?",
+                f"How can I improve the approach described in {filename}?"
+            ]
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting document insights: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Error analyzing document: {str(e)}")
+
+# Also add a debug endpoint to check RAG status:
+
+@router.get("/debug/rag-status")
+async def debug_rag_status(request: Request):
+    """
+    Debug endpoint to check RAG system status
+    """
+    try:
+        session_id = get_or_create_session_for_request(request)
+        
+        # Get RAG manager
+        rag_manager = get_rag_manager()
+        
+        # Get session stats
+        session_stats = session_manager.get_session_stats(session_id)
+        
+        # Test a simple search
+        test_search = rag_manager.search_documents(
+            query="test methodology research",
+            session_id=session_id,
+            persona_context="",
+            n_results=3
+        )
+        
+        return {
+            "rag_manager_healthy": True,
+            "session_id": session_id,
+            "session_stats": session_stats.get("rag_stats", {}),
+            "test_search_results": len(test_search),
+            "test_search_details": [
+                {
+                    "relevance": chunk.get("relevance_score", 0),
+                    "distance": chunk.get("distance", "unknown"),
+                    "text_length": len(chunk.get("text", "")),
+                    "filename": chunk.get("metadata", {}).get("filename", "unknown")
+                }
+                for chunk in test_search[:3]
+            ],
+            "persona_keywords": {
+                pid: chat_orchestrator._get_persona_context_keywords(pid)
+                for pid in chat_orchestrator.personas.keys()
+            }
+        }
+        
+    except Exception as e:
+        logger.error(f"Error in RAG debug: {str(e)}")
+        return {
+            "rag_manager_healthy": False,
+            "error": str(e),
+            "session_id": session_id if 'session_id' in locals() else "unknown"
+        }
+
+# Ask endpoint (SAME INTERFACE)
+class PersonaQuery(BaseModel):
+    question: str
+    persona: str
+
+@router.post("/ask/")
+async def ask_question(query: PersonaQuery, request: Request):
+    """Ask question - SAME INTERFACE"""
+    try:
+        session_id = get_or_create_session_for_request(request)
+        
+        # Use the new orchestrator
+        result = await chat_orchestrator.chat_with_persona(
+            user_input=query.question,
+            persona_id=query.persona,
+            session_id=session_id
+        )
+        
+        if result["type"] == "single_persona_response":
+            response_text = result["persona"]["response"]
+        else:
+            response_text = result.get("message", "I'm having trouble responding right now.")
+        
+        return {"response": response_text}
+        
+    except Exception as e:
+        logger.error(f"Error in ask endpoint: {str(e)}")
+        return {"response": "I encountered an error. Please try again."}
+    
+
+
+# Root endpoint (SAME INTERFACE)
+@router.get("/")
+def root():
+    """Root endpoint - SAME INTERFACE with updated info"""
+    return {
+        "message": "Multi-LLM PhD Advisor Backend is up and running",
+        "version": __version__,
+        "features": [
+            "Improved Session Management",
+            "Unified Context Handling", 
+            "Ollama Support", 
+            "Gemini API Support", 
+            "Provider Switching"
+        ]
+    }

multi_llm_chatbot_backend/app/api/routes/__init__.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter
+from .chat import router as chat_router
+from .documents import router as document_router
+from .sessions import router as session_router
+from .provider import router as provider_router
+from .debug import router as debug_router
+from .root import router as root_router
+from .phd_canvas import router as canvas_router
+from .voice import router as voice_router
+
+router = APIRouter()
+router.include_router(chat_router)
+router.include_router(document_router)
+router.include_router(session_router)
+router.include_router(provider_router)
+router.include_router(debug_router)
+router.include_router(root_router)
+router.include_router(canvas_router)
+router.include_router(voice_router)

multi_llm_chatbot_backend/app/api/routes/auth.py

@@ -0,0 +1,319 @@
+from fastapi import APIRouter, HTTPException, Depends, status
+from datetime import datetime, timedelta
+from app.models.user import UserCreate, UserLogin, User, Token, UserResponse, UserUpdate
+from pydantic import BaseModel, model_validator
+from typing import Optional
+from app.core.auth import (
+    get_password_hash, 
+    verify_password,
+    authenticate_user, 
+    create_access_token, 
+    get_user_by_email,
+    get_current_active_user,
+    create_user_response,
+    ACCESS_TOKEN_EXPIRE_MINUTES
+)
+from app.core.database import get_database
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class MessageResponse(BaseModel):
+    message: str
+
+
+class ChangePasswordRequest(BaseModel):
+    current_password: str
+    new_password: str
+
+    @model_validator(mode="after")
+    def passwords_must_differ(self):
+        if self.current_password == self.new_password:
+            raise ValueError("New password must be different from the current password")
+        return self
+
+
+class UpdateProfileRequest(BaseModel):
+    first_name: Optional[str] = None
+    last_name: Optional[str] = None
+
+    @model_validator(mode="after")
+    def at_least_one_field(self):
+        if self.first_name is not None:
+            self.first_name = self.first_name.strip() or None
+        if self.last_name is not None:
+            self.last_name = self.last_name.strip() or None
+        if self.first_name is None and self.last_name is None:
+            raise ValueError("At least one field must be provided")
+        return self
+
+
+class DeleteAccountRequest(BaseModel):
+    password: str
+
+
+router = APIRouter()
+
+@router.post("/signup", response_model=Token)
+async def signup(user_data: UserCreate):
+    """
+    Register a new user and return an access token.
+    @param user_data: UserCreate with name, email, password, and optional academic fields
+    @return: Token containing a JWT access token and the created UserResponse
+    """
+    try:
+        db = get_database()
+        
+        # Check if user already exists
+        existing_user = await get_user_by_email(user_data.email)
+        if existing_user:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Email already registered"
+            )
+        
+        # Create new user
+        hashed_password = get_password_hash(user_data.password)
+        user = User(
+            firstName=user_data.firstName,
+            lastName=user_data.lastName,
+            email=user_data.email,
+            hashed_password=hashed_password,
+            academicStage=user_data.academicStage,
+            researchArea=user_data.researchArea,
+            created_at=datetime.utcnow(),
+            is_active=True
+        )
+        
+        # Insert user into database
+        result = await db.users.insert_one(user.dict(by_alias=True))
+        user.id = result.inserted_id
+
+        profile_seed: dict = {
+            "user_id": user.id,
+            "updated_at": datetime.utcnow(),
+        }
+        if user_data.academicStage:
+            profile_seed["knowledge_level"] = user_data.academicStage
+        if user_data.researchArea:
+            profile_seed["timezone"] = user_data.researchArea
+        await db.user_profiles.update_one(
+            {"user_id": user.id},
+            {"$set": profile_seed},
+            upsert=True,
+        )
+        
+        # Create access token
+        access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+        access_token = create_access_token(
+            data={"sub": str(user.id)}, 
+            expires_delta=access_token_expires
+        )
+        
+        return Token(
+            access_token=access_token,
+            token_type="bearer",
+            user=create_user_response(user)
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during signup: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not create user account"
+        )
+
+@router.post("/login", response_model=Token)
+async def login(user_credentials: UserLogin):
+    """
+    Authenticate a user and return an access token.
+    @param user_credentials: UserLogin with email and password
+    @return: Token containing a JWT access token and the authenticated UserResponse
+    """
+    try:
+        # Authenticate user
+        user = await authenticate_user(user_credentials.email, user_credentials.password)
+        if not user:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Incorrect email or password",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        
+        # Update last login time
+        db = get_database()
+        await db.users.update_one(
+            {"_id": user.id},
+            {"$set": {"last_login": datetime.utcnow()}}
+        )
+        user.last_login = datetime.utcnow()
+        
+        # Create access token
+        access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+        access_token = create_access_token(
+            data={"sub": str(user.id)}, 
+            expires_delta=access_token_expires
+        )
+        
+        return Token(
+            access_token=access_token,
+            token_type="bearer",
+            user=create_user_response(user)
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during login: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Login failed"
+        )
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user_profile(current_user: User = Depends(get_current_active_user)):
+    """
+    Retrieve the profile of the currently authenticated user.
+    @param current_user: Authenticated user from dependency injection
+    @return: UserResponse with the user's profile information
+    """
+    return create_user_response(current_user)
+
+@router.post("/logout", response_model=MessageResponse)
+async def logout():
+    """
+    Log out the current user (client should discard the token).
+    @return: MessageResponse with a confirmation message
+    """
+    return MessageResponse(message="Successfully logged out")
+
+@router.post("/verify-token", response_model=UserResponse)
+async def verify_token(current_user: User = Depends(get_current_active_user)):
+    """
+    Validate the caller's JWT and return their profile.
+    @param current_user: Authenticated user from dependency injection
+    @return: UserResponse with the user's profile information
+    """
+    return create_user_response(current_user)
+
+@router.post("/me/password", response_model=MessageResponse)
+async def change_password(
+    body: ChangePasswordRequest,
+    current_user: User = Depends(get_current_active_user),
+):
+    """
+    Change the authenticated user's password.
+    @param body: ChangePasswordRequest with the current and new passwords
+    @param current_user: Authenticated user from dependency injection
+    @return: MessageResponse with a confirmation message
+    """
+    try:
+        if not verify_password(body.current_password, current_user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Current password is incorrect",
+            )
+        if len(body.new_password) < 8:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="New password must be at least 8 characters",
+            )
+        db = get_database()
+        await db.users.update_one(
+            {"_id": current_user.id},
+            {"$set": {"hashed_password": get_password_hash(body.new_password)}},
+        )
+        return MessageResponse(message="Password changed successfully")
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during password change: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not change password"
+        )
+
+@router.patch("/me", response_model=UserResponse)
+async def update_profile(
+    body: UserUpdate,
+    current_user: User = Depends(get_current_active_user),
+):
+    """Update account fields (name, email, avatar, signup preferences)."""
+    try:
+        db = get_database()
+        updates = {k: v for k, v in body.dict().items() if v is not None}
+        if body.firstName is not None:
+            updates["firstName"] = body.firstName.strip()
+        if body.lastName is not None:
+            updates["lastName"] = body.lastName.strip()
+        if not updates:
+            return create_user_response(current_user)
+
+        if "email" in updates and updates["email"] != current_user.email:
+            existing = await get_user_by_email(updates["email"])
+            if existing:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Email already in use",
+                )
+
+        await db.users.update_one({"_id": current_user.id}, {"$set": updates})
+        profile_sync: dict = {"updated_at": datetime.utcnow()}
+        if body.academicStage is not None:
+            profile_sync["knowledge_level"] = body.academicStage
+        if body.researchArea is not None:
+            profile_sync["timezone"] = body.researchArea
+        if len(profile_sync) > 1:
+            await db.user_profiles.update_one(
+                {"user_id": current_user.id},
+                {"$set": profile_sync, "$setOnInsert": {"user_id": current_user.id}},
+                upsert=True,
+            )
+        updated_user = await db.users.find_one({"_id": current_user.id})
+        return create_user_response(User(**updated_user))
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during profile update: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not update profile"
+        )
+
+@router.delete("/me", response_model=MessageResponse)
+async def delete_account(
+    body: DeleteAccountRequest,
+    current_user: User = Depends(get_current_active_user),
+):
+    """
+    Permanently delete the authenticated user's account, all chat sessions, and all PhD Canvas data.
+    @param body: DeleteAccountRequest with the user's password for confirmation
+    @param current_user: Authenticated user from dependency injection
+    @return: MessageResponse with a confirmation message
+    """
+    try:
+        if not verify_password(body.password, current_user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Incorrect password",
+            )
+        db = get_database()
+        uid = current_user.id
+        await db.chat_sessions.delete_many({"user_id": uid})
+        await db.phd_canvases.delete_many({"user_id": uid})
+        await db.users.delete_one({"_id": uid})
+        return MessageResponse(message="Account deleted")
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during account deletion: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not delete account"
+        )

multi_llm_chatbot_backend/app/api/routes/chat.py

@@ -0,0 +1,504 @@
+import asyncio
+import json
+import logging
+import traceback
+from typing import Any, Dict, List, Literal, Optional
+
+from bson import ObjectId
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+from app.api.routes.chat_sessions import persist_message
+from app.api.utils import get_or_create_session_for_request_async, load_chat_session_into_context
+from app.core.auth import get_current_active_user
+from app.core.bootstrap import chat_orchestrator
+from app.core.database import get_database
+from app.core.session_manager import get_session_manager
+from app.models.user import User
+from app.api.routes.user_profile import PROFILE_FIELDS, enrich_profile_from_user
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+session_manager = get_session_manager()
+
+
+async def _attach_user_profile_context(session, user: User) -> None:
+    """Load Mongo profile + signup fields into session for persona prompts."""
+    try:
+        db = get_database()
+        doc = await db.user_profiles.find_one({"user_id": user.id})
+        profile = enrich_profile_from_user(doc, user)
+        parts = []
+        for key in PROFILE_FIELDS:
+            val = profile.get(key)
+            if val:
+                if isinstance(val, list):
+                    val = ", ".join(str(v) for v in val)
+                parts.append(f"{key}: {val}")
+        if parts:
+            session.user_profile_context = "USER SECURITY PROFILE: " + "; ".join(parts)
+    except Exception as prof_err:
+        logger.warning(f"Could not load user profile: {prof_err}")
+
+# Enhanced data models
+class UserInput(BaseModel):
+    user_input: str
+
+class ChatMessage(BaseModel):
+    user_input: str
+    session_id: Optional[str] = None
+    chat_session_id: Optional[str] = None  # MongoDB chat session ID
+    response_length: str = "medium"
+    active_advisors: Optional[List[str]] = None
+
+class ReplyToAdvisor(BaseModel):
+    user_input: str
+    advisor_id: str
+    original_message_id: str = None
+    chat_session_id: Optional[str] = None
+
+class PersonaQuery(BaseModel):
+    question: str
+    persona: str
+
+class SwitchChatRequest(BaseModel):
+    chat_session_id: str
+
+class NewChatRequest(BaseModel):
+    title: Optional[str] = "New Chat"
+
+ChatStreamEventType = Literal["error", "progress", "clarification", "advisor"]
+
+
+class ChatStreamLine(BaseModel):
+    """One NDJSON line from ``/chat-stream``."""
+
+    type: ChatStreamEventType
+    data: Dict[str, Any] = Field(default_factory=dict)
+
+    def to_ndjson(self) -> str:
+        return json.dumps(self.model_dump(mode="json"), ensure_ascii=False) + "\n"
+
+
+@router.post("/chat-stream")
+async def chat_stream(
+    message: ChatMessage,
+    request: Request,
+    current_user: User = Depends(get_current_active_user),
+) -> StreamingResponse:
+    """
+    Streaming chat endpoint (newline-delimited JSON).
+    @param message: ChatMessage containing user input and optional session/chat IDs
+    @param request: FastAPI Request object for session management
+    @param current_user: Authenticated user from dependency injection
+    @return: StreamingResponse that yields ChatStreamLine events as NDJSON
+    """
+
+    async def _event_generator():
+        try:
+            # Load or create the in-memory session
+            if message.chat_session_id:
+                sid = f"chat_{message.chat_session_id}"
+                if sid not in session_manager.sessions:
+                    sid = await get_or_create_session_for_request_async(
+                        request,
+                        chat_session_id=message.chat_session_id,
+                        user_id=str(current_user.id),
+                    )
+                elif len(session_manager.get_session(sid).messages) == 0:
+                    # Cold start / new worker: hydrate from MongoDB before routing
+                    loaded = await load_chat_session_into_context(
+                        message.chat_session_id,
+                        str(current_user.id),
+                    )
+                    if loaded:
+                        sid = loaded
+            else:
+                sid = await get_or_create_session_for_request_async(request)
+
+            session = session_manager.get_session(sid)
+            await _attach_user_profile_context(session, current_user)
+
+            # Append user message to in-memory session and persist to MongoDB
+            session.append_message("user", message.user_input)
+            if message.chat_session_id:
+                await persist_message(message.chat_session_id, {
+                    "id": str(ObjectId()),
+                    "type": "user",
+                    "content": message.user_input,
+                })
+
+            if await chat_orchestrator.needs_clarification_improved(session, message.user_input):
+                clar = await chat_orchestrator.generate_contextual_clarification(message.user_input)
+                yield ChatStreamLine(
+                    type="clarification",
+                    data={
+                        "message": clar["question"],
+                        "suggestions": clar["suggestions"],
+                    },
+                ).to_ndjson()
+                yield ChatStreamLine(
+                    type="progress",
+                    data={"phase": "complete"},
+                ).to_ndjson()
+                return
+
+            # If an enabled tool can handle this query, return its response
+            # directly and skip persona generation.
+            tool_result = await chat_orchestrator.get_tool_response(message.user_input)
+            if tool_result.used_tool:
+                session.append_message("orchestrator", tool_result.text)
+                yield ChatStreamLine(
+                    type="advisor",
+                    data={
+                        "persona_id": "orchestrator",
+                        "persona_name": "Orchestrator",
+                        "content": tool_result.text,
+                        "used_documents": False,
+                        "document_chunks_used": 0,
+                    },
+                ).to_ndjson()
+                yield ChatStreamLine(
+                    type="progress",
+                    data={"phase": "complete"},
+                ).to_ndjson()
+                return
+
+            # Always relevance-rank to the top 3 advisors, scoped to the
+            # user's active-advisor selection (the header dropdown) when one is
+            # provided. The dropdown filters the candidate pool; the LLM
+            # ranking still picks the top 3 from that pool.
+            if message.active_advisors:
+                candidate_ids = [
+                    pid for pid in message.active_advisors
+                    if pid in chat_orchestrator.personas
+                ]
+            else:
+                candidate_ids = list(chat_orchestrator.personas.keys())
+            top_personas = await chat_orchestrator.get_top_personas(
+                session_id=sid,
+                k=3,
+                candidate_ids=candidate_ids,
+            )
+
+            # Tell the client which advisors will respond so it can show
+            # thinking indicators for just those, not the entire active pool.
+            yield ChatStreamLine(
+                type="progress",
+                data={
+                    "phase": "selected",
+                    "selected_advisors": top_personas,
+                },
+            ).to_ndjson()
+
+            done_queue: asyncio.Queue = asyncio.Queue()
+
+            async def _run(pid: str) -> None:
+                try:
+                    persona = chat_orchestrator.get_persona(pid)
+                    result = await chat_orchestrator.generate_single_persona_response(
+                        session, persona,
+                        message.response_length or "medium",
+                    )
+                    session.append_message(pid, result["response"])
+                    await done_queue.put(result)
+                except Exception as e:
+                    logger.exception(f"chat-stream _run failed for {pid}: {e}")
+                    failed_persona = chat_orchestrator.get_persona(pid)
+                    await done_queue.put({
+                        "persona_id": pid,
+                        "persona_name": failed_persona.name if failed_persona else pid,
+                        "response": f"I ran into a technical issue. Please try again. ({e!s})",
+                        "used_documents": False,
+                        "document_chunks_used": 0,
+                    })
+
+            tasks = [asyncio.create_task(_run(pid)) for pid in top_personas]
+
+            for _ in range(len(tasks)):
+                result = await done_queue.get()
+                line = ChatStreamLine(
+                    type="advisor",
+                    data={
+                        "persona_id": result["persona_id"],
+                        "persona_name": result["persona_name"],
+                        "content": result["response"],
+                        "used_documents": result.get("used_documents", False),
+                        "document_chunks_used": result.get("document_chunks_used", 0),
+                    },
+                )
+                yield line.to_ndjson()
+
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+            yield ChatStreamLine(
+                type="progress",
+                data={"phase": "complete"},
+            ).to_ndjson()
+
+        except Exception as exc:
+            logger.error(f"chat-stream error: {exc}")
+            logger.error(traceback.format_exc())
+            yield ChatStreamLine(
+                type="error",
+                data={"detail": str(exc)},
+            ).to_ndjson()
+
+    return StreamingResponse(
+        _event_generator(),
+        media_type="application/x-ndjson",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.post("/switch-chat")
+async def switch_to_chat(
+    request: SwitchChatRequest, 
+    req: Request,
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Switch to an existing chat session and load its context - FIXED VERSION
+    Ensures documents are accessible after switching
+    """
+    try:
+        logger.info(f"Switching to chat session: {request.chat_session_id}")
+        
+        # Load the chat session into memory context with consistent session ID
+        memory_session_id = await get_or_create_session_for_request_async(
+            req, 
+            chat_session_id=request.chat_session_id,
+            user_id=str(current_user.id)
+        )
+        
+        if not memory_session_id:
+            raise HTTPException(status_code=404, detail="Chat session not found")
+        
+        logger.info(f"Loaded chat into memory session: {memory_session_id}")
+        
+        # Get the loaded session
+        session = session_manager.get_session(memory_session_id)
+        
+        # Verify document access after loading
+        rag_stats = session.get_rag_stats()
+        logger.info(f"After switch - Session {memory_session_id} has {rag_stats.get('total_documents', 0)} documents")
+        
+        # Get the original MongoDB chat session to retrieve messages in proper format
+        db = get_database()
+        chat_session = await db.chat_sessions.find_one({
+            "_id": ObjectId(request.chat_session_id),
+            "user_id": current_user.id,
+            "is_active": True
+        })
+        
+        if not chat_session:
+            raise HTTPException(status_code=404, detail="Chat session not found in database")
+        
+        # Return the messages in the original frontend format from MongoDB
+        original_messages = chat_session.get("messages", [])
+        
+        logger.info(f"Switch successful - {len(original_messages)} messages, {rag_stats.get('total_documents', 0)} documents")
+        
+        return {
+            "status": "success",
+            "memory_session_id": memory_session_id,
+            "chat_session_id": request.chat_session_id,
+            "message_count": len(original_messages),
+            "context": {
+                "messages": original_messages,  # Return original format messages
+                "rag_info": rag_stats
+            },
+            # Include document access verification
+            "document_access": {
+                "total_documents": rag_stats.get('total_documents', 0),
+                "total_chunks": rag_stats.get('total_chunks', 0),
+                "documents": rag_stats.get('documents', []),
+                "uploaded_files": session.uploaded_files
+            },
+            "debug_info": {
+                "memory_session_format": memory_session_id,
+                "documents_accessible": rag_stats.get('total_documents', 0) > 0,
+                "session_loaded": memory_session_id in session_manager.sessions
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error switching to chat {request.chat_session_id}: {e}")
+        import traceback
+        logger.error(f"Full traceback: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail="Failed to switch to chat")
+
+@router.post("/new-chat")
+async def create_new_chat(
+    request: NewChatRequest,
+    req: Request,
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Create a new chat with fresh context
+    """
+    try:
+        # Create a completely new session (no chat_session_id means fresh context)
+        memory_session_id = await get_or_create_session_for_request_async(req)
+        
+        # Ensure the session is completely clean
+        session = session_manager.get_session(memory_session_id)
+        session.clear_all_data()  # This clears both messages and documents
+        
+        return {
+            "status": "success",
+            "memory_session_id": memory_session_id,
+            "message": "New chat created with fresh context",
+            "context": {
+                "messages": [],
+                "rag_info": {"total_documents": 0, "total_chunks": 0}
+            }
+        }
+        
+    except Exception as e:
+        logger.error(f"Error creating new chat: {e}")
+        raise HTTPException(status_code=500, detail="Failed to create new chat")
+
+@router.post("/chat/{persona_id}")
+async def chat_with_specific_advisor(persona_id: str, input: UserInput, request: Request):
+    """Chat with a specific advisor - UPDATED"""
+    try:
+        if persona_id not in chat_orchestrator.personas:
+            raise HTTPException(status_code=404, detail=f"Persona '{persona_id}' not found")
+
+        # Use async session management
+        session_id = await get_or_create_session_for_request_async(request)
+        
+        result = await chat_orchestrator.chat_with_persona(
+            user_input=input.user_input,
+            persona_id=persona_id,
+            session_id=session_id
+        )
+        
+        # Handle response structure
+        if result.get("type") == "single_persona_response" and "persona" in result:
+            persona_data = result["persona"]
+            return {
+                "persona": persona_data["persona_name"],
+                "persona_id": persona_data["persona_id"],
+                "response": persona_data["response"]
+            }
+        elif "persona_id" in result and "response" in result:
+            return {
+                "persona": result["persona_name"],
+                "persona_id": result["persona_id"],
+                "response": result["response"]
+            }
+        else:
+            return {
+                "persona": "System",
+                "response": "I'm having trouble generating a response right now. Please try again."
+            }
+            
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in chat_with_specific_advisor: {e}")
+        return {
+            "persona": "System",
+            "response": "I'm having trouble generating a response right now. Please try again."
+        }
+
+@router.post("/reply-to-advisor")
+async def reply_to_advisor(reply: ReplyToAdvisor, request: Request):
+    """Reply to a specific advisor with proper context - UPDATED"""
+    try:
+        if reply.advisor_id not in chat_orchestrator.personas:
+            raise HTTPException(status_code=404, detail=f"Advisor '{reply.advisor_id}' not found")
+
+        # Handle session management for existing chats
+        if reply.chat_session_id:
+            session_id = f"chat_{reply.chat_session_id}"
+        else:
+            session_id = await get_or_create_session_for_request_async(request)
+        
+        session = session_manager.get_session(session_id)
+        
+        # Find the original message being replied to for context
+        original_message = None
+        if reply.original_message_id:
+            for msg in session.messages:
+                if getattr(msg, 'id', None) == reply.original_message_id:
+                    original_message = msg.content
+                    break
+        
+        # Create context-aware input
+        contextual_input = reply.user_input
+        if original_message:
+            contextual_input = f"[Replying to your previous message: '{original_message[:100]}...'] {reply.user_input}"
+        
+        result = await chat_orchestrator.chat_with_persona(
+            user_input=contextual_input,
+            persona_id=reply.advisor_id,
+            session_id=session_id
+        )
+        
+        # Handle response structure
+        if result.get("type") == "single_persona_response" and "persona" in result:
+            persona_data = result["persona"]
+            return {
+                "type": "advisor_reply",
+                "persona": persona_data["persona_name"],
+                "persona_id": persona_data["persona_id"],
+                "response": persona_data["response"],
+                "original_message_id": reply.original_message_id
+            }
+        elif "persona_id" in result and "response" in result:
+            return {
+                "type": "advisor_reply",
+                "persona": result["persona_name"],
+                "persona_id": result["persona_id"],
+                "response": result["response"],
+                "original_message_id": reply.original_message_id
+            }
+        else:
+            return {
+                "type": "error",
+                "persona": "System",
+                "response": "I'm having trouble generating a reply right now. Please try again."
+            }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in reply_to_advisor: {e}")
+        return {
+            "type": "error",
+            "persona": "System",
+            "response": "I'm having trouble generating a reply right now. Please try again."
+        }
+
+@router.post("/ask/")
+async def ask_question(query: PersonaQuery, request: Request):
+    """Ask question - UPDATED"""
+    try:
+        session_id = await get_or_create_session_for_request_async(request)
+        
+        result = await chat_orchestrator.chat_with_persona(
+            user_input=query.question,
+            persona_id=query.persona,
+            session_id=session_id
+        )
+        
+        if result["type"] == "single_persona_response":
+            response_text = result["persona"]["response"]
+        else:
+            response_text = result.get("message", "I'm having trouble responding right now.")
+        
+        return {"response": response_text}
+        
+    except Exception as e:
+        logger.error(f"Error in ask endpoint: {str(e)}")
+        return {"response": "I encountered an error. Please try again."}

multi_llm_chatbot_backend/app/api/routes/chat_sessions.py

@@ -0,0 +1,293 @@
+from fastapi import APIRouter, HTTPException, Depends, status
+from typing import List, Optional
+from datetime import datetime
+from bson import ObjectId
+from app.models.user import User, ChatSession, ChatSessionResponse
+from app.core.auth import get_current_active_user
+from app.core.database import get_database
+from pydantic import BaseModel
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+class CreateChatSessionRequest(BaseModel):
+    title: str
+
+class UpdateChatSessionRequest(BaseModel):
+    title: Optional[str] = None
+    messages: Optional[List[dict]] = None
+
+class SaveMessageRequest(BaseModel):
+    session_id: str
+    message: dict
+
+async def persist_message(session_id: str, message: dict):
+    """Write a single message to a MongoDB chat session."""
+    db = get_database()
+    msg = message.copy()
+    if "timestamp" not in msg:
+        msg["timestamp"] = datetime.utcnow().isoformat()
+    await db.chat_sessions.update_one(
+        {"_id": ObjectId(session_id)},
+        {
+            "$push": {"messages": msg},
+            "$set": {"updated_at": datetime.utcnow()}
+        }
+    )
+
+
+@router.post("/chat-sessions", response_model=dict)
+async def create_chat_session(
+    request: CreateChatSessionRequest,
+    current_user: User = Depends(get_current_active_user)
+):
+    """Create a new chat session for the user"""
+    try:
+        db = get_database()
+        
+        session = ChatSession(
+            user_id=current_user.id,
+            title=request.title,
+            messages=[],
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow()
+        )
+        
+        result = await db.chat_sessions.insert_one(session.dict(by_alias=True))
+        session.id = result.inserted_id
+        
+        return {
+            "id": str(session.id),
+            "title": session.title,
+            "created_at": session.created_at,
+            "updated_at": session.updated_at,
+            "message_count": 0
+        }
+        
+    except Exception as e:
+        logger.error(f"Error creating chat session: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not create chat session"
+        )
+
+
+@router.get("/chat-sessions", response_model=List[ChatSessionResponse])
+async def get_user_chat_sessions(
+    current_user: User = Depends(get_current_active_user),
+    limit: int = 50,
+    skip: int = 0
+):
+    """Get all chat sessions for the current user"""
+    try:
+        db = get_database()
+        
+        cursor = db.chat_sessions.find(
+            {"user_id": current_user.id, "is_active": True}
+        ).sort("updated_at", -1).skip(skip).limit(limit)
+        
+        sessions = []
+        async for session_data in cursor:
+            sessions.append(ChatSessionResponse(
+                id=str(session_data["_id"]),
+                title=session_data["title"],
+                created_at=session_data["created_at"],
+                updated_at=session_data["updated_at"],
+                message_count=len(session_data.get("messages", []))
+            ))
+        
+        return sessions
+        
+    except Exception as e:
+        logger.error(f"Error fetching chat sessions: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not fetch chat sessions"
+        )
+
+
+
+@router.get("/chat-sessions/count")
+async def get_chat_sessions_count(
+    current_user: User = Depends(get_current_active_user)
+):
+    """Get count of user's chat sessions"""
+    try:
+        db = get_database()
+        user_object_id = ObjectId(str(current_user.id))
+        
+        count = await db.chat_sessions.count_documents({
+            "user_id": user_object_id,
+            "is_active": {"$ne": False},
+            "deleted_at": {"$exists": False}
+        })
+        
+        return {"count": count}
+        
+    except Exception as e:
+        logger.error(f"Error counting chat sessions for user {current_user.id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to count chat sessions"
+        )
+
+
+
+@router.get("/chat-sessions/{session_id}")
+async def get_chat_session(
+    session_id: str,
+    current_user: User = Depends(get_current_active_user)
+):
+    """Get a specific chat session with all messages"""
+    try:
+        db = get_database()
+        
+        session_data = await db.chat_sessions.find_one({
+            "_id": ObjectId(session_id),
+            "user_id": current_user.id,
+            "is_active": True
+        })
+        
+        if not session_data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Chat session not found"
+            )
+        
+        return {
+            "id": str(session_data["_id"]),
+            "title": session_data["title"],
+            "messages": session_data.get("messages", []),
+            "created_at": session_data["created_at"],
+            "updated_at": session_data["updated_at"]
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error fetching chat session: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not fetch chat session"
+        )
+
+@router.put("/chat-sessions/{session_id}")
+async def update_chat_session(
+    session_id: str,
+    request: UpdateChatSessionRequest,
+    current_user: User = Depends(get_current_active_user)
+):
+    """Update a chat session (title or messages)"""
+    try:
+        db = get_database()
+        
+        # Verify session belongs to user
+        session_data = await db.chat_sessions.find_one({
+            "_id": ObjectId(session_id),
+            "user_id": current_user.id,
+            "is_active": True
+        })
+        
+        if not session_data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Chat session not found"
+            )
+        
+        update_data = {"updated_at": datetime.utcnow()}
+        
+        if request.title is not None:
+            update_data["title"] = request.title
+        
+        if request.messages is not None:
+            update_data["messages"] = request.messages
+        
+        await db.chat_sessions.update_one(
+            {"_id": ObjectId(session_id)},
+            {"$set": update_data}
+        )
+        
+        return {"message": "Chat session updated successfully"}
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error updating chat session: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not update chat session"
+        )
+
+@router.post("/chat-sessions/{session_id}/messages")
+async def save_message_to_session(
+    session_id: str,
+    request: SaveMessageRequest,
+    current_user: User = Depends(get_current_active_user)
+):
+    """Add a message to a chat session"""
+    try:
+        db = get_database()
+        
+        # Verify session belongs to user
+        session_data = await db.chat_sessions.find_one({
+            "_id": ObjectId(session_id),
+            "user_id": current_user.id,
+            "is_active": True
+        })
+        
+        if not session_data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Chat session not found"
+            )
+        
+        await persist_message(session_id, request.message)
+        
+        return {"message": "Message saved successfully"}
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error saving message: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not save message"
+        )
+    
+
+
+@router.delete("/chat-sessions/{session_id}")
+async def delete_chat_session(
+    session_id: str,
+    current_user: User = Depends(get_current_active_user)
+):
+    """Delete a chat session (soft delete)"""
+    try:
+        db = get_database()
+        
+        result = await db.chat_sessions.update_one(
+            {
+                "_id": ObjectId(session_id),
+                "user_id": current_user.id
+            },
+            {"$set": {"is_active": False, "updated_at": datetime.utcnow()}}
+        )
+        
+        if result.matched_count == 0:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Chat session not found"
+            )
+        
+        return {"message": "Chat session deleted successfully"}
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error deleting chat session: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not delete chat session"
+        )

multi_llm_chatbot_backend/app/api/routes/debug.py

@@ -0,0 +1,102 @@
+from fastapi import APIRouter, Request, Query
+from app.core.session_manager import get_session_manager
+from app.core.rag_manager import get_rag_manager
+from app.core.bootstrap import chat_orchestrator
+import logging
+
+from app.api.old_routes import get_or_create_session_for_request
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+session_manager = get_session_manager()
+
+@router.get("/debug/personas")
+async def debug_personas(request: Request):
+    try:
+        session_id = get_or_create_session_for_request(request)
+        session = session_manager.get_session(session_id)
+        rag_manager = get_rag_manager()
+        rag_stats = rag_manager.get_document_stats(session_id)
+
+        return {
+            "personas": {
+                pid: {
+                    "name": persona.name,
+                    "prompt": persona.system_prompt[:100] + "...",
+                    "retrieval_keywords": chat_orchestrator._get_persona_context_keywords(pid)
+                } for pid, persona in chat_orchestrator.personas.items()
+            },
+            "session_info": {
+                "context_length": len(session.messages),
+                "uploaded_files": session.uploaded_files,
+                "rag_stats": rag_stats
+            }
+        }
+    except Exception as e:
+        logger.error(f"Error in debug endpoint: {str(e)}")
+        return {
+            "personas": {},
+            "session_info": {"context_length": 0},
+            "error": str(e)
+        }
+
+@router.get("/debug/ranked-personas")
+async def get_ranked_personas(request: Request, k: int = Query(3, ge=1, le=10)):
+    try:
+        session_id = get_or_create_session_for_request(request)
+        top_personas = await chat_orchestrator.get_top_personas(session_id=session_id, k=k)
+        return {
+            "ranked_personas": top_personas,
+            "available_personas": list(chat_orchestrator.personas.keys()),
+            "session_id": session_id
+        }
+    except Exception as e:
+        logger.error(f"Error in /debug/ranked-personas: {e}")
+        return {
+            "ranked_personas": [],
+            "error": str(e)
+        }
+
+@router.get("/debug/rag-status")
+async def debug_rag_status(request: Request):
+    try:
+        session_id = get_or_create_session_for_request(request)
+        rag_manager = get_rag_manager()
+        session_stats = session_manager.get_session_stats(session_id)
+
+        test_search = rag_manager.search_documents(
+            query="test methodology research",
+            session_id=session_id,
+            persona_context="",
+            n_results=3
+        )
+
+        return {
+            "rag_manager_healthy": True,
+            "session_id": session_id,
+            "session_stats": session_stats.get("rag_stats", {}),
+            "test_search_results": len(test_search),
+            "test_search_details": [
+                {
+                    "relevance": chunk.get("relevance_score", 0),
+                    "distance": chunk.get("distance", "unknown"),
+                    "text_length": len(chunk.get("text", "")),
+                    "filename": chunk.get("metadata", {}).get("filename", "unknown")
+                }
+                for chunk in test_search[:3]
+            ],
+            "persona_keywords": {
+                pid: chat_orchestrator._get_persona_context_keywords(pid)
+                for pid in chat_orchestrator.personas.keys()
+            }
+        }
+
+    except Exception as e:
+        logger.error(f"Error in RAG debug: {str(e)}")
+        return {
+            "rag_manager_healthy": False,
+            "error": str(e),
+            "session_id": session_id if 'session_id' in locals() else "unknown"
+        }

multi_llm_chatbot_backend/app/api/routes/documents.py

@@ -0,0 +1,530 @@
+from fastapi import APIRouter, Request, HTTPException, UploadFile, File, Body, Depends
+from fastapi import Query
+from app.utils.document_extractor import extract_text_from_file
+from app.core.session_manager import get_session_manager
+from app.core.rag_manager import get_rag_manager
+from app.api.utils import get_or_create_session_for_request_async
+from fastapi.responses import StreamingResponse
+from app.utils.chat_summary import generate_summary_from_messages, parse_summary_to_blocks, format_summary_for_text_export
+from app.utils.file_export import prepare_export_response, generate_pdf_file_from_blocks
+from app.core.session_manager import get_session_manager
+from app.core.bootstrap import chat_orchestrator
+from app.core.auth import get_current_active_user
+from app.core.database import get_database
+from app.models.user import User
+from bson import ObjectId
+import logging
+import re
+from html import unescape
+
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+session_manager = get_session_manager()
+get_rag_manager = get_rag_manager
+
+
+def sanitize_html_content(content):
+    """
+    Clean up HTML content by removing or fixing malformed tags.
+    This prevents PDF export errors caused by invalid HTML structure.
+    """
+    if not content:
+        return content
+    
+    try:
+        logger.debug(f"Sanitizing content (first 200 chars): {content[:200]}")
+        
+        # First, unescape HTML entities
+        content = unescape(content)
+        
+        # More aggressive approach: Strip ALL HTML tags first, then apply simple formatting
+        # This prevents malformed HTML from causing issues
+        
+        # Remove all HTML tags completely (most aggressive approach)
+        content = re.sub(r'<[^>]*>', '', content)
+        
+        # Clean up multiple spaces and normalize whitespace
+        content = re.sub(r'\s+', ' ', content)
+        content = content.strip()
+        
+        # Remove any remaining HTML entities that might have been missed
+        content = re.sub(r'&[a-zA-Z0-9#]+;', '', content)
+        
+        # Remove any remaining angle brackets that might cause issues
+        content = content.replace('<', '').replace('>', '')
+        
+        logger.debug(f"Sanitized content (first 200 chars): {content[:200]}")
+        return content
+        
+    except Exception as e:
+        logger.error(f"Error sanitizing HTML content: {str(e)}")
+        # Ultra-fallback: return only alphanumeric and basic punctuation
+        try:
+            import string
+            allowed_chars = string.ascii_letters + string.digits + string.punctuation + ' \n\r\t'
+            cleaned = ''.join(c for c in content if c in allowed_chars)
+            return re.sub(r'\s+', ' ', cleaned).strip()
+        except:
+            return "Content could not be sanitized for export"
+
+def convert_messages_for_export(messages):
+    """
+    Convert stored message format to export-compatible format.
+    Stored format uses 'type', export functions expect 'role' and specific structure.
+    """
+    converted_messages = []
+    
+    for i, msg in enumerate(messages):
+        try:
+            # Get and sanitize content
+            raw_content = msg.get('content', '')
+            sanitized_content = sanitize_html_content(raw_content)
+            
+            # Debug logging for problematic content
+            if i < 5 or '<' in raw_content or '>' in raw_content:  # Log first few messages and any with HTML
+                logger.debug(f"Message {i}: Original length: {len(raw_content)}, Sanitized length: {len(sanitized_content)}")
+                if raw_content != sanitized_content:
+                    logger.debug(f"Content changed during sanitization for message {msg.get('id', 'unknown')}")
+            
+            # Create base converted message
+            converted_msg = {
+                'id': msg.get('id', 'unknown'),
+                'timestamp': msg.get('timestamp', ''),
+                'content': sanitized_content,
+            }
+            
+            # Convert type to role and handle different message types
+            msg_type = msg.get('type', 'unknown')
+            
+            if msg_type == 'user':
+                converted_msg['role'] = 'user'
+                # Add reply context if present
+                if 'replyTo' in msg:
+                    reply_to = msg['replyTo']
+                    converted_msg['content'] = f"[Reply to {reply_to.get('advisorName', 'advisor')}] {converted_msg['content']}"
+                
+            elif msg_type == 'advisor':
+                converted_msg['role'] = 'assistant'
+                # Include advisor information
+                advisor_name = msg.get('advisorName', msg.get('persona', 'Advisor'))
+                converted_msg['advisor_name'] = advisor_name
+                converted_msg['advisor_id'] = msg.get('advisorId', msg.get('persona_id', 'unknown'))
+                
+                # Mark special response types
+                if msg.get('isReply'):
+                    converted_msg['content'] = f"[{advisor_name} replies] {converted_msg['content']}"
+                elif msg.get('isExpansion'):
+                    converted_msg['content'] = f"[{advisor_name} expands] {converted_msg['content']}"
+                else:
+                    converted_msg['content'] = f"[{advisor_name}] {converted_msg['content']}"
+                
+            elif msg_type == 'system':
+                converted_msg['role'] = 'system'
+                
+            elif msg_type == 'document_upload':
+                converted_msg['role'] = 'system'
+                converted_msg['content'] = f"📄 {converted_msg['content']}"
+                
+            elif msg_type == 'error':
+                converted_msg['role'] = 'system'
+                converted_msg['content'] = f"❌ Error: {converted_msg['content']}"
+                
+            else:
+                # Unknown type, treat as system message
+                converted_msg['role'] = 'system'
+                converted_msg['content'] = f"[{msg_type}] {converted_msg['content']}"
+            
+            converted_messages.append(converted_msg)
+            
+        except Exception as e:
+            logger.error(f"Error converting message {msg.get('id', 'unknown')}: {str(e)}")
+            # Add a fallback message to maintain conversation flow
+            converted_messages.append({
+                'id': msg.get('id', 'unknown'),
+                'role': 'system',
+                'content': f"[Message conversion error: {str(e)}]",
+                'timestamp': msg.get('timestamp', '')
+            })
+    
+    logger.info(f"Converted {len(messages)} messages for export")
+    return converted_messages
+
+
+@router.post("/upload-document")
+async def upload_document(
+    file: UploadFile = File(...), 
+    request: Request = None,
+    chat_session_id: str = Query(None, description="Chat session ID if uploading to specific chat"),
+    current_user: User = Depends(get_current_active_user)  # ADDED: Require authentication
+):
+    try:
+        if chat_session_id:
+            # If uploading to a specific chat, use chat_{id} format
+            session_id = f"chat_{chat_session_id}"
+            logger.info(f"Uploading document to specific chat session: {session_id}")
+        else:
+            # For new/temporary chats, use regular session management
+            session_id = await get_or_create_session_for_request_async(request)
+            logger.info(f"Uploading document to new session: {session_id}")
+        
+        # Add debug logging to track session IDs
+        logger.info(f"Document upload - chat_session_id parameter: {chat_session_id}")
+        logger.info(f"Document upload - final session_id: {session_id}")
+        logger.info(f"Document upload - user_id: {current_user.id}")
+        
+        session = session_manager.get_session(session_id)
+
+        MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
+        if file.size and file.size > MAX_FILE_SIZE:
+            raise HTTPException(status_code=413, detail="File size exceeds 10MB limit")
+
+        file_bytes = await file.read()
+        content = extract_text_from_file(file_bytes, file.content_type)
+        if not content.strip():
+            raise HTTPException(status_code=400, detail="Document is empty or unreadable.")
+
+        rag_manager = get_rag_manager()
+        file_type_map = {
+            "application/pdf": "pdf",
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx", 
+            "text/plain": "txt"
+        }
+        file_type = file_type_map.get(file.content_type, "unknown")
+
+        # Pass the consistent session_id to RAG manager
+        logger.info(f"Adding document {file.filename} to session {session_id}")
+        rag_result = rag_manager.add_document(
+            content=content,
+            filename=file.filename,
+            session_id=session_id,
+            file_type=file_type
+        )
+
+        if not rag_result["success"]:
+            raise HTTPException(status_code=500, detail=f"Failed to process document: {rag_result.get('error', 'Unknown error')}")
+
+        session.uploaded_files.append(file.filename)
+        session.total_upload_size += len(file_bytes)
+
+        doc_metadata = rag_result.get("document_metadata", {})
+        doc_title = doc_metadata.get("title", file.filename)
+
+        session.append_message(
+            "system", 
+            f"Document uploaded: '{doc_title}' ({file.filename}) - {rag_result['chunks_created']} sections processed, ~{rag_result['total_tokens']} tokens analyzed. You can now ask questions about this document by referencing it by name."
+        )
+
+        # Return session info for frontend tracking
+        return {
+            "message": f"Document '{file.filename}' uploaded and processed successfully.",
+            "filename": file.filename,
+            "document_title": doc_title,
+            "chunks_created": rag_result['chunks_created'],
+            "total_tokens": rag_result['total_tokens'],
+            "file_type": file_type,
+            "can_reference_by_name": True,
+            "session_id": session_id,
+            "chat_session_id": chat_session_id,
+            "user_id": str(current_user.id)  # ADDED: Include user ID for debugging
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error processing document upload: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Error processing document: {str(e)}")
+
+
+@router.post("/search-documents")
+async def search_documents(request: Request, query: str = Body(..., embed=True), persona: str = Body("", embed=True)):
+    try:
+        session_id = await get_or_create_session_for_request_async(request)  # FIXED: Added await
+        rag_manager = get_rag_manager()
+
+        persona_contexts = {
+            "methodologist": "methodology research design analysis",
+            "theorist": "theory theoretical framework conceptual",
+            "pragmatist": "practical application implementation"
+        }
+        persona_context = persona_contexts.get(persona, "")
+
+        results = rag_manager.search_documents(
+            query=query,
+            session_id=session_id,
+            persona_context=persona_context,
+            n_results=5
+        )
+
+        return {
+            "query": query,
+            "persona_filter": persona,
+            "results_count": len(results),
+            "results": results
+        }
+
+    except Exception as e:
+        logger.error(f"Error searching documents: {str(e)}")
+        return {"query": query, "results_count": 0, "results": [], "error": str(e)}
+
+
+@router.get("/document-stats")
+async def get_document_stats(request: Request):
+    try:
+        session_id = await get_or_create_session_for_request_async(request)  # FIXED: Added await
+        rag_manager = get_rag_manager()
+        return rag_manager.get_document_stats(session_id)
+    except Exception as e:
+        logger.error(f"Error getting document stats: {str(e)}")
+        return {"total_chunks": 0, "total_documents": 0, "documents": []}
+
+
+@router.get("/uploaded-files")
+async def get_uploaded_filenames(request: Request):
+    try:
+        session_id = await get_or_create_session_for_request_async(request)  # FIXED: Added await
+        session = session_manager.get_session(session_id)
+        return {"files": session.uploaded_files}
+    except Exception as e:
+        logger.error(f"Error getting uploaded files: {str(e)}")
+        return {"files": []}
+
+
+@router.get("/document-insights/{filename}")
+async def get_document_insights(filename: str, request: Request):
+    try:
+        session_id = await get_or_create_session_for_request_async(request)  # FIXED: Added await
+        rag_manager = get_rag_manager()
+        stats = rag_manager.get_document_stats(session_id)
+        document_info = next((doc for doc in stats.get("documents", []) if doc["filename"] == filename), None)
+
+        if not document_info:
+            raise HTTPException(status_code=404, detail=f"Document {filename} not found")
+
+        results = rag_manager.collection.get(
+            where={"session_id": session_id, "filename": filename},
+            limit=3,
+            include=["documents", "metadatas"]
+        )
+
+        sample_sections = []
+        if results["documents"]:
+            for doc, metadata in zip(results["documents"], results["metadatas"]):
+                sample_sections.append({
+                    "section": metadata.get("document_section", "unknown"),
+                    "content_preview": doc[:200] + "..." if len(doc) > 200 else doc,
+                    "keywords": metadata.get("keywords", "")
+                })
+
+        return {
+            "filename": filename,
+            "document_title": document_info.get("title", filename),
+            "file_type": document_info.get("file_type", "unknown"),
+            "statistics": {
+                "total_chunks": document_info["chunks"],
+                "estimated_tokens": document_info["estimated_tokens"],
+                "sections_identified": document_info["sections"]
+            },
+            "content_analysis": {
+                "has_methodology": document_info.get("has_methodology", False),
+                "has_theory": document_info.get("has_theory", False),
+                "has_references": document_info.get("has_references", False)
+            },
+            "sample_sections": sample_sections
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting document insights: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Error analyzing document: {str(e)}")
+    
+@router.get("/export-chat")
+async def export_chat(
+    request: Request, 
+    format: str = Query(..., regex="^(txt|pdf|docx)$"),
+    chat_session_id: str = Query(None, description="Optional: specific chat session ID to export"),
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Export chat messages. 
+    If chat_session_id is provided, exports that specific stored chat session.
+    Otherwise, exports the current in-memory session.
+    """
+    try:
+        messages = []
+        
+        if chat_session_id:
+            # Export specific stored chat session
+            db = get_database()
+            session_data = await db.chat_sessions.find_one({
+                "_id": ObjectId(chat_session_id),
+                "user_id": current_user.id,
+                "is_active": True
+            })
+            
+            if not session_data:
+                raise HTTPException(
+                    status_code=404, 
+                    detail="Chat session not found or you don't have permission to access it"
+                )
+            
+            raw_messages = session_data.get("messages", [])
+            # Convert stored message format to export-compatible format
+            messages = convert_messages_for_export(raw_messages)
+        else:
+            # Export current in-memory session (existing behavior)
+            session_id = await get_or_create_session_for_request_async(request)  # FIXED: Added await
+            session = session_manager.get_session(session_id)
+            # In-memory messages might already be in the right format, but convert to be safe
+            messages = convert_messages_for_export(session.messages)
+
+        if not messages:
+            return {"error": "No messages in this session."}
+
+        try:
+            return prepare_export_response(messages, format)
+        except Exception as export_error:
+            logger.error(f"Error in prepare_export_response: {str(export_error)}")
+            # Try with a simplified version of messages if the export fails
+            try:
+                # Create simplified messages with just basic text content
+                simplified_messages = []
+                for msg in messages:
+                    simplified_msg = {
+                        'id': msg.get('id', 'unknown'),
+                        'role': msg.get('role', 'system'),
+                        'content': str(msg.get('content', '')).replace('\n', ' ').strip(),
+                        'timestamp': msg.get('timestamp', '')
+                    }
+                    if 'advisor_name' in msg:
+                        simplified_msg['advisor_name'] = msg['advisor_name']
+                    simplified_messages.append(simplified_msg)
+                
+                return prepare_export_response(simplified_messages, format)
+            except Exception as fallback_error:
+                logger.error(f"Fallback export also failed: {str(fallback_error)}")
+                raise HTTPException(
+                    status_code=500,
+                    detail=f"Export failed due to content formatting issues. Please try a different format or contact support."
+                )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error exporting chat: {str(e)}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to export chat: {str(e)}"
+        )
+
+@router.get("/chat-summary")
+async def chat_summary(
+    request: Request,
+    format: str = Query("text", regex="^(txt|pdf|docx)$"),
+    chat_session_id: str = Query(None, description="Optional: specific chat session ID to summarize"),
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Generate and return a summary of chat messages.
+    If chat_session_id is provided, summarizes that specific stored chat session.
+    Otherwise, summarizes the current in-memory session.
+    Can return as plain txt, PDF, or DOCX.
+    """
+    try:
+        messages = []
+        
+        if chat_session_id:
+            # Summarize specific stored chat session
+            db = get_database()
+            session_data = await db.chat_sessions.find_one({
+                "_id": ObjectId(chat_session_id),
+                "user_id": current_user.id,
+                "is_active": True
+            })
+            
+            if not session_data:
+                raise HTTPException(
+                    status_code=404, 
+                    detail="Chat session not found or you don't have permission to access it"
+                )
+            
+            raw_messages = session_data.get("messages", [])
+            # Convert stored message format for summary generation
+            messages = convert_messages_for_export(raw_messages)
+        else:
+            # Summarize current in-memory session (existing behavior)
+            session_id = await get_or_create_session_for_request_async(request)  # FIXED: Added await
+            session = session_manager.get_session(session_id)
+            # Convert in-memory messages
+            messages = convert_messages_for_export(session.messages)
+
+        if not messages:
+            return {"error": "No messages in this session."}
+
+        try:
+            llm = next(iter(chat_orchestrator.personas.values())).llm
+            summary_text = await generate_summary_from_messages(messages, llm)
+
+            if format == "txt":
+                # Use improved formatting for text export
+                formatted_summary = format_summary_for_text_export(summary_text)
+                return prepare_export_response(formatted_summary, "txt", filename_prefix="chat_summary")
+
+            elif format == "docx":
+                # Use improved formatting for DOCX export
+                formatted_summary = format_summary_for_text_export(summary_text)
+                return prepare_export_response(formatted_summary, "docx", filename_prefix="chat_summary")
+
+            elif format == "pdf":
+                # Parse and render using block formatting
+                blocks = [{"type": "heading", "text": "Chat Summary"}] + parse_summary_to_blocks(summary_text)
+
+                file_stream = generate_pdf_file_from_blocks(blocks)
+                return StreamingResponse(
+                    file_stream,
+                    media_type="application/pdf",
+                    headers={"Content-Disposition": "attachment; filename=chat_summary.pdf"}
+                )
+        except Exception as summary_error:
+            logger.error(f"Error generating summary: {str(summary_error)}")
+            # Try with simplified content
+            try:
+                # Create a basic text summary if AI summary fails
+                basic_summary = "Chat Summary\n\n"
+                for msg in messages:
+                    if msg.get('role') == 'user':
+                        basic_summary += f"User: {msg.get('content', '')[:200]}...\n\n"
+                    elif msg.get('role') == 'assistant':
+                        advisor_name = msg.get('advisor_name', 'Advisor')
+                        basic_summary += f"{advisor_name}: {msg.get('content', '')[:200]}...\n\n"
+                
+                if format == "txt":
+                    return prepare_export_response(basic_summary, "txt", filename_prefix="chat_summary")
+                elif format == "docx":
+                    return prepare_export_response(basic_summary, "docx", filename_prefix="chat_summary")
+                elif format == "pdf":
+                    blocks = [{"type": "heading", "text": "Chat Summary"}, {"type": "paragraph", "text": basic_summary}]
+                    file_stream = generate_pdf_file_from_blocks(blocks)
+                    return StreamingResponse(
+                        file_stream,
+                        media_type="application/pdf",
+                        headers={"Content-Disposition": "attachment; filename=chat_summary.pdf"}
+                    )
+            except Exception as fallback_error:
+                logger.error(f"Fallback summary export also failed: {str(fallback_error)}")
+                raise HTTPException(
+                    status_code=500,
+                    detail=f"Summary generation failed due to content formatting issues. Please try a different format."
+                )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in chat-summary endpoint: {str(e)}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Summary generation failed: {str(e)}"
+        )

multi_llm_chatbot_backend/app/api/routes/onboarding.py

@@ -0,0 +1,152 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Framework
+# All Rights Reserved 2008-2025
+# Licensed under the BSD 3-Clause License
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# Copyright (c) 2008-2025, Neongecko.com Inc.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+# 3. Neither the name of the copyright holder nor the names of its contributors
+#    may be used to endorse or promote products derived from this software
+#    without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from app.api.routes.user_profile import _is_field_filled, enrich_profile_from_user
+from app.core.auth import get_current_active_user
+from app.core.bootstrap import create_llm_client
+from app.core.database import get_database
+from app.core.onboarding_agent import OnboardingAgent, PROFILE_FIELDS
+from app.models.user import User
+
+LOG = logging.getLogger(__name__)
+
+router = APIRouter()
+
+ONBOARDING_COLLECTION = "onboarding_conversations"
+
+
+class OnboardingMessage(BaseModel):
+    user_input: str
+
+
+def _progress(profile: Dict[str, Any]) -> int:
+    filled = sum(1 for k, *_ in PROFILE_FIELDS if _is_field_filled(profile.get(k)))
+    return int(filled / len(PROFILE_FIELDS) * 100)
+
+
+def _next_missing_question(profile: Dict[str, Any]) -> Optional[str]:
+    """Return the human-friendly question for the first unfilled field."""
+    for key, question, _desc in PROFILE_FIELDS:
+        if not _is_field_filled(profile.get(key)):
+            return question
+    return None
+
+
+@router.get("/onboarding/start")
+async def onboarding_start(
+    current_user: User = Depends(get_current_active_user),
+) -> Dict[str, Any]:
+    """Return conversation history (if any) and current progress.
+
+    If the user has an in-progress conversation it is returned so the
+    frontend can restore the chat.  Otherwise a fresh contextual welcome
+    message is generated based on which fields are still missing.
+    """
+    db = get_database()
+    doc = await db.user_profiles.find_one({"user_id": current_user.id})
+    profile = enrich_profile_from_user(doc, current_user)
+    progress = _progress(profile)
+
+    if progress >= 100:
+        await db[ONBOARDING_COLLECTION].delete_many({"user_id": current_user.id})
+        return {
+            "messages": [{"role": "agent",
+                          "text": "Your profile is already complete! Feel free to update anything by chatting here."}],
+            "progress": 100,
+            "complete": True,
+        }
+
+    conv = await db[ONBOARDING_COLLECTION].find_one({"user_id": current_user.id})
+
+    if conv and conv.get("messages"):
+        return {
+            "messages": conv["messages"],
+            "progress": progress,
+            "complete": False,
+        }
+
+    next_q = _next_missing_question(profile)
+    if progress == 0:
+        greeting = (
+            f"Hey {current_user.firstName}! I'd like to learn a bit about your security background so "
+            "your advisors can tailor depth and examples. "
+            f"Let's start — {next_q.lower() if next_q else 'tell me about your role and goals!'}"
+        )
+    else:
+        greeting = (
+            f"Welcome back, {current_user.firstName}! You're {progress}% done. "
+            f"Let's pick up where we left off — {next_q.lower() if next_q else 'what else can you tell me?'}"
+        )
+
+    messages = [{"role": "agent", "text": greeting}]
+    await db[ONBOARDING_COLLECTION].update_one(
+        {"user_id": current_user.id},
+        {"$set": {"messages": messages, "updated_at": datetime.utcnow()},
+         "$setOnInsert": {"user_id": current_user.id}},
+        upsert=True,
+    )
+
+    return {"messages": messages, "progress": progress, "complete": False}
+
+
+@router.post("/onboarding/chat")
+async def onboarding_chat(
+    msg: OnboardingMessage,
+    current_user: User = Depends(get_current_active_user),
+) -> Dict[str, Any]:
+    db = get_database()
+    doc = await db.user_profiles.find_one({"user_id": current_user.id})
+    profile = enrich_profile_from_user(doc, current_user)
+
+    agent = OnboardingAgent(create_llm_client())
+    result = await agent.chat(msg.user_input, current_user.id, profile)
+
+    user_msg = {"role": "user", "text": msg.user_input}
+    agent_msg = {"role": "agent", "text": result["reply"]}
+
+    await db[ONBOARDING_COLLECTION].update_one(
+        {"user_id": current_user.id},
+        {"$push": {"messages": {"$each": [user_msg, agent_msg]}},
+         "$set": {"updated_at": datetime.utcnow()},
+         "$setOnInsert": {"user_id": current_user.id}},
+        upsert=True,
+    )
+
+    if result.get("complete"):
+        await db[ONBOARDING_COLLECTION].delete_many({"user_id": current_user.id})
+
+    return result

multi_llm_chatbot_backend/app/api/routes/phd_canvas.py

@@ -0,0 +1,316 @@
+from fastapi import APIRouter, HTTPException, Depends, status, BackgroundTasks
+from typing import Dict, Optional
+from datetime import datetime
+import logging
+from bson import ObjectId
+
+from app.models.user import User
+from app.models.phd_canvas import PhdCanvas, CanvasResponse, UpdateCanvasRequest
+from app.core.auth import get_current_active_user
+from app.core.database import get_database
+
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+# Request/Response models
+class CanvasStatsResponse(BaseModel):
+    total_insights: int
+    total_sections: int
+    last_updated: Optional[str] = None
+    last_chat_processed: Optional[str] = None
+    created_at: Optional[str] = None
+    auto_update: bool = True
+    sections_breakdown: Dict = {}
+
+class PrintCanvasResponse(BaseModel):
+    user_id: str
+    generated_at: str
+    total_insights: int
+    last_updated: Optional[str] = None
+    sections: list
+    metadata: Dict
+
+def get_canvas_manager():
+    """Lazy import to avoid circular dependency"""
+    from app.core.canvas_manager import get_canvas_manager
+    return get_canvas_manager()
+
+@router.get("/phd-canvas", response_model=CanvasResponse)
+async def get_phd_canvas(
+    current_user: User = Depends(get_current_active_user)
+):
+    """Get the user's PhD Canvas, creating it if it doesn't exist"""
+    try:
+        canvas_manager = get_canvas_manager()
+        canvas = await canvas_manager.get_or_create_canvas(str(current_user.id))
+        
+        # Convert to response model
+        return CanvasResponse(
+            id=str(canvas.id),
+            user_id=str(canvas.user_id),
+            sections=canvas.sections,
+            created_at=canvas.created_at,
+            last_updated=canvas.last_updated,
+            last_chat_processed=canvas.last_chat_processed,
+            total_insights=canvas.total_insights,
+            auto_update=canvas.auto_update,
+            print_optimized=canvas.print_optimized
+        )
+        
+    except Exception as e:
+        logger.error(f"Error getting PhD canvas for user {current_user.id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve PhD canvas"
+        )
+
+@router.post("/phd-canvas/update", response_model=CanvasResponse)
+async def update_phd_canvas(
+    request: UpdateCanvasRequest,
+    background_tasks: BackgroundTasks,
+    current_user: User = Depends(get_current_active_user)
+):
+    """Update the PhD Canvas with latest insights from chat sessions"""
+    try:
+        canvas_manager = get_canvas_manager()
+        
+        # For large updates, run in background
+        if request.force_full_update:
+            logger.info(f"Queuing background canvas update for user {current_user.id}")
+            background_tasks.add_task(
+                _background_canvas_update,
+                str(current_user.id),
+                request
+            )
+            
+            # Return current canvas immediately
+            canvas = await canvas_manager.get_or_create_canvas(str(current_user.id))
+        else:
+            # For incremental updates, process immediately
+            logger.info(f"Processing incremental canvas update for user {current_user.id}")
+            canvas = await canvas_manager.update_canvas(str(current_user.id), request)
+        
+        return CanvasResponse(
+            id=str(canvas.id),
+            user_id=str(canvas.user_id),
+            sections=canvas.sections,
+            created_at=canvas.created_at,
+            last_updated=canvas.last_updated,
+            last_chat_processed=canvas.last_chat_processed,
+            total_insights=canvas.total_insights,
+            auto_update=canvas.auto_update,
+            print_optimized=canvas.print_optimized
+        )
+        
+    except Exception as e:
+        logger.error(f"Error updating PhD canvas for user {current_user.id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to update PhD canvas"
+        )
+
+@router.get("/phd-canvas/stats", response_model=CanvasStatsResponse)
+async def get_canvas_stats(
+    current_user: User = Depends(get_current_active_user)
+):
+    """Get statistics about the user's PhD Canvas"""
+    try:
+        canvas_manager = get_canvas_manager()
+        stats = await canvas_manager.get_canvas_stats(str(current_user.id))
+        
+        return CanvasStatsResponse(
+            total_insights=stats.get("total_insights", 0),
+            total_sections=stats.get("total_sections", 0),
+            last_updated=stats.get("last_updated").isoformat() if stats.get("last_updated") else None,
+            last_chat_processed=stats.get("last_chat_processed").isoformat() if stats.get("last_chat_processed") else None,
+            created_at=stats.get("created_at").isoformat() if stats.get("created_at") else None,
+            auto_update=stats.get("auto_update", True),
+            sections_breakdown=stats.get("sections_breakdown", {})
+        )
+        
+    except Exception as e:
+        logger.error(f"Error getting canvas stats for user {current_user.id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve canvas statistics"
+        )
+
+@router.get("/phd-canvas/print", response_model=PrintCanvasResponse)
+async def get_print_canvas(
+    current_user: User = Depends(get_current_active_user)
+):
+    """Get PhD Canvas formatted for printing"""
+    try:
+        canvas_manager = get_canvas_manager()
+        print_data = await canvas_manager.export_canvas_for_printing(str(current_user.id))
+        
+        return PrintCanvasResponse(
+            user_id=print_data["user_id"],
+            generated_at=print_data["generated_at"].isoformat(),
+            total_insights=print_data["total_insights"],
+            last_updated=print_data["last_updated"].isoformat() if print_data["last_updated"] else None,
+            sections=print_data["sections"],
+            metadata=print_data["metadata"]
+        )
+        
+    except Exception as e:
+        logger.error(f"Error exporting print canvas for user {current_user.id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to export canvas for printing"
+        )
+
+@router.post("/phd-canvas/auto-update")
+async def trigger_auto_update(
+    background_tasks: BackgroundTasks,
+    current_user: User = Depends(get_current_active_user)
+):
+    """Trigger automatic canvas update (typically called when user opens canvas page)"""
+    try:
+        canvas_manager = get_canvas_manager()
+        db = get_database()
+        
+        # Get current canvas to check if auto-update is needed
+        canvas = await canvas_manager.get_or_create_canvas(str(current_user.id))
+        
+        if not canvas.auto_update:
+            return {"message": "Auto-update is disabled for this canvas"}
+        
+        # Check if this is a first-time canvas (never processed any chats)
+        is_first_time_canvas = (
+            canvas.last_chat_processed is None and 
+            canvas.total_insights == 0
+        )
+        
+        if is_first_time_canvas:
+            logger.info(f"First-time canvas detected for user {current_user.id}, triggering full update")
+            
+            # For first-time canvas, always do full update to process all historical chats
+            background_tasks.add_task(
+                _background_canvas_update,
+                str(current_user.id),
+                UpdateCanvasRequest(force_full_update=True)
+            )
+            
+            return {
+                "message": "First-time canvas update initiated", 
+                "status": "processing",
+                "type": "full_update"
+            }
+        
+        # For existing canvas, check if there are actually new chats
+        user_object_id = ObjectId(str(current_user.id))
+        
+        # Count chats newer than last processed
+        query_filter = {
+            "user_id": user_object_id,
+            "is_active": {"$ne": False},
+            "deleted_at": {"$exists": False}
+        }
+        
+        if canvas.last_chat_processed:
+            query_filter["$or"] = [
+                {"created_at": {"$gt": canvas.last_chat_processed}},
+                {"updated_at": {"$gt": canvas.last_chat_processed}}
+            ]
+        
+        new_chat_count = await db.chat_sessions.count_documents(query_filter)
+        
+        if new_chat_count > 0:
+            logger.info(f"Found {new_chat_count} new/updated chats for user {current_user.id}, triggering incremental update")
+            
+            # Only update if there are actually new chats
+            background_tasks.add_task(
+                _background_canvas_update,
+                str(current_user.id),
+                UpdateCanvasRequest(force_full_update=False)
+            )
+            
+            return {
+                "message": f"Canvas update queued for {new_chat_count} new chats", 
+                "status": "updating",
+                "type": "incremental_update",
+                "new_chats": new_chat_count
+            }
+        else:
+            logger.info(f"No new chats found for user {current_user.id}, skipping update")
+            return {
+                "message": "Canvas is up to date", 
+                "status": "current",
+                "new_chats": 0
+            }
+            
+    except Exception as e:
+        logger.error(f"Error triggering auto-update for user {current_user.id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to trigger canvas auto-update"
+        )
+
+@router.delete("/phd-canvas")
+async def delete_canvas(
+    current_user: User = Depends(get_current_active_user)
+):
+    """Delete the user's PhD Canvas"""
+    try:
+        canvas_manager = get_canvas_manager()
+        deleted = await canvas_manager.delete_canvas(str(current_user.id))
+        
+        if deleted:
+            return {"message": "PhD Canvas deleted successfully"}
+        else:
+            return {"message": "No canvas found to delete"}
+            
+    except Exception as e:
+        logger.error(f"Error deleting canvas for user {current_user.id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to delete PhD canvas"
+        )
+
+@router.get("/phd-canvas/refresh")
+async def refresh_canvas_data(
+    background_tasks: BackgroundTasks,
+    current_user: User = Depends(get_current_active_user)
+):
+    """Force refresh canvas with full update from all chats"""
+    try:
+        logger.info(f"Force refreshing canvas for user {current_user.id}")
+        
+        # Queue full update in background
+        background_tasks.add_task(
+            _background_canvas_update,
+            str(current_user.id),
+            UpdateCanvasRequest(force_full_update=True)
+        )
+        
+        return {
+            "message": "Full canvas refresh initiated",
+            "status": "processing",
+            "estimated_completion": "2-3 minutes"
+        }
+        
+    except Exception as e:
+        logger.error(f"Error refreshing canvas for user {current_user.id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to refresh PhD canvas"
+        )
+
+# Background task functions
+async def _background_canvas_update(user_id: str, request: UpdateCanvasRequest):
+    """Background task to update canvas without blocking the API response"""
+    try:
+        logger.info(f"Starting background canvas update for user {user_id}")
+        canvas_manager = get_canvas_manager()
+        
+        updated_canvas = await canvas_manager.update_canvas(user_id, request)
+        
+        logger.info(f"Background canvas update completed for user {user_id}. Total insights: {updated_canvas.total_insights}")
+        
+    except Exception as e:
+        logger.error(f"Error in background canvas update for user {user_id}: {e}")
+        import traceback
+        logger.error(f"Traceback: {traceback.format_exc()}")

multi_llm_chatbot_backend/app/api/routes/provider.py

@@ -0,0 +1,111 @@
+from fastapi import APIRouter, Body, HTTPException
+from app.config import get_settings
+from app.llm.improved_gemini_client import ImprovedGeminiClient
+from app.llm.improved_ollama_client import ImprovedOllamaClient
+from app.llm.improved_vllm_client import ImprovedVllmClient
+from app.models.default_personas import get_default_personas
+from app.core.bootstrap import chat_orchestrator, llm, current_provider, available_providers
+from pydantic import BaseModel
+import os
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+def create_llm_client(provider: str = None):
+    global current_provider
+    if provider is None:
+        provider = current_provider
+
+    if provider == "gemini":
+        try:
+            return ImprovedGeminiClient(model_name=os.getenv("GEMINI_MODEL"))
+        except ValueError as e:
+            logger.warning(f"Gemini API key not found, falling back to Ollama: {e}")
+            return ImprovedOllamaClient(model_name="llama3.2:1b")
+    elif provider == "ollama":
+        return ImprovedOllamaClient(model_name="llama3.2:1b")
+    elif provider == "vllm":
+        settings = get_settings()
+        if not settings.llm.vllm.api_url:
+            raise ValueError("No vLLM endpoint configured. Set llm.vllm.api_url in your config.")
+        return ImprovedVllmClient(
+            api_url=settings.llm.vllm.api_url,
+            api_key=settings.llm.vllm.api_key,
+        )
+    else:
+        raise ValueError(f"Unknown provider: {provider}")
+
+# NOTE: Personas and `llm` are already created and registered by
+# app/core/bootstrap.py with the correct ResilientLLMClient wrapping
+# (primary vLLM + OpenAI fallback). Re-registering them here at module
+# import time replaces them with a raw vLLM client that lacks the
+# fallback wrapper AND lacks the api_username/api_key wiring, breaking
+# both auth and failover. Bootstrap already handles initial setup.
+
+class ProviderSwitch(BaseModel):
+    provider: str
+
+@router.get("/current-provider")
+async def get_current_provider():
+    return {
+        "current_provider": current_provider,
+        "available_providers": available_providers,
+        "model_info": {
+            "name": llm.model_name if hasattr(llm, 'model_name') else "gemini-2.0-flash",
+            "provider": current_provider
+        }
+    }
+
+@router.post("/switch-provider")
+async def switch_provider(provider_data: ProviderSwitch):
+    global current_provider, llm
+
+    if provider_data.provider not in available_providers:
+        raise HTTPException(status_code=400, detail=f"Unknown provider: {provider_data.provider}. Available: {available_providers}")
+
+    try:
+        from app.core.bootstrap import (
+            create_orchestrator_llm,
+            create_persona_llm,
+        )
+
+        current_provider = provider_data.provider
+        new_llm = create_orchestrator_llm()
+        llm = new_llm
+
+        chat_orchestrator.llm_client = new_llm
+
+        persona_llm = create_persona_llm()
+        new_personas = get_default_personas(persona_llm)
+        chat_orchestrator.personas.clear()
+        for persona in new_personas:
+            chat_orchestrator.register_persona(persona)
+
+        return {
+            "message": f"Successfully switched to {current_provider}",
+            "current_provider": current_provider,
+            "model_info": {
+                "name": new_llm.model_name if hasattr(new_llm, 'model_name') else "gemini-2.0-flash",
+                "provider": current_provider
+            }
+        }
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to switch to {provider_data.provider}: {str(e)}")
+
+@router.post("/switch-model")
+async def switch_model(model_name: str = Body(...)):
+    if "gemini" in model_name.lower():
+        return await switch_provider(ProviderSwitch(provider="gemini"))
+    else:
+        return await switch_provider(ProviderSwitch(provider="ollama"))
+
+@router.get("/current-model")
+async def get_current_model():
+    model_name = llm.model_name if hasattr(llm, 'model_name') else "gemini-2.0-flash"
+    return {
+        "model": model_name,
+        "provider": current_provider
+    }

multi_llm_chatbot_backend/app/api/routes/root.py

@@ -0,0 +1,30 @@
+from fastapi import APIRouter
+from app.config import get_settings
+from app.version import __version__
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# NB: keep this OFF the bare "/" path. In the single-container / Hugging Face
+# Spaces deployment the React SPA is mounted at "/" as a catch-all, and any
+# API route registered at exactly "/" would shadow the SPA's index.html and
+# leave users staring at this JSON banner instead of the app.
+@router.get("/api/health")
+def root():
+    title = get_settings().app.title
+    return {
+        "message": f"{title} Backend is up and running",
+        "version": __version__,
+        "features": [
+            "Configurable Personas",
+            "Improved Session Management",
+            "Unified Context Handling",
+            "Ollama Support",
+            "Gemini API Support",
+            "Provider Switching"
+        ]
+    }
+

multi_llm_chatbot_backend/app/api/routes/sessions.py

@@ -0,0 +1,265 @@
+from fastapi import APIRouter, Request, HTTPException, Depends
+from app.core.session_manager import get_session_manager
+from app.api.utils import get_or_create_session_for_request_async
+from app.core.auth import get_current_active_user
+from app.models.user import User
+from pydantic import BaseModel
+from typing import Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+session_manager = get_session_manager()
+
+class ResetSessionRequest(BaseModel):
+    chat_session_id: Optional[str] = None
+    force_new: bool = False
+
+@router.get("/context")
+async def get_context(
+    request: Request,
+    chat_session_id: Optional[str] = None,
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Get context for current session - ENHANCED with document access fix
+    Now properly handles different chat sessions and ensures document access
+    """
+    try:
+        # Determine which session to get context for with consistent session ID format
+        if chat_session_id:
+            # Getting context for a specific chat session - use consistent format
+            session_id = f"chat_{chat_session_id}"
+            logger.info(f"Getting context for specific chat session: {session_id}")
+            
+            # Ensure session is loaded in memory
+            if session_id not in session_manager.sessions:
+                logger.info(f"Chat session {session_id} not in memory, loading from database")
+                loaded_session_id = await get_or_create_session_for_request_async(
+                    request,
+                    chat_session_id=chat_session_id,
+                    user_id=str(current_user.id)
+                )
+                session_id = loaded_session_id
+                logger.info(f"Loaded session ID: {session_id}")
+        else:
+            # Getting context for current session
+            session_id = await get_or_create_session_for_request_async(request)
+            logger.info(f"Getting context for current session: {session_id}")
+        
+        session = session_manager.get_session(session_id)
+        rag_stats = session.get_rag_stats()
+        
+        #  Enhanced logging for document access debugging
+        logger.info(f"Retrieved context for session {session_id}:")
+        logger.info(f"  - Messages: {len(session.messages)}")
+        logger.info(f"  - Documents: {rag_stats.get('total_documents', 0)}")
+        logger.info(f"  - Chunks: {rag_stats.get('total_chunks', 0)}")
+        logger.info(f"  - Uploaded files: {len(session.uploaded_files)}")
+        
+        # Log document details if available
+        if rag_stats.get('documents'):
+            for doc in rag_stats['documents']:
+                logger.info(f"  - Available document: {doc.get('filename', 'unknown')} ({doc.get('chunks', 0)} chunks)")
+        
+        # Include session debugging info in response
+        context_response = {
+            "session_id": session_id,
+            "chat_session_id": chat_session_id,
+            "messages": session.messages,
+            "rag_info": {
+                "total_documents": rag_stats.get("total_documents", 0),
+                "total_chunks": rag_stats.get("total_chunks", 0),
+                "documents": rag_stats.get("documents", [])
+            },
+            "context_stats": {
+                "message_count": len(session.messages),
+                "user_messages": len([m for m in session.messages if m.get('role') == 'user']),
+                "uploaded_files": session.uploaded_files,
+                "total_upload_size": session.total_upload_size,
+                "created_at": session.created_at.isoformat(),
+                "last_accessed": session.last_accessed.isoformat()
+            },
+            # Add debugging info
+            "debug_info": {
+                "session_format": "chat_session" if chat_session_id else "new_session",
+                "session_in_memory": session_id in session_manager.sessions,
+                "document_access_working": rag_stats.get("total_documents", 0) > 0
+            }
+        }
+        
+        return context_response
+        
+    except Exception as e:
+        logger.error(f"Error getting context for session_id {session_id if 'session_id' in locals() else 'unknown'}: {str(e)}")
+        logger.error(f"Chat session ID: {chat_session_id}")
+        import traceback
+        logger.error(f"Full traceback: {traceback.format_exc()}")
+        
+        return {
+            "session_id": session_id if 'session_id' in locals() else None,
+            "chat_session_id": chat_session_id,
+            "messages": [], 
+            "rag_info": {"total_documents": 0, "total_chunks": 0, "documents": []},
+            "context_stats": {
+                "message_count": 0,
+                "user_messages": 0,
+                "uploaded_files": [],
+                "total_upload_size": 0
+            },
+            "error": str(e),
+            "debug_info": {
+                "error_occurred": True,
+                "error_type": type(e).__name__
+            }
+        }
+
+@router.post("/reset-session")
+async def reset_session(
+    reset_request: ResetSessionRequest,
+    request: Request,
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Reset session - ENHANCED
+    Now properly handles different reset scenarios
+    """
+    try:
+        if reset_request.force_new:
+            # Force create a completely new session
+            session_id = session_manager.create_session()
+            session = session_manager.get_session(session_id)
+            session.clear_all_data()
+            
+            logger.info(f"Force created new session: {session_id}")
+            
+            return {
+                "status": "reset", 
+                "message": "New session created with fresh context",
+                "session_id": session_id,
+                "chat_session_id": None
+            }
+        
+        elif reset_request.chat_session_id:
+            # Reset a specific chat session context
+            session_id = f"chat_{reset_request.chat_session_id}"
+            
+            if session_id in session_manager.sessions:
+                success = session_manager.reset_session_completely(session_id)
+                message = "Chat session context reset successfully" if success else "Failed to reset chat session context"
+            else:
+                # Create fresh context for this chat
+                session = session_manager.get_session(session_id)
+                session.clear_all_data()
+                success = True
+                message = "Fresh context created for chat session"
+            
+            logger.info(f"Reset chat session {reset_request.chat_session_id}, memory session: {session_id}")
+            
+            return {
+                "status": "reset" if success else "error",
+                "message": message,
+                "session_id": session_id,
+                "chat_session_id": reset_request.chat_session_id
+            }
+        
+        else:
+            # Reset current session
+            session_id = await get_or_create_session_for_request_async(request)
+            success = session_manager.reset_session_completely(session_id)
+            
+            logger.info(f"Reset current session: {session_id}")
+            
+            return {
+                "status": "reset" if success else "error",
+                "message": "Current session reset successfully" if success else "Failed to reset current session",
+                "session_id": session_id
+            }
+            
+    except Exception as e:
+        logger.error(f"Error resetting session: {e}")
+        return {"status": "error", "message": f"Failed to reset session: {str(e)}"}
+
+@router.get("/session-stats")
+async def get_session_stats(
+    request: Request,
+    chat_session_id: Optional[str] = None,
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Get session statistics - ENHANCED
+    Now provides detailed stats for different session types
+    """
+    try:
+        if chat_session_id:
+            # Stats for specific chat session
+            session_id = f"chat_{chat_session_id}"
+        else:
+            # Stats for current session
+            session_id = await get_or_create_session_for_request_async(request)
+        
+        stats = session_manager.get_session_stats(session_id)
+        
+        # Add additional context
+        stats["session_type"] = "chat_session" if chat_session_id else "current_session"
+        stats["chat_session_id"] = chat_session_id
+        
+        return stats
+        
+    except Exception as e:
+        logger.error(f"Error getting session stats: {str(e)}")
+        return {"error": str(e)}
+
+@router.get("/active-sessions")
+async def get_active_sessions(current_user: User = Depends(get_current_active_user)):
+    """
+    Get all active sessions for debugging
+    """
+    try:
+        active_count = session_manager.get_active_session_count()
+        
+        # Get overview of sessions (don't return full content for privacy)
+        session_overview = {}
+        for session_id, session in session_manager.sessions.items():
+            session_overview[session_id] = {
+                "message_count": len(session.messages),
+                "uploaded_files": len(session.uploaded_files),
+                "created_at": session.created_at.isoformat(),
+                "last_accessed": session.last_accessed.isoformat(),
+                "is_chat_session": session_id.startswith("chat_")
+            }
+        
+        return {
+            "active_session_count": active_count,
+            "sessions": session_overview
+        }
+        
+    except Exception as e:
+        logger.error(f"Error getting active sessions: {str(e)}")
+        return {"error": str(e)}
+
+@router.post("/cleanup-sessions")
+async def cleanup_expired_sessions(current_user: User = Depends(get_current_active_user)):
+    """
+    Manually trigger session cleanup
+    """
+    try:
+        initial_count = session_manager.get_active_session_count()
+        
+        # Force cleanup
+        session_manager._cleanup_expired_sessions()
+        
+        final_count = session_manager.get_active_session_count()
+        cleaned_count = initial_count - final_count
+        
+        return {
+            "status": "success",
+            "message": f"Cleaned up {cleaned_count} expired sessions",
+            "sessions_before": initial_count,
+            "sessions_after": final_count
+        }
+        
+    except Exception as e:
+        logger.error(f"Error during session cleanup: {str(e)}")
+        return {"status": "error", "message": str(e)}

multi_llm_chatbot_backend/app/api/routes/user_profile.py

@@ -0,0 +1,201 @@
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from app.core.auth import get_current_active_user
+from app.core.database import get_database
+from app.models.user import User
+from app.models.user_profile import UserProfileResponse, UserProfileUpdate
+
+LOG = logging.getLogger(__name__)
+
+router = APIRouter()
+
+PROFILE_FIELDS = [
+    "knowledge_level",
+    "timezone",
+    "cyber_role",
+    "organization_type",
+    "primary_domains",
+    "certifications",
+    "tools_stack",
+    "compliance_focus",
+    "current_goals",
+    "learning_preferences",
+]
+
+LIST_FIELDS = {"primary_domains", "certifications", "tools_stack"}
+
+_SELECT_OPTIONS: Dict[str, List[str]] = {
+    # NOTE: field keys are kept generic (cyber_role / organization_type) for
+    # storage compatibility; the labels/options are themed for the panel.
+    "cyber_role": [
+        "Internship search",
+        "Full-time / entry-level",
+        "Both internship and FT",
+        "Career exploration",
+        "Return offer conversion",
+        "Industry switch / pivot",
+        "Graduate school path",
+        "Other",
+    ],
+    "organization_type": [
+        "Handshake",
+        "LinkedIn",
+        "Company career pages",
+        "Career fairs / campus recruiting",
+        "Referrals / alumni",
+        "Hybrid (multiple channels)",
+    ],
+}
+
+
+def _is_field_filled(value: Any) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, str):
+        return bool(value.strip())
+    if isinstance(value, list):
+        return len(value) > 0
+    return bool(value)
+
+
+def enrich_profile_from_user(
+    doc: Optional[Dict[str, Any]], user: User
+) -> Dict[str, Any]:
+    """Merge account signup fields into the profile when profile slots are empty."""
+    merged = dict(doc or {})
+    if user.academicStage and not _is_field_filled(merged.get("knowledge_level")):
+        merged["knowledge_level"] = user.academicStage
+    if user.researchArea and not _is_field_filled(merged.get("timezone")):
+        merged["timezone"] = user.researchArea
+    return merged
+
+
+def _calc_completion(doc: Dict[str, Any]) -> int:
+    filled = sum(1 for f in PROFILE_FIELDS if _is_field_filled(doc.get(f)))
+    return int(filled / len(PROFILE_FIELDS) * 100)
+
+
+def _profile_response(doc: Dict[str, Any], user: User) -> UserProfileResponse:
+    enriched = enrich_profile_from_user(doc, user)
+    fields = {k: _normalize_field(k, enriched.get(k)) for k in PROFILE_FIELDS}
+    return UserProfileResponse(
+        user_id=str(enriched.get("user_id", user.id)),
+        **fields,
+        advisor_notes=enriched.get("advisor_notes"),
+        updated_at=enriched.get("updated_at"),
+        completion_pct=_calc_completion(enriched),
+    )
+
+
+_SELECT_LOOKUP: Dict[str, Dict[str, str]] = {
+    field: {opt.lower(): opt for opt in opts}
+    for field, opts in _SELECT_OPTIONS.items()
+}
+
+
+def _normalize_select(key: str, value: str) -> str:
+    lookup = _SELECT_LOOKUP.get(key)
+    if not lookup or not isinstance(value, str):
+        return value
+    v = value.strip()
+    if v.lower() in lookup:
+        return lookup[v.lower()]
+    for canonical_lower, canonical in lookup.items():
+        if canonical_lower in v.lower():
+            return canonical
+    return v
+
+
+def _normalize_field(key: str, value: Any) -> Any:
+    if key in LIST_FIELDS:
+        if isinstance(value, str):
+            return [s.strip() for s in value.split(",") if s.strip()]
+        if isinstance(value, list):
+            return value
+        return []
+    if key in _SELECT_OPTIONS:
+        return _normalize_select(key, value)
+    if isinstance(value, list):
+        return ", ".join(str(v) for v in value if v)
+    return value
+
+
+async def _sync_profile_to_user(user: User, update_data: Dict[str, Any]) -> None:
+    """Keep users.academicStage / researchArea aligned with profile edits."""
+    user_updates: Dict[str, Any] = {}
+    if "knowledge_level" in update_data:
+        user_updates["academicStage"] = update_data["knowledge_level"] or None
+    if "timezone" in update_data:
+        user_updates["researchArea"] = update_data["timezone"] or None
+    if user_updates:
+        db = get_database()
+        await db.users.update_one({"_id": user.id}, {"$set": user_updates})
+
+
+@router.get("/users/me/profile", response_model=UserProfileResponse)
+async def get_my_profile(
+    current_user: User = Depends(get_current_active_user),
+) -> UserProfileResponse:
+    db = get_database()
+    doc = await db.user_profiles.find_one({"user_id": current_user.id})
+    if not doc:
+        doc = {"user_id": current_user.id}
+    return _profile_response(doc, current_user)
+
+
+@router.put("/users/me/profile", response_model=UserProfileResponse)
+async def update_my_profile(
+    updates: UserProfileUpdate,
+    current_user: User = Depends(get_current_active_user),
+) -> UserProfileResponse:
+    db = get_database()
+    update_data = {k: v for k, v in updates.dict().items() if v is not None}
+    update_data["updated_at"] = datetime.utcnow()
+    await db.user_profiles.update_one(
+        {"user_id": current_user.id},
+        {"$set": update_data, "$setOnInsert": {"user_id": current_user.id}},
+        upsert=True,
+    )
+    await _sync_profile_to_user(current_user, update_data)
+    doc = await db.user_profiles.find_one({"user_id": current_user.id}) or {
+        "user_id": current_user.id
+    }
+    return _profile_response(doc, current_user)
+
+
+class ClearDataRequest(BaseModel):
+    profile: bool = False
+    chats: bool = False
+    canvas: bool = False
+
+
+@router.post("/users/me/clear-data")
+async def clear_user_data(
+    req: ClearDataRequest,
+    current_user: User = Depends(get_current_active_user),
+) -> Dict[str, List[str]]:
+    db = get_database()
+    cleared: List[str] = []
+
+    if req.profile:
+        await db.user_profiles.delete_many({"user_id": current_user.id})
+        await db.onboarding_conversations.delete_many({"user_id": current_user.id})
+        cleared.append("profile")
+
+    if req.chats:
+        result = await db.chat_sessions.update_many(
+            {"user_id": current_user.id, "is_active": True},
+            {"$set": {"is_active": False, "updated_at": datetime.utcnow()}},
+        )
+        cleared.append(f"chats ({result.modified_count})")
+
+    if req.canvas:
+        await db.phd_canvases.delete_many({"user_id": str(current_user.id)})
+        cleared.append("canvas")
+
+    return {"cleared": cleared}

multi_llm_chatbot_backend/app/api/routes/voice.py

@@ -0,0 +1,270 @@
+import asyncio
+import html as html_module
+import logging
+import re
+import struct
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Dict, List, Optional
+from urllib.parse import quote
+
+import httpx
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
+from fastapi.responses import Response
+from pydantic import BaseModel
+
+from app.core.auth import get_current_active_user
+from app.models.user import User
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+voice_settings = get_settings().voice
+TTS_BASE = voice_settings.tts_endpoint
+STT_BASE = voice_settings.stt_endpoint
+
+HTTP_TIMEOUT = 120
+# Coqui uses GET /synthesize/{text}; keep chunks small for URL limits.
+MAX_SYNTH_CHUNK = 200
+
+_SECTION_HEADERS = re.compile(
+    r"\b(Thought|What to do|Next step)\s*[:.]?\s*", flags=re.IGNORECASE
+)
+
+
+class TTSRequest(BaseModel):
+    text: str
+
+
+def _rough_spoken_text(raw: str) -> str:
+    """Light cleanup so model markdown is tolerable for TTS (no extra deps)."""
+    t = raw.strip()
+    t = re.sub(r"```[\s\S]*?```", " ", t)
+    t = re.sub(r"`([^`]+)`", r"\1", t)
+    t = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", t)
+    t = re.sub(r"!\[([^\]]*)\]\([^)]+\)", r"\1", t)
+    t = re.sub(r"^#{1,6}\s+", "", t, flags=re.MULTILINE)
+    t = re.sub(r"[*_]{1,3}", "", t)
+    t = html_module.unescape(t)
+    t = _SECTION_HEADERS.sub(" ", t)
+    t = re.sub(r"\s+", " ", t).strip()
+    return t
+
+
+def _text_chunks(text: str, max_len: int = MAX_SYNTH_CHUNK) -> List[str]:
+    text = text.strip()
+    if not text:
+        return []
+    out: List[str] = []
+    while text:
+        if len(text) <= max_len:
+            out.append(text)
+            break
+        cut = text.rfind(" ", 0, max_len)
+        if cut <= 0:
+            cut = max_len
+        piece = text[:cut].strip()
+        if piece:
+            out.append(piece)
+        text = text[cut:].strip()
+    return out
+
+
+async def _synthesize_one(client: httpx.AsyncClient, chunk: str) -> Optional[bytes]:
+    url = f"{TTS_BASE}/synthesize/{quote(chunk, safe='')}"
+    try:
+        r = await client.get(url)
+        r.raise_for_status()
+        return r.content
+    except Exception as exc:
+        logger.warning("TTS chunk failed (%s chars): %s", len(chunk), exc)
+        return None
+
+
+def _concat_wav(segments: List[bytes]) -> bytes:
+    if len(segments) == 1:
+        return segments[0]
+
+    pcm_parts: List[bytes] = []
+    first_header = b""
+
+    for i, seg in enumerate(segments):
+        # PCM WAV files begin with a 44-byte header; if the segment is shorter,
+        # then it cannot be valid WAV audio
+        if len(seg) < 44:
+            continue
+        if i == 0:
+            first_header = seg[:44]
+        data_offset = 44
+        idx = seg.find(b"data")
+        if idx != -1 and idx + 8 <= len(seg):
+            data_offset = idx + 8
+        pcm_parts.append(seg[data_offset:])
+
+    if not pcm_parts or not first_header:
+        return segments[0] if segments else b""
+
+    all_pcm = b"".join(pcm_parts)
+    pcm_len = len(all_pcm)
+
+    header = bytearray(first_header)
+    struct.pack_into("<I", header, 4, pcm_len + 36)
+    struct.pack_into("<I", header, 40, pcm_len)
+    return bytes(header) + all_pcm
+
+
+def _convert_to_wav(audio_bytes: bytes, src_mime: str) -> bytes:
+    with tempfile.TemporaryDirectory() as tmp:
+        ext = "webm" if "webm" in (src_mime or "") else "ogg"
+        src = Path(tmp) / f"in.{ext}"
+        dst = Path(tmp) / "out.wav"
+        src.write_bytes(audio_bytes)
+        result = subprocess.run(
+            [
+                "ffmpeg",
+                "-y",
+                "-i",
+                str(src),
+                "-ar",
+                "16000",
+                "-ac",
+                "1",
+                "-f",
+                "wav",
+                str(dst),
+            ],
+            capture_output=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            logger.warning(
+                "ffmpeg stderr: %s",
+                result.stderr.decode(errors="replace")[-500:],
+            )
+            raise RuntimeError("ffmpeg conversion failed")
+        return dst.read_bytes()
+
+
+@router.get("/voice/status")
+async def voice_status(
+    current_user: User = Depends(get_current_active_user),
+) -> Dict[str, bool]:
+    tts_ready = False
+    stt_ready = False
+    async with httpx.AsyncClient(timeout=5) as client:
+        if TTS_BASE not in ("", None):
+            try:
+                resp = await client.get(f"{TTS_BASE}/status")
+                tts_ready = resp.status_code == 200
+            except Exception:
+                tts_ready = False
+        if STT_BASE not in ("", None):
+            try:
+                resp = await client.get(f"{STT_BASE}/status")
+                stt_ready = resp.status_code == 200
+            except Exception:
+                stt_ready = False
+    return {"tts_ready": tts_ready, "stt_ready": stt_ready}
+
+
+@router.post("/voice/transcribe")
+async def transcribe_audio(
+    audio: UploadFile = File(...),
+    current_user: User = Depends(get_current_active_user),
+) -> Dict[str, str]:
+    """
+    Transcribe an uploaded audio file and return the text.
+    @param audio: The uploaded audio file (from a browser recording)
+    @param current_user: The authenticated user making the request
+    @return: A dictionary with the transcribed text under key "text"
+    """
+    contents = await audio.read()
+    if not contents:
+        return {"text": ""}
+
+    mime = audio.content_type or "audio/webm"
+    logger.info("STT: received %s bytes (%s)", len(contents), mime)
+
+    need_convert = "wav" not in mime.lower()
+    if need_convert:
+        try:
+            loop = asyncio.get_running_loop()
+            wav_bytes = await loop.run_in_executor(
+                None, _convert_to_wav, contents, mime
+            )
+            logger.info("STT: converted to WAV (%s bytes)", len(wav_bytes))
+        except Exception as e:
+            logger.error("STT conversion error: %s", e)
+            raise HTTPException(status_code=500, detail="Audio conversion failed")
+    else:
+        wav_bytes = contents
+
+    try:
+        async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
+            resp = await client.post(
+                f"{STT_BASE}/stt",
+                content=wav_bytes,
+                headers={"Content-Type": "audio/wav"},
+            )
+            resp.raise_for_status()
+            text = resp.text.strip().strip('"')
+            logger.info("STT result: %r", text[:100])
+            return {"text": text}
+    except httpx.TimeoutException:
+        raise HTTPException(status_code=504, detail="STT service timed out")
+    except Exception as e:
+        logger.error("STT proxy error: %s", e)
+        raise HTTPException(status_code=502, detail="STT service unavailable")
+
+
+@router.post("/voice/tts")
+async def text_to_speech(
+    req: TTSRequest,
+    current_user: User = Depends(get_current_active_user),
+) -> Response:
+    """
+    Generate spoken audio for the input text
+    @param req: A TTSRequest containing the text to synthesize
+    @param current_user: The authenticated user making the request
+    @return: A Response containing the synthesized audio in WAV format
+    """
+    raw = req.text.strip()
+    if not raw:
+        raise HTTPException(status_code=400, detail="Text is required")
+
+    if len(raw) > 5000:
+        raw = raw[:5000]
+
+    spoken = _rough_spoken_text(raw)
+    chunks = _text_chunks(spoken)
+    logger.info(
+        "TTS: %s chunk(s) from %s input chars → %s spoken chars",
+        len(chunks),
+        len(req.text),
+        len(spoken),
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
+            results = await asyncio.gather(
+                *[_synthesize_one(client, c) for c in chunks]
+            )
+            wav_segments = [r for r in results if r and len(r) > 44]
+
+            if not wav_segments:
+                raise HTTPException(
+                    status_code=502, detail="TTS synthesis failed for all chunks"
+                )
+
+            combined = _concat_wav(wav_segments)
+            return Response(content=combined, media_type="audio/wav")
+    except HTTPException:
+        raise
+    except httpx.TimeoutException:
+        raise HTTPException(status_code=504, detail="TTS service timed out")
+    except Exception as e:
+        logger.error("TTS proxy error: %s", e)
+        raise HTTPException(status_code=502, detail="TTS service unavailable")

multi_llm_chatbot_backend/app/api/utils.py

@@ -0,0 +1,140 @@
+from typing import Optional
+from fastapi import Request
+from app.core.session_manager import get_session_manager
+from app.core.database import get_database
+from bson import ObjectId
+import logging
+
+logger = logging.getLogger(__name__)
+session_manager = get_session_manager()
+
+async def load_chat_session_into_context(chat_session_id: str, user_id: str) -> str:
+    """
+    Load a chat session from MongoDB into memory context - ENHANCED DEBUG VERSION
+    """
+    try:
+        db = get_database()
+        
+        # Add enhanced debugging
+        logger.info(f"=== LOADING CHAT SESSION DEBUG ===")
+        logger.info(f"Attempting to load chat_session_id: {chat_session_id}")
+        logger.info(f"For user_id: {user_id}")
+        
+        # Try to find the session with enhanced debugging
+        chat_session = await db.chat_sessions.find_one({
+            "_id": ObjectId(chat_session_id),
+            "user_id": ObjectId(user_id),
+            "deleted_at": {"$exists": False}
+        })
+        
+        if not chat_session:
+            logger.warning(f"Chat session {chat_session_id} not found for user {user_id}")
+            
+            # Debug: Check if session exists for any user
+            try:
+                session_exists = await db.chat_sessions.find_one({"_id": ObjectId(chat_session_id)})
+                if session_exists:
+                    logger.warning(f"Session exists but for different user: {session_exists.get('user_id')}")
+                    logger.warning(f"Expected user: {user_id}")
+                    logger.warning(f"Session user: {session_exists.get('user_id')}")
+                    logger.warning(f"User ID types - Expected: {type(user_id)}, Found: {type(session_exists.get('user_id'))}")
+                else:
+                    logger.warning(f"Session {chat_session_id} does not exist in database at all")
+            except Exception as debug_error:
+                logger.error(f"Error during session debug: {debug_error}")
+            
+            # Debug: List recent sessions for this user
+            try:
+                recent_sessions = await db.chat_sessions.find(
+                    {"user_id": ObjectId(user_id), "deleted_at": {"$exists": False}}
+                ).limit(5).to_list(5)
+                logger.info(f"Recent sessions for user {user_id}: {[str(s['_id']) for s in recent_sessions]}")
+            except Exception as debug_error:
+                logger.error(f"Error listing recent sessions: {debug_error}")
+            
+            return None
+
+        logger.info(f"✅ Found chat session: {chat_session.get('title', 'Untitled')}")
+        logger.info(f"✅ Message count: {len(chat_session.get('messages', []))}")
+        
+        # Create consistent memory session ID  
+        memory_session_id = f"chat_{chat_session_id}"
+        logger.info(f"✅ Creating memory session: {memory_session_id}")
+        
+        # Get session manager and create memory session
+        session_manager = get_session_manager()
+        memory_session = session_manager.get_session(memory_session_id)
+        
+        # Clear any existing data
+        memory_session.clear_all_data()
+        
+        # Load messages into memory session
+        messages = chat_session.get('messages', [])
+        for msg_data in messages:
+            try:
+                msg_type = msg_data.get('type', '')
+                if msg_type == 'user':
+                    role = 'user'
+                elif msg_type == 'advisor':
+                    role = msg_data.get('persona_id') or 'assistant'
+                else:
+                    role = 'assistant'
+                message = {
+                    'id': msg_data.get('id', 'unknown'),
+                    'role': role,
+                    'content': msg_data.get('content', ''),
+                    'timestamp': msg_data.get('timestamp', '')
+                }
+                memory_session.append_message(message['role'], message['content'])
+                
+                # Store original message for export
+                if not hasattr(memory_session, 'original_messages'):
+                    memory_session.original_messages = []
+                
+                memory_session.original_messages.append(message)
+            except Exception as msg_error:
+                logger.error(f"Error loading message: {msg_error}")
+                continue
+        
+        logger.info(f"Loaded {len(messages)} messages into session {memory_session_id}")
+        return memory_session_id
+        
+    except Exception as e:
+        logger.error(f"Error loading chat session into context: {e}")
+        import traceback
+        logger.error(f"Full traceback: {traceback.format_exc()}")
+        return None
+
+async def get_or_create_session_for_request_async(
+    request: Request, 
+    session_id_override: Optional[str] = None,
+    chat_session_id: Optional[str] = None,
+    user_id: Optional[str] = None
+) -> str:
+    """
+    Async version that properly handles chat session loading
+    """
+    
+    # Case 1: Loading an existing chat session
+    if chat_session_id and user_id:
+        memory_session_id = f"chat_{chat_session_id}"
+        loaded = await load_chat_session_into_context(chat_session_id, user_id)
+        if loaded:
+            return loaded
+        # Keep a stable session id even when MongoDB load fails (e.g. race on first message)
+        session_manager.get_session(memory_session_id)
+        return memory_session_id
+    
+    # Case 2: Explicit session ID provided
+    if session_id_override:
+        return session_id_override
+
+    # Case 3: Check for session header
+    session_header = request.headers.get("X-Session-ID")
+    if session_header:
+        return session_header
+
+    # Case 4: Create a truly new session
+    new_session_id = session_manager.create_session()
+    logger.info(f"Created new session: {new_session_id}")
+    return new_session_id

multi_llm_chatbot_backend/app/config.py

@@ -0,0 +1,519 @@
+"""
+Centralized application configuration.
+
+Reads ``config.yaml`` from the project root (two levels above this file) and
+validates it with Pydantic models.  Every setting falls back to environment
+variables when the YAML value is empty, so existing ``.env`` workflows keep
+working.
+"""
+
+import os
+import logging
+import colorsys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from colorhash import ColorHash
+
+import httpx
+import yaml
+from pydantic import BaseModel, validator, Field, model_validator
+
+from app.utils.avatar_helpers import get_bundled_avatar_path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Pydantic models
+# ---------------------------------------------------------------------------
+
+class _IconValidatorMixin(BaseModel):
+    """Validates that the ``icon`` field is a known Lucide icon name."""
+
+    @model_validator(mode="after")
+    def _validate_icon(self):
+        from app.utils.lucide_icons import get_valid_icon_names
+
+        valid = get_valid_icon_names()
+        if valid and self.icon not in valid:
+            raise ValueError(
+                f"Unknown icon {self.icon!r}. "
+                f"Must be a valid Lucide icon name."
+            )
+        return self
+
+
+class FeatureConfig(_IconValidatorMixin):
+    title: str = ""
+    description: str = ""
+    icon: str = "HelpCircle"
+
+
+class UserAvatarOption(BaseModel):
+    id: str
+    icon: str = "User"
+    color: str = "#2563EB"
+    bg: str = "#EFF6FF"
+
+
+class AppConfig(BaseModel):
+    title: str = "Advisor Canvas"
+    subtitle: str = "AI-Powered Guidance"
+    primary_color: str = "#7C3AED"
+    logo_icon: str = "Users"
+    footer_text: str = ""
+    user_avatars: List[UserAvatarOption] = []
+
+
+class HomepageConfig(BaseModel):
+    headline_prefix: str = "Get Guidance from"
+    headline_highlight: str = "Advisor Personas"
+    description: str = ""
+    features_title: str = "Why Choose Our Advisory Panel?"
+    features: List[FeatureConfig] = []
+
+
+class AcademicStage(BaseModel):
+    value: str = ""
+    label: str = ""
+
+
+class LoginConfig(BaseModel):
+    subtitle: str = "Sign in to continue"
+    signup_subtitle: str = "Create your account to get personalized guidance from expert advisors"
+    academic_stages: List[AcademicStage] = []
+    knowledge_levels: List[AcademicStage] = []
+    timezones: List[AcademicStage] = []
+
+
+class ExampleCategory(_IconValidatorMixin):
+    title: str
+    icon: str = "BookOpen"
+    color: str = "#3B82F6"
+    bg_color: str = "#EFF6FF"
+    suggestions: List[str] = []
+
+
+class ChatPageConfig(BaseModel):
+    placeholder: str = "Ask your advisors anything..."
+    examples: List[ExampleCategory] = []
+
+
+class PersonaItemConfig(_IconValidatorMixin):
+    id: str
+    name: str
+    enabled: bool = True
+    role: str = ""
+    summary: str = ""
+    color: Optional[str] = None
+    bg_color: Optional[str] = None
+    dark_color: Optional[str] = None
+    dark_bg_color: Optional[str] = None
+    icon: str = "HelpCircle"
+    avatar: Optional[str] = None
+    temperature: int = 5
+    persona_prompt: str = ""
+
+    @model_validator(mode='after')
+    def _auto_generate_colors(self):
+        if self.color is None:
+            generated = generate_persona_colors(self.name)
+            self.color = generated["color"]
+            self.bg_color = generated["bg_color"]
+            self.dark_color = generated["dark_color"]
+            self.dark_bg_color = generated["dark_bg_color"]
+        return self
+
+    def _resolve_image(self) -> str:
+        """Resolve the persona's visual representation as a URI string.
+
+        Returns the avatar as a URI the frontend can dispatch on by scheme:
+
+        - ``https://…`` / ``http://…`` - external image URL
+        - ``/api/avatars/bundled/…`` - server-relative path for a bundled file
+        - ``icon://<LucideIconName>`` - render a Lucide icon component
+
+        Falls back to ``icon://`` when a bundled avatar name doesn't match a
+        file on disk or when an external URL is unreachable.
+        """
+        if self.avatar is None:
+            return f"icon://{self.icon}"
+        if self.avatar.startswith(("http://", "https://")):
+            try:
+                resp = httpx.head(self.avatar, timeout=5, follow_redirects=True)
+                if resp.is_success:
+                    return self.avatar
+                logger.warning(
+                    "Avatar URL %r returned status %d for persona %r, falling back to icon.",
+                    self.avatar, resp.status_code, self.id,
+                )
+            except httpx.HTTPError as exc:
+                logger.warning(
+                    "Avatar URL %r unreachable for persona %r (%s), falling back to icon.",
+                    self.avatar, self.id, exc,
+                )
+            return f"icon://{self.icon}"
+        if get_bundled_avatar_path(self.avatar) is None:
+            logger.warning(
+                "Bundled avatar %r not found for persona %r, falling back to icon.",
+                self.avatar, self.id,
+            )
+            return f"icon://{self.icon}"
+        # Default to empty string (→ relative URL) so single-origin Spaces
+        # deployments serve avatars off the same host as the SPA. Local
+        # ``npm start`` development setups can still set REACT_APP_API_URL
+        # explicitly to point at the backend on a different port.
+        base = os.getenv("REACT_APP_API_URL", "").rstrip("/")
+        return f"{base}/api/avatars/bundled/{self.avatar}"
+
+    def to_frontend_config(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "role": self.role,
+            "summary": self.summary,
+            "color": self.color,
+            "bg_color": self.bg_color,
+            "dark_color": self.dark_color,
+            "dark_bg_color": self.dark_bg_color,
+            "image": self._resolve_image(),
+            }
+
+
+class PersonasConfig(BaseModel):
+    base_prompt: str = ""
+    personas_dir: str = ""
+    config_dir: str = ""
+    items: List[PersonaItemConfig] = []
+
+    @model_validator(mode='after')
+    def _load_personas_from_directory(self):
+        if self.personas_dir:
+            dir_path = Path(self.personas_dir)
+            if not dir_path.is_absolute() and self.config_dir:
+                dir_path = Path(self.config_dir) / dir_path
+            loaded = load_personas_from_dir(str(dir_path))
+            if loaded:
+                self.items = loaded
+                logger.info(f"Loaded {len(loaded)} personas.")
+            else:
+                logger.warning(f"No personas found in {self.personas_dir}. falling back to personas.items config")
+        return self
+
+
+class OrchestratorConfig(BaseModel):
+    min_words_without_keywords: int = 6
+    conversation_history_token_threshold: int = 4000
+    specific_keywords: List[str] = []
+    clarification_questions: List[str] = [
+            "Could you provide more details about what you need help with?"]
+    clarification_suggestions: List[str] = [
+            "Provide more details about your question."]
+
+    @model_validator(mode="after")
+    def validate_clarificaiton_questions(self):
+        if len(self.clarification_questions) < 1:
+            raise ValueError("At least one clarification question is required.")
+        return self
+
+
+def resolve_jwt_secret(explicit: str = "") -> str:
+    """Resolve a stable JWT signing secret across restarts.
+
+    Precedence: config value → JWT_SECRET_KEY env → persisted file under
+    DATA_DIR (generated on first run) → insecure dev fallback.
+    """
+    if explicit and explicit.strip():
+        return explicit.strip()
+
+    env_secret = os.getenv("JWT_SECRET_KEY", "").strip()
+    if env_secret:
+        return env_secret
+
+    data_dir = Path(os.environ.get("DATA_DIR") or Path.home() / "data")
+    secret_path = data_dir / "jwt_secret"
+    try:
+        data_dir.mkdir(parents=True, exist_ok=True)
+        if secret_path.is_file():
+            stored = secret_path.read_text(encoding="utf-8").strip()
+            if stored:
+                return stored
+        import secrets
+
+        generated = secrets.token_urlsafe(48)
+        secret_path.write_text(generated, encoding="utf-8")
+        logger.info("Generated persistent JWT secret at %s", secret_path)
+        return generated
+    except OSError as exc:
+        logger.warning(
+            "Cannot persist JWT secret at %s (%s); using insecure default. "
+            "Set JWT_SECRET_KEY or auth.jwt_secret for production.",
+            secret_path,
+            exc,
+        )
+        return "your-secret-key-change-me"
+
+
+class AuthConfig(BaseModel):
+    jwt_secret: str = Field(default=os.getenv("JWT_SECRET_KEY", ""))
+    algorithm: str = "HS256"
+    token_expiry_minutes: int = 43200  # 30 days
+
+    @model_validator(mode="after")
+    def _validate_jwt_secret(self):
+        self.jwt_secret = resolve_jwt_secret(self.jwt_secret)
+        return self
+
+
+class MongoDBConfig(BaseModel):
+    connection_string: str = Field(default=os.getenv("MONGODB_CONNECTION_STRING")) 
+    database_name: str = "phd_advisor"
+
+    @model_validator(mode="after")
+    def _warn_connection_envvar(self):
+        if os.getenv("MONGODB_CONNECTION_STRING"):
+            if self.connection_string != os.getenv("MONGODB_CONNECTION_STRING"):
+                logger.warning(
+                    "MONGODB_CONNECTION_STRING envvar is overridden in "
+                    "config.yaml"
+                )
+            else:
+                logger.warning(
+                    "MongoDB connection string not set in config.yaml. "
+                    "Falling back to MONGODB_CONNECTION_STRING envvar."
+                )
+        return self
+
+
+class GeminiConfig(BaseModel):
+    api_key: str = Field(default=os.getenv("GEMINI_API_KEY"))
+    model: str = "gemini-2.5-flash"
+
+    @model_validator(mode="after")
+    def _warn_gemini_envvar(self):
+        if os.getenv("GEMINI_API_KEY"):
+            if self.api_key != os.getenv("GEMINI_API_KEY"):
+                logger.warning(
+                    "GEMINI_API_KEY envvar is overridden in config.yaml"
+                )
+            else:
+                logger.warning(
+                    "Gemini API key not set in config.yaml. "
+                    "Falling back to GEMINI_API_KEY environment variable."
+                )
+        return self
+
+
+class OllamaConfig(BaseModel):
+    model: str = "llama3.2:1b"
+    # TODO: Drop support for `OLLAMA_BASE_URL` envvar handling
+    base_url: str = Field(default=os.getenv("OLLAMA_BASE_URL", "http://localhost:11434"))
+
+
+class VllmConfig(BaseModel):
+    api_url: str = ""
+    api_key: str = Field(default=os.getenv("VLLM_API_KEY", ""))
+    api_username: str = Field(default=os.getenv("VLLM_API_USERNAME", ""))
+    model_id: str = ""
+    neon_persona_orchestrator: str = "vanilla"
+    neon_persona_advisors: str = "CybersecurityExpert"
+
+
+class OpenAIConfig(BaseModel):
+    api_key: str = Field(default=os.getenv("OPENAI_API_KEY", ""))
+    model: str = "gpt-5.4"
+    orchestrator_reasoning_effort: str = "low"
+    persona_reasoning_effort: str = "none"
+
+
+class ResilientConfig(BaseModel):
+    race_timeout_seconds: float = 3.0
+
+
+class LLMConfig(BaseModel):
+    provider: str = "gemini"
+    gemini: GeminiConfig = GeminiConfig()
+    ollama: OllamaConfig = OllamaConfig()
+    vllm: VllmConfig = VllmConfig()
+    openai: OpenAIConfig = OpenAIConfig()
+    resilient: ResilientConfig = ResilientConfig()
+
+
+class RAGConfig(BaseModel):
+    embedding_model: str = "all-MiniLM-L6-v2"
+    chroma_collection: str = "phd_advisor_documents"
+
+
+class ToolsConfig(BaseModel):
+    model_config = {"extra": "allow"}
+
+    def get_enabled_names(self) -> List[str]:
+        """Return tool names whose config has ``enabled: true``."""
+        return [
+            name
+            for name, cfg in self.__pydantic_extra__.items()
+            if isinstance(cfg, dict) and cfg.get("enabled", True)
+        ]
+
+    def get_tool_config(self, name: str) -> Dict[str, Any]:
+        """Return the raw config dict for a single tool, or ``{}``."""
+        cfg = self.__pydantic_extra__.get(name, {})
+        return cfg if isinstance(cfg, dict) else {}
+
+
+class VoiceConfig(BaseModel):
+    stt_endpoint: str = "https://whisper.neonaiservices.com"
+    tts_endpoint: str = "https://coqui.neonaiservices.com"
+
+
+class AppSettings(BaseModel):
+    """Top-level container that mirrors the YAML structure."""
+    app: AppConfig = AppConfig()
+    homepage: HomepageConfig = HomepageConfig()
+    login: LoginConfig = LoginConfig()
+    chat_page: ChatPageConfig = ChatPageConfig()
+    personas: PersonasConfig = PersonasConfig()
+    orchestrator: OrchestratorConfig = OrchestratorConfig()
+    auth: AuthConfig = AuthConfig()
+    mongodb: MongoDBConfig = MongoDBConfig()
+    llm: LLMConfig = LLMConfig()
+    rag: RAGConfig = RAGConfig()
+    tools: ToolsConfig = ToolsConfig()
+    voice: VoiceConfig = VoiceConfig()
+
+    # ------------------------------------------------------------------
+    # Convenience helpers
+    # ------------------------------------------------------------------
+
+    def get_frontend_config(self) -> dict:
+        """Return the subset of configuration safe to expose to the frontend
+        via ``GET /api/config``.  Secrets are excluded."""
+        return {
+            "app": self.app.dict(),
+            "homepage": self.homepage.dict(),
+            "login": self.login.dict(),
+            "chat_page": self.chat_page.dict(),
+            "personas": {
+                "items": [p.to_frontend_config() for p in self.personas.items],
+            },
+        }
+
+
+# ---------------------------------------------------------------------------
+# Singleton loader
+# ---------------------------------------------------------------------------
+
+_settings: Optional[AppSettings] = None
+
+
+def load_settings(config_path: Optional[str] = None) -> AppSettings:
+    """Load and validate ``config.yaml``, returning an ``AppSettings`` object.
+
+    The result is cached as a module-level singleton so subsequent calls are
+    free.  Pass *config_path* to override the auto-detected location (useful
+    for tests).
+    """
+    global _settings
+    if _settings is not None:
+        return _settings
+
+    config_path = config_path or os.getenv("CONFIG_PATH")
+    if not config_path:
+        logger.warning("No CONFIG_PATH specified. Using default values")
+        raw = {}
+    else:
+        path = Path(config_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Configuration file not found at {config_path}")
+        logger.info(f"Loading configuration from {path}")
+        with open(path, "r", encoding="utf-8") as fh:
+            raw = yaml.safe_load(fh) or {}
+
+    personas_cfg = raw.setdefault("personas", {})
+
+    if config_path:
+        personas_cfg["config_dir"] = str(Path(config_path).parent)
+
+    _settings = AppSettings(**raw)
+    logger.info(f"Configuration loaded: app.title={_settings.app.title}")
+    return _settings
+
+
+def get_settings() -> AppSettings:
+    """Return the cached settings singleton (loads on first call)."""
+    return load_settings()
+
+
+# ---------------------------------------------------------------------------
+# Helper Functions
+# ---------------------------------------------------------------------------
+
+
+def load_personas_from_dir(personas_dir: str) -> List[PersonaItemConfig]:
+    """Load persona configs from individual YAML files in a directory.
+    
+    Each file is validated independently — invalid files are skipped with a
+    warning.  Duplicate ids/names and disabled personas are filtered out.
+    """
+
+    dir_path = Path(personas_dir)
+    if not dir_path.is_dir():
+        logger.warning(f"Personas directory not found: {personas_dir}")
+        return []
+
+    personas: List[PersonaItemConfig] = []
+    seen_ids: dict[str, str] = {}     # id -> filename that defined it
+    seen_names: dict[str, str] = {}   # name -> filename that defined it
+
+    # sorting files alphabetically ensures consistent and predictable loading order
+    for filepath in sorted(dir_path.glob("*.yaml")):
+        try:
+            with open(filepath, "r", encoding="utf-8") as fh:
+                raw = yaml.safe_load(fh) or {}
+            persona = PersonaItemConfig(**raw)
+        except Exception as exc:
+            logger.warning(f"Skipping invalid persona file {filepath.name}: {exc}")
+            continue
+
+        if not persona.enabled:
+            logger.info(f"Persona '{persona.id}' is disabled, skipping")
+            continue
+
+        if persona.id in seen_ids:
+            logger.warning(
+                f"Duplicate persona id '{persona.id}' in {filepath.name} "
+                f"(already defined in {seen_ids[persona.id]}), skipping"
+            )
+            continue
+
+        if persona.name in seen_names:
+            logger.warning(
+                f"Duplicate persona name '{persona.name}' in {filepath.name} "
+                f"(already defined in {seen_names[persona.name]}), skipping"
+            )
+            continue
+
+        seen_ids[persona.id] = filepath.name
+        seen_names[persona.name] = filepath.name
+        personas.append(persona)
+
+    logger.info(f"Loaded {len(personas)} persona(s) from {personas_dir}")
+    return personas
+
+
+def generate_persona_colors(name: str) -> dict:
+    """Deterministically generate four theme colors from a persona name."""
+
+    ch = ColorHash(name.lower(), lightness=[0.55], saturation=[0.65])
+    hue = ch.hsl[0]  # grab the hue colorhash picked
+    h = hue / 360
+
+    def hsl_to_hex(h, s, l):
+        r, g, b = colorsys.hls_to_rgb(h, l, s)
+        return f"#{int(r*255):02X}{int(g*255):02X}{int(b*255):02X}"
+
+    return {
+        "color":         hsl_to_hex(h, 0.65, 0.55),
+        "bg_color":      hsl_to_hex(h, 0.60, 0.95),
+        "dark_color":    hsl_to_hex(h, 0.70, 0.70),
+        "dark_bg_color": hsl_to_hex(h, 0.65, 0.25),
+    }

multi_llm_chatbot_backend/app/core/README.md

@@ -0,0 +1,200 @@
+# `app/core` – Application Core Logic
+
+This is the **central brain** of the multi-LLM chatbot system. It orchestrates user interaction, persona logic, context management, document-based retrieval (RAG), session tracking, authentication, and initialization.
+
+---
+
+## Overview of Modules
+
+| Module | Responsibility |
+|--------|----------------|
+| `auth.py` | Authentication (JWT, password hashing, user resolution) |
+| `bootstrap.py` | System startup logic: loads LLMs, personas, orchestrators |
+| `context.py` | Global per-session context (simplified storage) |
+| `context_manager.py` | Core context formatting & windowing for Gemini/Ollama |
+| `database.py` | MongoDB connection & index management |
+| `improved_orchestrator.py` | Main message routing engine: document-aware, multi-persona orchestrator |
+| `rag_manager.py` | RAG with ChromaDB: chunking, storage, semantic search |
+| `session_manager.py` | Full chat lifecycle tracker (in-memory) with RAG hooks |
+
+---
+
+## `auth.py` – Authentication System
+
+Handles secure authentication via:
+- Bcrypt hashing (`passlib`)
+- JWT creation and validation (`python-jose`)
+- Secure route access using FastAPI’s `Depends`
+
+### Functions
+
+- `get_password_hash(password)` – Hash password using bcrypt
+- `verify_password(plain, hashed)` – Verify password
+- `create_access_token(data)` – Return JWT (30-day expiry default)
+- `get_current_user()` – Decodes token and returns `User` model
+- `authenticate_user(email, password)` – Checks login credentials
+- `create_user_response(user)` – Returns `UserResponse` for frontend
+
+---
+
+## `bootstrap.py` – System Bootstrap
+
+Runs once on app startup to:
+- Determine the default LLM provider (Gemini or Ollama)
+- Initialize `ImprovedChatOrchestrator`
+- Inject personas using `get_default_personas(llm)`
+
+```python
+llm = create_llm_client()  # Gemini or Ollama
+chat_orchestrator = ImprovedChatOrchestrator()
+DEFAULT_PERSONAS = get_default_personas(llm)
+```
+
+Each persona is **registered** into the orchestrator using `.register_persona()`.
+
+---
+
+## `context.py` – Global Per-Session Context
+
+A basic context storage class (`GlobalSessionContext`) that keeps:
+- `full_log`: List of all messages
+- `uploaded_files`: Tracked files per session
+- `total_upload_size`: Helps enforce limits
+
+Used primarily in earlier versions or smaller contexts.
+
+---
+
+## `context_manager.py` – LLM Context Window Formatter
+
+This class builds optimized context windows for both Gemini and Ollama:
+
+### `ContextManager.prepare_context_for_llm()`
+Returns a `ContextWindow(messages, token_count, truncated)` with:
+- LLM-specific formatting
+- Automatic message pruning based on token limits
+- Recency- and relevance-weighted scoring for old messages
+- Automatic stop tokens, system prompts, and formatting
+
+### Key Features
+
+| Feature | Gemini | Ollama |
+|--------|--------|--------|
+| Format | JSON roles + parts | Flat prompt string |
+| Role Mapping | 'user', 'model' | 'User:', 'Assistant:' |
+| Chunking Strategy | Full doc as `Context Document:` | Plain text injection |
+| Stop Sequences | Customizable | Enforced via `stop[]` |
+
+Used **by all LLM clients** (Ollama/Gemini) and the **orchestrator**.
+
+---
+
+## `database.py` – MongoDB Connector
+
+- Uses `motor` for async MongoDB
+- Exposes `get_database()` to other modules
+- Automatically creates indexes on `users` and `chat_sessions`
+- Controlled via `.env` (`MONGODB_CONNECTION_STRING`)
+
+```python
+await connect_to_mongo()
+await close_mongo_connection()
+```
+
+---
+
+## `improved_orchestrator.py` – Brain of the Chatbot
+
+This is the main **message routing engine**.
+
+### Main Responsibilities
+
+- Route user input through:
+  - Clarification detection
+  - Document-aware context building
+  - Persona-level response generation
+- Aggregate responses from **multiple advisors**
+- Embed document-based context (RAG)
+
+### Key Functions
+
+- `process_message()` – Entry point for chat flow (calls all advisors)
+- `chat_with_persona()` – Talk to one specific advisor
+- `_generate_persona_responses()` – Routes through each registered persona
+- `_build_enhanced_context_for_persona()` – Combines conversation + document info
+
+### Extras
+- Document parsing hints (`"my thesis"`, `"section 2"`, etc.)
+- Top-K persona ranking (`get_top_personas()`)
+- Persona-specific fallback logic
+- Session reset/deletion
+
+Used by `/chat-stream`, `/reply-to-advisor`, etc.
+
+---
+
+## `rag_manager.py` – RAG System for Docs
+
+Supports **vector-based retrieval** using:
+
+- Sentence Transformers (`all-MiniLM-L6-v2`)
+- ChromaDB (`PersistentClient` with metadata)
+- Metadata-aware enhanced chunking
+- Overlapping token window strategy
+- Section-wise classification
+
+### Core Components
+
+| Class | Role |
+|-------|------|
+| `RAGManager` | Standard chunking, basic RAG |
+| `EnhancedRAGManager` | Persona-aware + metadata-annotated vector chunks |
+
+### `EnhancedRAGManager` supports:
+- Section tagging (`methodology`, `theory`, etc.)
+- Multi-level filters (`session_id`, `filename`)
+- Attribution fields (`chunk_position`, `has_methodology`)
+- Relevance scoring and ranking
+
+Used by orchestrator when generating document-aware responses.
+
+---
+
+## `session_manager.py` – Chat Lifecycle Controller
+
+Handles:
+- In-memory session creation + cleanup (with expiration)
+- Tracks uploaded files and size
+- Holds message logs for each session
+- Links to RAG via `add_uploaded_file()` and `get_rag_stats()`
+
+### `ConversationContext`
+
+| Attribute | Description |
+|-----------|-------------|
+| `messages` | List of role-message entries |
+| `uploaded_files` | Filenames (content stored in RAG DB) |
+| `document_chunks_count` | Count of indexed doc chunks |
+| `last_retrieval_stats` | From last RAG search |
+| `created_at`, `last_accessed` | Session activity tracking |
+
+Includes:
+- Reset functions (`clear_all_data()`)
+- File-level message logging (`append_message()`)
+
+### `SessionManager`
+
+- Thread-safe via locks
+- Handles cleanup of expired sessions (`_cleanup_expired_sessions()`)
+- Returns statistics via `get_session_stats()`
+
+---
+
+## Interactions Summary
+
+```text
+User Input → Orchestrator
+             ↳ SessionManager → Context
+             ↳ RAGManager → Relevant Docs
+             ↳ LLMClient (Gemini/Ollama) ← ContextManager
+```

multi_llm_chatbot_backend/app/core/auth.py

@@ -0,0 +1,119 @@
+import os
+from datetime import datetime, timedelta
+from typing import Optional
+from fastapi import HTTPException, Depends, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from passlib.context import CryptContext
+from jose import JWTError, jwt
+from bson import ObjectId
+from app.core.database import get_database
+from app.models.user import User, UserResponse
+from app.config import get_settings
+
+# Password hashing
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# JWT settings — driven by config.yaml with env-var fallback
+_cfg = get_settings().auth
+SECRET_KEY = _cfg.jwt_secret
+ALGORITHM = _cfg.algorithm
+ACCESS_TOKEN_EXPIRE_MINUTES = _cfg.token_expiry_minutes
+
+# Security scheme
+security = HTTPBearer()
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash"""
+    return pwd_context.verify(plain_password, hashed_password)
+
+def get_password_hash(password: str) -> str:
+    """Hash a password"""
+    return pwd_context.hash(password)
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
+    """Create a JWT access token"""
+    to_encode = data.copy()
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+
+    # JWT NumericDate must be a Unix timestamp (RFC 7519).
+    to_encode.update({"exp": int(expire.timestamp())})
+    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+    return encoded_jwt
+
+async def get_user_by_email(email: str) -> Optional[User]:
+    """Get user by email from database"""
+    db = get_database()
+    user_data = await db.users.find_one({"email": email})
+    if user_data:
+        return User(**user_data)
+    return None
+
+async def get_user_by_id(user_id: str) -> Optional[User]:
+    """Get user by ID from database"""
+    try:
+        db = get_database()
+        user_data = await db.users.find_one({"_id": ObjectId(user_id)})
+        if user_data:
+            return User(**user_data)
+        return None
+    except Exception:
+        return None
+
+async def authenticate_user(email: str, password: str) -> Optional[User]:
+    """Authenticate user with email and password"""
+    user = await get_user_by_email(email)
+    if not user:
+        return None
+    if not verify_password(password, user.hashed_password):
+        return None
+    return user
+
+async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)) -> User:
+    """Get current user from JWT token"""
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    
+    try:
+        payload = jwt.decode(credentials.credentials, SECRET_KEY, algorithms=[ALGORITHM])
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+    
+    user = await get_user_by_id(user_id)
+    if user is None:
+        raise credentials_exception
+    
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Inactive user"
+        )
+    return user
+
+async def get_current_active_user(current_user: User = Depends(get_current_user)) -> User:
+    """Get current active user"""
+    if not current_user.is_active:
+        raise HTTPException(status_code=400, detail="Inactive user")
+    return current_user
+
+def create_user_response(user: User) -> UserResponse:
+    """Create user response model"""
+    return UserResponse(
+        id=str(user.id),
+        firstName=user.firstName,
+        lastName=user.lastName,
+        email=user.email,
+        academicStage=user.academicStage,
+        researchArea=user.researchArea,
+        avatarId=user.avatarId,
+        created_at=user.created_at,
+        last_login=user.last_login
+    )

multi_llm_chatbot_backend/app/core/bootstrap.py

@@ -0,0 +1,159 @@
+# app/core/bootstrap.py
+import os
+from pathlib import Path
+
+from app.core.env_loader import load_application_env
+
+load_application_env()
+
+from app.config import get_settings
+from app.llm.improved_gemini_client import ImprovedGeminiClient
+from app.llm.improved_ollama_client import ImprovedOllamaClient
+from app.llm.improved_vllm_client import ImprovedVllmClient
+from app.llm.openai_fallback_client import OpenAIFallbackClient
+from app.llm.resilient_client import ResilientLLMClient
+from app.core.improved_orchestrator import ImprovedChatOrchestrator
+from app.models.default_personas import get_default_personas
+
+settings = get_settings()
+
+current_provider = settings.llm.provider or "vllm"
+available_providers = ["ollama", "gemini", "vllm", "openai"]
+
+
+def _load_shared_env_var(name: str) -> str:
+    explicit = os.environ.get("SHARED_ENV", "").strip()
+    candidates = [Path(explicit)] if explicit else []
+    candidates.append(Path.home() / ".secrets" / "shared.env")
+    prefix = f"{name}="
+    for shared in candidates:
+        if not shared.is_file():
+            continue
+        for line in shared.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line.startswith(prefix):
+                return line.split("=", 1)[1].strip()
+    return ""
+
+
+def _vllm_api_username() -> str:
+    """Optional HTTP Basic auth username for the vLLM endpoint.
+
+    The Neon BrainForge/Security endpoint at 4090-x1-3 requires HTTP Basic
+    auth using HANA_USERNAME_KLATCHAT / HANA_KLATCHAT_PASSWORD from
+    ~/.secrets/shared.env. We allow explicit override via api_username
+    in config or VLLM_API_USERNAME env var, falling back to the shared
+    HANA_USERNAME_KLATCHAT entry.
+    """
+    return (
+        settings.llm.vllm.api_username
+        or os.getenv("VLLM_API_USERNAME", "")
+        or _load_shared_env_var("HANA_USERNAME_KLATCHAT")
+    )
+
+
+def _vllm_api_key() -> str:
+    """vLLM key/password. If api_username is set (HANA Basic auth), prefer
+    HANA_KLATCHAT_PASSWORD; otherwise use the generic VLLM_API_KEY Bearer
+    token. This matches the dual-auth nature of the Neon endpoints.
+    """
+    if _vllm_api_username():
+        return (
+            settings.llm.vllm.api_key
+            or os.getenv("HANA_KLATCHAT_PASSWORD", "")
+            or _load_shared_env_var("HANA_KLATCHAT_PASSWORD")
+            or os.getenv("VLLM_API_KEY", "")
+            or _load_shared_env_var("VLLM_API_KEY")
+        )
+    return (
+        settings.llm.vllm.api_key
+        or os.getenv("VLLM_API_KEY", "")
+        or _load_shared_env_var("VLLM_API_KEY")
+    )
+
+
+def _openai_api_key() -> str:
+    return (
+        settings.llm.openai.api_key
+        or os.getenv("OPENAI_API_KEY", "")
+        or _load_shared_env_var("OPENAI_API_KEY")
+    )
+
+
+def _build_neon_vllm(neon_persona: str | None) -> ImprovedVllmClient:
+    vllm = settings.llm.vllm
+    if not vllm.api_url:
+        raise ValueError("No vLLM endpoint configured. Set llm.vllm.api_url in your config.")
+    model_name = vllm.model_id or None
+    return ImprovedVllmClient(
+        api_url=vllm.api_url,
+        api_key=_vllm_api_key(),
+        model_name=model_name,
+        neon_persona=neon_persona,
+        api_username=_vllm_api_username() or None,
+    )
+
+
+def _build_openai(reasoning_effort: str) -> OpenAIFallbackClient:
+    return OpenAIFallbackClient(
+        api_key=_openai_api_key(),
+        model=settings.llm.openai.model,
+        reasoning_effort=reasoning_effort,
+    )
+
+
+def _wrap_resilient(primary: ImprovedVllmClient, fallback: OpenAIFallbackClient, label: str):
+    return ResilientLLMClient(
+        primary=primary,
+        fallback=fallback,
+        race_timeout_seconds=settings.llm.resilient.race_timeout_seconds,
+        primary_label=label,
+    )
+
+
+def create_llm_client(provider=None):
+    if provider is None:
+        provider = current_provider
+    if provider == "openai":
+        # Standalone OpenAI (GPT) client. OpenAIFallbackClient implements the same
+        # LLMClient interface as the Gemini client, so it works as the primary
+        # orchestrator/persona LLM, not just a vLLM fallback.
+        return _build_openai(settings.llm.openai.orchestrator_reasoning_effort)
+    if provider == "gemini":
+        return ImprovedGeminiClient(model_name=settings.llm.gemini.model)
+    if provider == "vllm":
+        neon = settings.llm.vllm.neon_persona_orchestrator
+        primary = _build_neon_vllm(neon if neon != "vanilla" else None)
+        fallback = _build_openai(settings.llm.openai.orchestrator_reasoning_effort)
+        return _wrap_resilient(primary, fallback, "orchestrator")
+    return ImprovedOllamaClient(
+        model_name=settings.llm.ollama.model,
+        base_url=settings.llm.ollama.base_url,
+    )
+
+
+def create_orchestrator_llm():
+    if current_provider != "vllm":
+        return create_llm_client()
+    neon = settings.llm.vllm.neon_persona_orchestrator
+    primary = _build_neon_vllm(neon if neon != "vanilla" else None)
+    fallback = _build_openai(settings.llm.openai.orchestrator_reasoning_effort)
+    return _wrap_resilient(primary, fallback, "orchestrator")
+
+
+def create_persona_llm():
+    if current_provider != "vllm":
+        return create_llm_client()
+    neon = settings.llm.vllm.neon_persona_advisors
+    primary = _build_neon_vllm(neon)
+    fallback = _build_openai(settings.llm.openai.persona_reasoning_effort)
+    return _wrap_resilient(primary, fallback, "persona")
+
+
+llm = create_orchestrator_llm()
+chat_orchestrator = ImprovedChatOrchestrator(llm_client=llm)
+
+persona_llm = create_persona_llm() if current_provider == "vllm" else llm
+DEFAULT_PERSONAS = get_default_personas(persona_llm)
+for persona in DEFAULT_PERSONAS:
+    chat_orchestrator.register_persona(persona)

multi_llm_chatbot_backend/app/core/canvas_analysis.py

@@ -0,0 +1,287 @@
+import re
+import json
+import logging
+from typing import Dict, List
+from collections import defaultdict
+
+from app.models.phd_canvas import CanvasInsight
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+class CanvasAnalysisService:
+    """Service for extracting and categorizing insights from chat messages"""
+    
+    def __init__(self, llm_client=None):
+        self.llm_client = llm_client
+        
+        # Predefined section mappings for semantic analysis
+        self.section_keywords = {
+            "research_progress": [
+                "progress", "milestone", "completed", "finished", "accomplished", 
+                "achieved", "timeline", "deadline", "chapter", "draft", "version"
+            ],
+            "methodology": [
+                "method", "methodology", "approach", "design", "data collection",
+                "survey", "interview", "experiment", "analysis", "statistical", 
+                "qualitative", "quantitative", "mixed methods"
+            ],
+            "theoretical_framework": [
+                "theory", "theoretical", "framework", "concept", "model",
+                "literature", "author", "philosophy", "paradigm", "assumption"
+            ],
+            "challenges_obstacles": [
+                "challenge", "problem", "difficulty", "obstacle", "stuck",
+                "confused", "frustrated", "struggle", "barrier", "issue"
+            ],
+            "next_steps": [
+                "next", "plan", "should", "will", "going to", "need to",
+                "action", "step", "priority", "focus", "goal", "objective"
+            ],
+            "writing_communication": [
+                "write", "writing", "paper", "thesis", "dissertation", "publication",
+                "communication", "presentation", "defense", "draft", "revision"
+            ],
+            "career_development": [
+                "career", "job", "position", "networking", "conference",
+                "skills", "CV", "resume", "application", "fellowship", "grant"
+            ],
+            "literature_review": [
+                "literature", "sources", "papers", "articles", "bibliography",
+                "citation", "author", "study", "research", "gap", "review"
+            ],
+            "data_analysis": [
+                "data", "analysis", "results", "findings", "statistics",
+                "coding", "software", "tool", "visualization", "pattern"
+            ],
+            "motivation_mindset": [
+                "motivation", "confidence", "stress", "anxiety", "balance",
+                "mental health", "mindset", "support", "overwhelmed", "burnout"
+            ]
+        }
+    
+    async def extract_insights_from_messages(self, messages: List[Dict], chat_session_id: str) -> List[CanvasInsight]:
+        """Extract actionable insights from chat messages using semantic analysis"""
+        try:
+            insights = []
+            
+            for message in messages:
+                # Handle the actual stored message format from your database
+                msg_type = message.get("type", "")
+                
+                if msg_type == "advisor":
+                    # This is the format used in your database
+                    content = message.get("content", "")
+                    persona_id = message.get("advisorName", message.get("persona", "advisor"))
+                    message_id = message.get("id", str(message.get("_id", "")))
+                    
+                    if content and len(content.strip()) > 20:  # Only process substantial content
+                        persona_insights = await self._extract_insights_from_content(
+                            content, persona_id, message_id, chat_session_id
+                        )
+                        insights.extend(persona_insights)
+                        logger.debug(f"Extracted {len(persona_insights)} insights from {persona_id} message")
+                        
+                elif msg_type == "assistant" and "responses" in message:
+                    # Handle multi-persona responses (if this format exists)
+                    for response in message.get("responses", []):
+                        persona_insights = await self._extract_insights_from_persona_response(
+                            response, message.get("id"), chat_session_id
+                        )
+                        insights.extend(persona_insights)
+                        
+                elif message.get("role") == "assistant" and message.get("content"):
+                    # Handle converted message format (from export functions)
+                    persona_insights = await self._extract_insights_from_content(
+                        message.get("content", ""), "assistant", 
+                        message.get("id"), chat_session_id
+                    )
+                    insights.extend(persona_insights)
+            
+            # Remove duplicates and low-confidence insights
+            unique_insights = self._deduplicate_insights(insights)
+            high_confidence_insights = [i for i in unique_insights if i.confidence_score >= 0.5]  # Lowered threshold
+            
+            logger.info(f"Extracted {len(high_confidence_insights)} insights from {len(messages)} messages")
+            return high_confidence_insights
+            
+        except Exception as e:
+            logger.error(f"Error extracting insights from messages: {e}")
+            import traceback
+            logger.error(f"Full traceback: {traceback.format_exc()}")
+            return []
+    
+    async def _extract_insights_from_persona_response(self, response: Dict, message_id: str, chat_session_id: str) -> List[CanvasInsight]:
+        """Extract insights from a single persona response"""
+        persona_id = response.get("persona_id", "unknown")
+        content = response.get("content", "")
+        
+        return await self._extract_insights_from_content(content, persona_id, message_id, chat_session_id)
+    
+    async def _extract_insights_from_content(self, content: str, persona_id: str, message_id: str, chat_session_id: str) -> List[CanvasInsight]:
+        """Extract actionable insights from content using LLM analysis"""
+        if not content or len(content.strip()) < 30:
+            return []
+        
+        try:
+            app_title = get_settings().app.title
+            extraction_prompt = f"""
+            Extract actionable insights from this {app_title} advisor response that would be valuable for a user's progress summary:
+
+            PERSONA: {persona_id}
+            CONTENT: {content}
+
+            Return a JSON list of insights. Each insight should be:
+            - Actionable and specific to the user's progress
+            - 1-2 sentences long
+            - Valuable for advisor meetings
+            - Not generic advice
+
+            Format: [{{"insight": "specific actionable insight here", "keywords": ["keyword1", "keyword2"]}}]
+            
+            Return ONLY the JSON array, no other text.
+            """
+
+            if self.llm_client:
+                try:
+                    llm_response = await self.llm_client.generate(
+                        system_prompt=f"You are an expert at extracting actionable guidance from {app_title} advisor responses.",
+                        context=[{"role": "user", "content": extraction_prompt}],
+                        temperature=0.3,
+                        max_tokens=1000,
+                        response_mime_type="application/json"
+                    )
+
+                    insights_data = json.loads(llm_response)
+                    insights = []
+
+                    for item in insights_data:
+                        if isinstance(item, dict) and "insight" in item:
+                            insight = CanvasInsight(
+                                content=item["insight"],
+                                source_persona=persona_id,
+                                source_message_id=message_id,
+                                source_chat_session=chat_session_id,
+                                confidence_score=0.8,  # High confidence from LLM extraction
+                                keywords=item.get("keywords", [])
+                            )
+                            insights.append(insight)
+                    
+                    if insights:
+                        logger.debug(f"LLM extracted {len(insights)} insights from {persona_id}")
+                        return insights
+                    
+                    logger.warning(f"LLM returned no parseable insights for {persona_id}, falling back to rule-based")
+                    
+                except Exception as llm_error:
+                    logger.warning(f"LLM extraction failed for {persona_id}: {llm_error}")
+            
+            # Fallback if no LLM available
+            return self._extract_insights_rule_based(content, persona_id, message_id, chat_session_id)
+            
+        except Exception as e:
+            logger.error(f"Error extracting insights from {persona_id} content: {e}")
+            return []
+    
+    def _extract_insights_rule_based(self, content: str, persona_id: str, message_id: str, chat_session_id: str) -> List[CanvasInsight]:
+        """Fallback rule-based insight extraction"""
+        insights = []
+        
+        # Extract actionable sentences
+        sentences = re.split(r'[.!?]+', content)
+        actionable_patterns = [
+            r"(?:you should|consider|try|focus on|prioritize|next step|recommended?|suggest)",
+            r"(?:action item|goal|objective|plan|strategy)",
+            r"(?:deadline|timeline|schedule|by \w+)",
+            r"(?:complete|finish|work on|tackle|address)"
+        ]
+        
+        for sentence in sentences:
+            sentence = sentence.strip()
+            if len(sentence) < 15:  # Lowered minimum length
+                continue
+                
+            match_count = sum(1 for pattern in actionable_patterns if re.search(pattern, sentence, re.IGNORECASE))
+            
+            if match_count > 0:
+                keywords = self._extract_keywords_from_sentence(sentence)
+                confidence = round(0.55 + min(match_count * 0.05, 0.15), 2)
+                
+                insight = CanvasInsight(
+                    content=sentence,
+                    source_persona=persona_id,
+                    source_message_id=message_id,
+                    source_chat_session=chat_session_id,
+                    confidence_score=confidence,
+                    keywords=keywords
+                )
+                insights.append(insight)
+        
+        logger.debug(f"Rule-based extracted {len(insights)} insights from {persona_id}")
+        return insights[:3]  # Limit to 3 insights per message to avoid noise
+    
+    def _extract_keywords_from_sentence(self, sentence: str) -> List[str]:
+        """Extract relevant keywords from a sentence"""
+        # Simple keyword extraction
+        words = re.findall(r'\b\w{4,}\b', sentence.lower())  # Words with 4+ chars
+        
+        # Filter out common words
+        stop_words = {
+            "should", "could", "would", "your", "research", "work", "study", 
+            "consider", "think", "important", "also", "really", "maybe",
+            "probably", "definitely", "certainly", "particular", "specific"
+        }
+        
+        keywords = [word for word in words if word not in stop_words]
+        return keywords[:5]  # Limit to 5 keywords
+    
+    def categorize_insights(self, insights: List[CanvasInsight]) -> Dict[str, List[CanvasInsight]]:
+        """Categorize insights into canvas sections using semantic analysis"""
+        categorized = defaultdict(list)
+        
+        for insight in insights:
+            section = self._determine_section(insight)
+            categorized[section].append(insight)
+        
+        return dict(categorized)
+    
+    def _determine_section(self, insight: CanvasInsight) -> str:
+        """Determine which section an insight belongs to"""
+        content_lower = insight.content.lower()
+        keywords_lower = [k.lower() for k in insight.keywords]
+        all_text = content_lower + " " + " ".join(keywords_lower)
+        
+        # Score each section based on keyword matches
+        section_scores = {}
+        for section, keywords in self.section_keywords.items():
+            score = sum(1 for keyword in keywords if keyword in all_text)
+            if score > 0:
+                section_scores[section] = score
+        
+        # Return the section with highest score, or default
+        if section_scores:
+            return max(section_scores, key=section_scores.get)
+        else:
+            return "general_notes"  # Default section
+    
+    def prioritize_insights(self, insights: List[CanvasInsight]) -> List[CanvasInsight]:
+        """Sort insights by priority (confidence score and recency)"""
+        return sorted(insights, key=lambda x: (x.confidence_score, x.extracted_at), reverse=True)
+    
+    def _deduplicate_insights(self, insights: List[CanvasInsight]) -> List[CanvasInsight]:
+        """Remove duplicate or very similar insights"""
+        if not insights:
+            return insights
+        
+        unique_insights = []
+        seen_content = set()
+        
+        for insight in insights:
+            # Simple deduplication based on content similarity
+            content_key = insight.content.lower().strip()[:100]  # First 100 chars
+            
+            if content_key not in seen_content:
+                seen_content.add(content_key)
+                unique_insights.append(insight)
+        
+        return unique_insights

multi_llm_chatbot_backend/app/core/canvas_database.py

@@ -0,0 +1,35 @@
+"""PhD Canvas database setup — SQLite-shim aware.
+
+The original implementation was a Mongo-only module that created compound
+indexes and a TTL index on the ``phd_canvases`` collection at startup. With
+the SQLite-on-HF-bucket persistence shim, the schema (including the
+``user_id`` index) is declared once at connection time inside
+``app.core.db``, so this module becomes a compatibility no-op.
+
+We keep the function signatures so any caller that still imports
+``setup_canvas_collections`` or ``cleanup_old_canvas_data`` keeps working.
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+async def setup_canvas_collections(db: Any) -> None:
+    """No-op on the SQLite shim — indexes are created by ``app.core.db``."""
+    logger.info(
+        "PhD Canvas setup: schema and indexes are managed by the SQLite shim; "
+        "skipping legacy Mongo index creation."
+    )
+
+
+async def cleanup_old_canvas_data(db: Any) -> None:
+    """Maintenance helper — disabled on the SQLite shim.
+
+    The original used a Mongo ``$lookup`` aggregation against the ``users``
+    collection, which the in-process aggregation runner doesn't support. If
+    you need the orphan cleanup, run it via a separate script that does two
+    passes (``users``, then ``phd_canvases``) and calls ``delete_many``.
+    """
+    logger.info("cleanup_old_canvas_data is a no-op on the SQLite shim.")

multi_llm_chatbot_backend/app/core/canvas_manager.py

@@ -0,0 +1,408 @@
+import logging
+from typing import Dict, List, Optional
+from datetime import datetime, timedelta
+from bson import ObjectId
+import asyncio
+import hashlib
+
+from app.models.phd_canvas import PhdCanvas, CanvasInsight, UpdateCanvasRequest
+from app.core.canvas_analysis import CanvasAnalysisService
+from app.core.bootstrap import llm
+
+logger = logging.getLogger(__name__)
+
+class CanvasManager:
+    """Manages PhD Canvas creation, updates, and incremental processing"""
+    
+    def __init__(self):
+        self.analysis_service = CanvasAnalysisService(llm_client=llm)
+        self._db = None
+        # Add lock dictionary to prevent concurrent updates for the same user
+        self._update_locks = {}
+    
+    def get_database(self):
+        """Lazy database connection to avoid circular imports"""
+        if self._db is None:
+            # Import here to avoid circular import
+            from app.core.database import get_database
+            self._db = get_database()
+        return self._db
+    
+    async def get_or_create_canvas(self, user_id: str) -> PhdCanvas:
+        """Get existing canvas or create new one for user"""
+        try:
+            db = self.get_database()
+            user_object_id = ObjectId(user_id)
+            
+            # Try to find existing canvas
+            canvas_doc = await db.phd_canvases.find_one({"user_id": user_object_id})
+            
+            if canvas_doc:
+                # Convert to PhdCanvas model
+                canvas = PhdCanvas(**canvas_doc)
+                logger.info(f"Found existing canvas for user {user_id} with {canvas.total_insights} insights")
+                return canvas
+            else:
+                # Create new canvas
+                canvas = PhdCanvas(user_id=user_object_id)
+                
+                # Insert into database
+                result = await db.phd_canvases.insert_one(canvas.dict(by_alias=True))
+                canvas.id = result.inserted_id
+                
+                logger.info(f"Created new canvas for user {user_id}")
+                return canvas
+                
+        except Exception as e:
+            logger.error(f"Error getting/creating canvas for user {user_id}: {e}")
+            # Return empty canvas as fallback
+            return PhdCanvas(user_id=ObjectId(user_id))
+    
+    async def update_canvas(self, user_id: str, request: UpdateCanvasRequest) -> PhdCanvas:
+        """Update canvas with latest insights from chat sessions"""
+        
+        # Get or create a lock for this user
+        if user_id not in self._update_locks:
+            self._update_locks[user_id] = asyncio.Lock()
+        
+        # Check if an update is already in progress
+        if self._update_locks[user_id].locked():
+            logger.warning(f"Canvas update already in progress for user {user_id}, skipping duplicate request")
+            # Return current canvas without updating
+            return await self.get_or_create_canvas(user_id)
+        
+        # Acquire lock to prevent concurrent updates
+        async with self._update_locks[user_id]:
+            try:
+                db = self.get_database()
+                canvas = await self.get_or_create_canvas(user_id)
+                
+                logger.info(f"Updating canvas for user {user_id}, force_full={request.force_full_update}")
+                
+                # IMPORTANT: Auto-detect if this should be a full update for first-time canvas
+                is_first_time_update = (
+                    canvas.last_chat_processed is None and 
+                    canvas.total_insights == 0 and
+                    not request.force_full_update
+                )
+                
+                if is_first_time_update:
+                    logger.info(f"Auto-detecting first-time canvas update for user {user_id}. Converting to full update.")
+                    request.force_full_update = True
+                
+                # Store the timestamp BEFORE we start processing
+                update_started_at = datetime.utcnow()
+                
+                # Determine which chats to process
+                if request.force_full_update:
+                    # Process all chats
+                    chat_sessions = await self._get_all_user_chat_sessions(user_id)
+                    logger.info(f"Force full update: processing {len(chat_sessions)} total chat sessions")
+                else:
+                    # Process only chats created/updated after last canvas update
+                    chat_sessions = await self._get_new_chat_sessions(user_id, canvas.last_chat_processed)
+                    logger.info(f"Incremental update: processing {len(chat_sessions)} new chat sessions since {canvas.last_chat_processed}")
+                
+                if not chat_sessions:
+                    logger.info("No new chat sessions to process")
+                    return canvas
+                
+                # Filter chat sessions if specific ones requested
+                if request.include_chat_sessions:
+                    chat_sessions = [
+                        chat for chat in chat_sessions 
+                        if str(chat["_id"]) in request.include_chat_sessions
+                    ]
+                    logger.info(f"Filtered to {len(chat_sessions)} specifically requested chat sessions")
+                
+                # Track processed chat+message combinations to prevent duplicates
+                processed_sources = set()
+                
+                # Get existing processed sources from canvas
+                for section in canvas.sections.values():
+                    for insight in section.insights:
+                        if insight.source_chat_session and insight.source_message_id:
+                            processed_sources.add((insight.source_chat_session, insight.source_message_id))
+                
+                # Process each chat session for insights
+                all_new_insights = []
+                processed_chat_ids = []
+                
+                for chat_session in chat_sessions:
+                    try:
+                        chat_id = str(chat_session["_id"])
+                        messages = chat_session.get("messages", [])
+                        
+                        if not messages:
+                            continue
+                        
+                        # Check if we've already processed these messages
+                        messages_to_process = []
+                        for msg in messages:
+                            msg_id = msg.get('id', '')
+                            if (chat_id, msg_id) not in processed_sources:
+                                messages_to_process.append(msg)
+                        
+                        if not messages_to_process:
+                            logger.info(f"All messages from chat {chat_id} already processed, skipping")
+                            continue
+                        
+                        logger.info(f"Processing {len(messages_to_process)} new messages from chat {chat_id}")
+                        
+                        # Extract insights from new messages only
+                        session_insights = await self.analysis_service.extract_insights_from_messages(
+                            messages_to_process, chat_id
+                        )
+                        
+                        if session_insights:
+                            all_new_insights.extend(session_insights)
+                            processed_chat_ids.append(chat_id)
+                            logger.info(f"Extracted {len(session_insights)} insights from chat {chat_id}")
+                        
+                    except Exception as e:
+                        logger.error(f"Error processing chat session {chat_session.get('_id')}: {e}")
+                        continue
+                
+                if all_new_insights:
+                    # Categorize insights by section
+                    categorized_insights = self.analysis_service.categorize_insights(all_new_insights)
+                    
+                    # Update canvas sections
+                    sections_updated = 0
+                    for section_key, insights in categorized_insights.items():
+                        if request.exclude_sections and section_key in request.exclude_sections:
+                            continue
+                        
+                        # Prioritize insights before adding
+                        prioritized_insights = self.analysis_service.prioritize_insights(insights)
+                        
+                        # Limit insights per section to avoid overwhelming canvas
+                        max_insights_per_section = 10
+                        limited_insights = prioritized_insights[:max_insights_per_section]
+                        
+                        if limited_insights:
+                            canvas.update_section(section_key, limited_insights)
+                            sections_updated += 1
+                            logger.info(f"Updated section '{section_key}' with {len(limited_insights)} insights")
+                    
+                    # Update canvas metadata with the timestamp from BEFORE processing
+                    canvas.last_chat_processed = update_started_at
+                    canvas.last_updated = datetime.utcnow()
+                    
+                    # Save updated canvas to database
+                    await self._save_canvas(canvas)
+                    
+                    logger.info(f"Canvas update completed: {len(all_new_insights)} new insights, {sections_updated} sections updated")
+                else:
+                    logger.info("No insights extracted from chat sessions")
+                
+                return canvas
+                
+            except Exception as e:
+                logger.error(f"Error updating canvas for user {user_id}: {e}")
+                import traceback
+                logger.error(f"Full traceback: {traceback.format_exc()}")
+                raise
+            finally:
+                # Clean up lock if no longer needed
+                if user_id in self._update_locks and not self._update_locks[user_id].locked():
+                    # Remove lock after some time to prevent memory buildup
+                    pass  # Keep lock for potential future use
+    
+    async def _get_all_user_chat_sessions(self, user_id: str) -> List[Dict]:
+        """Get all chat sessions for a user"""
+        try:
+            db = self.get_database()
+            user_object_id = ObjectId(user_id)
+            
+            cursor = db.chat_sessions.find({
+                "user_id": user_object_id,
+                "is_active": {"$ne": False},  # Include active sessions
+                "deleted_at": {"$exists": False}  # Exclude deleted sessions
+            }).sort("created_at", -1)  # Most recent first
+            
+            chat_sessions = await cursor.to_list(length=100)  # Limit to last 100 chats
+            return chat_sessions
+            
+        except Exception as e:
+            logger.error(f"Error getting all chat sessions for user {user_id}: {e}")
+            return []
+    
+    async def _get_new_chat_sessions(self, user_id: str, since: Optional[datetime]) -> List[Dict]:
+        """Get chat sessions created or updated after a specific time"""
+        try:
+            db = self.get_database()
+            user_object_id = ObjectId(user_id)
+            
+            # Build query filter
+            query_filter = {
+                "user_id": user_object_id,
+                "is_active": {"$ne": False},
+                "deleted_at": {"$exists": False}
+            }
+            
+            if since:
+                # Get chats created or updated after the since timestamp
+                query_filter["$or"] = [
+                    {"created_at": {"$gt": since}},
+                    {"updated_at": {"$gt": since}}
+                ]
+            else:
+                # IMPORTANT FIX: If no since time and this is being called for incremental update,
+                # we should still get more chats for proper first-time processing
+                # The caller should handle the force_full_update logic properly
+                
+                # For now, get chats from last 30 days instead of 7 as a safer fallback
+                # But ideally, first-time canvas should always use force_full_update=True
+                one_month_ago = datetime.utcnow() - timedelta(days=30)
+                query_filter["created_at"] = {"$gte": one_month_ago}
+                
+                logger.warning(f"Getting new chat sessions for user {user_id} with no 'since' timestamp. "
+                             f"This should only happen for incremental updates. Consider using force_full_update=True for first-time canvas.")
+            
+            # Increase limit for incremental updates to catch more historical chats
+            limit = 100  # Increased from 50
+            cursor = db.chat_sessions.find(query_filter).sort("created_at", -1)
+            chat_sessions = await cursor.to_list(length=limit)
+            
+            return chat_sessions
+            
+        except Exception as e:
+            logger.error(f"Error getting new chat sessions for user {user_id}: {e}")
+            return []
+    
+    async def _save_canvas(self, canvas: PhdCanvas):
+        """Save canvas to database"""
+        try:
+            db = self.get_database()
+            
+            # Update existing canvas
+            await db.phd_canvases.replace_one(
+                {"_id": canvas.id},
+                canvas.dict(by_alias=True),
+                upsert=True
+            )
+            
+            logger.info(f"Saved canvas {canvas.id} to database")
+            
+        except Exception as e:
+            logger.error(f"Error saving canvas to database: {e}")
+            raise
+    
+    async def delete_canvas(self, user_id: str) -> bool:
+        """Delete canvas for a user"""
+        try:
+            db = self.get_database()
+            user_object_id = ObjectId(user_id)
+            
+            result = await db.phd_canvases.delete_one({"user_id": user_object_id})
+            
+            if result.deleted_count > 0:
+                logger.info(f"Deleted canvas for user {user_id}")
+                return True
+            else:
+                logger.info(f"No canvas found to delete for user {user_id}")
+                return False
+                
+        except Exception as e:
+            logger.error(f"Error deleting canvas for user {user_id}: {e}")
+            return False
+    
+    async def get_canvas_stats(self, user_id: str) -> Dict:
+        """Get statistics about the user's PhD Canvas"""
+        try:
+            canvas = await self.get_or_create_canvas(user_id)
+            
+            # Calculate section breakdown
+            sections_breakdown = {}
+            for section_key, section in canvas.sections.items():
+                sections_breakdown[section_key] = {
+                    "title": section.title,
+                    "insight_count": len(section.insights),
+                    "priority": section.priority,
+                    "last_updated": section.updated_at
+                }
+            
+            return {
+                "total_insights": canvas.total_insights,
+                "total_sections": len(canvas.sections),
+                "last_updated": canvas.last_updated,
+                "last_chat_processed": canvas.last_chat_processed,
+                "created_at": canvas.created_at,
+                "auto_update": canvas.auto_update,
+                "sections_breakdown": sections_breakdown
+            }
+            
+        except Exception as e:
+            logger.error(f"Error getting canvas stats for user {user_id}: {e}")
+            return {
+                "total_insights": 0,
+                "total_sections": 0,
+                "sections_breakdown": {}
+            }
+    
+    async def export_canvas_for_printing(self, user_id: str) -> Dict:
+        """Export canvas in a format optimized for printing"""
+        try:
+            canvas = await self.get_or_create_canvas(user_id)
+            
+            # Format sections for printing
+            sections = []
+            for section_key, section in canvas.sections.items():
+                formatted_section = {
+                    "title": section.title,
+                    "description": section.description,
+                    "insights": [
+                        {
+                            "content": insight.content,
+                            "source": insight.source_persona,
+                            "confidence": insight.confidence_score
+                        }
+                        for insight in section.insights[:5]  # Limit to top 5 for printing
+                    ]
+                }
+                sections.append(formatted_section)
+            
+            return {
+                "user_id": str(canvas.user_id),
+                "generated_at": datetime.utcnow(),
+                "total_insights": canvas.total_insights,
+                "last_updated": canvas.last_updated,
+                "sections": sections,
+                "metadata": {
+                    "created_at": canvas.created_at,
+                    "last_chat_processed": canvas.last_chat_processed,
+                    "print_optimized": True
+                }
+            }
+            
+        except Exception as e:
+            logger.error(f"Error exporting canvas for printing for user {user_id}: {e}")
+            raise
+    
+    async def toggle_auto_update(self, user_id: str, enabled: bool) -> bool:
+        """Toggle auto-update setting for a canvas"""
+        try:
+            db = self.get_database()
+            user_object_id = ObjectId(user_id)
+            
+            result = await db.phd_canvases.update_one(
+                {"user_id": user_object_id},
+                {"$set": {"auto_update": enabled}}
+            )
+            
+            return result.modified_count > 0
+            
+        except Exception as e:
+            logger.error(f"Error toggling auto-update for user {user_id}: {e}")
+            return False
+
+# Singleton instance
+_canvas_manager_instance = None
+
+def get_canvas_manager() -> CanvasManager:
+    """Get singleton instance of CanvasManager"""
+    global _canvas_manager_instance
+    if _canvas_manager_instance is None:
+        _canvas_manager_instance = CanvasManager()
+    return _canvas_manager_instance

multi_llm_chatbot_backend/app/core/context.py

@@ -0,0 +1,17 @@
+# Global context storage
+class GlobalSessionContext:
+    def __init__(self):
+        self.full_log: list[dict] = []
+        self.uploaded_files: list[str] = []
+        self.total_upload_size: int = 0
+
+    def append(self, role: str, content: str):
+        self.full_log.append({"role": role, "content": content})
+
+    def filter_by_persona(self, persona_id: str):
+        return self.full_log
+
+    def clear(self):
+        self.full_log = []
+        self.uploaded_files = []
+        self.total_upload_size = 0

multi_llm_chatbot_backend/app/core/context_manager.py

@@ -0,0 +1,296 @@
+from typing import List, Dict, Optional, Tuple
+from dataclasses import dataclass
+import re
+from datetime import datetime
+
+@dataclass
+class ContextWindow:
+    """Represents a context window for LLM processing"""
+    messages: List[dict]
+    total_tokens: int
+    truncated: bool = False
+    
+class ContextManager:
+    """Unified context management for consistent LLM behavior"""
+    
+    def __init__(self, 
+                 max_context_tokens: int = 8000,
+                 preserve_recent_messages: int = 5,
+                 chars_per_token: float = 4.0):
+        self.max_context_tokens = max_context_tokens
+        self.preserve_recent_messages = preserve_recent_messages
+        self.chars_per_token = chars_per_token
+    
+    def prepare_context_for_llm(self, 
+                               messages: List[dict], 
+                               system_prompt: str,
+                               llm_provider: str = "gemini") -> ContextWindow:
+        """
+        Prepare context for LLM with intelligent windowing and formatting
+        """
+        # Calculate token budget
+        system_tokens = self._estimate_tokens(system_prompt)
+        available_tokens = self.max_context_tokens - system_tokens - 500  # Reserve for response
+        
+        # Get relevant context window
+        context_messages = self._get_optimal_context_window(messages, available_tokens)
+        
+        # Format for specific LLM provider
+        formatted_messages = self._format_for_provider(context_messages, system_prompt, llm_provider)
+        
+        return ContextWindow(
+            messages=formatted_messages,
+            total_tokens=self._estimate_tokens_for_messages(formatted_messages),
+            truncated=len(context_messages) < len(messages)
+        )
+    
+    def _get_optimal_context_window(self, messages: List[dict], token_budget: int) -> List[dict]:
+        """
+        Select optimal messages for context window using recency + relevance
+        """
+        if not messages:
+            return []
+        
+        # Always preserve the most recent messages
+        recent_messages = messages[-self.preserve_recent_messages:]
+        recent_tokens = self._estimate_tokens_for_messages(recent_messages)
+        
+        if recent_tokens >= token_budget:
+            # If recent messages exceed budget, truncate to fit
+            return self._truncate_to_fit(recent_messages, token_budget)
+        
+        # Add older messages if we have token budget remaining
+        remaining_budget = token_budget - recent_tokens
+        older_messages = messages[:-self.preserve_recent_messages] if len(messages) > self.preserve_recent_messages else []
+        
+        # Score older messages by relevance and recency
+        scored_messages = self._score_messages_for_relevance(older_messages, messages[-1]['content'] if messages else "")
+        
+        # Add highest scoring messages that fit in budget
+        selected_older = []
+        for message, score in scored_messages:
+            message_tokens = self._estimate_tokens(message['content'])
+            if message_tokens <= remaining_budget:
+                selected_older.append(message)
+                remaining_budget -= message_tokens
+            else:
+                break
+        
+        # Combine in chronological order
+        return selected_older + recent_messages
+    
+    def _score_messages_for_relevance(self, messages: List[dict], current_query: str) -> List[Tuple[dict, float]]:
+        """
+        Score messages by relevance to current query and recency
+        """
+        scored = []
+        current_query_lower = current_query.lower()
+        
+        for i, message in enumerate(messages):
+            score = 0.0
+            content_lower = message['content'].lower()
+            
+            # Recency score (more recent = higher score)
+            recency_score = (i + 1) / len(messages) * 0.3
+            
+            # Keyword overlap score
+            current_words = set(current_query_lower.split())
+            message_words = set(content_lower.split())
+            overlap = len(current_words.intersection(message_words))
+            keyword_score = min(overlap / max(len(current_words), 1) * 0.4, 0.4)
+            
+            # Role importance (user questions and document content more important)
+            role_score = 0.3 if message['role'] in ['user', 'document'] else 0.1
+            
+            score = recency_score + keyword_score + role_score
+            scored.append((message, score))
+        
+        # Sort by score descending
+        return sorted(scored, key=lambda x: x[1], reverse=True)
+    
+    def _truncate_to_fit(self, messages: List[dict], token_budget: int) -> List[dict]:
+        """
+        Truncate messages to fit within token budget, preserving most recent
+        """
+        result = []
+        current_tokens = 0
+        
+        # Add messages from most recent backward
+        for message in reversed(messages):
+            message_tokens = self._estimate_tokens(message['content'])
+            if current_tokens + message_tokens <= token_budget:
+                result.insert(0, message)
+                current_tokens += message_tokens
+            else:
+                break
+        
+        return result
+    
+    def _format_for_provider(self, messages: List[dict], system_prompt: str, provider: str) -> List[dict]:
+        """
+        Format messages for specific LLM provider
+        """
+        if provider.lower() == "gemini":
+            return self._format_for_gemini(messages, system_prompt)
+        elif provider.lower() in ["ollama", "mistral"]:
+            return self._format_for_ollama(messages, system_prompt)
+        elif provider.lower() == "vllm":
+            return self._format_for_vllm(messages, system_prompt)
+        else:
+            # Default format
+            return [{"role": "system", "content": system_prompt}] + messages
+
+    def _format_for_vllm(self, messages: List[dict], system_prompt: str) -> List[dict]:
+        """
+        Format messages for vLLM's OpenAI-compatible API.
+        Normalizes custom persona roles to 'assistant' since the API
+        only accepts system/user/assistant.
+        """
+        formatted = [{"role": "system", "content": system_prompt}]
+        for message in messages:
+            role = message["role"]
+            content = message["content"]
+            if role == "system":
+                continue
+            if role not in ("user", "assistant"):
+                content = f"[{role.title()} Advisor]: {content}"
+                role = "assistant"
+            formatted.append({"role": role, "content": content})
+        return formatted
+
+    def _format_for_gemini(self, messages: List[dict], system_prompt: str) -> List[dict]:
+        """
+        Format messages for Gemini API (uses user/model roles with parts structure)
+        FIXED VERSION - Better handles system messages and document context
+        """
+        formatted = []
+        
+        # Process all messages, handling system messages properly
+        system_message_content = ""
+        conversation_messages = []
+        
+        # Add initial system prompt if provided
+        if system_prompt:
+            system_message_content = system_prompt
+        
+        for message in messages:
+            role = message['role']
+            content = message['content']
+            
+            if role == 'system':
+                # Accumulate system messages
+                if system_message_content:
+                    system_message_content += "\n\n" + content
+                else:
+                    system_message_content = content
+            else:
+                conversation_messages.append(message)
+        
+        # Add accumulated system content as initial exchange
+        if system_message_content:
+            formatted.extend([
+                {
+                    "role": "user",
+                    "parts": [{"text": system_message_content}]
+                },
+                {
+                    "role": "model",
+                    "parts": [{"text": "I understand. I'll follow these instructions and use the document context you've provided."}]
+                }
+            ])
+        
+        # Convert conversation messages to Gemini format
+        for message in conversation_messages:
+            role = message['role']
+            content = message['content']
+            
+            if role == 'user':
+                formatted.append({
+                    "role": "user",
+                    "parts": [{"text": content}]
+                })
+            elif role == 'document':
+                formatted.append({
+                    "role": "user",
+                    "parts": [{"text": f"[Context Document] {content}"}]
+                })
+            else:
+                formatted.append({
+                    "role": "model",
+                    "parts": [{"text": content}]
+                })
+
+        return formatted
+    
+    def _format_for_ollama(self, messages: List[dict], system_prompt: str) -> str:
+        """
+        Format messages for Ollama (returns formatted prompt string)
+        """
+        parts = [system_prompt] if system_prompt else []
+        
+        for message in messages:
+            role = message['role'].capitalize()
+            content = message['content']
+            
+            if role == 'Document':
+                parts.append(f"Context: {content}")
+            else:
+                parts.append(f"{role}: {content}")
+        
+        parts.append("Assistant:")
+        return "\n\n".join(parts)
+    
+    def _estimate_tokens(self, text: str) -> int:
+        """
+        Estimate token count for text
+        """
+        return int(len(text) / self.chars_per_token)
+    
+    def _estimate_tokens_for_messages(self, messages: List[dict]) -> int:
+        """
+        Estimate total tokens for list of messages
+        """
+        if isinstance(messages, str):
+            return self._estimate_tokens(messages)
+        
+        total = 0
+        for message in messages:
+            if isinstance(message, dict):
+                if 'content' in message:
+                    total += self._estimate_tokens(message['content'])
+                elif 'parts' in message:
+                    # Gemini format
+                    for part in message['parts']:
+                        if 'text' in part:
+                            total += self._estimate_tokens(part['text'])
+            else:
+                total += self._estimate_tokens(str(message))
+        
+        return total
+    
+    def get_context_summary(self, messages: List[dict]) -> Dict[str, any]:
+        """
+        Get summary information about context
+        """
+        if not messages:
+            return {"total_messages": 0, "estimated_tokens": 0, "roles": {}}
+        
+        role_counts = {}
+        for message in messages:
+            role = message.get('role', 'unknown')
+            role_counts[role] = role_counts.get(role, 0) + 1
+        
+        return {
+            "total_messages": len(messages),
+            "estimated_tokens": self._estimate_tokens_for_messages(messages),
+            "roles": role_counts,
+            "oldest_message": messages[0].get('timestamp', 'unknown') if messages else None,
+            "newest_message": messages[-1].get('timestamp', 'unknown') if messages else None
+        }
+
+# Global context manager instance
+context_manager = ContextManager()
+
+def get_context_manager() -> ContextManager:
+    """Get the global context manager instance"""
+    return context_manager

multi_llm_chatbot_backend/app/core/database.py

@@ -0,0 +1,50 @@
+"""Database connection facade.
+
+Used to wrap pymongo / motor against a real MongoDB instance. For Hugging
+Face Spaces deployment we now back the same public API with SQLite on a HF
+Storage Bucket mount (see ``app.core.db``). The shim emulates the Mongo
+idioms the routers and services use, so this module simply forwards to it
+and keeps the legacy ``connect_to_mongo`` / ``close_mongo_connection`` /
+``get_database`` API intact for ``main.py`` and the route files.
+"""
+
+import logging
+
+from app.core.db import _close, _open, get_database as _get_database
+
+logger = logging.getLogger(__name__)
+
+
+async def connect_to_mongo() -> None:
+    """Open the SQLite-backed database and run schema bootstrap."""
+    await _open()
+    logger.info("SQLite-backed database ready (Mongo API shim active).")
+    # Legacy hook: previously called ``setup_canvas_collections`` here.
+    # The phd_canvases table is already declared in the shim's schema, so
+    # the call below is a no-op but kept for symmetry with the original
+    # startup path.
+    try:
+        from app.core.canvas_database import setup_canvas_collections
+
+        await setup_canvas_collections(_get_database())
+        logger.info("Canvas database initialization completed (no-op on SQLite shim).")
+    except Exception as canvas_error:  # pragma: no cover
+        logger.error(f"Canvas database initialization failed: {canvas_error}")
+
+
+async def close_mongo_connection() -> None:
+    """Best-effort connection close on FastAPI shutdown."""
+    await _close()
+    logger.info("Disconnected from SQLite-backed database.")
+
+
+async def create_indexes() -> None:
+    """Index creation is handled by the shim's schema bootstrap; kept for
+    backwards compatibility so any out-of-process maintenance script that
+    imports this name keeps working."""
+    return None
+
+
+def get_database():
+    """Return the SQLite-backed Mongo-API-compatible Database object."""
+    return _get_database()