Feat/persona avatars (#43)

* added persona avatar support to backend with bundled advisor images pulled from Clary's branch.

* Enhanced AdvisorCard and AdvisorStatusDropdown components with avatar selection functionality and hover effects. Updated AppConfigContext to support avatar URL overrides and custom avatar management.

* Refactor AvatarPickerModal component to remove adding your own avatar.

* added backend api support to persist user uploaded avatars in the db.

* revert backend to only serve up static bundle of advisor images.

* fixed the icon fallback for advisors without avatar image.

* added validation of external avatar URLs with fallback to icon on failure.

* return avatar image as URI string instead of typed dict.

* updated frontend to parse URI string instead of type/value dict.

* moved _resolve_image imports to top of file.

* converted bundled avatar paths to full URLs.

* updated avatar image test to expect full URL.

---------

Co-authored-by: Ryan-Venturi1 <157062856+Ryan-Venturi1@users.noreply.github.com>
Co-authored-by: Neon:ryan <ryan@neon.ai>

multi_llm_chatbot_backend/app/config.py

@@ -14,9 +14,12 @@ 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__)
 
 # ---------------------------------------------------------------------------
@@ -95,6 +98,7 @@ class PersonaItemConfig(_IconValidatorMixin):
     dark_color: Optional[str] = None
     dark_bg_color: Optional[str] = None
     icon: str = "HelpCircle"
+    avatar: Optional[str] = None
     temperature: int = 5
     persona_prompt: str = ""
 
@@ -108,6 +112,44 @@ class PersonaItemConfig(_IconValidatorMixin):
             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}"
+        base = os.getenv("REACT_APP_API_URL", "http://localhost:8000").rstrip("/")
+        return f"{base}/api/avatars/bundled/{self.avatar}"
+
     def to_frontend_config(self) -> dict:
         return {
             "id": self.id,
@@ -118,7 +160,7 @@ class PersonaItemConfig(_IconValidatorMixin):
             "bg_color": self.bg_color,
             "dark_color": self.dark_color,
             "dark_bg_color": self.dark_bg_color,
-            "icon": self.icon
+            "image": self._resolve_image(),
             }
 
 

multi_llm_chatbot_backend/app/main.py

@@ -3,8 +3,11 @@ from dotenv import load_dotenv
 
 load_dotenv()
 
+from pathlib import Path
+
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
 from contextlib import asynccontextmanager
 
 # Load configuration FIRST so every module can use it
@@ -58,6 +61,15 @@ app.include_router(auth_router, prefix="/auth", tags=["authentication"])
 app.include_router(chat_sessions_router, prefix="/api", tags=["chat-sessions"])
 app.include_router(phd_canvas_router, prefix="/api", tags=["phd-canvas"])
 
+# Serve bundled avatar images
+_avatars_dir = Path(__file__).resolve().parent / "assets" / "avatars"
+if _avatars_dir.is_dir():
+    app.mount(
+        "/api/avatars/bundled",
+        StaticFiles(directory=_avatars_dir),
+        name="bundled-avatars",
+    )
+
 
 # ---------------------------------------------------------------------------
 # Public configuration endpoint — serves the frontend-safe subset

multi_llm_chatbot_backend/app/tests/unit/test_avatar_resolution.py

@@ -0,0 +1,135 @@
+import unittest
+import tempfile
+import os
+from unittest.mock import patch, MagicMock
+from pathlib import Path
+
+import httpx
+
+from app.config import PersonaItemConfig
+from app.utils.avatar_helpers import get_bundled_avatar_path, list_bundled_avatars
+
+
+class TestAvatarHelpers(unittest.TestCase):
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.tmp_path = Path(self._tmp.name)
+        (self.tmp_path / "advisor1.png").write_bytes(b"fake png")
+        (self.tmp_path / "advisor2.svg").write_bytes(b"<svg/>")
+
+    def tearDown(self):
+        self._tmp.cleanup()
+        list_bundled_avatars.cache_clear()
+
+    @patch("app.utils.avatar_helpers._AVATARS_DIR")
+    def test_get_bundled_avatar_path_returns_path_for_existing_file(self, mock_dir):
+        mock_dir.__class__ = Path
+        with patch("app.utils.avatar_helpers._AVATARS_DIR", self.tmp_path):
+            result = get_bundled_avatar_path("advisor1.png")
+            self.assertEqual(result, self.tmp_path / "advisor1.png")
+
+    @patch("app.utils.avatar_helpers._AVATARS_DIR")
+    def test_get_bundled_avatar_path_returns_none_for_missing_file(self, mock_dir):
+        with patch("app.utils.avatar_helpers._AVATARS_DIR", self.tmp_path):
+            result = get_bundled_avatar_path("nonexistent.png")
+            self.assertIsNone(result)
+
+    def test_get_bundled_avatar_path_returns_none_when_dir_missing(self):
+        with patch("app.utils.avatar_helpers._AVATARS_DIR", Path("/nonexistent/dir")):
+            result = get_bundled_avatar_path("advisor1.png")
+            self.assertIsNone(result)
+
+    def test_list_bundled_avatars_returns_filenames(self):
+        with patch("app.utils.avatar_helpers._AVATARS_DIR", self.tmp_path):
+            list_bundled_avatars.cache_clear()
+            result = list_bundled_avatars()
+            self.assertEqual(result, ("advisor1.png", "advisor2.svg"))
+
+
+class TestResolveImage(unittest.TestCase):
+
+    def test_no_avatar_returns_icon_uri(self):
+        persona = PersonaItemConfig(id="test", name="Test", icon="Brain")
+        self.assertEqual(persona._resolve_image(), "icon://Brain")
+
+    @patch("httpx.head")
+    def test_external_url_passed_through(self, mock_head):
+        mock_head.return_value = MagicMock(is_success=True)
+        persona = PersonaItemConfig(
+            id="test", name="Test", icon="Brain",
+            avatar="https://example.com/avatar.png",
+        )
+        self.assertEqual(
+            persona._resolve_image(),
+            "https://example.com/avatar.png",
+        )
+        mock_head.assert_called_once_with(
+            "https://example.com/avatar.png", timeout=5, follow_redirects=True,
+        )
+
+    @patch("httpx.head")
+    def test_http_url_passed_through(self, mock_head):
+        mock_head.return_value = MagicMock(is_success=True)
+        persona = PersonaItemConfig(
+            id="test", name="Test", icon="Brain",
+            avatar="http://example.com/avatar.png",
+        )
+        self.assertEqual(
+            persona._resolve_image(),
+            "http://example.com/avatar.png",
+        )
+
+    @patch("httpx.head")
+    def test_url_returning_404_falls_back_to_icon(self, mock_head):
+        mock_head.return_value = MagicMock(is_success=False, status_code=404)
+        persona = PersonaItemConfig(
+            id="test", name="Test", icon="Brain",
+            avatar="https://example.com/missing.png",
+        )
+        self.assertEqual(persona._resolve_image(), "icon://Brain")
+
+    @patch("httpx.head")
+    def test_unreachable_url_falls_back_to_icon(self, mock_head):
+        mock_head.side_effect = httpx.ConnectError("DNS lookup failed")
+        persona = PersonaItemConfig(
+            id="test", name="Test", icon="Brain",
+            avatar="https://nonexistent.invalid/avatar.png",
+        )
+        self.assertEqual(persona._resolve_image(), "icon://Brain")
+
+    @patch("httpx.head")
+    def test_url_timeout_falls_back_to_icon(self, mock_head):
+        mock_head.side_effect = httpx.TimeoutException("timed out")
+        persona = PersonaItemConfig(
+            id="test", name="Test", icon="Brain",
+            avatar="https://slow.example.com/avatar.png",
+        )
+        self.assertEqual(persona._resolve_image(), "icon://Brain")
+
+    @patch("app.utils.avatar_helpers.get_bundled_avatar_path")
+    def test_bundled_avatar_exists_returns_path(self, mock_get_path):
+        mock_get_path.return_value = Path("/fake/path/advisor1.png")
+        persona = PersonaItemConfig(
+            id="test", name="Test", icon="Brain", avatar="advisor1.png",
+        )
+        with patch.dict(os.environ, {"REACT_APP_API_URL": "http://localhost:8000"}):
+            self.assertEqual(
+                persona._resolve_image(),
+                "http://localhost:8000/api/avatars/bundled/advisor1.png",
+            )
+
+    @patch("app.utils.avatar_helpers.get_bundled_avatar_path")
+    def test_bundled_avatar_missing_falls_back_to_icon(self, mock_get_path):
+        mock_get_path.return_value = None
+        persona = PersonaItemConfig(
+            id="test", name="Test", icon="Brain", avatar="missing.png",
+        )
+        self.assertEqual(persona._resolve_image(), "icon://Brain")
+
+    def test_to_frontend_config_includes_image_field(self):
+        persona = PersonaItemConfig(id="test", name="Test", icon="Brain")
+        config = persona.to_frontend_config()
+        self.assertIn("image", config)
+        self.assertNotIn("icon", config)
+        self.assertEqual(config["image"], "icon://Brain")

multi_llm_chatbot_backend/app/utils/avatar_helpers.py

@@ -0,0 +1,35 @@
+"""
+Bundled avatar image registry.
+
+Provides helpers for resolving and listing the avatar images shipped in
+``app/assets/avatars/``.
+"""
+
+import logging
+from functools import lru_cache
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_AVATARS_DIR = Path(__file__).resolve().parent.parent / "assets" / "avatars"
+
+
+def get_bundled_avatar_path(name: str) -> Path | None:
+    """Return the filesystem path for a bundled avatar, or *None* if the
+    file does not exist."""
+    if not _AVATARS_DIR.is_dir():
+        return None
+    candidate = _AVATARS_DIR / name
+    if candidate.is_file():
+        return candidate
+    return None
+
+
+@lru_cache(maxsize=1)
+def list_bundled_avatars() -> tuple[str, ...]:
+    """Return the filenames of all bundled avatar images."""
+    if not _AVATARS_DIR.is_dir():
+        return ()
+    avatars = tuple(sorted(f.name for f in _AVATARS_DIR.iterdir() if f.is_file()))
+    logger.info("Found %d bundled avatar images.", len(avatars))
+    return avatars

personas/phd_advisors/critic.yaml

@@ -7,6 +7,7 @@ bg_color: "#FEF2F2"
 dark_color: "#F87171"
 dark_bg_color: "#7F1D1D"
 icon: "Search"
+avatar: "advisor1.png"
 temperature: 6
 persona_prompt: |
   You are a rigorous PhD advisor and Constructive Critic with expertise in academic quality assurance and scholarly rigor. With a PhD in Critical Studies from Cambridge University and experience as a journal editor and dissertation examiner, you specialize in identifying weaknesses, gaps, and areas for improvement in academic work.

personas/phd_advisors/empathetic.yaml

@@ -7,6 +7,7 @@ bg_color: "#FDF2F8"
 dark_color: "#F472B6"
 dark_bg_color: "#BE185D"
 icon: "Heart"
+avatar: "advisor2.png"
 temperature: 6
 persona_prompt: |
   You are a compassionate PhD advisor and Empathetic Listener with expertise in student well-being, emotional support, and holistic academic guidance. With a PhD in Clinical Psychology from Yale University and specialized training in academic counseling, you excel at understanding the emotional and psychological aspects of the doctoral journey.

personas/phd_advisors/methodologist.yaml

@@ -7,6 +7,7 @@ bg_color: "#EFF6FF"
 dark_color: "#60A5FA"
 dark_bg_color: "#1E3A8A"
 icon: "BookOpen"
+avatar: "advisor3.png"
 temperature: 4
 persona_prompt: |
   You are a distinguished PhD advisor and Research Methodology Expert with 15+ years of experience guiding doctoral students across multiple disciplines. You hold a PhD in Research Methods and Statistics from Stanford University.

personas/phd_advisors/minimalist.yaml

@@ -7,6 +7,7 @@ bg_color: "#F9FAFB"
 dark_color: "#9CA3AF"
 dark_bg_color: "#374151"
 icon: "Minus"
+avatar: "advisor4.png"
 temperature: 2
 persona_prompt: |
   You are a focused PhD advisor and Minimalist Mentor with expertise in essential thinking and efficient academic progress. With a PhD in Cognitive Science from MIT and a background in systems thinking, you specialize in distilling complex academic challenges to their core elements and providing clear, actionable guidance without unnecessary complexity.

personas/phd_advisors/motivator.yaml

@@ -7,6 +7,7 @@ bg_color: "#FEF2F2"
 dark_color: "#F87171"
 dark_bg_color: "#991B1B"
 icon: "Zap"
+avatar: "advisor5.png"
 temperature: 6
 persona_prompt: |
   You are an inspiring PhD advisor and Motivational Coach with expertise in academic resilience and peak performance psychology. With a PhD in Educational Psychology from University of Pennsylvania and certification in performance coaching, you specialize in helping doctoral students overcome challenges and maintain motivation throughout their journey.

personas/phd_advisors/pragmatist.yaml

@@ -7,6 +7,7 @@ bg_color: "#ECFDF5"
 dark_color: "#34D399"
 dark_bg_color: "#065F46"
 icon: "Target"
+avatar: "advisor6.png"
 temperature: 5
 persona_prompt: |
   You are an energetic and results-oriented PhD advisor specializing in turning research plans into actionable progress. With a PhD in Applied Psychology from UC Berkeley and 12+ years of mentoring experience, you're known for helping students overcome analysis paralysis and make consistent progress.

personas/phd_advisors/socratic.yaml

@@ -7,6 +7,7 @@ bg_color: "#FEF3C7"
 dark_color: "#FBBF24"
 dark_bg_color: "#92400E"
 icon: "HelpCircle"
+avatar: "advisor7.png"
 temperature: 7
 persona_prompt: |
   You are a distinguished PhD advisor and Socratic Mentor with expertise in critical thinking development and philosophical inquiry. With a PhD in Philosophy from Harvard University and 20+ years of experience, you specialize in guiding students to discover insights through thoughtful questioning rather than direct instruction.

phd-advisor-frontend/src/components/AdvisorCard.js

@@ -1,30 +1,46 @@
-import React from 'react';
+import React, { useState } from 'react';
+import { Pencil } from 'lucide-react';
 import { useAppConfig } from '../contexts/AppConfigContext';
 import { useTheme } from '../contexts/ThemeContext';
+import AvatarPickerModal from './AvatarPickerModal';
 
 const AdvisorCard = ({ advisor, advisorId }) => {
   const Icon = advisor.icon;
   const { isDark } = useTheme();
   const { getAdvisorColors } = useAppConfig();
   const colors = getAdvisorColors(advisorId, isDark);
+  const [hovered, setHovered] = useState(false);
+  const [pickerOpen, setPickerOpen] = useState(false);
 
   return (
-    <div className="advisor-card">
-      <div 
-        className="advisor-card-icon" 
-        style={{ backgroundColor: colors.bgColor }}
-      >
-        <Icon style={{ color: colors.color }} />
+    <>
+      <div className="advisor-card">
+        <div
+          className="advisor-card-icon"
+          style={{ backgroundColor: colors.bgColor, position: 'relative', cursor: 'pointer', overflow: 'hidden' }}
+          onMouseEnter={() => setHovered(true)}
+          onMouseLeave={() => setHovered(false)}
+          onClick={() => setPickerOpen(true)}
+        >
+          {advisor.avatarUrl ? (
+            <img src={advisor.avatarUrl} alt={advisor.name} style={{ width: '100%', height: '100%', objectFit: 'cover', borderRadius: 'inherit' }} />
+          ) : (
+            <Icon style={{ color: colors.color }} />
+          )}
+          {hovered && (
+            <div style={{ position: 'absolute', inset: 0, borderRadius: 'inherit', background: 'rgba(0,0,0,0.45)', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+              <Pencil size={18} color="#fff" />
+            </div>
+          )}
+        </div>
+        <h3 className="advisor-card-title">{advisor.name}</h3>
+        <p className="advisor-card-role" style={{ color: colors.color }}>{advisor.role}</p>
+        <p className="advisor-card-description">{advisor.description}</p>
       </div>
-      <h3 className="advisor-card-title">{advisor.name}</h3>
-      <p 
-        className="advisor-card-role" 
-        style={{ color: colors.color }}
-      >
-        {advisor.role}
-      </p>
-      <p className="advisor-card-description">{advisor.description}</p>
-    </div>
+      {pickerOpen && (
+        <AvatarPickerModal advisorId={advisorId} advisorName={advisor.name} onClose={() => setPickerOpen(false)} />
+      )}
+    </>
   );
 };
 

phd-advisor-frontend/src/components/AdvisorStatusDropdown.js

@@ -1,8 +1,11 @@
 import React, { useState, useEffect } from 'react';
-import { Users, ChevronDown } from 'lucide-react';
+import { Users, ChevronDown, Pencil } from 'lucide-react';
+import AvatarPickerModal from './AvatarPickerModal';
 
 const AdvisorStatusDropdown = ({ advisors, thinkingAdvisors, getAdvisorColors, isDark }) => {
   const [isOpen, setIsOpen] = useState(false);
+  const [hoveredId, setHoveredId] = useState(null);
+  const [pickerAdvisor, setPickerAdvisor] = useState(null);
   
   // Close dropdown when clicking outside
   useEffect(() => {
@@ -50,6 +53,13 @@ const AdvisorStatusDropdown = ({ advisors, thinkingAdvisors, getAdvisorColors, i
         <ChevronDown size={14} className={`dropdown-arrow ${isOpen ? 'rotated' : ''}`} />
       </button>
       
+      {pickerAdvisor && (
+        <AvatarPickerModal
+          advisorId={pickerAdvisor.id}
+          advisorName={pickerAdvisor.name}
+          onClose={() => setPickerAdvisor(null)}
+        />
+      )}
       {isOpen && (
         <div className="advisor-dropdown-panel">
           <div className="advisor-list">
@@ -59,16 +69,27 @@ const AdvisorStatusDropdown = ({ advisors, thinkingAdvisors, getAdvisorColors, i
               const isThinking = Array.isArray(thinkingAdvisors) && thinkingAdvisors.includes(id);
               
               return (
-                <div 
-                  key={id} 
+                <div
+                  key={id}
                   className={`advisor-item ${isThinking ? 'thinking' : ''}`}
-                  style={{ 
-                    '--advisor-color': colors.color,
-                    '--advisor-bg': colors.bgColor
-                  }}
+                  style={{ '--advisor-color': colors.color, '--advisor-bg': colors.bgColor }}
                 >
-                  <div className="advisor-icon">
-                    <IconComponent size={16} />
+                  <div
+                    className="advisor-icon"
+                    style={{ position: 'relative', cursor: 'pointer', overflow: 'hidden', width: 32, height: 32, borderRadius: 8, flexShrink: 0 }}
+                    onMouseEnter={() => setHoveredId(id)}
+                    onMouseLeave={() => setHoveredId(null)}
+                    onClick={() => setPickerAdvisor({ id, name: advisor.name })}
+                  >
+                    {advisor.avatarUrl
+                      ? <img src={advisor.avatarUrl} alt={advisor.name} style={{ width: 32, height: 32, objectFit: 'cover', display: 'block' }} />
+                      : <IconComponent size={16} />
+                    }
+                    {hoveredId === id && (
+                      <div style={{ position: 'absolute', inset: 0, borderRadius: 8, background: 'rgba(0,0,0,0.45)', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+                        <Pencil size={10} color="#fff" />
+                      </div>
+                    )}
                   </div>
                   <div className="advisor-details">
                     <div className="advisor-name">{advisor.name}</div>
@@ -94,7 +115,7 @@ const AdvisorStatusDropdown = ({ advisors, thinkingAdvisors, getAdvisorColors, i
         </div>
       )}
       
-      <style jsx>{`
+      <style>{`
         .advisor-status-dropdown {
           position: relative;
           display: inline-block;

phd-advisor-frontend/src/components/AvatarPickerModal.js

@@ -0,0 +1,75 @@
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { X } from 'lucide-react';
+import { useAppConfig } from '../contexts/AppConfigContext';
+
+const API = process.env.REACT_APP_API_URL || '';
+
+const BUNDLED = [
+  'advisor1.png','advisor2.png','advisor3.png','advisor4.png',
+  'advisor5.png','advisor6.png','advisor7.png',
+];
+
+const overlay = {
+  position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.5)',
+  display: 'flex', alignItems: 'center', justifyContent: 'center', zIndex: 1000,
+};
+
+const modal = {
+  background: 'var(--bg-primary)', borderRadius: 16, padding: 24, width: 480,
+  maxWidth: '95vw', maxHeight: '85vh', overflowY: 'auto',
+  boxShadow: 'var(--shadow-xl)',
+};
+
+const AvatarPickerModal = ({ advisorId, advisorName, onClose }) => {
+  const { setAdvisorAvatar } = useAppConfig();
+
+  const select = (url) => {
+    setAdvisorAvatar(advisorId, url || '');
+    onClose();
+  };
+
+  return ReactDOM.createPortal(
+    <div style={overlay} onClick={(e) => e.target === e.currentTarget && onClose()} onMouseDown={(e) => e.stopPropagation()}>
+      <div style={modal}>
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 20 }}>
+          <h3 style={{ margin: 0, color: 'var(--text-primary)', fontSize: 18 }}>
+            Choose Avatar — {advisorName}
+          </h3>
+          <button onClick={onClose} style={{ background: 'none', border: 'none', cursor: 'pointer', color: 'var(--text-secondary)' }}>
+            <X size={20} />
+          </button>
+        </div>
+
+        <p style={{ margin: '0 0 10px', color: 'var(--text-secondary)', fontSize: 13, fontWeight: 600 }}>Pre-made Avatars</p>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(7, 1fr)', gap: 8, marginBottom: 20 }}>
+          {BUNDLED.map((file) => (
+            <img
+              key={file}
+              src={`${API}/api/avatars/bundled/${file}`}
+              alt={file}
+              onClick={() => select(`${API}/api/avatars/bundled/${file}`)}
+              style={{ width: '100%', aspectRatio: '1', borderRadius: '50%', objectFit: 'cover', cursor: 'pointer', border: '2px solid transparent', transition: 'border-color 0.15s' }}
+              onMouseEnter={e => e.target.style.borderColor = 'var(--accent-primary)'}
+              onMouseLeave={e => e.target.style.borderColor = 'transparent'}
+            />
+          ))}
+        </div>
+
+        <button
+          onClick={() => select(null)}
+          style={{ display: 'flex', alignItems: 'center', gap: 10, padding: '10px 14px', background: 'transparent', border: '1px solid var(--border-primary)', borderRadius: 10, color: 'var(--text-secondary)', cursor: 'pointer', fontSize: 13.5 }}
+        >
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round">
+            <circle cx="12" cy="8" r="4" />
+            <path d="M4 20c0-4 3.6-7 8-7s8 3 8 7" />
+          </svg>
+          Use default icon
+        </button>
+      </div>
+    </div>,
+    document.body
+  );
+};
+
+export default AvatarPickerModal;

phd-advisor-frontend/src/contexts/AppConfigContext.js

@@ -8,18 +8,32 @@ const AppConfigContext = createContext(null);
  * component.  Falls back to HelpCircle if the name isn't found.
  */
 const resolveIcon = (iconName) => {
-  if (!iconName) return LucideIcons.HelpCircle;
-  return LucideIcons[iconName] || LucideIcons.HelpCircle;
+  if (!iconName) return LucideIcons.User;
+  return LucideIcons[iconName] || LucideIcons.User;
 };
 
 /**
  * Build the advisors lookup object (keyed by persona id) from the config
  * personas array, mirroring the shape that components already expect.
  */
-const buildAdvisors = (personaItems) => {
+const buildAdvisors = (personaItems, overrides = {}) => {
   if (!personaItems || !Array.isArray(personaItems)) return {};
   const advisors = {};
   for (const p of personaItems) {
+    const image = p.image || '';
+    const isIcon = image.startsWith('icon://');
+    const rawImageUrl = isIcon ? null : image || null;
+    const configImageUrl = rawImageUrl && rawImageUrl.startsWith('/')
+      ? `${process.env.REACT_APP_API_URL}${rawImageUrl}`
+      : rawImageUrl;
+
+    // Override takes precedence if the advisor has one set.
+    // Override = truthy URL → use it. Override = '' → force default icon.
+    // No override key → fall back to config image.
+    const hasOverride = Object.prototype.hasOwnProperty.call(overrides, p.id);
+    const overrideValue = overrides[p.id];
+    const avatarUrl = hasOverride ? (overrideValue || null) : configImageUrl;
+
     advisors[p.id] = {
       name: p.name,
       role: p.role || '',
@@ -28,7 +42,8 @@ const buildAdvisors = (personaItems) => {
       bgColor: p.bg_color || '#F3F4F6',
       darkColor: p.dark_color || '#9CA3AF',
       darkBgColor: p.dark_bg_color || '#374151',
-      icon: resolveIcon(p.icon),
+      icon: resolveIcon(isIcon ? image.replace('icon://', '') : null),
+      avatarUrl,
     };
   }
   return advisors;
@@ -62,21 +77,27 @@ export const useAppConfig = () => {
 
 export const AppConfigProvider = ({ children }) => {
   const [config, setConfig] = useState(null);
+  const [personaItems, setPersonaItems] = useState([]);
   const [advisors, setAdvisors] = useState({});
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState(null);
+  const [avatarOverrides, setAvatarOverrides] = useState(() => {
+    try { return JSON.parse(localStorage.getItem('advisorAvatarOverrides') || '{}'); }
+    catch { return {}; }
+  });
+  const [myCustomAvatars, setMyCustomAvatars] = useState(() => {
+    try { return JSON.parse(localStorage.getItem('myCustomAvatars') || '[]'); }
+    catch { return []; }
+  });
 
   useEffect(() => {
     const fetchConfig = async () => {
       try {
-        const response = await fetch(
-          `${process.env.REACT_APP_API_URL}/api/config`
-        );
+        const response = await fetch(`${process.env.REACT_APP_API_URL}/api/config`);
         if (!response.ok) throw new Error(`Config fetch failed: ${response.status}`);
         const data = await response.json();
         setConfig(data);
-        const builtAdvisors = buildAdvisors(data.personas?.items);
-        setAdvisors(builtAdvisors);
+        setPersonaItems(data.personas?.items || []);
       } catch (err) {
         console.error('Failed to load app config:', err);
         setError(err.message);
@@ -87,6 +108,23 @@ export const AppConfigProvider = ({ children }) => {
     fetchConfig();
   }, []);
 
+  useEffect(() => {
+    setAdvisors(buildAdvisors(personaItems, avatarOverrides));
+  }, [personaItems, avatarOverrides]);
+
+  const setAdvisorAvatar = (advisorId, url) => {
+    const next = { ...avatarOverrides, [advisorId]: url };
+    setAvatarOverrides(next);
+    localStorage.setItem('advisorAvatarOverrides', JSON.stringify(next));
+  };
+
+  const addMyAvatar = (url) => {
+    if (myCustomAvatars.includes(url)) return;
+    const next = [url, ...myCustomAvatars];
+    setMyCustomAvatars(next);
+    localStorage.setItem('myCustomAvatars', JSON.stringify(next));
+  };
+
   // Inject the primary colour as a CSS custom property on <html> so it is
   // available everywhere without prop-drilling.
   useEffect(() => {
@@ -115,6 +153,9 @@ export const AppConfigProvider = ({ children }) => {
     resolveIcon,
     loading,
     error,
+    setAdvisorAvatar,
+    addMyAvatar,
+    myCustomAvatars,
   };
 
   if (loading) {