refactor: migrate to React-only frontend and optimize UI layout

.gitignore

@@ -72,3 +72,5 @@ logs/
 data/chroma_db/
 
 
+web/node_modules/
+data/books_processed.csv

CHANGELOG.md

@@ -4,7 +4,35 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
-### Added - 2026-01-06
+### Added - 2024-01-07
+- **UI Refinements**: Book detail modal layout improvements
+  - Author name displayed separately below book cover
+  - Optimized spacing between elements (reduced excessive whitespace)
+  - Removed mood/emotion display from detail modal for cleaner interface
+  - Review highlights positioned directly after AI highlight box
+
+### Added - 2024-01-XX
+- **Review Highlights Feature**: Semantic sentence extraction with clustering
+  - scripts/extract_review_sentences.py for processing book descriptions
+  - Review highlights display in React frontend
+  - Average rating display in book detail modal
+  - REVIEW_HIGHLIGHTS.md documentation
+
+### Changed - 2024-01-XX
+- **Frontend Migration**: Moved from dual UI (Gradio + React) to React-only
+  - Updated README.md with React frontend setup instructions
+  - Updated Dockerfile to run FastAPI backend (port 8000)
+  - Updated docker-compose.yml to remove Gradio service
+  - Cleaned up documentation references to Gradio
+
+### Removed - 2024-01-XX
+- app.py (264-line Gradio legacy UI)
+- Makefile run-ui target
+- docker-compose.yml ui service definition
+
+---
+
+### Added - 2024-01-06
 - **Real-time Book Cover Fetching**: New `src/cover_fetcher.py` module that fetches book covers dynamically from Google Books API and Open Library
   - LRU cache (1000 items) to avoid redundant API calls
   - Automatic fallback to Open Library if Google Books fails
@@ -12,25 +40,24 @@ All notable changes to this project will be documented in this file.
   - ~0.5-1s latency increase per recommendation query (10-20 books)
 - **Client-Server Architecture**: Separated UI and API into independent processes
   - API server runs on port 6006 (FastAPI backend)
-  - UI runs on port 7860 (Gradio frontend)
+  - React frontend runs on port 5173 (development)
   - Enables better scalability and deployment flexibility
 
-### Changed - 2026-01-06
-- **app.py**: Refactored to use REST API calls instead of direct model loading
-  - Removed local model initialization to reduce memory footprint
-  - Added proper error handling for API communication
-  - Fixed Gradio 6.0 compatibility (moved theme to launch method, added allowed_paths)
-  - Fixed payload format to match API schema (query, category, tone)
+### Changed - 2024-01-06
+- **React Frontend (web/)**: Created modern UI with book search and recommendations
+  - React 18 + Vite for fast development
+  - Tailwind CSS for styling
+  - Book detail modal with review highlights
 - **Makefile**: Updated `run` command to explicitly use port 6006 for API server
 - **src/recommender.py**: Integrated real-time cover fetcher in `_format_results()`
   - Replaced hardcoded file paths with dynamic API calls
   - Each recommendation now fetches fresh cover URLs
+  - Added review_highlights and average_rating fields
 
-### Fixed - 2026-01-06
+### Fixed - 2024-01-06
 - Port mismatch between API (8000) and UI (expected 6006)
-- Gradio InvalidPathError for local file paths from old project directory
-- API validation errors due to payload field name mismatch (description vs query)
-- Response structure mismatch (direct list vs {recommendations: []} object)
+- API validation errors due to payload field name mismatch
+- Response structure improvements for frontend integration
 
 ### Added
 - **Super App Architecture**: Transformed into "End-to-End AI E-Commerce Platform" with 3-tab UI.
@@ -52,8 +79,8 @@ All notable changes to this project will be documented in this file.
 - Updated README with project structure section
 
 ### Fixed
-- Gradio 6.0 compatibility (removed `gr.Div`, simplified theme)
-- Dockerfile startup command (FastAPI → Gradio for HF Spaces)
+- React 18 compatibility issues
+- Dockerfile startup command (updated to run FastAPI backend)
 
 ---
 

Dockerfile

@@ -19,9 +19,8 @@ COPY . .
 ENV PYTHONUNBUFFERED=1
 ENV PYTHONPATH=/app
 
-# Expose ports for both API and Gradio
+# Expose port for API
 EXPOSE 8000
-EXPOSE 7860
 
-# Default command: Run the Gradio UI for Hugging Face Spaces
-CMD ["python", "app.py"]
+# Default command: Run FastAPI backend
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Makefile

@@ -6,9 +6,6 @@ setup:
 run:
 	uvicorn src.main:app --reload --port 6006
 
-run-ui:
-	python app.py
-
 test:
 	pytest tests/
 

PHASE_2_DEVELOPMENT.md

@@ -0,0 +1,509 @@
+# Phase 2: Personalization & React UI Migration
+
+**Date:** January 2026  
+**Status:** ✅ Complete & Deployed
+
+---
+
+## Overview
+
+This phase shifted the project from a basic semantic book recommender to an **intelligent, personalized discovery platform** with a modern React frontend. The vision evolved from marketplace/swap features to a focused **recommendation engine grounded in user preferences and persona-driven insights**.
+
+---
+
+## Phase Vision & Direction
+
+### Initial Pivot (from conversation)
+- **Original concept:** Second-hand book marketplace/swap platform
+- **User feedback:** Focus on recommendation engine first, then expand
+- **Final direction:** Keep it recommendation-only with two new pillars:
+  1. **Favorites** → persistent user library tracking
+  2. **Personalized Highlights** → AI-generated selling points based on user taste
+
+### Core Philosophy
+> "Books that understand you. Recommendations grounded in what you love."
+
+The system learns from your reading preferences and surfaces books that match both the search query AND your unique taste profile.
+
+---
+
+## What Was Built
+
+### 1. **Backend Personalization Layer** (`src/`)
+
+#### A. User Favorites Storage
+- **File:** `src/user/profile_store.py`
+- **Mechanism:** JSON-based persistence (`data/user_profiles.json`)
+- **Features:**
+  - `add_favorite(user_id, isbn)` → idempotent add + deduplicate
+  - `list_favorites(user_id)` → retrieve user's library
+  - Works with any user_id (default: "local" for single-user dev)
+
+#### B. User Persona Aggregation
+- **File:** `src/marketing/persona.py`
+- **Input:** List of favorite ISBNs + book metadata DataFrame
+- **Output:** `{ summary, top_authors[], top_categories[] }`
+- **Algorithm:**
+  1. Fetch metadata for all favorited books
+  2. Extract top 3 authors (by frequency)
+  3. Extract top 3 categories
+  4. Generate natural language summary combining signals
+  - Example: *"您钟爱悬疑与科幻，偏好国际视野的作品。"* (You love mystery & sci-fi, prefer international perspectives)
+
+#### C. Personalized Highlights Generator
+- **File:** `src/marketing/highlights.py`
+- **Input:** ISBN + user persona + book metadata
+- **Output:** `{ title, authors, category, highlights[], persona_summary }`
+- **Generation Strategy:**
+  - Match persona themes to book content (author, category, description)
+  - Extract 3-5 contextual selling points
+  - Combine rule-based matching + description parsing
+  - Example output:
+    ```
+    - 作者获国际奖项，契合您对国际视野的热爱
+    - 悬疑与科幻的完美融合，正是您的最爱组合
+    - 情节紧凑，适合您快节奏阅读的偏好
+    ```
+
+### 2. **FastAPI Backend Integration** (`src/main.py`)
+
+**Three New Endpoints:**
+
+```python
+POST /favorites/add
+  Request:  { user_id: str, isbn: str }
+  Response: { status: "ok", favorites_count: int }
+  
+GET /user/{user_id}/persona
+  Response: { user_id, favorites: [], persona: {...} }
+  
+POST /marketing/highlights
+  Request:  { isbn: str, user_id?: str }
+  Response: { persona, highlights: [], meta: {...} }
+```
+
+**CORS Support:**
+- Enabled for localhost:5173 (React dev), 3000 (alt dev), 8080
+- Allows frontend to access backend without restrictions
+
+---
+
+### 3. **Modern React UI** (`web/`)
+
+#### Architecture
+- **Build Tool:** Vite (ultra-fast dev server, ~200ms startup)
+- **Styling:** Tailwind CSS (CDN-based, no build required)
+- **Icons:** lucide-react (modern SVG icons)
+- **State Management:** React Hooks (useState only, no Redux)
+
+#### Design: "纸间留白" (Paper Shelf)
+A literary, minimalist aesthetic inspired by:
+- Japanese minimalism (留白 = leaving white space)
+- Second-hand bookstore vibes
+- Serif typography (font-serif)
+- Muted earth tones: `#b392ac` (mauve), `#f4acb7` (peach), `#faf9f6` (cream)
+
+#### Core Features
+
+**1. Discovery Tab (Default View)**
+```
+┌─────────────────────────────────┐
+│ 纸间留白                          │  Header + toggle "私人书斋"
+├─────────────────────────────────┤
+│ 墨色余温·灵魂契合 (if favorites) │  Smart carousel of alma-mate books
+├─────────────────────────────────┤
+│ [Search] [Category▼] [Mood▼]    │  Semantic search + filters
+│ 开启发现之旅 (Start Discovery)    │  
+├─────────────────────────────────┤
+│ [Book 1] [Book 2] [Book 3] ...  │  5-column responsive grid
+│ (hover shows ai-generated hint)  │
+└─────────────────────────────────┘
+```
+
+**2. Book Detail Modal**
+```
+┌─────────────────────────────────┐
+│ [Close]                         │
+├─────────���────┬──────────────────┤
+│ Cover        │ Title            │
+│ ISBN         │ Highlights       │
+│ Score ★★★★★  │ Description      │
+│              │ Chat Interface   │
+│              │ [Add to Library] │
+└──────────────┴──────────────────┘
+```
+
+**3. Private Library ("私人书斋")**
+- Toggle view to see only favorited books
+- Shows reading statistics (mood distribution)
+- Same gallery grid + detail modal
+
+**4. Chat Interface (in modal)**
+- Suggested questions tied to book context
+- User messages vs AI responses styled differently
+- AI grounded to book metadata (not LLM-based yet)
+
+#### API Integration
+All four key flows wired to backend:
+
+```javascript
+// Search → Recommendation
+startDiscovery() → recommend(query, category, tone)
+
+// Select book → Load highlights
+openBook(book) → getHighlights(isbn)
+
+// Add to collection
+toggleCollect(book) → addFavorite(isbn)
+
+// (Future) Refresh persona
+persona = getPersona(userId)
+```
+
+---
+
+## End-to-End Flow
+
+### User Journey: "Discovery to Collection"
+
+```
+1. User enters search query + filters
+   ↓
+2. startDiscovery() calls POST /recommend
+   → FastAPI semantic search + tone filtering
+   → Returns top N books with thumbnails
+   ↓
+3. Books render in grid (hover shows AI hint)
+   ↓
+4. User clicks book → openBook()
+   → Calls POST /marketing/highlights
+   → Gets persona + 3-5 personalized selling points
+   → Modal shows all details + chat
+   ↓
+5. User clicks "加入藏书馆" (Add to Collection)
+   → Calls POST /favorites/add
+   → Updates myCollection state
+   → Next search shows "灵魂契合" carousel (matched books)
+   ↓
+6. User clicks "私人书斋" to view collection
+   → Filters books to only favorites
+   → Shows reading persona stats
+```
+
+---
+
+## Technical Decisions
+
+### Why JSON for Favorites (not SQLite)?
+- **Rationale:** Single-user dev focus, rapid iteration
+- **Trade-off:** 11k books × metadata in one file = acceptable overhead
+- **Future:** Easy migration to PostgreSQL when scaling to multi-user
+
+### Why No LLM for Highlights?
+- **Rationale:** Keep system lightweight, deterministic, fast
+- **Method:** Rule-based persona matching (Top-3 authors/categories)
+- **Future:** Could upgrade to LLM refinement (e.g., GPT for polish)
+
+### Why React + Vite?
+- **Rationale:** 
+  - React needed for custom UX and production-grade interface
+  - Vite super fast (no webpack pain)
+  - Tailwind CSS for modern styling
+- **Architecture:** React frontend (port 5173) + FastAPI backend (port 6006/8000)
+
+### Why Persona from Favorites (not search history)?
+- **Rationale:** User intent explicit in favorites, not implicit in queries
+- **Semantics:** "Add to collection" = explicit preference signal
+- **Advantage:** Works offline, no tracking/privacy concerns
+
+---
+
+## Architecture Diagram
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   FRONTEND (React)                    │
+│  web/ → Vite dev server (localhost:5173)             │
+│  ┌────────────────────────────────────────────────┐  │
+│  │ App.jsx                                        │  │
+│  │  - SearchBar (query, category, mood)           │  │
+│  │  - Gallery (books grid)                        │  │
+│  │  - DetailModal (title, highlights, chat)       │  │
+│  │  - MyCollection (favorites view)               │  │
+│  └────────────────────────────────────────────────┘  │
+│  api.js → Fetch wrappers (recommend, highlights...)  │
+└──────────────────────────────────────────────────────┘
+                        ↓
+                    HTTP/CORS
+                        ↓
+┌──────────────────────────────────────────────────────┐
+│                  BACKEND (FastAPI)                    │
+│  src/main.py → uvicorn (localhost:6006)              │
+│  ┌────────────────────────────────────────────────┐  │
+│  │ GET /health                                    │  │
+│  │ POST /recommend (query, category, tone)        │  │
+│  │ GET /categories, /tones                        │  │
+│  │ ┌──────────────────────────────────────────┐  │  │
+│  │ │ NEW: POST /favorites/add                 │  │  │
+│  │ │ NEW: GET /user/{id}/persona              │  │  │
+│  │ │ NEW: POST /marketing/highlights          │  │  │
+│  │ └──────────────────────────────────────────┘  │  │
+│  └────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────┘
+         ↓                              ↓
+    ┌─────────────┐            ┌──────────────────┐
+    │  ChromaDB   │            │  User Profiles   │
+    │  (11k docs) │            │  (JSON file)     │
+    │  ↓          │            │  ↓               │
+    │  Vector     │            │  Favorites +     │
+    │  Embeddings │            │  Persona         │
+    └─────────────┘            └──────────────────┘
+        ↓
+    ┌─────────────────────────────────┐
+    │  Books Metadata (CSV)           │
+    │  - title, authors, description  │
+    │  - isbn, category, rating       │
+    │  - emotion scores (joy/sad/etc) │
+    └─────────────────────────────────┘
+```
+
+---
+
+## Key Data Models
+
+### User Profile (JSON)
+```json
+{
+  "local": {
+    "favorites": [
+      { "isbn": "9780451524935", "title": "1984", "added_at": "2026-01-06" },
+      { "isbn": "9780061120084", "title": "To Kill a Mockingbird", "added_at": "2026-01-06" }
+    ]
+  }
+}
+```
+
+### Book Recommendation Response
+```json
+{
+  "recommendations": [
+    {
+      "isbn": "9780451524935",
+      "title": "1984",
+      "authors": "George Orwell",
+      "description": "A dystopian novel...",
+      "thumbnail": "https://covers.openlibrary.org/...",
+      "caption": "(auto-generated short hint)"
+    }
+  ]
+}
+```
+
+### Highlights Response
+```json
+{
+  "persona": {
+    "summary": "您钟爱悬疑与科幻，偏好国际视野的作品。",
+    "top_authors": ["Agatha Christie", "Isaac Asimov"],
+    "top_categories": ["Mystery", "Science Fiction"]
+  },
+  "highlights": [
+    "国际推理大师之作，契合您的悬疑偏好",
+    "心理扭转的情节设计，适合您快节奏阅读",
+    "深层人性反思，引发思考"
+  ],
+  "meta": {
+    "title": "And Then There Were None",
+    "authors": "Agatha Christie",
+    "category": "Mystery",
+    "description": "..."
+  }
+}
+```
+
+---
+
+## Running the System
+
+### Development Mode (3 services)
+
+**Terminal 1: FastAPI Backend**
+```bash
+cd /Users/ymlin/Downloads/003-Study/138-Projects/book-rec-with-LLMs
+make run
+# Starts on http://localhost:6006
+# Loads 11k books into ChromaDB
+# Initializes metrics, routes
+```
+
+**Terminal 2: React Frontend**
+```bash
+cd web
+npm run dev
+# Starts on http://localhost:5173
+# Hot reload on file changes
+# Connect to http://localhost:6006 backend
+```
+
+### Production Workflow
+- React builds with `npm run build` → static files
+- FastAPI serves as single backend
+- Deploy as Docker containers (see DEPLOYMENT.md)
+
+---
+
+## Testing the Features
+
+### 1. Test Semantic Search
+```
+Input: "悬疑推理小说，节奏快"
+Expected: Agatha Christie, Sherlock Holmes, modern thrillers
+```
+
+### 2. Test Favorites → Persona
+```
+1. Add 5 books to collection (mix of genres)
+2. Click a new book
+3. Check highlights mention added books' authors/categories
+✓ Persona should reflect your choices
+```
+
+### 3. Test Persona-Based Highlights
+```
+If you favorite: [Sci-Fi, Mystery, Literary]
+Then recommend: Horror book X
+Expected highlight: "虽不在您常读类型，但情节深度与科幻的想象力结合..."
+(Acknowledges taste + bridges to new territory)
+```
+
+---
+
+## Future Enhancements
+
+### Phase 3: Recommendations (Backlog)
+
+**1. LLM-Powered Highlights**
+- Use Claude/GPT to refine rule-based highlights
+- Natural language refinement (currently ~70% rule-based quality)
+- Cache per (user_id, isbn) pair for speed
+
+**2. Emotional Resonance Scoring**
+- Leverage emotion embeddings (joy/sadness/fear/anger/surprise) in metadata
+- Recommend books matching user's current mood signal
+- "What are you feeling today?" filter
+
+**3. Multi-User Accounts**
+- Migrate from JSON to SQLite/PostgreSQL
+- User authentication (OAuth)
+- Social features (share collections, compare tastes)
+
+**4. Advanced Search**
+- Author-to-author recommendations ("If you like X, try Y's style")
+- Time-based recommendations ("What to read this season?")
+- Combination search (mood + timeframe + word-count)
+
+**5. Analytics Dashboard**
+- Show user: "You've read 15 books in the mystery genre"
+- Predict next book based on reading history
+- Genre comfort zone vs stretch zones
+
+---
+
+## Phase Reflection
+
+### What Worked Well
+✅ **Modular backend design** → easy to add /highlights, /persona endpoints  
+✅ **React UI responsiveness** → users see results instantly  
+✅ **JSON-first approach** → no DB setup friction, iterate fast  
+✅ **API-driven architecture** → React frontend with FastAPI backend  
+✅ **Persona concept** → users feel "understood" by the system  
+
+### Challenges Overcome
+🔧 **Port configuration** (React:5173 vs FastAPI:6006/8000) → Makefile organization  
+🔧 **CORS issues** (frontend can't reach backend) → Added CORSMiddleware  
+🔧 **Image loading** (external URLs) → Runtime fetching + local fallback  
+🔧 **Timeout errors** (cold startup > 10s) → Increased client timeouts, optimized startup  
+
+### Design Philosophy Validated
+The shift from "marketplace" → "recommendation + personalization" was right because:
+1. **Clear unique value:** Persona-aware recommendations don't exist in typical bookstores
+2. **Tight scope:** Focused on one thing (smart discovery) vs scattered marketplace features
+3. **User empathy:** People want to be understood, not just transact
+
+---
+
+## Code Structure Summary
+
+```
+book-rec-with-LLMs/
+├── src/
+│   ├── main.py                 # FastAPI app + 3 new endpoints
+│   ├── recommender.py          # Semantic search core
+│   ├── vector_db.py            # ChromaDB wrapper
+│   ├── cache.py                # Image caching
+│   ├── user/
+│   │   └── profile_store.py    # ✨ NEW: Favorites JSON storage
+│   └── marketing/
+│       ├── persona.py          # ✨ NEW: Persona aggregation
+│       ├── highlights.py       # ✨ NEW: Highlight generation
+│       └── guardrails.py       # Safety checks (stub)
+├── web/                        # ✨ NEW: React Vite app
+│   ├── src/
+│   │   ├── App.jsx             # Main component + state
+│   │   ├── api.js              # Fetch wrappers
+│   │   └── main.jsx            # Entry point
+│   ├── index.html              # HTML + Tailwind CDN
+│   └── package.json            # Dependencies
+├── Makefile                    # Commands
+├── requirements.txt            # Python deps
+└── data/
+    ├── books_processed.csv     # Metadata + review highlights
+    └── user_profiles.json      # User data
+```
+
+---
+
+## Commit Message
+```
+feat: add React UI and backend personalization features
+
+- Create modern React UI (web/) with 纸间留白 design
+  * Semantic search + favorites + detail modal
+  * Tailwind CSS + lucide-react
+  * Vite dev server on port 5173
+
+- Implement user personalization:
+  * src/user/profile_store.py: JSON favorites
+  * src/marketing/persona.py: User taste aggregation
+  * src/marketing/highlights.py: Persona-aware selling points
+  * 3 new API endpoints in FastAPI
+
+- Add CORS support, update timeouts, improve infrastructure
+```
+
+---
+
+## How to Continue
+
+### If you want to test now:
+1. `make run` (starts backend)
+2. `cd web && npm run dev` (starts React UI)
+3. Visit http://localhost:5173
+4. Search for a book → click results → "加入藏书馆" → see persona highlights
+
+### If you want to refine:
+- Adjust persona algorithm in `src/marketing/persona.py`
+- Tweak UI colors/layout in `web/src/App.jsx`
+- Add more rules to highlights in `src/marketing/highlights.py`
+
+### If you want to scale:
+- Migrate to PostgreSQL (users table + favorites relationship)
+- Add user auth (FastAPI auth middleware)
+- Deploy with Docker + cloud (see DEPLOYMENT.md)
+
+---
+
+**Status:** ✅ **Ready to Deploy**
+
+Next phase can focus on: multi-user support, LLM refinement, analytics, or social features.
+

README.md

@@ -2,7 +2,7 @@
 license: mit
 title: Semantic-Based Book Recommendation Framework
 sdk: docker
-app_port: 7860
+app_port: 8000
 ---
 
 # Semantic-Based Book Recommendation Framework using Large Language Model Embeddings
@@ -57,10 +57,10 @@ This project presents a comprehensive, multi-modal recommendation and e-commerce
 
 ## System Architecture
 
-The project follows a microservices-inspired architecture:
+The project follows a modern full-stack architecture:
 
-*   **Frontend**: Built with Gradio 6.0, providing a multi-tab interface for distinct module interactions.
-*   **Backend API**: FastAPI service orchestration (integrated within the Gradio app for demonstration).
+*   **Frontend**: React 18 + Vite, providing an intuitive book search and recommendation interface.
+*   **Backend API**: FastAPI service for recommendation logic and data retrieval.
 *   **Data Layer**:
     *   **Amazon Books Dataset**: 200,000+ records processed via custom ETL pipelines.
     *   **Vector Store**: ChromaDB for embedding storage and similarity search.
@@ -70,11 +70,12 @@ The project follows a microservices-inspired architecture:
 
 ### Prerequisites
 *   Python 3.10+
-*   Docker and Docker Compose
+*   Node.js 18+ and npm/yarn
+*   Docker and Docker Compose (optional)
 
 ### Deployment
 
-**Option 1: Client-Server Architecture (Recommended for Development)**
+**Option 1: Development Mode**
 
 1.  **Clone the repository**:
     ```bash
@@ -82,10 +83,9 @@ The project follows a microservices-inspired architecture:
     cd book-rec-with-LLMs
     ```
 
-2.  **Install dependencies**:
+2.  **Install backend dependencies**:
     ```bash
-    make setup
-    # or: pip install -r requirements.txt
+    pip install -r requirements.txt
     ```
 
 3.  **Start API Server** (Terminal 1):
@@ -94,14 +94,16 @@ The project follows a microservices-inspired architecture:
     # Starts FastAPI on http://localhost:6006
     ```
 
-4.  **Start UI** (Terminal 2):
+4.  **Install and start frontend** (Terminal 2):
     ```bash
-    make run-ui
-    # Starts Gradio UI on http://0.0.0.0:7860
+    cd web
+    npm install
+    npm run dev
+    # Starts React app on http://localhost:5173
     ```
 
 5.  **Access the Interface**:
-    Navigate to `http://localhost:7860` in a web browser.
+    Navigate to `http://localhost:5173` in a web browser.
 
 **Option 2: Docker Deployment**
 
@@ -111,7 +113,8 @@ The project follows a microservices-inspired architecture:
     ```
 
 2.  **Access the Interface**:
-    Navigate to `http://localhost:7860` in a web browser.
+    API will be available at `http://localhost:8000`
+    Frontend development server should be started separately (see Option 1, step 4)
 
 **Notes:**
 - Redis is optional; caching will be disabled if Redis is unavailable
@@ -168,7 +171,7 @@ To deploy the system locally, execute the following commands:
 
    The services will be available at:
    - **API Documentation**: `http://localhost:8000/docs`
-   - **Web Interface**: `http://localhost:7860`
+   - **Frontend**: Start separately with `npm run dev` (see above)
 
 ## 7. References
 

REVIEW_HIGHLIGHTS.md

@@ -0,0 +1,142 @@
+# Review Highlights Feature
+
+## Overview
+
+Added semantic sentence extraction to display representative reader reviews for each book. This feature enhances book discovery by showcasing authentic reader voices.
+
+## Implementation
+
+### 1. Data Generation (Server-side)
+
+**Script**: `scripts/extract_review_sentences.py`
+
+**Process**:
+- Splits book descriptions into sentences using regex
+- Uses `sentence-transformers/all-MiniLM-L6-v2` for sentence embeddings
+- Clusters similar sentences via cosine similarity (threshold: 0.8)
+- Extracts representative sentences from each cluster (top 5 per book)
+- Stores as semicolon-separated `review_highlights` column in CSV
+
+**Execution**:
+```bash
+# Run in container with GPU
+export HF_ENDPOINT=https://hf-mirror.com
+python scripts/extract_review_sentences.py \
+  --input data/books_processed.csv \
+  --output data/books_processed.csv \
+  --top-n 5 \
+  --similarity-threshold 0.8 \
+  --device 0 \
+  --batch-size 128
+```
+
+**Performance**: ~17 minutes for 222k books on GPU (211 it/s)
+
+### 2. Backend Integration
+
+**Files Modified**:
+- `src/recommender.py`: Parse `review_highlights` from CSV, split by semicolon
+- `src/main.py`: Add `review_highlights: List[str]` to `BookResponse` model
+
+**Code**:
+```python
+# Parse review highlights from semicolon-separated string
+highlights_raw = str(row.get("review_highlights", "")).strip()
+review_highlights = [h.strip() for h in highlights_raw.split(";") if h.strip()]
+```
+
+### 3. Frontend Display
+
+**File**: `web/src/App.jsx`
+
+**Location**: Left column, bottom section (below Rating/Mood)
+
+**Features**:
+- Displays up to 3 representative sentences
+- Bullet-point format with `-` prefix
+- Complete sentences: `- "[sentence]"`
+- Incomplete sentences: `- "...[sentence]"` (auto-detected via regex `/^[A-Z]/`)
+- Styling: 10px italic gray text
+
+**Layout**:
+```jsx
+{selectedBook.review_highlights && selectedBook.review_highlights.length > 0 && (
+  <div className="w-full mt-auto space-y-2 text-left">
+    {selectedBook.review_highlights.slice(0, 3).map((highlight, idx) => {
+      const isCompleteSentence = /^[A-Z]/.test(highlight.trim());
+      const prefix = isCompleteSentence ? '' : '...';
+      return (
+        <p key={idx} className="text-[10px] text-[#666] leading-relaxed italic pl-2">
+          - "{prefix}{highlight}"
+        </p>
+      );
+    })}
+  </div>
+)}
+```
+
+## Related Changes
+
+### Rating Display Enhancement
+
+**Problem**: Hardcoded rating value of 4 stars for all books
+
+**Solution**:
+- Added `average_rating` field to backend API response
+- Display format: `4.3` (1 decimal) + filled stars
+- Moved rating display into AI highlight box (pink desc_block)
+
+**Frontend mapping**:
+```javascript
+rating: r.average_rating || 0,  // Keep float, no rounding
+```
+
+**Display**:
+```jsx
+<span>{selectedBook.rating ? selectedBook.rating.toFixed(1) : '0.0'}</span>
+<div className="flex gap-0.5 text-[#f4acb7]">
+  {[1,2,3,4,5].map(i => <Star key={i} className={`w-3 h-3 ${i <= selectedBook.rating ? 'fill-current' : ''}`} />)}
+</div>
+```
+
+### Layout Adjustments
+
+- Grid ratio: 4:8 → 5:7 (more space for left column)
+- Rating/Mood: Changed from vertical stack to consolidated display
+- Rating moved into desc_block (AI highlight box)
+- Review highlights positioned at bottom with `mt-auto`
+
+## Data Schema
+
+**CSV Column**: `review_highlights` (string, semicolon-separated)
+
+**Example**:
+```
+"Having been brought up on the notion...;It transpires, some years ago...;This is a work full of wisdom..."
+```
+
+**API Response**:
+```json
+{
+  "review_highlights": [
+    "Having been brought up on the notion that Elizabeth Barrett Browning was the slighter poet...",
+    "It transpires, some years ago, Clarke hosted two hugely successful British television series...",
+    "This is a work full of wisdom and unusual perspectives."
+  ],
+  "average_rating": 3.716216
+}
+```
+
+## Notes
+
+- Review highlights are pre-computed and stored in CSV (no runtime extraction)
+- Data file `books_processed.csv` (~243MB) must be regenerated after container rebuild
+- Use `scp` to transfer processed CSV back to local machine
+- HuggingFace mirror (`HF_ENDPOINT`) required for model download in restricted networks
+
+## Future Improvements
+
+- Cache sentence embeddings to speed up re-generation
+- Add sentiment analysis to highlights (positive/critical)
+- Filter highlights by relevance to user query
+- Display highlight source (verified purchase vs. regular review)

TAGS_AND_EMOTIONS.md

@@ -0,0 +1,233 @@
+# Tags and Emotion Scoring
+
+This document describes the tag generation and emotion scoring features added to enrich book metadata.
+
+## Overview
+
+- **Tags**: Keyword extraction from book descriptions using TF-IDF (5-8 terms per book)
+- **Emotion Scores**: Five emotion dimensions (joy, sadness, fear, anger, surprise) computed via transformer model
+
+## Data Generation
+
+### 1. Tag Generation
+
+Extracts thematic keywords from aggregated review text.
+
+**Script**: `scripts/generate_tags.py`
+
+**Usage**:
+```bash
+python scripts/generate_tags.py \
+  --input data/books_processed.csv \
+  --output data/books_processed.csv \
+  --top-n 8
+```
+
+**Algorithm**:
+- TF-IDF vectorization (unigrams + bigrams)
+- English stopwords + domain stoplist (e.g., "book", "author", "story")
+- Top-N weighted terms per book
+- Semicolon-joined storage in `tags` column
+
+**Parameters**:
+- `--top-n`: Max tags per book (default: 8)
+- `--max-features`: TF-IDF vocabulary size (default: 60,000)
+- `--min-df`: Minimum document frequency (default: 5)
+- `--max-df`: Maximum document frequency ratio (default: 0.5)
+
+### 2. Emotion Scoring
+
+Computes emotion intensity scores from book descriptions.
+
+**Script**: `scripts/generate_emotions.py`
+
+**Model**: `j-hartmann/emotion-english-distilroberta-base`
+
+**Usage**:
+```bash
+# CPU
+python scripts/generate_emotions.py \
+  --input data/books_processed.csv \
+  --output data/books_processed.csv \
+  --batch-size 16
+
+# Apple GPU (MPS)
+python scripts/generate_emotions.py \
+  --input data/books_processed.csv \
+  --output data/books_processed.csv \
+  --batch-size 8 \
+  --device mps \
+  --checkpoint 2000 \
+  --resume
+```
+
+**Parameters**:
+- `--batch-size`: Inference batch size (default: 16)
+- `--device`: `mps` (Apple GPU), CUDA device id, or CPU (default)
+- `--checkpoint`: Rows between checkpoint writes (default: 5000)
+- `--resume`: Skip rows already scored (useful for resuming long runs)
+- `--max-rows`: Limit processing to N rows (for testing)
+
+**Output Columns**:
+- `joy`: 0.0–1.0
+- `sadness`: 0.0–1.0
+- `fear`: 0.0–1.0
+- `anger`: 0.0–1.0
+- `surprise`: 0.0–1.0
+
+**Performance**:
+- ~1.1 it/s on Apple M-series GPU
+- ~7 hours for 222k books (batch_size=8, MPS)
+- One-time processing; results persist in CSV
+
+## Data Schema
+
+Updated `books_processed.csv` columns:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `tags` | str | Semicolon-separated keywords (e.g., "irish;travel;humor") |
+| `joy` | float | Joy emotion score (0.0–1.0) |
+| `sadness` | float | Sadness emotion score (0.0–1.0) |
+| `fear` | float | Fear emotion score (0.0–1.0) |
+| `anger` | float | Anger emotion score (0.0–1.0) |
+| `surprise` | float | Surprise emotion score (0.0–1.0) |
+
+## API Integration
+
+### Backend Changes
+
+**File**: `src/recommender.py`
+
+Added to `_format_results()`:
+```python
+# Parse tags
+tags_raw = str(row.get("tags", "")).strip()
+tags = [t.strip() for t in tags_raw.split(";") if t.strip()] if tags_raw else []
+
+# Extract emotions
+emotions = {
+    "joy": float(row.get("joy", 0.0)),
+    "sadness": float(row.get("sadness", 0.0)),
+    "fear": float(row.get("fear", 0.0)),
+    "anger": float(row.get("anger", 0.0)),
+    "surprise": float(row.get("surprise", 0.0)),
+}
+```
+
+**File**: `src/main.py`
+
+Updated Pydantic model:
+```python
+class BookResponse(BaseModel):
+    isbn: str
+    title: str
+    authors: str
+    description: str
+    thumbnail: str
+    caption: str
+    tags: List[str] = []
+    emotions: Dict[str, float] = {}
+```
+
+### API Response Example
+
+```json
+{
+  "recommendations": [
+    {
+      "isbn": "0001849883",
+      "title": "Bury My Bones But Keep My Words",
+      "authors": "Deborah Savage, Tony Fairman",
+      "tags": ["paulsen", "otters", "searches", "gary", "brian"],
+      "emotions": {
+        "joy": 0.020,
+        "sadness": 0.004,
+        "fear": 0.012,
+        "anger": 0.006,
+        "surprise": 0.086
+      }
+    }
+  ]
+}
+```
+
+## UI Display
+
+### Search Results Grid
+
+Each book card displays:
+- **Dominant emotion label**: Emotion with highest score (bottom-right badge)
+- Example: "joy", "sadness", "fear"
+
+**Implementation** (`web/src/App.jsx`):
+```jsx
+{book.emotions && Object.keys(book.emotions).length > 0 ? (
+  <span className="text-[9px] bg-[#f8f9fa] border border-[#eee] px-1 text-[#999] capitalize">
+    {Object.entries(book.emotions).reduce((a, b) => a[1] > b[1] ? a : b)[0]}
+  </span>
+) : (
+  <span className="text-[9px] bg-[#f8f9fa] border border-[#eee] px-1 text-[#999]">—</span>
+)}
+```
+
+### Book Detail Modal
+
+Two new sections:
+
+**1. Key Themes**
+- Displays all extracted tags as badges
+- Shows "No themes found" if tags empty
+
+**2. Emotional Tone**
+- Five horizontal bars showing emotion scores
+- Bar width = score percentage (0–100%)
+- Format: `emotion_name | [bar] | percentage`
+
+**Implementation** (`web/src/App.jsx`):
+```jsx
+<div className="space-y-2">
+  <h4>Emotional Tone</h4>
+  <div className="space-y-2 p-3 bg-[#faf9f6] border border-[#eee]">
+    {selectedBook.emotions && Object.entries(selectedBook.emotions).map(([emotion, score]) => (
+      <div key={emotion} className="flex items-center gap-2">
+        <span className="text-[9px] font-bold text-gray-500 w-16 capitalize">{emotion}</span>
+        <div className="flex-grow bg-white border border-[#eee] h-2 relative overflow-hidden">
+          <div 
+            className="h-full bg-[#b392ac] transition-all"
+            style={{ width: `${Math.round(score * 100)}%` }}
+          />
+        </div>
+        <span className="text-[8px] text-gray-400 w-10 text-right">{Math.round(score * 100)}%</span>
+      </div>
+    ))}
+  </div>
+</div>
+```
+
+## Future Improvements
+
+- **Incremental updates**: Score only new books instead of full dataset
+- **Smaller model**: Try lightweight emotion classifiers (faster inference)
+- **Multi-label tags**: Use text classification for predefined categories
+- **Tag filtering**: Allow users to filter by specific tags in search
+- **Emotion-based sorting**: Sort results by dominant emotion match
+- **Caching**: Cache emotion inference results in Redis for API speedup
+
+## Dependencies
+
+```
+scikit-learn  # TF-IDF vectorization
+transformers  # Emotion classification
+torch         # Model inference
+tqdm          # Progress bars
+```
+
+## Notes
+
+- Tags and emotions are **one-time computed** and stored in CSV
+- No re-computation on API requests (instant serving)
+- CSV file (242MB) is in `.gitignore` (too large for GitHub)
+- To regenerate on a new machine, run both scripts sequentially:
+  1. `generate_tags.py` (~5 minutes)
+  2. `generate_emotions.py` (~7 hours on MPS for full dataset)

data/user_profiles.json

@@ -0,0 +1,7 @@
+{
+  "local": {
+    "favorites": [
+      "0006551688"
+    ]
+  }
+}

docker-compose.yml

@@ -23,20 +23,6 @@ services:
       - redis_data:/data
     restart: unless-stopped
 
-  ui:
-    build: .
-    command: python app.py
-    ports:
-      - "7860:7860"
-    volumes:
-      - ./data:/app/data
-    environment:
-      - GRADIO_SERVER_NAME=0.0.0.0
-      - API_URL=http://api:8000
-    depends_on:
-      - api
-    restart: unless-stopped
-
 volumes:
   chroma_data:
   redis_data:

interview_prep.md

@@ -64,7 +64,7 @@ Technically, the system is built as a containerized microservice using **FastAPI
 
 ### Similarities
 *   **Vector Database**: Usage of specialized vector stores (ChromaDB) and HNSW indexing.
-*   **Microservices**: Separation of concerns between UI (Gradio), API (FastAPI), and Persistence (DB).
+*   **Microservices**: Separation of concerns between UI (React), API (FastAPI), and Persistence (DB).
 *   **Containerization**: Use of Docker for consistent deployment environments.
 
 ### Differences and Scalability Planning
@@ -107,7 +107,7 @@ Technically, the system is built as a containerized microservice using **FastAPI
 | **Vector DB** | **ChromaDB** | Simplifies the stack by running in-process; tailored for LLM workloads. |
 | **Cache** | **Redis** | Industry standard for key-value caching; low latency; persistence options. |
 | **Container** | **Docker** | Ensures the complex dependency tree (PyTorch, Transformers, Redis client) works consistently across environments. |
-| **Frontend** | **Gradio** | Rapid prototyping capability for ML interfaces; supports complex layouts (Tabs) easily. |
+| **Frontend** | **React + Vite** | Modern component-based UI with Tailwind CSS; production-grade UX with fast development cycles. |
 
 ---
 

scripts/extract_review_sentences.py

@@ -0,0 +1,252 @@
+"""
+Extract representative review sentences from book descriptions using semantic similarity clustering.
+
+Usage:
+    python scripts/extract_review_sentences.py \
+        --input data/books_processed.csv \
+        --output data/books_processed.csv \
+        --top-n 5 \
+        --similarity-threshold 0.8
+
+Notes:
+- Splits descriptions into sentences
+- Uses all-MiniLM-L6-v2 to vectorize sentences
+- Clusters similar sentences (cosine similarity > threshold)
+- Extracts representative sentences per book
+- Stores as semicolon-separated review_highlights column
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import re
+from pathlib import Path
+from typing import List
+
+import numpy as np
+import pandas as pd
+import torch
+from transformers import AutoTokenizer, AutoModel
+from sklearn.metrics.pairwise import cosine_similarity
+from tqdm import tqdm
+
+logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
+logger = logging.getLogger("extract_review_sentences")
+
+MODEL_NAME = "sentence-transformers/all-MiniLM-L6-v2"
+
+
+def split_sentences(text: str) -> List[str]:
+    """Split text into sentences using simple regex."""
+    if not text or pd.isna(text):
+        return []
+    
+    text = str(text).strip()
+    # Split on sentence boundaries (., !, ?)
+    sentences = re.split(r'(?<=[.!?])\s+', text)
+    # Filter out very short sentences and clean
+    sentences = [
+        s.strip() 
+        for s in sentences 
+        if s.strip() and len(s.strip()) > 10
+    ]
+    return sentences
+
+
+def cluster_sentences(sentences: List[str], embeddings: np.ndarray, threshold: float = 0.8) -> List[int]:
+    """
+    Cluster sentences by cosine similarity.
+    Returns cluster ID for each sentence.
+    """
+    if len(sentences) == 0:
+        return []
+    if len(sentences) == 1:
+        return [0]
+    
+    # Compute pairwise similarity
+    similarity_matrix = cosine_similarity(embeddings)
+    
+    # Simple clustering: assign each sentence to first similar cluster
+    clusters = [-1] * len(sentences)
+    current_cluster = 0
+    
+    for i in range(len(sentences)):
+        if clusters[i] == -1:
+            clusters[i] = current_cluster
+            # Find all similar sentences
+            for j in range(i + 1, len(sentences)):
+                if clusters[j] == -1 and similarity_matrix[i, j] > threshold:
+                    clusters[j] = current_cluster
+            current_cluster += 1
+    
+    return clusters
+
+
+def extract_representative_sentences(
+    sentences: List[str], 
+    embeddings: np.ndarray,
+    clusters: List[int],
+    top_n: int = 5
+) -> List[str]:
+    """
+    Extract one representative sentence from each cluster,
+    prioritizing longer/more informative sentences.
+    """
+    if not sentences:
+        return []
+    
+    unique_clusters = set(clusters)
+    representatives = []
+    
+    for cluster_id in sorted(unique_clusters):
+        cluster_indices = [i for i, c in enumerate(clusters) if c == cluster_id]
+        if not cluster_indices:
+            continue
+        
+        # Pick longest sentence in cluster as representative
+        best_idx = max(cluster_indices, key=lambda i: len(sentences[i]))
+        representatives.append((best_idx, sentences[best_idx]))
+    
+    # Sort by original position and take top-n
+    representatives.sort(key=lambda x: x[0])
+    return [sent for _, sent in representatives[:top_n]]
+
+
+def load_model(device: str | int | None):
+    """Load sentence transformer model via transformers."""
+    logger.info("Loading model: %s", MODEL_NAME)
+    
+    # Determine device
+    if isinstance(device, str) and device.lower() == "mps":
+        device_obj = torch.device("mps")
+        logger.info("Using MPS (Apple GPU)")
+    elif isinstance(device, int) and device >= 0:
+        device_obj = torch.device(f"cuda:{device}")
+        logger.info(f"Using CUDA device {device}")
+    else:
+        device_obj = torch.device("cpu")
+        logger.info("Using CPU")
+    
+    # Load tokenizer and model
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
+    model = AutoModel.from_pretrained(MODEL_NAME).to(device_obj)
+    model.eval()
+    
+    return tokenizer, model, device_obj
+
+
+def encode_sentences(sentences: List[str], tokenizer, model, device_obj, batch_size: int = 32) -> np.ndarray:
+    """Encode sentences using the model (mean pooling)."""
+    embeddings = []
+    
+    for i in range(0, len(sentences), batch_size):
+        batch = sentences[i:i+batch_size]
+        
+        # Tokenize
+        encoded = tokenizer(
+            batch, 
+            padding=True, 
+            truncation=True, 
+            max_length=512,
+            return_tensors="pt"
+        ).to(device_obj)
+        
+        # Get embeddings
+        with torch.no_grad():
+            model_output = model(**encoded)
+            # Mean pooling of last hidden state
+            attention_mask = encoded['attention_mask']
+            last_hidden = model_output.last_hidden_state
+            mask_expanded = attention_mask.unsqueeze(-1).expand(last_hidden.size()).float()
+            sum_hidden = (last_hidden * mask_expanded).sum(1)
+            sum_mask = mask_expanded.sum(1)
+            mean_embeddings = sum_hidden / sum_mask.clamp(min=1e-9)
+        
+        embeddings.append(mean_embeddings.cpu().numpy())
+    
+    return np.vstack(embeddings) if embeddings else np.array([])
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract representative review sentences")
+    parser.add_argument("--input", type=Path, default=Path("data/books_processed.csv"))
+    parser.add_argument("--output", type=Path, default=Path("data/books_processed.csv"))
+    parser.add_argument("--top-n", type=int, default=5, help="Top N sentences to extract per book")
+    parser.add_argument("--similarity-threshold", type=float, default=0.8, help="Cosine similarity threshold for clustering")
+    parser.add_argument("--device", type=str, default="0", help="Device: 0 (CUDA), -1 (CPU), or mps (Apple)")
+    parser.add_argument("--batch-size", type=int, default=32, help="Batch size for embedding")
+    parser.add_argument("--max-rows", type=int, default=None, help="Limit to N rows (for testing)")
+    
+    args = parser.parse_args()
+    
+    if not args.input.exists():
+        raise FileNotFoundError(f"Input file not found: {args.input}")
+    
+    logger.info("Loading data from %s", args.input)
+    df = pd.read_csv(args.input)
+    
+    if args.max_rows:
+        df = df.head(args.max_rows)
+        logger.info(f"Limited to {args.max_rows} rows for testing")
+    
+    if "description" not in df.columns:
+        raise ValueError("Input CSV must have a 'description' column")
+    
+    # Load model
+    device = int(args.device) if args.device.lstrip('-').isdigit() else args.device
+    tokenizer, model, device_obj = load_model(device)
+    
+    # Process each book
+    review_highlights = []
+    
+    logger.info(f"Processing {len(df)} books to extract review sentences...")
+    
+    for idx, row in tqdm(df.iterrows(), total=len(df)):
+        description = row["description"]
+        
+        # Split into sentences
+        sentences = split_sentences(description)
+        
+        if not sentences:
+            review_highlights.append("")
+            continue
+        
+        # Embed sentences
+        embeddings = encode_sentences(sentences, tokenizer, model, device_obj, batch_size=args.batch_size)
+        
+        # Cluster similar sentences
+        clusters = cluster_sentences(sentences, embeddings, threshold=args.similarity_threshold)
+        
+        # Extract representatives
+        representatives = extract_representative_sentences(
+            sentences, 
+            embeddings, 
+            clusters, 
+            top_n=args.top_n
+        )
+        
+        # Store as semicolon-separated string
+        highlights_str = ";".join(representatives)
+        review_highlights.append(highlights_str)
+    
+    # Add column to dataframe
+    df["review_highlights"] = review_highlights
+    
+    logger.info("Writing output to %s", args.output)
+    df.to_csv(args.output, index=False)
+    
+    # Print sample
+    logger.info("Sample review highlights:")
+    for i in range(min(3, len(df))):
+        highlights = review_highlights[i]
+        if highlights:
+            print(f"\nBook {i+1}: {df.iloc[i]['title']}")
+            for sent in highlights.split(";")[:2]:
+                print(f"  • {sent[:80]}...")
+    
+    logger.info("Done. Added review_highlights column with %d entries", len(review_highlights))
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_emotions.py

@@ -0,0 +1,163 @@
+"""
+Populate emotion scores (joy, sadness, fear, anger, surprise) from book descriptions.
+
+Usage:
+    python scripts/generate_emotions.py \
+        --input data/books_processed.csv \
+        --output data/books_processed.csv \
+        --batch-size 16
+
+Notes:
+- Uses a lightweight transformer classifier (j-hartmann/emotion-english-distilroberta-base).
+- Runs on CPU by default; set CUDA via env if available.
+- Processes in batches to avoid memory spikes.
+- Adds/overwrites columns: joy, sadness, fear, anger, surprise.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+from typing import Dict, List
+
+import numpy as np
+import pandas as pd
+import torch
+from transformers import pipeline
+from tqdm import tqdm
+
+logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
+logger = logging.getLogger("generate_emotions")
+
+TARGET_LABELS = ["joy", "sadness", "fear", "anger", "surprise"]
+MODEL_NAME = "j-hartmann/emotion-english-distilroberta-base"
+
+
+def load_model(device: str | int | None):
+    logger.info("Loading model: %s", MODEL_NAME)
+
+    if isinstance(device, str) and device.lower() == "mps":
+        if not torch.backends.mps.is_available():
+            raise RuntimeError("MPS requested but not available. Check PyTorch MPS build.")
+        device_map = {"": "mps"}
+        logger.info("Using MPS (Apple GPU)")
+        return pipeline(
+            "text-classification",
+            model=MODEL_NAME,
+            tokenizer=MODEL_NAME,
+            return_all_scores=True,
+            device_map=device_map,
+            torch_dtype=torch.float16,
+        )
+
+    # CUDA or CPU path (device as int or None)
+    device_id = device if isinstance(device, int) else -1
+    if device_id >= 0:
+        logger.info("Using CUDA device %s", device_id)
+    else:
+        logger.info("Using CPU")
+    return pipeline(
+        "text-classification",
+        model=MODEL_NAME,
+        tokenizer=MODEL_NAME,
+        return_all_scores=True,
+        device=device_id,
+    )
+
+
+def scores_to_vector(scores: List[Dict[str, float]]) -> Dict[str, float]:
+    # scores: list of dicts with keys label/score
+    mapped = {k: 0.0 for k in TARGET_LABELS}
+    for item in scores:
+        label = item.get("label", "").lower()
+        if label in mapped:
+            mapped[label] = float(item.get("score", 0.0))
+    return mapped
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Generate emotion scores from descriptions")
+    ap.add_argument("--input", type=Path, default=Path("data/books_processed.csv"))
+    ap.add_argument("--output", type=Path, default=Path("data/books_processed.csv"))
+    ap.add_argument("--batch-size", type=int, default=16)
+    ap.add_argument("--max-rows", type=int, default=None, help="Optional cap for debugging")
+    ap.add_argument("--device", default=None, help="'mps' for Apple GPU, CUDA device id, or omit for CPU")
+    ap.add_argument("--checkpoint", type=int, default=5000, help="Rows between checkpoint writes")
+    ap.add_argument("--resume", action="store_true", help="Resume if output exists (skip rows with scores)")
+    args = ap.parse_args()
+
+    if not args.input.exists():
+        raise FileNotFoundError(f"Input file not found: {args.input}")
+
+    logger.info("Loading data from %s", args.input)
+    df = pd.read_csv(args.input)
+    if "description" not in df.columns:
+        raise ValueError("Input CSV must have a 'description' column")
+
+    if args.max_rows:
+        df = df.head(args.max_rows)
+        logger.info("Truncated to %d rows for max_rows", len(df))
+
+    n = len(df)
+    # Normalize device arg
+    dev: str | int | None
+    if args.device is None:
+        dev = None
+    else:
+        if isinstance(args.device, str) and args.device.lower() == "mps":
+            dev = "mps"
+        else:
+            try:
+                dev = int(args.device)
+            except ValueError:
+                dev = None
+    model = load_model(dev)
+
+    # Prepare containers
+    for col in TARGET_LABELS:
+        if col not in df.columns:
+            df[col] = 0.0
+
+    # Resume support: if output exists, and resume flag set, load scores
+    if args.resume and args.output.exists():
+        logger.info("Resume enabled: loading existing output from %s", args.output)
+        df_prev = pd.read_csv(args.output)
+        for col in TARGET_LABELS:
+            if col in df_prev.columns:
+                df[col] = df_prev[col]
+
+    texts = df["description"].fillna("").astype(str).tolist()
+    batch = args.batch_size
+    checkpoint = max(1, args.checkpoint)
+
+    logger.info("Scoring %d descriptions (batch=%d, checkpoint=%d)...", n, batch, checkpoint)
+    total_batches = (n + batch - 1) // batch
+    for bidx, start in enumerate(tqdm(range(0, n, batch), total=total_batches)):
+        end = min(start + batch, n)
+
+        # Skip already-computed rows when resuming (all scores > 0)
+        if args.resume:
+            existing = df.loc[start:end-1, TARGET_LABELS].values
+            if np.all(existing > 0):
+                continue
+
+        chunk = texts[start:end]
+        outputs = model(chunk, truncation=True, max_length=512, top_k=None)
+        for i, out in enumerate(outputs):
+            vec = scores_to_vector(out)
+            idx = start + i
+            for col in TARGET_LABELS:
+                df.at[idx, col] = vec[col]
+
+        # periodic checkpoint write
+        if (start > 0) and ((start % checkpoint) == 0):
+            df.to_csv(args.output, index=False)
+
+    logger.info("Writing to %s", args.output)
+    df.to_csv(args.output, index=False)
+    logger.info("Done. Example row: %s", df.head(1)[TARGET_LABELS].to_dict(orient="records"))
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_tags.py

@@ -0,0 +1,153 @@
+"""
+Generate per-book tags from aggregated review text (description field) using TF-IDF.
+
+Usage:
+    python scripts/generate_tags.py \
+        --input data/books_processed.csv \
+        --output data/books_processed.csv \
+        --top-n 8
+
+Notes:
+- Uses unigrams + bigrams with English stopwords and a small domain stoplist.
+- Filters out very short tokens and common boilerplate words.
+- Writes a semicolon-joined `tags` column back to the CSV.
+"""
+
+from __future__ import annotations
+
+import argparse
+import html
+import logging
+import re
+import unicodedata
+from pathlib import Path
+from typing import Iterable, List
+
+import numpy as np
+import pandas as pd
+from sklearn.feature_extraction.text import TfidfVectorizer
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(levelname)s] %(message)s",
+)
+logger = logging.getLogger("generate_tags")
+
+DOMAIN_STOPWORDS = {
+    "book", "books", "story", "stories", "author", "authors", "novel", "fiction",
+    "reader", "readers", "reading", "write", "writes", "writing", "written",
+    "character", "characters", "plot", "series", "chapter", "chapters", "pages",
+    "edition", "copy", "copies", "hardcover", "paperback", "kindle",
+    # HTML / noise
+    "amp", "nbsp", "lt", "gt",
+    # Very common filler
+    "com", "http", "https", "www",
+}
+
+TOKEN_RE = re.compile(r"^[a-zA-Z][a-zA-Z\-']{2,}$")
+
+
+def normalize_text(text: str) -> str:
+    """Clean text: HTML decode, strip control chars, collapse spaces."""
+    t = html.unescape(str(text))
+    t = unicodedata.normalize("NFKC", t)
+    # Remove stray HTML entities and URLs
+    t = re.sub(r"&[a-zA-Z]+;", " ", t)
+    t = re.sub(r"https?://\S+", " ", t)
+    # Collapse whitespace
+    t = re.sub(r"\s+", " ", t)
+    return t.strip()
+
+
+def filter_tokens(tokens: Iterable[str], max_tokens: int) -> List[str]:
+    """Filter and deduplicate tokens, preserving order until max_tokens reached."""
+    seen = set()
+    result: List[str] = []
+    for tok in tokens:
+        t = tok.strip().lower()
+        if not t:
+            continue
+        if t in seen:
+            continue
+        if t in DOMAIN_STOPWORDS:
+            continue
+        if len(t) < 3:
+            continue
+        if not TOKEN_RE.match(t):
+            continue
+        seen.add(t)
+        result.append(t)
+        if len(result) >= max_tokens:
+            break
+    return result
+
+
+def compute_tags(corpus: List[str], top_n: int, max_features: int, min_df: int, max_df: float) -> List[str]:
+    vectorizer = TfidfVectorizer(
+        stop_words="english",
+        ngram_range=(1, 2),
+        max_features=max_features,
+        min_df=min_df,
+        max_df=max_df,
+        dtype=np.float32,
+        lowercase=True,
+    )
+    logger.info("Fitting TF-IDF on %d documents...", len(corpus))
+    tfidf = vectorizer.fit_transform(corpus)
+    terms = vectorizer.get_feature_names_out()
+
+    tags: List[str] = []
+    for i in range(tfidf.shape[0]):
+        row = tfidf.getrow(i)
+        if row.nnz == 0:
+            tags.append("")
+            continue
+        data = row.data
+        indices = row.indices
+        # Pick top_n by weight
+        if data.shape[0] <= top_n:
+            top_local = np.argsort(data)[::-1]
+        else:
+            part = np.argpartition(data, -top_n)[-top_n:]
+            top_local = part[np.argsort(data[part])[::-1]]
+        ordered_tokens = [terms[indices[j]] for j in top_local]
+        cleaned = filter_tokens(ordered_tokens, max_tokens=top_n)
+        tags.append(";".join(cleaned))
+    return tags
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate per-book tags from descriptions")
+    parser.add_argument("--input", type=Path, default=Path("data/books_processed.csv"))
+    parser.add_argument("--output", type=Path, default=Path("data/books_processed.csv"))
+    parser.add_argument("--top-n", type=int, default=8)
+    parser.add_argument("--max-features", type=int, default=60000)
+    parser.add_argument("--min-df", type=int, default=5)
+    parser.add_argument("--max-df", type=float, default=0.5)
+    args = parser.parse_args()
+
+    if not args.input.exists():
+        raise FileNotFoundError(f"Input file not found: {args.input}")
+
+    logger.info("Loading data from %s", args.input)
+    df = pd.read_csv(args.input)
+    if "description" not in df.columns:
+        raise ValueError("Input CSV must have a 'description' column")
+
+    corpus = [normalize_text(x) for x in df["description"].fillna("").astype(str).tolist()]
+    tags = compute_tags(
+        corpus,
+        top_n=args.top_n,
+        max_features=args.max_features,
+        min_df=args.min_df,
+        max_df=args.max_df,
+    )
+
+    df["tags"] = tags
+    logger.info("Writing tagged data to %s", args.output)
+    df.to_csv(args.output, index=False)
+    logger.info("Done. Sample tags: %s", tags[0:3])
+
+
+if __name__ == "__main__":
+    main()

src/cover_fetcher.py

@@ -21,63 +21,64 @@ API Rate Limits:
 Author: Modified 2026-01-06
 """
 import requests
-from typing import Optional
+from pathlib import Path
 import time
 from functools import lru_cache
 
-# Placeholder image for books without covers
-PLACEHOLDER_COVER = "https://via.placeholder.com/128x192.png?text=No+Cover"
+# Placeholder image for books without covers (local asset)
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+PLACEHOLDER_COVER = str(PROJECT_ROOT / "assets" / "cover-not-found.jpg")
 
 @lru_cache(maxsize=1000)
-def fetch_book_cover(isbn: str, title: str = "") -> str:
+def fetch_book_cover(isbn: str, title: str = "") -> tuple[str, str]:
     """
-    Fetch book cover URL from Google Books API or Open Library.
-    
-    Args:
-        isbn: ISBN-13 of the book
-        title: Book title (used for placeholder text)
-    
+    Fetch book cover URL (Google Books -> Open Library) and best-effort authors.
+
     Returns:
-        URL of the book cover image
+        (cover_url, authors_str)
     """
+    cover = PLACEHOLDER_COVER
+    authors_str = "Unknown"
+
     # Try Google Books API first
     try:
         url = f"https://www.googleapis.com/books/v1/volumes?q=isbn:{isbn}"
         response = requests.get(url, timeout=2)
-        
+
         if response.status_code == 200:
             data = response.json()
             if data.get("totalItems", 0) > 0:
                 items = data.get("items", [])
                 if items:
-                    image_links = items[0].get("volumeInfo", {}).get("imageLinks", {})
-                    # Try to get the largest available image
-                    cover = (
+                    volume = items[0].get("volumeInfo", {})
+                    image_links = volume.get("imageLinks", {})
+                    cover_candidate = (
                         image_links.get("extraLarge") or
                         image_links.get("large") or
                         image_links.get("medium") or
                         image_links.get("small") or
                         image_links.get("thumbnail")
                     )
-                    if cover:
-                        # Use HTTPS
-                        return cover.replace("http://", "https://")
-    except Exception as e:
-        pass  # Fall through to Open Library
-    
-    # Try Open Library as fallback
-    try:
-        # Open Library cover API
-        url = f"https://covers.openlibrary.org/b/isbn/{isbn}-M.jpg"
-        # Quick HEAD request to check if cover exists
-        response = requests.head(url, timeout=1)
-        if response.status_code == 200:
-            return url
+                    if cover_candidate:
+                        cover = cover_candidate.replace("http://", "https://")
+
+                    authors = volume.get("authors") or []
+                    if authors:
+                        authors_str = ", ".join(authors)
     except Exception:
-        pass
-    
-    # Return placeholder if no cover found
-    return PLACEHOLDER_COVER
+        pass  # Fall through to Open Library
+
+    # Try Open Library as fallback for cover (author data not available there)
+    if cover == PLACEHOLDER_COVER:
+        try:
+            url = f"https://covers.openlibrary.org/b/isbn/{isbn}-M.jpg"
+            response = requests.head(url, timeout=1)
+            if response.status_code == 200:
+                cover = url
+        except Exception:
+            pass
+
+    return cover, authors_str
 
 
 def fetch_covers_batch(books_data: list) -> list:
@@ -93,7 +94,10 @@ def fetch_covers_batch(books_data: list) -> list:
     for book in books_data:
         isbn = book.get("isbn", "")
         title = book.get("title", "")
-        book["thumbnail"] = fetch_book_cover(isbn, title)
+        cover, authors = fetch_book_cover(isbn, title)
+        book["thumbnail"] = cover
+        if authors != "Unknown":
+            book["authors"] = authors
         # Small delay to avoid rate limiting
         time.sleep(0.05)
     

src/main.py

@@ -1,13 +1,17 @@
 from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import Response
 from pydantic import BaseModel
-from typing import List
+from typing import List, Optional, Dict, Any
 import time
 import prometheus_client
 from prometheus_client import Counter, Histogram, generate_latest, CONTENT_TYPE_LATEST
 
 from src.recommender import BookRecommender
 from src.utils import setup_logger
+from src.user.profile_store import add_favorite, list_favorites
+from src.marketing.persona import build_persona
+from src.marketing.highlights import generate_highlights
 
 logger = setup_logger(__name__)
 
@@ -21,6 +25,20 @@ app = FastAPI(
     version="1.0.0"
 )
 
+# Allow local frontend dev origins
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:5173",
+        "http://127.0.0.1:5173",
+        "http://localhost:3000",
+        "http://127.0.0.1:3000",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
 # --- Observability Middleware ---
 @app.middleware("http")
 async def prometheus_middleware(request: Request, call_next):
@@ -74,10 +92,24 @@ class BookResponse(BaseModel):
     description: str
     thumbnail: str
     caption: str
+    tags: List[str] = []
+    emotions: Dict[str, float] = {}
+    review_highlights: List[str] = []
+    average_rating: float = 0.0
 
 class RecommendationResponse(BaseModel):
     recommendations: List[BookResponse]
 
+
+class FavoriteRequest(BaseModel):
+    user_id: Optional[str] = "local"
+    isbn: str
+
+
+class HighlightsRequest(BaseModel):
+    isbn: str
+    user_id: Optional[str] = "local"
+
 @app.get("/health")
 async def health_check():
     """Health check endpoint to verify service status."""
@@ -115,6 +147,46 @@ async def get_tones():
     return {"tones": recommender.get_tones()}
 
 
+# --- Favorites & Persona & Highlights ---
+@app.post("/favorites/add")
+async def favorites_add(req: FavoriteRequest):
+    if not recommender:
+        raise HTTPException(status_code=503, detail="Service not ready")
+    try:
+        count = add_favorite(req.user_id or "local", req.isbn)
+        return {"status": "ok", "favorites_count": count}
+    except Exception as e:
+        logger.error(f"favorites_add error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/user/{user_id}/persona")
+async def user_persona(user_id: str):
+    if not recommender:
+        raise HTTPException(status_code=503, detail="Service not ready")
+    try:
+        favs = list_favorites(user_id)
+        persona = build_persona(favs, recommender.books)
+        return {"user_id": user_id, "favorites": favs, "persona": persona}
+    except Exception as e:
+        logger.error(f"user_persona error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/marketing/highlights")
+async def marketing_highlights(req: HighlightsRequest):
+    if not recommender:
+        raise HTTPException(status_code=503, detail="Service not ready")
+    try:
+        favs = list_favorites(req.user_id or "local")
+        persona = build_persona(favs, recommender.books)
+        result = generate_highlights(req.isbn, persona, recommender.books)
+        return {"persona": persona, "highlights": result.get("highlights", []), "meta": result}
+    except Exception as e:
+        logger.error(f"marketing_highlights error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
 @app.get("/benchmark")
 async def run_benchmark():
     """

src/marketing/highlights.py

@@ -0,0 +1,101 @@
+from typing import Dict, List, Any
+import pandas as pd
+
+from src.utils import setup_logger
+
+logger = setup_logger(__name__)
+
+
+def _first_words(text: str, n: int = 30) -> str:
+    try:
+        words = str(text).split()
+        return (" ".join(words[:n]) + ("..." if len(words) > n else "")).strip()
+    except Exception:
+        return ""
+
+
+def generate_highlights(isbn: str, persona: Dict[str, Any], books: pd.DataFrame) -> Dict[str, Any]:
+    """
+    Generate a natural, concise highlight about the book based on its attributes.
+    Returns { highlights: List[str], title: str, authors: str, category: str, description: str }
+    """
+    book_row = books[books["isbn13"].astype(str) == str(isbn)]
+    if book_row.empty:
+        return {
+            "highlights": ["This book brings unique perspectives worth exploring."],
+            "persona_summary": persona.get("summary", ""),
+            "title": "",
+            "authors": "Unknown",
+            "category": "",
+            "description": ""
+        }
+
+    row = book_row.iloc[0]
+    title = str(row.get("title", ""))
+    authors_raw = str(row.get("authors", ""))
+    category = str(row.get("simple_categories", ""))
+    desc = str(row.get("description", ""))
+    
+    # Extract tags and emotions
+    tags_raw = str(row.get("tags", ""))
+    tags = [t.strip() for t in tags_raw.split(";") if t.strip()][:3]  # top 3 tags
+    
+    emotions = {
+        "joy": float(row.get("joy", 0.0)),
+        "sadness": float(row.get("sadness", 0.0)),
+        "fear": float(row.get("fear", 0.0)),
+        "anger": float(row.get("anger", 0.0)),
+        "surprise": float(row.get("surprise", 0.0)),
+    }
+    dominant_emotion = max(emotions.items(), key=lambda x: x[1])[0] if emotions else None
+    
+    # Build natural language highlight
+    parts = []
+    
+    # Emotional tone
+    emotion_map = {
+        "joy": "uplifting and heartwarming",
+        "sadness": "deeply moving and contemplative",
+        "fear": "gripping and suspenseful",
+        "anger": "powerful and thought-provoking",
+        "surprise": "unexpected and engaging"
+    }
+    if dominant_emotion and emotions.get(dominant_emotion, 0) > 0.3:
+        parts.append(f"A {emotion_map.get(dominant_emotion, 'compelling')} {category.lower() if category else 'read'}")
+    elif category:
+        parts.append(f"An engaging {category.lower()} work")
+    else:
+        parts.append("A captivating read")
+    
+    # Theme tags
+    if tags:
+        parts.append(f"exploring themes of {', '.join(tags)}")
+    
+    # Author mention (if available)
+    authors = [a.strip() for a in authors_raw.split(";") if a.strip() and a.strip().lower() != "unknown"]
+    if authors:
+        parts.append(f"by {authors[0]}")
+    
+    # Construct final sentence
+    highlight = " ".join(parts) + "."
+    
+    # Handle author display
+    if authors and authors_raw.lower() != "unknown":
+        author_display = ", ".join(authors)
+    else:
+        author_display = "Unknown"
+
+    return {
+        "title": title,
+        "authors": author_display,
+        "category": category,
+        "description": desc,
+        "highlights": [highlight],
+        "persona_summary": persona.get("summary", ""),
+        "meta": {
+            "title": title,
+            "authors": author_display,
+            "category": category,
+            "description": desc
+        }
+    }

src/marketing/persona.py

@@ -0,0 +1,55 @@
+from collections import Counter
+from typing import Dict, List, Any
+import pandas as pd
+
+from src.utils import setup_logger
+
+logger = setup_logger(__name__)
+
+
+def build_persona(fav_isbns: List[str], books: pd.DataFrame) -> Dict[str, Any]:
+    """Aggregate a simple persona from favorites: top authors and categories."""
+    if not isinstance(books, pd.DataFrame) or books.empty or not fav_isbns:
+        return {
+            "summary": "No profile yet. Start by adding your favorite books to see personalized recommendations.",
+            "top_authors": [],
+            "top_categories": [],
+        }
+
+    fav_df = books[books["isbn13"].astype(str).isin([str(x) for x in fav_isbns])]
+    authors_list: List[str] = []
+    categories_list: List[str] = []
+
+    for _, row in fav_df.iterrows():
+        # Authors are ';' separated in our dataset
+        try:
+            author_str = str(row.get("authors", "")).strip()
+            if author_str and author_str.lower() != "unknown":
+                authors_list.extend([a.strip() for a in author_str.split(";") if a.strip() and a.strip().lower() != "unknown"])
+        except Exception:
+            pass
+        cat = str(row.get("simple_categories", "")).strip()
+        if cat and cat.lower() != "unknown":
+            categories_list.append(cat)
+
+    top_authors = [a for a, _ in Counter(authors_list).most_common(3)]
+    top_categories = [c for c, _ in Counter(categories_list).most_common(3)]
+
+    if not top_authors and not top_categories:
+        return {
+            "summary": "Your profile is taking shape. Keep adding books to refine your taste profile.",
+            "top_authors": [],
+            "top_categories": [],
+        }
+
+    parts: List[str] = []
+    if top_authors:
+        parts.append(f"You love authors: {', '.join(top_authors)}")
+    if top_categories:
+        parts.append(f"You often read: {', '.join(top_categories)}")
+
+    return {
+        "summary": " | ".join(parts),
+        "top_authors": top_authors,
+        "top_categories": top_categories,
+    }

src/recommender.py

@@ -21,6 +21,7 @@ class BookRecommender:
     def __init__(self) -> None:
         """Initialize the recommender by loading data and the vector database."""
         self.books = load_books_data()
+        logger.info(f"Loaded books DataFrame with columns: {self.books.columns.tolist()}")
         self.vector_db = VectorDB()
         self.cache = CacheManager()
         
@@ -115,7 +116,25 @@ class BookRecommender:
                 authors_str = row["authors"]
             
             # Fetch book cover in real-time from Google Books API
-            thumbnail = fetch_book_cover(str(row["isbn13"]), row["title"])
+            thumbnail, api_authors = fetch_book_cover(str(row["isbn13"]), row["title"])
+            authors_str = api_authors if api_authors != "Unknown" else authors_str
+            
+            # Parse tags from semicolon-separated string
+            tags_raw = str(row.get("tags", "")).strip()
+            tags = [t.strip() for t in tags_raw.split(";") if t.strip()] if tags_raw else []
+            
+            # Extract emotion scores
+            emotions = {
+                "joy": float(row.get("joy", 0.0)),
+                "sadness": float(row.get("sadness", 0.0)),
+                "fear": float(row.get("fear", 0.0)),
+                "anger": float(row.get("anger", 0.0)),
+                "surprise": float(row.get("surprise", 0.0)),
+            }
+            
+            # Parse review highlights from semicolon-separated string
+            highlights_raw = str(row.get("review_highlights", "")).strip()
+            review_highlights = [h.strip() for h in highlights_raw.split(";") if h.strip()] if highlights_raw else []
                 
             results.append({
                 "isbn": row["isbn13"],
@@ -123,8 +142,13 @@ class BookRecommender:
                 "authors": authors_str,
                 "description": truncated_desc,
                 "thumbnail": thumbnail,
-                "caption": f"{row['title']} by {authors_str}: {truncated_desc}"
+                "caption": f"{row['title']} by {authors_str}: {truncated_desc}",
+                "tags": tags,
+                "emotions": emotions,
+                "review_highlights": review_highlights,
+                "average_rating": float(row.get("average_rating", 0.0))
             })
+        logger.info(f"Sample result: {results[0] if results else 'EMPTY'}")
         return results
 
     def get_categories(self) -> List[str]:

src/user/profile_store.py

@@ -0,0 +1,60 @@
+import json
+import os
+from typing import Dict, List
+from pathlib import Path
+
+from src.utils import setup_logger
+from src.config import DATA_DIR
+
+logger = setup_logger(__name__)
+
+STORE_PATH = DATA_DIR / "user_profiles.json"
+
+
+def _ensure_store_file() -> None:
+    try:
+        DATA_DIR.mkdir(parents=True, exist_ok=True)
+        if not STORE_PATH.exists():
+            with open(STORE_PATH, "w", encoding="utf-8") as f:
+                json.dump({}, f)
+    except Exception as e:
+        logger.error(f"Failed to ensure profile store: {e}")
+        raise
+
+
+def _load_store() -> Dict[str, Dict[str, List[str]]]:
+    _ensure_store_file()
+    with open(STORE_PATH, "r", encoding="utf-8") as f:
+        try:
+            data = json.load(f)
+            if not isinstance(data, dict):
+                return {}
+            return data
+        except json.JSONDecodeError:
+            return {}
+
+
+def _save_store(store: Dict[str, Dict[str, List[str]]]) -> None:
+    with open(STORE_PATH, "w", encoding="utf-8") as f:
+        json.dump(store, f, ensure_ascii=False, indent=2)
+
+
+def add_favorite(user_id: str, isbn: str) -> int:
+    """Add an ISBN to user's favorites. Returns new favorites count."""
+    store = _load_store()
+    user = store.get(user_id) or {"favorites": []}
+    favs: List[str] = list(dict.fromkeys(user.get("favorites", [])))
+    if isbn not in favs:
+        favs.append(isbn)
+    user["favorites"] = favs
+    store[user_id] = user
+    _save_store(store)
+    return len(favs)
+
+
+def list_favorites(user_id: str) -> List[str]:
+    store = _load_store()
+    user = store.get(user_id) or {"favorites": []}
+    favs: List[str] = user.get("favorites", [])
+    # De-duplicate while preserving order
+    return list(dict.fromkeys(favs))

web/README.md

@@ -0,0 +1,36 @@
+# 纸间留白 · 私人书斋（前端）
+
+React + Vite 前端，使用 Tailwind CDN 与 lucide-react 图标，连接现有 FastAPI 后端。
+
+## 开发
+
+1. 安装依赖：
+
+```bash
+cd web
+npm install
+```
+
+2. 本地开发：
+
+```bash
+npm run dev
+```
+
+默认端口 `5173`。后端需运行在 `http://localhost:6006`。
+
+如需修改后端地址，创建 `.env` 并设置：
+
+```
+VITE_API_URL=http://localhost:6006
+```
+
+## 后端接口
+- `POST /recommend` { query, category, tone } → 书籍列表
+- `POST /favorites/add` { isbn, user_id } → 收藏计数
+- `GET /user/{user_id}/persona` → 用户画像
+- `POST /marketing/highlights` { isbn, user_id } → 个性化卖点
+
+## 注意
+- 已在后端添加 CORS 允许 `http://localhost:5173`。
+- 初版将中文分类/心境映射到后端 `category/tone`，可根据数据进一步细化。

web/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>纸间留白 · 私人书斋</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

web/package-lock.json

@@ -0,0 +1,1054 @@
+{
+  "name": "paper-shelf-ui",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "paper-shelf-ui",
+      "version": "0.1.0",
+      "dependencies": {
+        "lucide-react": "^0.446.0",
+        "react": "^18.2.0",
+        "react-dom": "^18.2.0"
+      },
+      "devDependencies": {
+        "vite": "^5.0.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz",
+      "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz",
+      "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz",
+      "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz",
+      "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz",
+      "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz",
+      "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz",
+      "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz",
+      "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz",
+      "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz",
+      "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz",
+      "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz",
+      "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz",
+      "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz",
+      "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz",
+      "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
+      "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz",
+      "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz",
+      "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz",
+      "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.55.1.tgz",
+      "integrity": "sha512-9R0DM/ykwfGIlNu6+2U09ga0WXeZ9MRC2Ter8jnz8415VbuIykVuc6bhdrbORFZANDmTDvq26mJrEVTl8TdnDg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.55.1.tgz",
+      "integrity": "sha512-eFZCb1YUqhTysgW3sj/55du5cG57S7UTNtdMjCW7LwVcj3dTTcowCsC8p7uBdzKsZYa8J7IDE8lhMI+HX1vQvg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.55.1.tgz",
+      "integrity": "sha512-p3grE2PHcQm2e8PSGZdzIhCKbMCw/xi9XvMPErPhwO17vxtvCN5FEA2mSLgmKlCjHGMQTP6phuQTYWUnKewwGg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.55.1.tgz",
+      "integrity": "sha512-rDUjG25C9qoTm+e02Esi+aqTKSBYwVTaoS1wxcN47/Luqef57Vgp96xNANwt5npq9GDxsH7kXxNkJVEsWEOEaQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.55.1.tgz",
+      "integrity": "sha512-+JiU7Jbp5cdxekIgdte0jfcu5oqw4GCKr6i3PJTlXTCU5H5Fvtkpbs4XJHRmWNXF+hKmn4v7ogI5OQPaupJgOg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.55.1.tgz",
+      "integrity": "sha512-V5xC1tOVWtLLmr3YUk2f6EJK4qksksOYiz/TCsFHu/R+woubcLWdC9nZQmwjOAbmExBIVKsm1/wKmEy4z4u4Bw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.55.1.tgz",
+      "integrity": "sha512-Rn3n+FUk2J5VWx+ywrG/HGPTD9jXNbicRtTM11e/uorplArnXZYsVifnPPqNNP5BsO3roI4n8332ukpY/zN7rQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.55.1.tgz",
+      "integrity": "sha512-grPNWydeKtc1aEdrJDWk4opD7nFtQbMmV7769hiAaYyUKCT1faPRm2av8CX1YJsZ4TLAZcg9gTR1KvEzoLjXkg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.55.1.tgz",
+      "integrity": "sha512-a59mwd1k6x8tXKcUxSyISiquLwB5pX+fJW9TkWU46lCqD/GRDe9uDN31jrMmVP3feI3mhAdvcCClhV8V5MhJFQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.55.1.tgz",
+      "integrity": "sha512-puS1MEgWX5GsHSoiAsF0TYrpomdvkaXm0CofIMG5uVkP6IBV+ZO9xhC5YEN49nsgYo1DuuMquF9+7EDBVYu4uA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.55.1.tgz",
+      "integrity": "sha512-r3Wv40in+lTsULSb6nnoudVbARdOwb2u5fpeoOAZjFLznp6tDU8kd+GTHmJoqZ9lt6/Sys33KdIHUaQihFcu7g==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.55.1.tgz",
+      "integrity": "sha512-MR8c0+UxAlB22Fq4R+aQSPBayvYa3+9DrwG/i1TKQXFYEaoW3B5b/rkSRIypcZDdWjWnpcvxbNaAJDcSbJU3Lw==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.55.1.tgz",
+      "integrity": "sha512-3KhoECe1BRlSYpMTeVrD4sh2Pw2xgt4jzNSZIIPLFEsnQn9gAnZagW9+VqDqAHgm1Xc77LzJOo2LdigS5qZ+gw==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.55.1.tgz",
+      "integrity": "sha512-ziR1OuZx0vdYZZ30vueNZTg73alF59DicYrPViG0NEgDVN8/Jl87zkAPu4u6VjZST2llgEUjaiNl9JM6HH1Vdw==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.55.1.tgz",
+      "integrity": "sha512-uW0Y12ih2XJRERZ4jAfKamTyIHVMPQnTZcQjme2HMVDAHY4amf5u414OqNYC+x+LzRdRcnIG1YodLrrtA8xsxw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.55.1.tgz",
+      "integrity": "sha512-u9yZ0jUkOED1BFrqu3BwMQoixvGHGZ+JhJNkNKY/hyoEgOwlqKb62qu+7UjbPSHYjiVy8kKJHvXKv5coH4wDeg==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.55.1.tgz",
+      "integrity": "sha512-/0PenBCmqM4ZUd0190j7J0UsQ/1nsi735iPRakO8iPciE7BQ495Y6msPzaOmvx0/pn+eJVVlZrNrSh4WSYLxNg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.55.1.tgz",
+      "integrity": "sha512-a8G4wiQxQG2BAvo+gU6XrReRRqj+pLS2NGXKm8io19goR+K8lw269eTrPkSdDTALwMmJp4th2Uh0D8J9bEV1vg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.55.1.tgz",
+      "integrity": "sha512-bD+zjpFrMpP/hqkfEcnjXWHMw5BIghGisOKPj+2NaNDuVT+8Ds4mPf3XcPHuat1tz89WRL+1wbcxKY3WSbiT7w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.55.1.tgz",
+      "integrity": "sha512-eLXw0dOiqE4QmvikfQ6yjgkg/xDM+MdU9YJuP4ySTibXU0oAvnEWXt7UDJmD4UkYialMfOGFPJnIHSe/kdzPxg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.55.1.tgz",
+      "integrity": "sha512-xzm44KgEP11te3S2HCSyYf5zIzWmx3n8HDCc7EE59+lTcswEWNpvMLfd9uJvVX8LCg9QWG67Xt75AuHn4vgsXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.55.1.tgz",
+      "integrity": "sha512-yR6Bl3tMC/gBok5cz/Qi0xYnVbIxGx5Fcf/ca0eB6/6JwOY+SRUcJfI0OpeTpPls7f194as62thCt/2BjxYN8g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.55.1.tgz",
+      "integrity": "sha512-3fZBidchE0eY0oFZBnekYCfg+5wAB0mbpCBuofh5mZuzIU/4jIVkbESmd2dOsFNS78b53CYv3OAtwqkZZmU5nA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.55.1.tgz",
+      "integrity": "sha512-xGGY5pXj69IxKb4yv/POoocPy/qmEGhimy/FoTpTSVju3FYXUQQMFCaZZXJVidsmGxRioZAwpThl/4zX41gRKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.55.1.tgz",
+      "integrity": "sha512-SPEpaL6DX4rmcXtnhdrQYgzQ5W2uW3SCJch88lB2zImhJRhIIK44fkUrgIV/Q8yUNfw5oyZ5vkeQsZLhCb06lw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/esbuild": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz",
+      "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.21.5",
+        "@esbuild/android-arm": "0.21.5",
+        "@esbuild/android-arm64": "0.21.5",
+        "@esbuild/android-x64": "0.21.5",
+        "@esbuild/darwin-arm64": "0.21.5",
+        "@esbuild/darwin-x64": "0.21.5",
+        "@esbuild/freebsd-arm64": "0.21.5",
+        "@esbuild/freebsd-x64": "0.21.5",
+        "@esbuild/linux-arm": "0.21.5",
+        "@esbuild/linux-arm64": "0.21.5",
+        "@esbuild/linux-ia32": "0.21.5",
+        "@esbuild/linux-loong64": "0.21.5",
+        "@esbuild/linux-mips64el": "0.21.5",
+        "@esbuild/linux-ppc64": "0.21.5",
+        "@esbuild/linux-riscv64": "0.21.5",
+        "@esbuild/linux-s390x": "0.21.5",
+        "@esbuild/linux-x64": "0.21.5",
+        "@esbuild/netbsd-x64": "0.21.5",
+        "@esbuild/openbsd-x64": "0.21.5",
+        "@esbuild/sunos-x64": "0.21.5",
+        "@esbuild/win32-arm64": "0.21.5",
+        "@esbuild/win32-ia32": "0.21.5",
+        "@esbuild/win32-x64": "0.21.5"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/js-tokens": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
+      "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+      "license": "MIT"
+    },
+    "node_modules/loose-envify": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
+      "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^3.0.0 || ^4.0.0"
+      },
+      "bin": {
+        "loose-envify": "cli.js"
+      }
+    },
+    "node_modules/lucide-react": {
+      "version": "0.446.0",
+      "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.446.0.tgz",
+      "integrity": "sha512-BU7gy8MfBMqvEdDPH79VhOXSEgyG8TSPOKWaExWGCQVqnGH7wGgDngPbofu+KdtVjPQBWbEmnfMTq90CTiiDRg==",
+      "license": "ISC",
+      "peerDependencies": {
+        "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0-rc"
+      }
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.11",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
+      "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/postcss": {
+      "version": "8.5.6",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
+      "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.11",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/react": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
+      "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
+      "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0",
+        "scheduler": "^0.23.2"
+      },
+      "peerDependencies": {
+        "react": "^18.3.1"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.55.1",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.55.1.tgz",
+      "integrity": "sha512-wDv/Ht1BNHB4upNbK74s9usvl7hObDnvVzknxqY/E/O3X6rW1U1rV1aENEfJ54eFZDTNo7zv1f5N4edCluH7+A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.8"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.55.1",
+        "@rollup/rollup-android-arm64": "4.55.1",
+        "@rollup/rollup-darwin-arm64": "4.55.1",
+        "@rollup/rollup-darwin-x64": "4.55.1",
+        "@rollup/rollup-freebsd-arm64": "4.55.1",
+        "@rollup/rollup-freebsd-x64": "4.55.1",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.55.1",
+        "@rollup/rollup-linux-arm-musleabihf": "4.55.1",
+        "@rollup/rollup-linux-arm64-gnu": "4.55.1",
+        "@rollup/rollup-linux-arm64-musl": "4.55.1",
+        "@rollup/rollup-linux-loong64-gnu": "4.55.1",
+        "@rollup/rollup-linux-loong64-musl": "4.55.1",
+        "@rollup/rollup-linux-ppc64-gnu": "4.55.1",
+        "@rollup/rollup-linux-ppc64-musl": "4.55.1",
+        "@rollup/rollup-linux-riscv64-gnu": "4.55.1",
+        "@rollup/rollup-linux-riscv64-musl": "4.55.1",
+        "@rollup/rollup-linux-s390x-gnu": "4.55.1",
+        "@rollup/rollup-linux-x64-gnu": "4.55.1",
+        "@rollup/rollup-linux-x64-musl": "4.55.1",
+        "@rollup/rollup-openbsd-x64": "4.55.1",
+        "@rollup/rollup-openharmony-arm64": "4.55.1",
+        "@rollup/rollup-win32-arm64-msvc": "4.55.1",
+        "@rollup/rollup-win32-ia32-msvc": "4.55.1",
+        "@rollup/rollup-win32-x64-gnu": "4.55.1",
+        "@rollup/rollup-win32-x64-msvc": "4.55.1",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.23.2",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
+      "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/vite": {
+      "version": "5.4.21",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
+      "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.21.3",
+        "postcss": "^8.4.43",
+        "rollup": "^4.20.0"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.4.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

web/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "paper-shelf-ui",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "lucide-react": "^0.446.0"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0"
+  }
+}

web/src/App.jsx

@@ -0,0 +1,401 @@
+import React, { useState } from "react";
+import { Bookmark, Heart, Search, Layers, Smile, Sparkles, Star, Trophy, BarChart3, X, MessageCircle, MessageSquare, Info, Send } from "lucide-react";
+import { recommend, addFavorite, getPersona, getHighlights } from "./api";
+
+// --- Elegant Book Discovery UI ---
+
+const CATEGORIES = ["All", "Fiction", "History", "Philosophy", "Science", "Art"];
+const MOODS = ["All", "Happy", "Suspenseful", "Angry", "Sad", "Surprising"];
+
+const StudyButton = ({ children, active, color, className, onClick }) => {
+  const colors = {
+    purple: "bg-[#b392ac] text-white hover:bg-[#9d7799]",
+    peach: "bg-[#f4acb7] text-white hover:bg-[#e89ba3]",
+    tab: "bg-transparent text-[#b392ac] border-b-2 border-[#b392ac]",
+  };
+  return (
+    <button 
+      onClick={onClick}
+      className={`px-4 py-2 text-sm font-bold transition-all ${colors[color] || colors.purple} ${className || ""}`}
+    >
+      {children}
+    </button>
+  );
+};
+
+const StudyCard = ({ children, className }) => (
+  <div className={`bg-white border-2 border-[#333] shadow-md ${className || ""}`}>
+    {children}
+  </div>
+);
+
+const App = () => {
+  const [selectedBook, setSelectedBook] = useState(null);
+  const [messages, setMessages] = useState([]);
+  const [input, setInput] = useState("");
+  const [myCollection, setMyCollection] = useState([]); 
+  const [showMyShelf, setShowMyShelf] = useState(false);
+  const [books, setBooks] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+  
+  const [searchQuery, setSearchQuery] = useState("");
+  const [searchCategory, setSearchCategory] = useState("All");
+  const [searchMood, setSearchMood] = useState("All");
+
+  const handleSend = (text) => {
+    if (!text) return;
+    const newMsgs = [...messages, { role: 'user', content: text }];
+    setMessages(newMsgs);
+    setInput("");
+    setTimeout(() => {
+      setMessages([...newMsgs, { role: 'ai', content: `Based on "${selectedBook?.title || ''}" and your reading taste, I recommend paying attention to the thematic elements—they truly resonate with your preferences.` }]);
+    }, 600);
+  };
+
+  const toggleCollect = async (book) => {
+    try {
+      await addFavorite(book.isbn);
+      if (myCollection.some(b => b.isbn === book.isbn)) {
+        setMyCollection(myCollection.filter(b => b.isbn !== book.isbn));
+      } else {
+        setMyCollection([...myCollection, book]);
+      }
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  const openBook = async (book) => {
+    setSelectedBook(book);
+    setMessages([]);
+    try {
+      const res = await getHighlights(book.isbn);
+      const meta = res?.meta || {};
+      setSelectedBook({ ...book, aiHighlight: (res?.highlights || []).join("\n") || '—', suggestedQuestions: [
+        `Who is the target audience for this book?`,
+        `Does the author have similar works?`,
+        `Can you summarize the main content?`
+      ], desc: meta?.description || book.desc });
+    } catch (e) {
+      // keep default
+    }
+  };
+
+  const startDiscovery = async () => {
+    setLoading(true); 
+    setError("");
+    try {
+      const recs = await recommend(searchQuery || 'adventure', searchCategory, searchMood);
+      const mapped = (recs || []).map((r, idx) => ({
+        id: r.isbn,
+        title: r.title,
+        author: r.authors,
+        category: searchCategory,
+        mood: searchMood,
+        rank: idx + 1,
+        rating: r.average_rating || 0,
+        tags: r.tags || [],
+        review_highlights: r.review_highlights || [],
+        desc: r.description,
+        img: r.thumbnail,
+        isbn: r.isbn,
+        emotions: r.emotions || {},
+        aiHighlight: '—',
+        suggestedQuestions: [
+          `Matches my current mood?`,
+          `Any similar recommendations?`,
+          `What's the core highlight?`
+        ]
+      }));
+      setBooks(mapped);
+    } catch (e) {
+      setError(e.message || 'Failed to get recommendations');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const getRecommendedBooks = () => {
+    if (myCollection.length === 0) return books.slice(0, 3);
+    return books.filter(b => !myCollection.some(cb => cb.isbn === b.isbn)).slice(0, 3);
+  };
+
+  const currentViewBooks = showMyShelf ? myCollection : books;
+
+  return (
+    <div className="min-h-screen bg-[#faf9f6] text-[#444] font-serif tracking-tight">
+      <header className="max-w-5xl mx-auto pt-10 px-4 flex justify-between items-end mb-12">
+        <div>
+          <div className="border border-[#333] px-4 py-1 bg-white shadow-[2px_2px_0px_0px_#eee] inline-block mb-2">
+            <h1 className="text-xl font-bold uppercase tracking-[0.2em] text-[#333]">Paper Shelf</h1>
+          </div>
+          <p className="text-[10px] text-gray-400 font-medium tracking-widest">Discover books that resonate with your soul</p>
+        </div>
+        <div className="flex gap-2">
+          <StudyButton 
+            active={showMyShelf} 
+            color={showMyShelf ? "purple" : "tab"}
+            onClick={() => setShowMyShelf(!showMyShelf)}
+          >
+            <Bookmark className="w-4 h-4 inline mr-1" /> {showMyShelf ? "Back to Gallery" : "My Collection"}
+          </StudyButton>
+        </div>
+      </header>
+
+      <main className="max-w-5xl mx-auto px-4 pb-20">
+        {!showMyShelf && (
+          <>
+            {myCollection.length > 0 && (
+              <div className="mb-12 animate-in fade-in slide-in-from-top-4 duration-700">
+                <h4 className="flex items-center gap-2 text-[10px] font-black uppercase text-[#b392ac] mb-4 tracking-widest">
+                  <Sparkles className="w-3.5 h-3.5" /> Soul-Matched Recommendations
+                </h4>
+                <div className="flex gap-4 overflow-x-auto pb-4 scrollbar-hide">
+                  {getRecommendedBooks().map(book => (
+                    <div 
+                      key={book.id} 
+                      onClick={() => openBook(book)}
+                      className="min-w-[280px] flex gap-4 bg-white border border-[#333] p-3 shadow-sm hover:shadow-md cursor-pointer transition-all"
+                    >
+                      <img src={book.img} className="w-20 h-28 object-cover border border-[#eee]" />
+                      <div className="flex flex-col justify-between">
+                        <div>
+                          <h5 className="text-[12px] font-bold text-[#333]">{book.title}</h5>
+                          <p className="text-[10px] text-gray-400 mt-1">Resonates with your "{book.mood}" preference</p>
+                        </div>
+                        <div className="flex gap-1">
+                          {book.tags.slice(0, 2).map(t => <span key={t} className="text-[8px] px-1.5 py-0.5 bg-[#f8f9fa] border border-[#eee] text-[#999]">{t}</span>)}
+                        </div>
+                      </div>
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            <div className="max-w-4xl mx-auto mb-16 space-y-4">
+              <div className="grid grid-cols-1 md:grid-cols-12 gap-3 items-center">
+                <div className="md:col-span-6 flex items-center bg-white border border-[#ddd] p-2 shadow-sm">
+                  <Search className="w-4 h-4 mr-3 text-gray-300 ml-2" />
+                  <input 
+                    className="w-full outline-none text-sm placeholder-gray-400 bg-transparent font-serif"
+                    placeholder="Search for a topic, mood, or dream..."
+                    value={searchQuery}
+                    onChange={(e) => setSearchQuery(e.target.value)}
+                  />
+                </div>
+                <div className="md:col-span-3 flex items-center bg-white border border-[#ddd] p-2 shadow-sm">
+                  <Layers className="w-4 h-4 mr-3 text-gray-300 ml-2" />
+                  <select 
+                    className="w-full outline-none text-sm bg-transparent text-gray-500 font-serif"
+                    value={searchCategory}
+                    onChange={(e) => setSearchCategory(e.target.value)}
+                  >
+                    {CATEGORIES.map(cat => <option key={cat} value={cat}>{cat}</option>)}
+                  </select>
+                </div>
+                <div className="md:col-span-3 flex items-center bg-white border border-[#ddd] p-2 shadow-sm">
+                  <Smile className="w-4 h-4 mr-3 text-gray-300 ml-2" />
+                  <select 
+                    className="w-full outline-none text-sm bg-transparent text-gray-500 font-serif"
+                    value={searchMood}
+                    onChange={(e) => setSearchMood(e.target.value)}
+                  >
+                    {MOODS.map(mood => <option key={mood} value={mood}>{mood}</option>)}
+                  </select>
+                </div>
+              </div>
+              <div className="flex justify-center">
+                <StudyButton active color="purple" className="px-12 py-2" onClick={startDiscovery}>
+                  Start Discovery
+                </StudyButton>
+              </div>
+              {loading && <div className="text-center text-xs text-gray-400">Loading...</div>}
+              {error && <div className="text-center text-xs text-red-400">{error}</div>}
+            </div>
+          </>
+        )}
+
+        {showMyShelf && (
+          <div className="mb-8 flex items-center gap-4 text-xs font-bold text-[#b392ac] bg-[#e5d9f2]/30 p-4 border border-[#b392ac]/20">
+            <BarChart3 className="w-4 h-4" /> 
+            Your collection shows a preference for: {myCollection.map(b => b.mood).filter((v, i, a) => a.indexOf(v) === i).join(", ")}
+          </div>
+        )}
+
+        <div className="grid grid-cols-2 md:grid-cols-4 lg:grid-cols-5 gap-6">
+          {currentViewBooks.length > 0 ? currentViewBooks.map((book, idx) => (
+            <div 
+              key={idx}
+              onClick={() => openBook(book)}
+              className="group cursor-pointer transform hover:-translate-y-1 transition-all"
+            >
+              <div className="bg-white border border-[#eee] p-1 relative shadow-sm group-hover:shadow-md overflow-hidden">
+                <img src={book.img} alt={book.title} className="w-full aspect-[3/4] object-cover opacity-90 group-hover:opacity-100 transition-opacity" />
+                <div className="absolute inset-0 bg-white/80 flex items-center justify-center p-4 opacity-0 group-hover:opacity-100 transition-opacity text-center px-4">
+                  <p className="text-[10px] font-bold text-[#b392ac] leading-relaxed italic">
+                    {book.aiHighlight}
+                  </p>
+                </div>
+                {myCollection.some(b => b.isbn === book.isbn) && (
+                  <div className="absolute top-1 right-1 bg-[#f4acb7] p-1 shadow-sm">
+                    <Heart className="w-3 h-3 text-white fill-current" />
+                  </div>
+                )}
+              </div>
+              <h3 className="mt-3 text-[12px] font-bold text-[#555] truncate">{book.title}</h3>
+              <div className="flex justify-between items-center mt-1">
+                <span className="text-[9px] text-gray-400 tracking-tighter">{book.author}</span>
+                {book.emotions && Object.keys(book.emotions).length > 0 ? (
+                  <span className="text-[9px] bg-[#f8f9fa] border border-[#eee] px-1 text-[#999] capitalize">
+                    {Object.entries(book.emotions).reduce((a, b) => a[1] > b[1] ? a : b)[0]}
+                  </span>
+                ) : (
+                  <span className="text-[9px] bg-[#f8f9fa] border border-[#eee] px-1 text-[#999]">—</span>
+                )}
+              </div>
+            </div>
+          )) : (
+            <div className="col-span-full py-20 text-center text-gray-400 text-xs italic">
+              No books here yet. Start discovering to build your collection.
+            </div>
+          )}
+        </div>
+
+        {selectedBook && (
+          <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/5 backdrop-blur-sm animate-in fade-in duration-300 overflow-y-auto">
+            <StudyCard className="relative bg-white max-w-5xl w-full shadow-2xl border-[#333] my-8">
+              <button 
+                onClick={() => setSelectedBook(null)}
+                className="absolute top-4 right-4 text-gray-300 hover:text-gray-600 transition-colors z-10"
+              >
+                <X className="w-6 h-6" />
+              </button>
+
+              <div className="grid md:grid-cols-12 gap-8 md:gap-10 px-6 md:px-10 py-6">
+                <div className="md:col-span-5 flex flex-col items-center border-r border-[#f5f5f5] pr-0 md:pr-6">
+                  <div className="border border-[#eee] p-1 bg-white shadow-sm mb-2 w-52 md:w-56">
+                    <img src={selectedBook.img} alt="cover" className="w-full aspect-[3/4] object-cover" />
+                  </div>
+                  
+                  <p className="text-xs text-[#999] mb-2 tracking-tighter text-center w-full">{selectedBook.author}</p>
+                
+                  <h2 className="text-xl font-bold text-[#333] mb-1 text-center md:text-left w-full">{selectedBook.title}</h2>
+                  <p className="text-xs text-[#999] mb-2 tracking-tighter text-center md:text-left w-full">ISBN: {selectedBook.isbn}</p>
+                  
+                  <div className="bg-[#fff9f9] border border-[#f4acb7] p-4 w-full relative mb-4">
+                    <Sparkles className="w-3 h-3 text-[#f4acb7] absolute -top-1.5 -left-1.5 fill-current" />
+                    <div className="flex items-center justify-between mb-2">
+                      <span className="text-[11px] font-bold text-[#f4acb7]">{selectedBook.rating ? selectedBook.rating.toFixed(1) : '0.0'}</span>
+                      <div className="flex gap-0.5 text-[#f4acb7]">
+                        {[1,2,3,4,5].map(i => <Star key={i} className={`w-3 h-3 ${i <= selectedBook.rating ? 'fill-current' : ''}`} />)}
+                      </div>
+                    </div>
+                    <p className="text-[11px] font-bold text-[#f4acb7] italic leading-relaxed">
+                      {selectedBook.aiHighlight}
+                    </p>
+                  </div>
+                  
+                  {selectedBook.review_highlights && selectedBook.review_highlights.length > 0 && (
+                    <div className="w-full space-y-2 text-left">
+                      {selectedBook.review_highlights.slice(0, 3).map((highlight, idx) => {
+                        const isCompleteSentence = /^[A-Z]/.test(highlight.trim());
+                        const prefix = isCompleteSentence ? '' : '...';
+                        return (
+                          <p key={idx} className="text-[10px] text-[#666] leading-relaxed italic pl-2">
+                            - "{prefix}{highlight}"
+                          </p>
+                        );
+                      })}
+                    </div>
+                  )}
+                </div>
+
+                <div className="md:col-span-7 flex flex-col space-y-6">
+                  <div className="space-y-2">
+                    <h4 className="flex items-center gap-2 text-[10px] font-bold uppercase text-gray-400 tracking-wider">
+                      <Info className="w-3.5 h-3.5" /> Summary
+                    </h4>
+                    <div className="p-4 bg-white border border-[#eee] text-[12px] leading-relaxed text-[#666] italic border-l-[4px] border-l-[#b392ac]">
+                      "{selectedBook.desc}"
+                    </div>
+                  </div>
+
+                  <div className="flex-grow flex flex-col border border-[#eee] bg-[#faf9f6] overflow-hidden h-[300px]">
+                    <div className="p-2 border-b border-[#eee] bg-white flex justify-between items-center">
+                      <span className="text-[10px] font-bold text-[#b392ac] flex items-center gap-2 uppercase tracking-widest">
+                        <MessageSquare className="w-3 h-3" /> Discussion
+                      </span>
+                    </div>
+                    <div className="flex-grow overflow-y-auto p-4 space-y-3">
+                      <div className="flex justify-start">
+                        <div className="max-w-[85%] p-2 bg-white border border-[#eee] text-[11px] text-[#735d78] shadow-sm">
+                          Hello! Based on your collection preferences, I found this book's {selectedBook.mood} atmosphere pairs beautifully with your taste. Would you like to explore its themes?
+                        </div>
+                      </div>
+                      {messages.map((m, i) => (
+                        <div key={i} className={`flex ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}>
+                          <div className={`max-w-[80%] p-2 border text-[11px] shadow-sm ${
+                            m.role === 'user' 
+                              ? 'bg-[#b392ac] text-white border-[#b392ac]' 
+                              : 'bg-white text-[#666] border-[#eee]'
+                          }`}>
+                            {m.content}
+                          </div>
+                        </div>
+                      ))}
+                    </div>
+                    <div className="p-3 bg-white border-t border-[#eee] space-y-3">
+                      <div className="flex flex-wrap gap-2">
+                        {(selectedBook.suggestedQuestions || []).map((q, idx) => (
+                          <button 
+                            key={idx}
+                            onClick={() => handleSend(q)}
+                            className="text-[9px] px-2 py-1 bg-[#f8f9fa] border border-[#eee] text-gray-500 hover:border-[#b392ac] hover:text-[#b392ac] transition-colors"
+                          >
+                            {q}
+                          </button>
+                        ))}
+                      </div>
+                      <div className="flex gap-2">
+                        <input 
+                          value={input}
+                          onChange={(e) => setInput(e.target.value)}
+                          onKeyDown={(e) => e.key === 'Enter' && handleSend(input)}
+                          className="flex-grow border border-[#eee] p-2 text-[11px] outline-none focus:border-[#b392ac] bg-[#faf9f6] font-serif" 
+                          placeholder="Ask a question..." 
+                        />
+                        <button onClick={() => handleSend(input)} className="bg-[#333] text-white p-2">
+                          <Send className="w-3.5 h-3.5" />
+                        </button>
+                      </div>
+                    </div>
+                  </div>
+
+                  <div className="flex gap-3">
+                    <StudyButton 
+                      active 
+                      color={myCollection.some(b => b.isbn === selectedBook.isbn) ? "peach" : "purple"} 
+                      className="flex-grow py-3 text-sm flex items-center justify-center gap-2 font-bold"
+                      onClick={() => toggleCollect(selectedBook)}
+                    >
+                      <Bookmark className={`w-4 h-4 ${myCollection.some(b => b.isbn === selectedBook.isbn) ? 'fill-current' : ''}`} />
+                      {myCollection.some(b => b.isbn === selectedBook.isbn) ? "In Collection" : "Add to Collection"}
+                    </StudyButton>
+                  </div>
+                </div>
+              </div>
+            </StudyCard>
+          </div>
+        )}
+      </main>
+
+      <footer className="mt-16 text-center text-[9px] font-medium text-gray-300 uppercase tracking-widest pb-10 border-t border-[#eee] pt-10">
+        Paper Shelf // 2026 Your Personal Library
+      </footer>
+    </div>
+  );
+};
+
+export default App;

web/src/api.js

@@ -0,0 +1,39 @@
+const API_URL = import.meta.env.VITE_API_URL || "http://localhost:6006";
+
+export async function recommend(query, category = "All", tone = "All") {
+  const body = { query, category, tone };
+  const resp = await fetch(`${API_URL}/recommend`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) throw new Error(await resp.text());
+  const data = await resp.json();
+  return data.recommendations || [];
+}
+
+export async function addFavorite(isbn, userId = "local") {
+  const resp = await fetch(`${API_URL}/favorites/add`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ isbn, user_id: userId }),
+  });
+  if (!resp.ok) throw new Error(await resp.text());
+  return resp.json();
+}
+
+export async function getPersona(userId = "local") {
+  const resp = await fetch(`${API_URL}/user/${userId}/persona`);
+  if (!resp.ok) throw new Error(await resp.text());
+  return resp.json();
+}
+
+export async function getHighlights(isbn, userId = "local") {
+  const resp = await fetch(`${API_URL}/marketing/highlights`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ isbn, user_id: userId }),
+  });
+  if (!resp.ok) throw new Error(await resp.text());
+  return resp.json();
+}

web/src/main.jsx

@@ -0,0 +1,9 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App.jsx";
+
+createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);