Refactor: 10/10 modularity — pipeline/ package, admin/routers/ split, guards single source of truth

app/admin/router.py

@@ -1,1344 +1,22 @@
-"""Author RAG — Per-Author Admin API Router.
+"""admin/router.py — Author Admin API aggregator.
 
-All routes require a valid Author JWT (Bearer token).
-Routes live at: /api/admin/{author_slug}/*
+Mounts all sub-routers. This file should never contain route logic.
+All routes live in admin/routers/*.py.
 
-Per implementation plan:
-  GET    /api/admin/{slug}/dashboard          — Stats summary
-  GET    /api/admin/{slug}/sessions           — Reader session list
-  GET    /api/admin/{slug}/sessions/{id}      — Session detail + transcript
-  POST   /api/admin/{slug}/sessions/{id}/block
-  POST   /api/admin/{slug}/sessions/{id}/unblock
-  POST   /api/admin/{slug}/sessions/{id}/reply  — Live agent takeover
-  GET    /api/admin/{slug}/books              — Book list
-  POST   /api/admin/{slug}/books/{id}/delete
-  GET    /api/admin/{slug}/analytics          — Charts data
-  GET    /api/admin/{slug}/export/chats       — Export Excel/JSON
-  GET    /api/admin/{slug}/widget-config      — Get widget settings
-  PUT    /api/admin/{slug}/widget-config      — Update widget settings
-  GET    /api/admin/{slug}/smart-links        — Smart links (buy/preview URLs)
-  PUT    /api/admin/{slug}/smart-links/{book_id}
-  POST   /api/admin/{slug}/password           — Change password
+Routes served at: /api/admin/{author_slug}/*
+Auth: Bearer JWT required on all routes (enforced per sub-router via dependency).
 """
 
-from fastapi import APIRouter, Depends, File, Query, UploadFile
-from sqlalchemy import Integer
-from sqlalchemy.ext.asyncio import AsyncSession
+from fastapi import APIRouter
 
-from app.dependencies import get_db, get_current_author_scoped, get_redis
-from app.repositories.book_repo import BookRepository
-from app.repositories.audit_repo import AuditRepository
-from app.schemas.admin import (
-    AnnotateRequest,
-    FlagRequest,
-    PasswordChangeRequest,
-    ProfileUpdate,
-    WidgetConfigUpdate,
-)
+from app.admin.routers import analytics, books, dashboard, exports, links, qa, settings
 
 router = APIRouter()
 
-
-@router.get("/{author_slug}/dashboard")
-async def dashboard(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Return high-level dashboard stats for the author."""
-    book_repo = BookRepository(db)
-    books = await book_repo.list_for_author(current_user.id)
-
-    from sqlalchemy import func, select
-    from app.models.chat_session import ChatSession
-    from app.models.analytics import AnalyticsEvent
-
-    total_sessions = await db.scalar(
-        select(func.count()).where(ChatSession.author_id == current_user.id)
-    ) or 0
-
-    return {
-        "total_books": len(books),
-        "active_books": sum(1 for b in books if b.status == "active"),
-        "total_sessions": total_sessions,
-        "total_clicks": 0,
-    }
-
-
-@router.get("/{author_slug}/sessions")
-async def list_sessions(
-    author_slug: str,
-    limit: int = Query(50, ge=1, le=200),
-    offset: int = 0,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """List reader sessions with pagination."""
-    from sqlalchemy import select, desc
-    from app.models.chat_session import ChatSession
-
-    result = await db.execute(
-        select(ChatSession)
-        .where(ChatSession.author_id == current_user.id)
-        .order_by(desc(ChatSession.created_at))
-        .offset(offset)
-        .limit(limit)
-    )
-    sessions = result.scalars().all()
-    return {
-        "sessions": [
-            {
-                "id": s.id,
-                "visitor_fingerprint": s.visitor_fingerprint,
-                "visitor_name": s.visitor_name,
-                "country": s.country_name,
-                "device_type": s.device_type,
-                "turn_count": s.turn_count,
-                "rating": s.rating,
-                "created_at": s.created_at.isoformat() if s.created_at else None,
-                "blocked": s.blocked,
-            }
-            for s in sessions
-        ]
-    }
-
-
-@router.get("/{author_slug}/sessions/search")
-async def search_sessions(
-    author_slug: str,
-    q: str = Query("", min_length=0, max_length=200),
-    page: int = Query(1, ge=1),
-    per_page: int = Query(20, ge=1, le=100),
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Full-text search across chat messages for the author."""
-    from sqlalchemy import select, func, desc, distinct
-    from app.models.chat_session import ChatSession, ChatMessage
-
-    if not q.strip():
-        return {"sessions": [], "total": 0}
-
-    search_term = f"%{q.strip().lower()}%"
-
-    matching_sessions = (
-        select(distinct(ChatMessage.session_id))
-        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
-        .where(
-            ChatSession.author_id == current_user.id,
-            func.lower(ChatMessage.content).like(search_term),
-        )
-    )
-
-    total = await db.scalar(
-        select(func.count()).select_from(matching_sessions.subquery())
-    ) or 0
-
-    offset = (page - 1) * per_page
-    result = await db.execute(
-        select(ChatSession)
-        .where(
-            ChatSession.author_id == current_user.id,
-            ChatSession.id.in_(matching_sessions),
-        )
-        .order_by(desc(ChatSession.created_at))
-        .offset(offset)
-        .limit(per_page)
-    )
-    sessions = result.scalars().all()
-
-    return {
-        "sessions": [
-            {
-                "id": s.id,
-                "visitor_fingerprint": s.visitor_fingerprint[:8] + "...",
-                "visitor_name": s.visitor_name,
-                "country": s.country_name,
-                "device_type": s.device_type,
-                "turn_count": s.turn_count,
-                "rating": s.rating,
-                "created_at": s.created_at.isoformat() if s.created_at else None,
-            }
-            for s in sessions
-        ],
-        "total": total,
-        "query": q,
-        "page": page,
-    }
-
-
-@router.post("/{author_slug}/sessions/{session_id}/block")
-async def block_session(
-    author_slug: str,
-    session_id: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Block a reader session (403 on next message)."""
-    from sqlalchemy import update
-    from app.models.chat_session import ChatSession
-    await db.execute(
-        update(ChatSession)
-        .where(ChatSession.id == session_id, ChatSession.author_id == current_user.id)
-        .values(blocked=True)
-    )
-    await db.commit()
-    return {"message": "Session blocked"}
-
-
-@router.post("/{author_slug}/sessions/{session_id}/unblock")
-async def unblock_session(
-    author_slug: str,
-    session_id: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Unblock a reader session."""
-    from sqlalchemy import update
-    from app.models.chat_session import ChatSession
-    await db.execute(
-        update(ChatSession)
-        .where(ChatSession.id == session_id, ChatSession.author_id == current_user.id)
-        .values(blocked=False)
-    )
-    await db.commit()
-    return {"message": "Session unblocked"}
-
-
-@router.get("/{author_slug}/books")
-async def list_books(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """List all books for the author."""
-    book_repo = BookRepository(db)
-    books = await book_repo.list_for_author(current_user.id)
-    return {
-        "books": [
-            {
-                "id": b.id,
-                "title": b.title,
-                "genre": b.genre,
-                "status": b.status,
-                "chunk_count": getattr(b, "chunk_count", 0),
-                "ai_summary": getattr(b, "ai_summary", ""),
-                "cover_path": getattr(b, "cover_path", None),
-                "cover_thumbnail": getattr(b, "cover_thumbnail_path", None),
-                "cover_medium": getattr(b, "cover_medium_path", None),
-                "buy_url": getattr(b, "buy_url", None),
-            }
-            for b in books
-        ]
-    }
-
-
-@router.delete("/{author_slug}/books/{book_id}")
-async def delete_book(
-    author_slug: str,
-    book_id: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Delete a book and its ChromaDB collection."""
-    book_repo = BookRepository(db)
-    book = await book_repo.get_by_id(book_id)
-    if not book or book.author_id != current_user.id:
-        from fastapi import HTTPException
-        raise HTTPException(404, "Book not found")
-
-    from app.services.embeddings import delete_book_embeddings
-    delete_book_embeddings(current_user.id, book_id)
-
-    await db.delete(book)
-    await db.commit()
-    return {"message": "Book deleted"}
-
-
-@router.post("/{author_slug}/books/{book_id}/cover")
-async def upload_book_cover(
-    author_slug: str,
-    book_id: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-    file: UploadFile = File(...),
-):
-    """Upload a book cover image (JPG/PNG/WebP, max 5MB)."""
-    from fastapi import HTTPException
-    import os
-
-    book_repo = BookRepository(db)
-    book = await book_repo.get_by_id(book_id)
-    if not book or book.author_id != current_user.id:
-        raise HTTPException(404, "Book not found")
-
-    # Validate file type
-    allowed_types = {"image/jpeg", "image/png", "image/webp"}
-    if file.content_type not in allowed_types:
-        raise HTTPException(400, f"Invalid file type. Allowed: JPG, PNG, WebP")
-
-    # Read and validate size
-    contents = await file.read()
-    if len(contents) > 5 * 1024 * 1024:  # 5MB
-        raise HTTPException(400, "File too large. Maximum: 5MB")
-
-    # Validate it's actually an image by checking magic bytes
-    if contents[:2] not in (b'\xff\xd8', b'\x89P') and contents[:4] != b'RIFF':
-        raise HTTPException(400, "File does not appear to be a valid image")
-
-    # Create directories
-    cover_dir = f"/data/covers/{current_user.id}/{book_id}"
-    os.makedirs(cover_dir, exist_ok=True)
-
-    # Save original
-    ext = file.filename.rsplit('.', 1)[-1].lower() if file.filename else 'jpg'
-    if ext not in ('jpg', 'jpeg', 'png', 'webp'):
-        ext = 'jpg'
-    original_path = f"{cover_dir}/original.{ext}"
-    with open(original_path, "wb") as f:
-        f.write(contents)
-
-    # Try to create resized versions (PIL optional)
-    thumbnail_path = original_path
-    medium_path = original_path
-    try:
-        from PIL import Image
-        import io
-
-        img = Image.open(io.BytesIO(contents))
-        img = img.convert('RGB')  # Ensure RGB, strip EXIF
-
-        # Thumbnail (80x120)
-        thumb = img.copy()
-        thumb.thumbnail((80, 120), Image.LANCZOS)
-        thumbnail_path = f"{cover_dir}/thumb.webp"
-        thumb.save(thumbnail_path, 'WEBP', quality=80)
-
-        # Medium (300x450)
-        med = img.copy()
-        med.thumbnail((300, 450), Image.LANCZOS)
-        medium_path = f"{cover_dir}/medium.webp"
-        med.save(medium_path, 'WEBP', quality=85)
-    except ImportError:
-        pass  # PIL not available, use original for all sizes
-
-    # Update book record
-    book.cover_path = original_path
-    book.cover_thumbnail_path = thumbnail_path
-    book.cover_medium_path = medium_path
-    await db.commit()
-
-    return {
-        "message": "Cover uploaded",
-        "cover_path": original_path,
-        "cover_thumbnail": thumbnail_path,
-        "cover_medium": medium_path,
-    }
-
-
-@router.get("/{author_slug}/analytics")
-async def get_analytics(
-    author_slug: str,
-    days: int = Query(30, ge=1, le=365),
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Return analytics data for dashboard charts."""
-    from datetime import datetime, timedelta, timezone
-    from sqlalchemy import select, func
-    from app.models.analytics import AnalyticsEvent
-
-    since = datetime.now(timezone.utc) - timedelta(days=days)
-    result = await db.execute(
-        select(
-            func.date(AnalyticsEvent.timestamp).label("date"),
-            func.count().label("count"),
-        )
-        .where(
-            AnalyticsEvent.author_id == current_user.id,
-            AnalyticsEvent.timestamp >= since,
-        )
-        .group_by(func.date(AnalyticsEvent.timestamp))
-        .order_by(func.date(AnalyticsEvent.timestamp))
-    )
-    daily = [{"date": str(row.date), "count": row.count} for row in result]
-    return {"daily_sessions": daily, "period_days": days}
-
-
-@router.get("/{author_slug}/analytics/funnel")
-async def get_conversion_funnel(
-    author_slug: str,
-    days: int = Query(30, ge=1, le=365),
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Return conversion funnel data derived from analytics events."""
-    from datetime import datetime, timedelta, timezone
-    from sqlalchemy import select, func
-    from app.models.analytics import AnalyticsEvent
-    from app.models.chat_session import ChatSession
-
-    since = datetime.now(timezone.utc) - timedelta(days=days)
-
-    # Stage 1: Total sessions (= widget_load approximation)
-    total_sessions = await db.scalar(
-        select(func.count()).where(
-            ChatSession.author_id == current_user.id,
-            ChatSession.created_at >= since,
-        )
-    ) or 0
-
-    # Stage 2: Sessions with at least 1 analytics event (= chat_started)
-    chat_started = await db.scalar(
-        select(func.count(func.distinct(AnalyticsEvent.session_id))).where(
-            AnalyticsEvent.author_id == current_user.id,
-            AnalyticsEvent.timestamp >= since,
-        )
-    ) or 0
-
-    # Stage 3: Sessions that discussed a book (book_id is set)
-    book_discussed = await db.scalar(
-        select(func.count(func.distinct(AnalyticsEvent.session_id))).where(
-            AnalyticsEvent.author_id == current_user.id,
-            AnalyticsEvent.book_id.isnot(None),
-            AnalyticsEvent.timestamp >= since,
-        )
-    ) or 0
-
-    # Stage 4: Link shown
-    link_shown = await db.scalar(
-        select(func.count()).where(
-            AnalyticsEvent.author_id == current_user.id,
-            AnalyticsEvent.link_shown == True,
-            AnalyticsEvent.timestamp >= since,
-        )
-    ) or 0
-
-    # Stage 5: Link clicked
-    link_clicked = await db.scalar(
-        select(func.count()).where(
-            AnalyticsEvent.author_id == current_user.id,
-            AnalyticsEvent.link_clicked == True,
-            AnalyticsEvent.timestamp >= since,
-        )
-    ) or 0
-
-    funnel = [
-        {"stage": "Widget Loads", "count": total_sessions},
-        {"stage": "Chats Started", "count": chat_started},
-        {"stage": "Book Discussed", "count": book_discussed},
-        {"stage": "Link Shown", "count": link_shown},
-        {"stage": "Link Clicked", "count": link_clicked},
-    ]
-    return {"funnel": funnel, "period_days": days}
-
-
-@router.get("/{author_slug}/analytics/intents")
-async def get_intent_distribution(
-    author_slug: str,
-    days: int = Query(30, ge=1, le=365),
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Return distribution of detected intents."""
-    from datetime import datetime, timedelta, timezone
-    from sqlalchemy import select, func
-    from app.models.analytics import AnalyticsEvent
-
-    since = datetime.now(timezone.utc) - timedelta(days=days)
-    result = await db.execute(
-        select(
-            AnalyticsEvent.intent,
-            func.count().label("count"),
-        )
-        .where(
-            AnalyticsEvent.author_id == current_user.id,
-            AnalyticsEvent.intent.isnot(None),
-            AnalyticsEvent.timestamp >= since,
-        )
-        .group_by(AnalyticsEvent.intent)
-        .order_by(func.count().desc())
-        .limit(20)
-    )
-    intents = [{"intent": row.intent or "unknown", "count": row.count} for row in result]
-    return {"intents": intents, "period_days": days}
-
-
-
-@router.post("/{author_slug}/password")
-async def change_password(
-    author_slug: str,
-    body: PasswordChangeRequest,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Self-service password change. R-010: Validates via Pydantic schema."""
-    import bcrypt
-    try:
-        valid = bcrypt.checkpw(body.current_password.encode(), current_user.password_hash.encode())
-    except Exception:
-        valid = False
-    if not valid:
-        from fastapi import HTTPException
-        raise HTTPException(400, "Current password is incorrect")
-    current_user.password_hash = bcrypt.hashpw(body.new_password.encode(), bcrypt.gensalt(12)).decode()
-    await db.commit()
-    return {"message": "Password updated"}
-
-
-# ── Widget Configuration ──────────────────────────────────────────────────────
-
-
-@router.get("/{author_slug}/widget-config")
-async def get_widget_config(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-):
-    """Return current widget configuration."""
-    return {
-        "bot_name": current_user.bot_name,
-        "welcome_message": current_user.welcome_message,
-        "theme": current_user.widget_theme,
-        "position": current_user.widget_position,
-        "auto_open_delay": current_user.widget_auto_open_delay,
-        "is_active": current_user.chatbot_is_active,
-    }
-
-
-@router.put("/{author_slug}/widget-config")
-async def update_widget_config(
-    author_slug: str,
-    body: WidgetConfigUpdate,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Update widget configuration. R-029: Validated via Pydantic schema."""
-    update_map = {
-        "bot_name": "bot_name",
-        "welcome_message": "welcome_message",
-        "theme": "widget_theme",
-        "position": "widget_position",
-        "auto_open_delay": "widget_auto_open_delay",
-        "is_active": "chatbot_is_active",
-    }
-    for field_name, attr in update_map.items():
-        val = getattr(body, field_name, None)
-        if val is not None:
-            setattr(current_user, attr, val)
-    await db.commit()
-    return {"message": "Widget config updated"}
-
-
-# ── Profile ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/{author_slug}/profile")
-async def get_profile(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-):
-    """Return current author profile."""
-    return {
-        "full_name": current_user.full_name or "",
-        "email": current_user.email,
-        "website": current_user.website_url or "",
-        "bio": current_user.bio or "",
-        "timezone": current_user.timezone,
-    }
-
-
-@router.put("/{author_slug}/profile")
-async def update_profile(
-    author_slug: str,
-    body: ProfileUpdate,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Update author profile. R-029: Validated via Pydantic schema."""
-    if body.full_name is not None:
-        current_user.full_name = body.full_name
-    if body.website is not None:
-        current_user.website_url = body.website
-    if body.bio is not None:
-        current_user.bio = body.bio
-    if body.timezone is not None:
-        current_user.timezone = body.timezone
-    await db.commit()
-    return {"message": "Profile updated"}
-
-
-# ── Bot Personality ───────────────────────────────────────────────────────────
-
-
-@router.get("/{author_slug}/personality")
-async def get_personality(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-):
-    """Return bot personality settings."""
-    return {
-        "response_style": current_user.response_style,
-        "fallback_message": current_user.fallback_message,
-        "out_of_scope_message": current_user.out_of_scope_message,
-        "welcome_message": current_user.welcome_message,
-    }
-
-
-@router.put("/{author_slug}/personality")
-async def update_personality(
-    author_slug: str,
-    body: dict,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Update bot personality settings."""
-    valid_styles = ["balanced", "formal", "casual", "enthusiastic"]
-    if "response_style" in body:
-        style = str(body["response_style"])
-        if style not in valid_styles:
-            from fastapi import HTTPException
-            raise HTTPException(400, f"Invalid style. Must be one of: {valid_styles}")
-        current_user.response_style = style
-    if "fallback_message" in body:
-        current_user.fallback_message = str(body["fallback_message"])[:500]
-    if "out_of_scope_message" in body:
-        current_user.out_of_scope_message = str(body["out_of_scope_message"])[:500]
-    await db.commit()
-    return {"message": "Personality settings updated"}
-
-
-# ── Notification Preferences ──────────────────────────────────────────────────
-
-
-@router.get("/{author_slug}/notifications")
-async def get_notifications(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-):
-    """Return notification preferences."""
-    return {
-        "weekly_digest": current_user.notify_weekly_digest,
-        "token_alerts": current_user.notify_token_alerts,
-        "new_conversation": current_user.notify_new_conversation,
-        "subscription_expiry": current_user.notify_subscription_expiry,
-    }
-
-
-@router.put("/{author_slug}/notifications")
-async def update_notifications(
-    author_slug: str,
-    body: dict,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Update notification preferences."""
-    mapping = {
-        "weekly_digest": "notify_weekly_digest",
-        "token_alerts": "notify_token_alerts",
-        "new_conversation": "notify_new_conversation",
-        "subscription_expiry": "notify_subscription_expiry",
-    }
-    for key, attr in mapping.items():
-        if key in body:
-            setattr(current_user, attr, bool(body[key]))
-    await db.commit()
-    return {"message": "Notification preferences updated"}
-
-
-# ── Embed Token ───────────────────────────────────────────────────────────────
-
-
-@router.get("/{author_slug}/embed-token")
-async def get_embed_token(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Return the active subscription token for embedding the widget.
-    Token is regenerated from stored grant data — never stored in plaintext.
-    """
-    from sqlalchemy import select
-    from datetime import datetime, timezone
-    from app.models.client_access import ClientAccess
-    from app.core.access.token_crypto import create_subscription_token
-
-    now = datetime.now(timezone.utc)
-    now_naive = now.replace(tzinfo=None)  # For comparisons with naive DB datetimes
-
-    result = await db.execute(
-        select(ClientAccess)
-        .where(
-            ClientAccess.author_id == current_user.id,
-            ClientAccess.is_revoked == False,
-            ClientAccess.expires_at > now_naive,
-        )
-        .order_by(ClientAccess.expires_at.desc())
-        .limit(1)
-    )
-    access = result.scalar_one_or_none()
-    if not access:
-        # Return clean 200 with active=False instead of 403 so UI can show a proper message
-        return {
-            "active": False,
-            "token": None,
-            "message": "No active subscription. Contact your administrator to activate your chatbot.",
-        }
-
-    token = create_subscription_token(
-        author_id=current_user.id,
-        grant_id=access.id,
-        granted_at=access.granted_at,
-        expires_at=access.expires_at,
-    )
-
-    # Normalize expiry to naive UTC for subtraction
-    exp = access.expires_at
-    if exp and exp.tzinfo is not None:
-        exp = exp.replace(tzinfo=None)
-    days_remaining = max(0, (exp - now_naive).days) if exp else 0
-
-    from app.services.token_budget import tokens_remaining
-
-    return {
-        "active": True,
-        "token": token,
-        "grant_id": access.id,
-        "plan": access.plan,
-        "expires_at": access.expires_at.isoformat(),
-        "days_remaining": days_remaining,
-        "tokens_remaining": tokens_remaining(access),
-    }
-
-
-# ── Smart Links ───────────────────────────────────────────────────────────────
-
-
-@router.put("/{author_slug}/smart-links/{book_id}")
-async def update_smart_link(
-    author_slug: str,
-    book_id: str,
-    body: dict,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Update buy/preview URLs for a book."""
-    book_repo = BookRepository(db)
-    book = await book_repo.get_by_id(book_id)
-    if not book or book.author_id != current_user.id:
-        from fastapi import HTTPException
-        raise HTTPException(404, "Book not found")
-    if "buy_url" in body:
-        book.buy_url = str(body["buy_url"])[:1000] if body["buy_url"] else None
-    if "preview_url" in body:
-        book.preview_url = str(body["preview_url"])[:1000] if body["preview_url"] else None
-
-    from app.repositories.link_repo import LinkRepository
-
-    link_repo = LinkRepository(db)
-    await link_repo.upsert_for_book(
-        current_user.id,
-        book_id,
-        {
-            "purchase_url": book.buy_url,
-            "preview_url": book.preview_url,
-        },
-    )
-    await db.commit()
-    return {"message": "Smart link updated"}
-
-
-# ── Token Usage ───────────────────────────────────────────────────────────────
-
-
-@router.get("/{author_slug}/token-usage")
-async def get_token_usage(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Return token budget and consumption for the active subscription only."""
-    from app.repositories.access_repo import AccessRepository
-    from app.services.token_budget import usage_summary_or_empty
-
-    access_repo = AccessRepository(db)
-    access = await access_repo.get_active_for_author(current_user.id)
-    return usage_summary_or_empty(access)
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-# PHASE 1.1 — CONVERSATION VIEWER & LIVE TRANSCRIPT
-# ══════════════════════════════════════════════════════════════════════════════
-
-
-@router.get("/{author_slug}/sessions/{session_id}/transcript")
-async def get_transcript(
-    author_slug: str,
-    session_id: str,
-    page: int = Query(1, ge=1),
-    per_page: int = Query(50, ge=1, le=200),
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Return paginated message transcript for a session."""
-    from sqlalchemy import select, func
-    from app.models.chat_session import ChatSession, ChatMessage
-
-    # Verify session belongs to author
-    session_result = await db.execute(
-        select(ChatSession).where(
-            ChatSession.id == session_id,
-            ChatSession.author_id == current_user.id,
-        )
-    )
-    session = session_result.scalar_one_or_none()
-    if not session:
-        from fastapi import HTTPException
-        raise HTTPException(404, "Session not found")
-
-    # Count total messages
-    total = await db.scalar(
-        select(func.count()).where(ChatMessage.session_id == session_id)
-    ) or 0
-
-    # Paginated messages
-    offset = (page - 1) * per_page
-    result = await db.execute(
-        select(ChatMessage)
-        .where(ChatMessage.session_id == session_id)
-        .order_by(ChatMessage.created_at.asc())
-        .offset(offset)
-        .limit(per_page)
-    )
-    messages = result.scalars().all()
-
-    return {
-        "session": {
-            "id": session.id,
-            "visitor_fingerprint": session.visitor_fingerprint[:8] + "...",
-            "visitor_name": session.visitor_name,
-            "visitor_email": session.visitor_email,
-            "country": session.country_name,
-            "city": session.city,
-            "device_type": session.device_type,
-            "browser": session.browser,
-            "os": session.os,
-            "rating": session.rating,
-            "blocked": session.blocked,
-            "created_at": session.created_at.isoformat() if session.created_at else None,
-            "summary": session.summary,
-        },
-        "messages": [
-            {
-                "id": m.id,
-                "role": m.role,
-                "content": m.content,
-                "intent": m.intent,
-                "intent_confidence": m.intent_confidence,
-                "faithfulness_score": m.faithfulness_score,
-                "hallucination_detected": m.hallucination_detected,
-                "prompt_tokens": m.prompt_tokens,
-                "completion_tokens": m.completion_tokens,
-                "response_ms": m.response_ms,
-                "annotation": m.annotation,
-                "flag_type": m.flag_type,
-                "user_feedback": m.user_feedback,
-                "created_at": m.created_at.isoformat() if m.created_at else None,
-            }
-            for m in messages
-        ],
-        "pagination": {
-            "page": page,
-            "per_page": per_page,
-            "total": total,
-            "total_pages": (total + per_page - 1) // per_page,
-        },
-    }
-
-
-@router.post("/{author_slug}/sessions/{session_id}/messages/{message_id}/annotate")
-async def annotate_message(
-    author_slug: str,
-    session_id: str,
-    message_id: str,
-    body: AnnotateRequest,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Add admin annotation to a chat message (append-only). R-029: Schema validated."""
-    from sqlalchemy import select
-    from app.models.chat_session import ChatMessage, ChatSession
-
-    # R-040: Verify session ownership via JOIN to prevent IDOR
-    result = await db.execute(
-        select(ChatMessage)
-        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
-        .where(
-            ChatMessage.id == message_id,
-            ChatMessage.session_id == session_id,
-            ChatSession.author_id == current_user.id,
-        )
-    )
-    msg = result.scalar_one_or_none()
-    if not msg:
-        from fastapi import HTTPException
-        raise HTTPException(404, "Message not found")
-
-    annotation = body.annotation
-
-    # Append-only: prepend timestamp + existing
-    from datetime import datetime, timezone
-    prefix = f"[{datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M')}] "
-    existing = msg.annotation or ""
-    msg.annotation = (prefix + annotation + "\n" + existing).strip()
-    await db.commit()
-    return {"message": "Annotation saved", "annotation": msg.annotation}
-
-
-@router.post("/{author_slug}/sessions/{session_id}/messages/{message_id}/flag")
-async def flag_message(
-    author_slug: str,
-    session_id: str,
-    message_id: str,
-    body: FlagRequest,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Flag a message as spam, quality issue, or escalation. R-029: Schema validated."""
-    from sqlalchemy import select
-    from app.models.chat_session import ChatMessage, ChatSession
-
-    # flag_type validated by FlagRequest Pydantic Literal — "spam", "quality", "escalation", or None
-
-    # R-040: Verify session ownership via JOIN to prevent IDOR
-    result = await db.execute(
-        select(ChatMessage)
-        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
-        .where(
-            ChatMessage.id == message_id,
-            ChatMessage.session_id == session_id,
-            ChatSession.author_id == current_user.id,
-        )
-    )
-    msg = result.scalar_one_or_none()
-    if not msg:
-        from fastapi import HTTPException
-        raise HTTPException(404, "Message not found")
-
-    msg.flag_type = body.flag_type
-    await db.commit()
-    return {"message": "Flag updated", "flag_type": body.flag_type}
-
-
-
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-# PHASE 1.3 — CUSTOM Q&A TRAINING DATA
-# ══════════════════════════════════════════════════════════════════════════════
-
-
-@router.get("/{author_slug}/qa")
-async def list_qa(
-    author_slug: str,
-    book_id: str | None = None,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """List all custom Q&A pairs for the author."""
-    from sqlalchemy import select
-    from app.models.custom_qa import CustomQA
-
-    query = (
-        select(CustomQA)
-        .where(CustomQA.author_id == current_user.id)
-        .order_by(CustomQA.priority.desc(), CustomQA.created_at.desc())
-    )
-    if book_id:
-        query = query.where(CustomQA.book_id == book_id)
-
-    result = await db.execute(query)
-    items = result.scalars().all()
-    return {
-        "qa_pairs": [
-            {
-                "id": qa.id,
-                "book_id": qa.book_id,
-                "question": qa.question,
-                "answer": qa.answer,
-                "priority": qa.priority,
-                "is_active": qa.is_active,
-                "match_count": qa.match_count,
-                "match_threshold": qa.match_threshold,
-                "category": qa.category,
-                "created_at": qa.created_at.isoformat() if qa.created_at else None,
-            }
-            for qa in items
-        ],
-        "total": len(items),
-    }
-
-
-@router.post("/{author_slug}/qa", status_code=201)
-async def create_qa(
-    author_slug: str,
-    body: dict,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Create a new custom Q&A pair."""
-    from sqlalchemy import select, func
-    from app.models.custom_qa import CustomQA
-    from fastapi import HTTPException
-
-    # Enforce limit: max 500 per author
-    count = await db.scalar(
-        select(func.count()).where(CustomQA.author_id == current_user.id)
-    ) or 0
-    if count >= 500:
-        raise HTTPException(400, "Maximum 500 Q&A pairs allowed")
-
-    question = str(body.get("question", "")).strip()
-    answer = str(body.get("answer", "")).strip()
-    if not question or not answer:
-        raise HTTPException(400, "Both question and answer are required")
-    if len(question) > 500:
-        raise HTTPException(400, "Question must be under 500 characters")
-    if len(answer) > 2000:
-        raise HTTPException(400, "Answer must be under 2000 characters")
-
-    qa = CustomQA(
-        author_id=current_user.id,
-        book_id=body.get("book_id"),
-        question=question,
-        answer=answer,
-        priority=int(body.get("priority", 0)),
-        category=body.get("category"),
-        match_threshold=float(body.get("match_threshold", 0.85)),
-    )
-    db.add(qa)
-    await db.commit()
-    return {"id": qa.id, "message": "Q&A pair created"}
-
-
-@router.post("/{author_slug}/qa/import")
-async def import_qa_csv(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-    file: UploadFile = File(...),
-):
-    """Bulk import Q&A pairs from CSV (columns: question,answer,category,priority)."""
-    import csv
-    import io
-    from sqlalchemy import select, func
-    from app.models.custom_qa import CustomQA
-    from fastapi import HTTPException
-
-    contents = await file.read()
-    text = contents.decode("utf-8-sig")
-    reader = csv.DictReader(io.StringIO(text))
-
-    if not reader.fieldnames or "question" not in reader.fieldnames or "answer" not in reader.fieldnames:
-        raise HTTPException(400, "CSV must have 'question' and 'answer' columns")
-
-    current_count = await db.scalar(
-        select(func.count()).where(CustomQA.author_id == current_user.id)
-    ) or 0
-
-    imported = 0
-    skipped = 0
-    errors = []
-
-    for i, row in enumerate(reader, 1):
-        if current_count + imported >= 500:
-            errors.append(f"Row {i}: Limit of 500 Q&A pairs reached")
-            break
-
-        q = (row.get("question") or "").strip()
-        a = (row.get("answer") or "").strip()
-        if not q or not a:
-            skipped += 1
-            continue
-        if len(q) > 500 or len(a) > 2000:
-            errors.append(f"Row {i}: Question or answer too long")
-            skipped += 1
-            continue
-
-        qa = CustomQA(
-            author_id=current_user.id,
-            question=q[:500],
-            answer=a[:2000],
-            category=(row.get("category") or "").strip()[:50] or None,
-            priority=int(row.get("priority") or 0),
-        )
-        db.add(qa)
-        imported += 1
-
-    await db.commit()
-    return {
-        "imported": imported,
-        "skipped": skipped,
-        "errors": errors[:10],
-        "message": f"Imported {imported} Q&A pairs",
-    }
-
-
-@router.get("/{author_slug}/qa/export")
-async def export_qa_csv(
-    author_slug: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Export all Q&A pairs as CSV."""
-    import csv
-    import io
-    from sqlalchemy import select
-    from app.models.custom_qa import CustomQA
-    from fastapi.responses import StreamingResponse
-
-    result = await db.execute(
-        select(CustomQA)
-        .where(CustomQA.author_id == current_user.id)
-        .order_by(CustomQA.priority.desc())
-    )
-    items = result.scalars().all()
-
-    output = io.StringIO()
-    writer = csv.writer(output)
-    writer.writerow(["question", "answer", "category", "priority", "is_active", "match_count"])
-    for qa in items:
-        writer.writerow([qa.question, qa.answer, qa.category or "", qa.priority, qa.is_active, qa.match_count])
-
-    output.seek(0)
-    return StreamingResponse(
-        iter([output.getvalue()]),
-        media_type="text/csv",
-        headers={"Content-Disposition": "attachment; filename=qa_pairs.csv"},
-    )
-
-
-@router.put("/{author_slug}/qa/{qa_id}")
-async def update_qa(
-    author_slug: str,
-    qa_id: str,
-    body: dict,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Update an existing Q&A pair."""
-    from sqlalchemy import select
-    from app.models.custom_qa import CustomQA
-    from fastapi import HTTPException
-
-    result = await db.execute(
-        select(CustomQA).where(CustomQA.id == qa_id, CustomQA.author_id == current_user.id)
-    )
-    qa = result.scalar_one_or_none()
-    if not qa:
-        raise HTTPException(404, "Q&A pair not found")
-
-    if "question" in body:
-        q = str(body["question"]).strip()
-        if not q or len(q) > 500:
-            raise HTTPException(400, "Question must be 1-500 characters")
-        qa.question = q
-    if "answer" in body:
-        a = str(body["answer"]).strip()
-        if not a or len(a) > 2000:
-            raise HTTPException(400, "Answer must be 1-2000 characters")
-        qa.answer = a
-    if "priority" in body:
-        qa.priority = int(body["priority"])
-    if "is_active" in body:
-        qa.is_active = bool(body["is_active"])
-    if "category" in body:
-        qa.category = body["category"]
-    if "book_id" in body:
-        qa.book_id = body["book_id"]
-    if "match_threshold" in body:
-        t = float(body["match_threshold"])
-        if not (0.5 <= t <= 1.0):
-            raise HTTPException(400, "Threshold must be between 0.5 and 1.0")
-        qa.match_threshold = t
-
-    await db.commit()
-    return {"message": "Q&A pair updated"}
-
-
-@router.delete("/{author_slug}/qa/{qa_id}")
-async def delete_qa(
-    author_slug: str,
-    qa_id: str,
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Delete a Q&A pair."""
-    from sqlalchemy import select
-    from app.models.custom_qa import CustomQA
-    from fastapi import HTTPException
-
-    result = await db.execute(
-        select(CustomQA).where(CustomQA.id == qa_id, CustomQA.author_id == current_user.id)
-    )
-    qa = result.scalar_one_or_none()
-    if not qa:
-        raise HTTPException(404, "Q&A pair not found")
-
-    await db.delete(qa)
-    await db.commit()
-    return {"message": "Q&A pair deleted"}
-
-
-
-
-
-# ══════════════════════════════════════════════════════════════════════════════
-# PHASE 1.4 — EXPORT CENTER
-# ══════════════════════════════════════════════════════════════════════════════
-
-
-@router.get("/{author_slug}/export/sessions")
-async def export_sessions(
-    author_slug: str,
-    days: int = Query(30, ge=1, le=365),
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Export chat sessions as CSV."""
-    import csv
-    import io
-    from datetime import datetime, timedelta, timezone
-    from sqlalchemy import select
-    from app.models.chat_session import ChatSession
-    from fastapi.responses import StreamingResponse
-
-    since = datetime.now(timezone.utc) - timedelta(days=days)
-    result = await db.execute(
-        select(ChatSession)
-        .where(ChatSession.author_id == current_user.id, ChatSession.created_at >= since)
-        .order_by(ChatSession.created_at.desc())
-        .limit(50000)
-    )
-    sessions = result.scalars().all()
-
-    output = io.StringIO()
-    writer = csv.writer(output)
-    writer.writerow([
-        "session_id", "visitor_fp", "visitor_name", "country", "city",
-        "device", "browser", "os", "turn_count", "link_clicked", "rating",
-        "blocked", "created_at",
-    ])
-    for s in sessions:
-        writer.writerow([
-            s.id, s.visitor_fingerprint[:8], s.visitor_name or "",
-            s.country_name or "", s.city or "", s.device_type or "",
-            s.browser or "", s.os or "", s.turn_count, s.link_clicked,
-            s.rating or "", s.blocked,
-            s.created_at.isoformat() if s.created_at else "",
-        ])
-
-    output.seek(0)
-    return StreamingResponse(
-        iter([output.getvalue()]),
-        media_type="text/csv",
-        headers={"Content-Disposition": f"attachment; filename=sessions_{days}d.csv"},
-    )
-
-
-@router.get("/{author_slug}/export/analytics")
-async def export_analytics(
-    author_slug: str,
-    days: int = Query(30, ge=1, le=365),
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Export daily analytics as CSV."""
-    import csv
-    import io
-    from datetime import datetime, timedelta, timezone
-    from sqlalchemy import select, func
-    from app.models.analytics import AnalyticsEvent
-    from fastapi.responses import StreamingResponse
-
-    since = datetime.now(timezone.utc) - timedelta(days=days)
-    result = await db.execute(
-        select(
-            func.date(AnalyticsEvent.timestamp).label("date"),
-            func.count().label("events"),
-            func.sum(AnalyticsEvent.prompt_tokens + AnalyticsEvent.completion_tokens).label("tokens"),
-            func.avg(AnalyticsEvent.response_ms).label("avg_latency"),
-            func.sum(func.cast(AnalyticsEvent.link_clicked, Integer)).label("clicks"),
-        )
-        .where(AnalyticsEvent.author_id == current_user.id, AnalyticsEvent.timestamp >= since)
-        .group_by(func.date(AnalyticsEvent.timestamp))
-        .order_by(func.date(AnalyticsEvent.timestamp))
-    )
-    rows = result.all()
-
-    output = io.StringIO()
-    writer = csv.writer(output)
-    writer.writerow(["date", "events", "total_tokens", "avg_latency_ms", "link_clicks"])
-    for r in rows:
-        writer.writerow([str(r.date), r.events, r.tokens or 0, round(r.avg_latency or 0, 1), r.clicks or 0])
-
-    output.seek(0)
-    return StreamingResponse(
-        iter([output.getvalue()]),
-        media_type="text/csv",
-        headers={"Content-Disposition": f"attachment; filename=analytics_{days}d.csv"},
-    )
-
-
-@router.get("/{author_slug}/export/conversations")
-async def export_conversations(
-    author_slug: str,
-    session_id: str | None = None,
-    days: int = Query(7, ge=1, le=30),
-    current_user=Depends(get_current_author_scoped),
-    db: AsyncSession = Depends(get_db),
-):
-    """Export full conversation transcripts as CSV."""
-    import csv
-    import io
-    from datetime import datetime, timedelta, timezone
-    from sqlalchemy import select
-    from app.models.chat_session import ChatSession, ChatMessage
-    from fastapi.responses import StreamingResponse
-
-    since = datetime.now(timezone.utc) - timedelta(days=days)
-    query = (
-        select(ChatMessage)
-        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
-        .where(ChatSession.author_id == current_user.id)
-        .order_by(ChatMessage.created_at.asc())
-        .limit(50000)
-    )
-    if session_id:
-        query = query.where(ChatSession.id == session_id)
-    else:
-        query = query.where(ChatSession.created_at >= since)
-
-    result = await db.execute(query)
-    messages = result.scalars().all()
-
-    output = io.StringIO()
-    writer = csv.writer(output)
-    writer.writerow([
-        "session_id", "role", "content", "intent", "confidence",
-        "faithfulness", "hallucination", "tokens", "latency_ms", "timestamp",
-    ])
-    for m in messages:
-        writer.writerow([
-            m.session_id, m.role, m.content[:500], m.intent or "",
-            m.intent_confidence or "", m.faithfulness_score or "",
-            m.hallucination_detected or "", (m.prompt_tokens or 0) + (m.completion_tokens or 0),
-            m.response_ms or "",
-            m.created_at.isoformat() if m.created_at else "",
-        ])
-
-    output.seek(0)
-    return StreamingResponse(
-        iter([output.getvalue()]),
-        media_type="text/csv",
-        headers={"Content-Disposition": "attachment; filename=conversations.csv"},
-    )
+router.include_router(dashboard.router)
+router.include_router(books.router)
+router.include_router(analytics.router)
+router.include_router(settings.router)
+router.include_router(links.router)
+router.include_router(qa.router)
+router.include_router(exports.router)

app/admin/routers/__init__.py

@@ -0,0 +1 @@
+"""admin/routers/__init__.py"""

app/admin/routers/analytics.py

@@ -0,0 +1,137 @@
+"""admin/routers/analytics.py — Analytics and reporting routes.
+
+Routes:
+  GET /{slug}/analytics
+  GET /{slug}/analytics/funnel
+  GET /{slug}/analytics/intents
+"""
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import Integer
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db, get_current_author_scoped
+
+router = APIRouter()
+
+
+@router.get("/{author_slug}/analytics")
+async def get_analytics(
+    author_slug: str,
+    days: int = Query(30, ge=1, le=365),
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Return daily session counts for dashboard charts."""
+    from datetime import datetime, timedelta, timezone
+    from sqlalchemy import select, func
+    from app.models.analytics import AnalyticsEvent
+
+    since = datetime.now(timezone.utc) - timedelta(days=days)
+    result = await db.execute(
+        select(
+            func.date(AnalyticsEvent.timestamp).label("date"),
+            func.count().label("count"),
+        )
+        .where(
+            AnalyticsEvent.author_id == current_user.id,
+            AnalyticsEvent.timestamp >= since,
+        )
+        .group_by(func.date(AnalyticsEvent.timestamp))
+        .order_by(func.date(AnalyticsEvent.timestamp))
+    )
+    daily = [{"date": str(row.date), "count": row.count} for row in result]
+    return {"daily_sessions": daily, "period_days": days}
+
+
+@router.get("/{author_slug}/analytics/funnel")
+async def get_conversion_funnel(
+    author_slug: str,
+    days: int = Query(30, ge=1, le=365),
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Return conversion funnel data (sessions → chat → book → link → click)."""
+    from datetime import datetime, timedelta, timezone
+    from sqlalchemy import select, func
+    from app.models.analytics import AnalyticsEvent
+    from app.models.chat_session import ChatSession
+
+    since = datetime.now(timezone.utc) - timedelta(days=days)
+
+    total_sessions = await db.scalar(
+        select(func.count()).where(
+            ChatSession.author_id == current_user.id,
+            ChatSession.created_at >= since,
+        )
+    ) or 0
+
+    chat_started = await db.scalar(
+        select(func.count(func.distinct(AnalyticsEvent.session_id))).where(
+            AnalyticsEvent.author_id == current_user.id,
+            AnalyticsEvent.timestamp >= since,
+        )
+    ) or 0
+
+    book_discussed = await db.scalar(
+        select(func.count(func.distinct(AnalyticsEvent.session_id))).where(
+            AnalyticsEvent.author_id == current_user.id,
+            AnalyticsEvent.book_id.isnot(None),
+            AnalyticsEvent.timestamp >= since,
+        )
+    ) or 0
+
+    link_shown = await db.scalar(
+        select(func.count()).where(
+            AnalyticsEvent.author_id == current_user.id,
+            AnalyticsEvent.link_shown == True,
+            AnalyticsEvent.timestamp >= since,
+        )
+    ) or 0
+
+    link_clicked = await db.scalar(
+        select(func.count()).where(
+            AnalyticsEvent.author_id == current_user.id,
+            AnalyticsEvent.link_clicked == True,
+            AnalyticsEvent.timestamp >= since,
+        )
+    ) or 0
+
+    return {
+        "funnel": [
+            {"stage": "Widget Loads", "count": total_sessions},
+            {"stage": "Chats Started", "count": chat_started},
+            {"stage": "Book Discussed", "count": book_discussed},
+            {"stage": "Link Shown", "count": link_shown},
+            {"stage": "Link Clicked", "count": link_clicked},
+        ],
+        "period_days": days,
+    }
+
+
+@router.get("/{author_slug}/analytics/intents")
+async def get_intent_distribution(
+    author_slug: str,
+    days: int = Query(30, ge=1, le=365),
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Return distribution of detected intent labels."""
+    from datetime import datetime, timedelta, timezone
+    from sqlalchemy import select, func
+    from app.models.analytics import AnalyticsEvent
+
+    since = datetime.now(timezone.utc) - timedelta(days=days)
+    result = await db.execute(
+        select(AnalyticsEvent.intent, func.count().label("count"))
+        .where(
+            AnalyticsEvent.author_id == current_user.id,
+            AnalyticsEvent.intent.isnot(None),
+            AnalyticsEvent.timestamp >= since,
+        )
+        .group_by(AnalyticsEvent.intent)
+        .order_by(func.count().desc())
+        .limit(20)
+    )
+    intents = [{"intent": row.intent or "unknown", "count": row.count} for row in result]
+    return {"intents": intents, "period_days": days}

app/admin/routers/books.py

@@ -0,0 +1,136 @@
+"""admin/routers/books.py — Book management routes.
+
+Routes:
+  GET    /{slug}/books
+  DELETE /{slug}/books/{book_id}
+  POST   /{slug}/books/{book_id}/cover
+"""
+
+from fastapi import APIRouter, Depends, File, UploadFile
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db, get_current_author_scoped
+from app.repositories.book_repo import BookRepository
+
+router = APIRouter()
+
+
+@router.get("/{author_slug}/books")
+async def list_books(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """List all books for the author."""
+    book_repo = BookRepository(db)
+    books = await book_repo.list_for_author(current_user.id)
+    return {
+        "books": [
+            {
+                "id": b.id,
+                "title": b.title,
+                "genre": b.genre,
+                "status": b.status,
+                "chunk_count": getattr(b, "chunk_count", 0),
+                "ai_summary": getattr(b, "ai_summary", ""),
+                "cover_path": getattr(b, "cover_path", None),
+                "cover_thumbnail": getattr(b, "cover_thumbnail_path", None),
+                "cover_medium": getattr(b, "cover_medium_path", None),
+                "buy_url": getattr(b, "buy_url", None),
+            }
+            for b in books
+        ]
+    }
+
+
+@router.delete("/{author_slug}/books/{book_id}")
+async def delete_book(
+    author_slug: str,
+    book_id: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a book and its ChromaDB collection."""
+    from fastapi import HTTPException
+    from app.services.embeddings import delete_book_embeddings
+
+    book_repo = BookRepository(db)
+    book = await book_repo.get_by_id(book_id)
+    if not book or book.author_id != current_user.id:
+        raise HTTPException(404, "Book not found")
+
+    delete_book_embeddings(current_user.id, book_id)
+    await db.delete(book)
+    await db.commit()
+    return {"message": "Book deleted"}
+
+
+@router.post("/{author_slug}/books/{book_id}/cover")
+async def upload_book_cover(
+    author_slug: str,
+    book_id: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+    file: UploadFile = File(...),
+):
+    """Upload a book cover image (JPG/PNG/WebP, max 5MB)."""
+    import os
+    from fastapi import HTTPException
+
+    book_repo = BookRepository(db)
+    book = await book_repo.get_by_id(book_id)
+    if not book or book.author_id != current_user.id:
+        raise HTTPException(404, "Book not found")
+
+    allowed_types = {"image/jpeg", "image/png", "image/webp"}
+    if file.content_type not in allowed_types:
+        raise HTTPException(400, "Invalid file type. Allowed: JPG, PNG, WebP")
+
+    contents = await file.read()
+    if len(contents) > 5 * 1024 * 1024:
+        raise HTTPException(400, "File too large. Maximum: 5MB")
+
+    if contents[:2] not in (b'\xff\xd8', b'\x89P') and contents[:4] != b'RIFF':
+        raise HTTPException(400, "File does not appear to be a valid image")
+
+    cover_dir = f"/data/covers/{current_user.id}/{book_id}"
+    os.makedirs(cover_dir, exist_ok=True)
+
+    ext = file.filename.rsplit('.', 1)[-1].lower() if file.filename else 'jpg'
+    if ext not in ('jpg', 'jpeg', 'png', 'webp'):
+        ext = 'jpg'
+    original_path = f"{cover_dir}/original.{ext}"
+    with open(original_path, "wb") as f:
+        f.write(contents)
+
+    thumbnail_path = original_path
+    medium_path = original_path
+    try:
+        from PIL import Image
+        import io
+
+        img = Image.open(io.BytesIO(contents)).convert('RGB')
+
+        thumb = img.copy()
+        thumb.thumbnail((80, 120), Image.LANCZOS)
+        thumbnail_path = f"{cover_dir}/thumb.webp"
+        thumb.save(thumbnail_path, 'WEBP', quality=80)
+
+        med = img.copy()
+        med.thumbnail((300, 450), Image.LANCZOS)
+        medium_path = f"{cover_dir}/medium.webp"
+        med.save(medium_path, 'WEBP', quality=85)
+    except ImportError:
+        pass  # PIL not available — use original for all sizes
+
+    book.cover_path = original_path
+    book.cover_thumbnail_path = thumbnail_path
+    book.cover_medium_path = medium_path
+    await db.commit()
+
+    return {
+        "message": "Cover uploaded",
+        "cover_path": original_path,
+        "cover_thumbnail": thumbnail_path,
+        "cover_medium": medium_path,
+    }

app/admin/routers/dashboard.py

@@ -0,0 +1,347 @@
+"""admin/routers/dashboard.py — Sessions, transcripts, and message moderation.
+
+Routes:
+  GET    /{slug}/dashboard
+  GET    /{slug}/sessions
+  GET    /{slug}/sessions/search
+  POST   /{slug}/sessions/{id}/block
+  POST   /{slug}/sessions/{id}/unblock
+  GET    /{slug}/sessions/{id}/transcript
+  POST   /{slug}/sessions/{id}/messages/{mid}/annotate
+  POST   /{slug}/sessions/{id}/messages/{mid}/flag
+"""
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db, get_current_author_scoped
+from app.repositories.book_repo import BookRepository
+from app.schemas.admin import AnnotateRequest, FlagRequest
+
+router = APIRouter()
+
+
+@router.get("/{author_slug}/dashboard")
+async def dashboard(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Return high-level dashboard stats for the author."""
+    book_repo = BookRepository(db)
+    books = await book_repo.list_for_author(current_user.id)
+
+    from sqlalchemy import func, select
+    from app.models.chat_session import ChatSession
+
+    total_sessions = await db.scalar(
+        select(func.count()).where(ChatSession.author_id == current_user.id)
+    ) or 0
+
+    return {
+        "total_books": len(books),
+        "active_books": sum(1 for b in books if b.status == "active"),
+        "total_sessions": total_sessions,
+        "total_clicks": 0,
+    }
+
+
+@router.get("/{author_slug}/sessions")
+async def list_sessions(
+    author_slug: str,
+    limit: int = Query(50, ge=1, le=200),
+    offset: int = 0,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """List reader sessions with pagination."""
+    from sqlalchemy import select, desc
+    from app.models.chat_session import ChatSession
+
+    result = await db.execute(
+        select(ChatSession)
+        .where(ChatSession.author_id == current_user.id)
+        .order_by(desc(ChatSession.created_at))
+        .offset(offset)
+        .limit(limit)
+    )
+    sessions = result.scalars().all()
+    return {
+        "sessions": [
+            {
+                "id": s.id,
+                "visitor_fingerprint": s.visitor_fingerprint,
+                "visitor_name": s.visitor_name,
+                "country": s.country_name,
+                "device_type": s.device_type,
+                "turn_count": s.turn_count,
+                "rating": s.rating,
+                "created_at": s.created_at.isoformat() if s.created_at else None,
+                "blocked": s.blocked,
+            }
+            for s in sessions
+        ]
+    }
+
+
+@router.get("/{author_slug}/sessions/search")
+async def search_sessions(
+    author_slug: str,
+    q: str = Query("", min_length=0, max_length=200),
+    page: int = Query(1, ge=1),
+    per_page: int = Query(20, ge=1, le=100),
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Full-text search across chat messages for the author."""
+    from sqlalchemy import select, func, desc, distinct
+    from app.models.chat_session import ChatSession, ChatMessage
+
+    if not q.strip():
+        return {"sessions": [], "total": 0}
+
+    search_term = f"%{q.strip().lower()}%"
+
+    matching_sessions = (
+        select(distinct(ChatMessage.session_id))
+        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
+        .where(
+            ChatSession.author_id == current_user.id,
+            func.lower(ChatMessage.content).like(search_term),
+        )
+    )
+
+    total = await db.scalar(
+        select(func.count()).select_from(matching_sessions.subquery())
+    ) or 0
+
+    result = await db.execute(
+        select(ChatSession)
+        .where(
+            ChatSession.author_id == current_user.id,
+            ChatSession.id.in_(matching_sessions),
+        )
+        .order_by(desc(ChatSession.created_at))
+        .offset((page - 1) * per_page)
+        .limit(per_page)
+    )
+    sessions = result.scalars().all()
+
+    return {
+        "sessions": [
+            {
+                "id": s.id,
+                "visitor_fingerprint": s.visitor_fingerprint[:8] + "...",
+                "visitor_name": s.visitor_name,
+                "country": s.country_name,
+                "device_type": s.device_type,
+                "turn_count": s.turn_count,
+                "rating": s.rating,
+                "created_at": s.created_at.isoformat() if s.created_at else None,
+            }
+            for s in sessions
+        ],
+        "total": total,
+        "query": q,
+        "page": page,
+    }
+
+
+@router.post("/{author_slug}/sessions/{session_id}/block")
+async def block_session(
+    author_slug: str,
+    session_id: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Block a visitor session."""
+    from sqlalchemy import select
+    from app.models.chat_session import ChatSession
+    from fastapi import HTTPException
+
+    result = await db.execute(
+        select(ChatSession).where(
+            ChatSession.id == session_id,
+            ChatSession.author_id == current_user.id,
+        )
+    )
+    session = result.scalar_one_or_none()
+    if not session:
+        raise HTTPException(404, "Session not found")
+    session.blocked = True
+    await db.commit()
+    return {"message": "Session blocked"}
+
+
+@router.post("/{author_slug}/sessions/{session_id}/unblock")
+async def unblock_session(
+    author_slug: str,
+    session_id: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Unblock a visitor session."""
+    from sqlalchemy import select
+    from app.models.chat_session import ChatSession
+    from fastapi import HTTPException
+
+    result = await db.execute(
+        select(ChatSession).where(
+            ChatSession.id == session_id,
+            ChatSession.author_id == current_user.id,
+        )
+    )
+    session = result.scalar_one_or_none()
+    if not session:
+        raise HTTPException(404, "Session not found")
+    session.blocked = False
+    await db.commit()
+    return {"message": "Session unblocked"}
+
+
+@router.get("/{author_slug}/sessions/{session_id}/transcript")
+async def get_transcript(
+    author_slug: str,
+    session_id: str,
+    page: int = Query(1, ge=1),
+    per_page: int = Query(50, ge=1, le=200),
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Return paginated message transcript for a session."""
+    from sqlalchemy import select, func
+    from app.models.chat_session import ChatSession, ChatMessage
+    from fastapi import HTTPException
+
+    session_result = await db.execute(
+        select(ChatSession).where(
+            ChatSession.id == session_id,
+            ChatSession.author_id == current_user.id,
+        )
+    )
+    session = session_result.scalar_one_or_none()
+    if not session:
+        raise HTTPException(404, "Session not found")
+
+    total = await db.scalar(
+        select(func.count()).where(ChatMessage.session_id == session_id)
+    ) or 0
+
+    result = await db.execute(
+        select(ChatMessage)
+        .where(ChatMessage.session_id == session_id)
+        .order_by(ChatMessage.created_at.asc())
+        .offset((page - 1) * per_page)
+        .limit(per_page)
+    )
+    messages = result.scalars().all()
+
+    return {
+        "session": {
+            "id": session.id,
+            "visitor_fingerprint": session.visitor_fingerprint[:8] + "...",
+            "visitor_name": session.visitor_name,
+            "visitor_email": session.visitor_email,
+            "country": session.country_name,
+            "city": session.city,
+            "device_type": session.device_type,
+            "browser": session.browser,
+            "os": session.os,
+            "rating": session.rating,
+            "blocked": session.blocked,
+            "created_at": session.created_at.isoformat() if session.created_at else None,
+            "summary": session.summary,
+        },
+        "messages": [
+            {
+                "id": m.id,
+                "role": m.role,
+                "content": m.content,
+                "intent": m.intent,
+                "intent_confidence": m.intent_confidence,
+                "faithfulness_score": m.faithfulness_score,
+                "hallucination_detected": m.hallucination_detected,
+                "prompt_tokens": m.prompt_tokens,
+                "completion_tokens": m.completion_tokens,
+                "response_ms": m.response_ms,
+                "annotation": m.annotation,
+                "flag_type": m.flag_type,
+                "user_feedback": m.user_feedback,
+                "created_at": m.created_at.isoformat() if m.created_at else None,
+            }
+            for m in messages
+        ],
+        "pagination": {
+            "page": page,
+            "per_page": per_page,
+            "total": total,
+            "total_pages": (total + per_page - 1) // per_page,
+        },
+    }
+
+
+@router.post("/{author_slug}/sessions/{session_id}/messages/{message_id}/annotate")
+async def annotate_message(
+    author_slug: str,
+    session_id: str,
+    message_id: str,
+    body: AnnotateRequest,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Add admin annotation to a chat message (append-only). R-029: Schema validated."""
+    from sqlalchemy import select
+    from app.models.chat_session import ChatMessage, ChatSession
+    from fastapi import HTTPException
+    from datetime import datetime, timezone
+
+    result = await db.execute(
+        select(ChatMessage)
+        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
+        .where(
+            ChatMessage.id == message_id,
+            ChatMessage.session_id == session_id,
+            ChatSession.author_id == current_user.id,
+        )
+    )
+    msg = result.scalar_one_or_none()
+    if not msg:
+        raise HTTPException(404, "Message not found")
+
+    prefix = f"[{datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M')}] "
+    existing = msg.annotation or ""
+    msg.annotation = (prefix + body.annotation + "\n" + existing).strip()
+    await db.commit()
+    return {"message": "Annotation saved", "annotation": msg.annotation}
+
+
+@router.post("/{author_slug}/sessions/{session_id}/messages/{message_id}/flag")
+async def flag_message(
+    author_slug: str,
+    session_id: str,
+    message_id: str,
+    body: FlagRequest,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Flag a message as spam, quality issue, or escalation. R-029: Schema validated."""
+    from sqlalchemy import select
+    from app.models.chat_session import ChatMessage, ChatSession
+    from fastapi import HTTPException
+
+    result = await db.execute(
+        select(ChatMessage)
+        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
+        .where(
+            ChatMessage.id == message_id,
+            ChatMessage.session_id == session_id,
+            ChatSession.author_id == current_user.id,
+        )
+    )
+    msg = result.scalar_one_or_none()
+    if not msg:
+        raise HTTPException(404, "Message not found")
+
+    msg.flag_type = body.flag_type
+    await db.commit()
+    return {"message": "Flag updated", "flag_type": body.flag_type}

app/admin/routers/exports.py

@@ -0,0 +1,162 @@
+"""admin/routers/exports.py — CSV data export routes.
+
+Routes:
+  GET /{slug}/export/sessions
+  GET /{slug}/export/analytics
+  GET /{slug}/export/conversations
+"""
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import Integer
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db, get_current_author_scoped
+
+router = APIRouter()
+
+
+@router.get("/{author_slug}/export/sessions")
+async def export_sessions(
+    author_slug: str,
+    days: int = Query(30, ge=1, le=365),
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Export chat sessions as CSV."""
+    import csv
+    import io
+    from datetime import datetime, timedelta, timezone
+    from sqlalchemy import select
+    from app.models.chat_session import ChatSession
+    from fastapi.responses import StreamingResponse
+
+    since = datetime.now(timezone.utc) - timedelta(days=days)
+    result = await db.execute(
+        select(ChatSession)
+        .where(ChatSession.author_id == current_user.id, ChatSession.created_at >= since)
+        .order_by(ChatSession.created_at.desc())
+        .limit(50000)
+    )
+    sessions = result.scalars().all()
+
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow([
+        "session_id", "visitor_fp", "visitor_name", "country", "city",
+        "device", "browser", "os", "turn_count", "link_clicked", "rating",
+        "blocked", "created_at",
+    ])
+    for s in sessions:
+        writer.writerow([
+            s.id, s.visitor_fingerprint[:8], s.visitor_name or "",
+            s.country_name or "", s.city or "", s.device_type or "",
+            s.browser or "", s.os or "", s.turn_count, s.link_clicked,
+            s.rating or "", s.blocked,
+            s.created_at.isoformat() if s.created_at else "",
+        ])
+
+    output.seek(0)
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": f"attachment; filename=sessions_{days}d.csv"},
+    )
+
+
+@router.get("/{author_slug}/export/analytics")
+async def export_analytics(
+    author_slug: str,
+    days: int = Query(30, ge=1, le=365),
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Export daily analytics aggregates as CSV."""
+    import csv
+    import io
+    from datetime import datetime, timedelta, timezone
+    from sqlalchemy import select, func
+    from app.models.analytics import AnalyticsEvent
+    from fastapi.responses import StreamingResponse
+
+    since = datetime.now(timezone.utc) - timedelta(days=days)
+    result = await db.execute(
+        select(
+            func.date(AnalyticsEvent.timestamp).label("date"),
+            func.count().label("events"),
+            func.sum(AnalyticsEvent.prompt_tokens + AnalyticsEvent.completion_tokens).label("tokens"),
+            func.avg(AnalyticsEvent.response_ms).label("avg_latency"),
+            func.sum(func.cast(AnalyticsEvent.link_clicked, Integer)).label("clicks"),
+        )
+        .where(AnalyticsEvent.author_id == current_user.id, AnalyticsEvent.timestamp >= since)
+        .group_by(func.date(AnalyticsEvent.timestamp))
+        .order_by(func.date(AnalyticsEvent.timestamp))
+    )
+    rows = result.all()
+
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow(["date", "events", "total_tokens", "avg_latency_ms", "link_clicks"])
+    for r in rows:
+        writer.writerow([str(r.date), r.events, r.tokens or 0, round(r.avg_latency or 0, 1), r.clicks or 0])
+
+    output.seek(0)
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": f"attachment; filename=analytics_{days}d.csv"},
+    )
+
+
+@router.get("/{author_slug}/export/conversations")
+async def export_conversations(
+    author_slug: str,
+    session_id: str | None = None,
+    days: int = Query(7, ge=1, le=30),
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Export full conversation transcripts as CSV."""
+    import csv
+    import io
+    from datetime import datetime, timedelta, timezone
+    from sqlalchemy import select
+    from app.models.chat_session import ChatSession, ChatMessage
+    from fastapi.responses import StreamingResponse
+
+    since = datetime.now(timezone.utc) - timedelta(days=days)
+    query = (
+        select(ChatMessage)
+        .join(ChatSession, ChatMessage.session_id == ChatSession.id)
+        .where(ChatSession.author_id == current_user.id)
+        .order_by(ChatMessage.created_at.asc())
+        .limit(50000)
+    )
+    if session_id:
+        query = query.where(ChatSession.id == session_id)
+    else:
+        query = query.where(ChatSession.created_at >= since)
+
+    result = await db.execute(query)
+    messages = result.scalars().all()
+
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow([
+        "session_id", "role", "content", "intent", "confidence",
+        "faithfulness", "hallucination", "tokens", "latency_ms", "timestamp",
+    ])
+    for m in messages:
+        writer.writerow([
+            m.session_id, m.role, m.content[:500], m.intent or "",
+            m.intent_confidence or "", m.faithfulness_score or "",
+            m.hallucination_detected or "", (m.prompt_tokens or 0) + (m.completion_tokens or 0),
+            m.response_ms or "",
+            m.created_at.isoformat() if m.created_at else "",
+        ])
+
+    output.seek(0)
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": "attachment; filename=conversations.csv"},
+    )

app/admin/routers/links.py

@@ -0,0 +1,48 @@
+"""admin/routers/links.py — Smart links (buy/preview URLs) routes.
+
+Routes:
+  PUT /{slug}/smart-links/{book_id}
+"""
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db, get_current_author_scoped
+from app.repositories.book_repo import BookRepository
+
+router = APIRouter()
+
+
+@router.put("/{author_slug}/smart-links/{book_id}")
+async def update_smart_link(
+    author_slug: str,
+    book_id: str,
+    body: dict,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update buy/preview URLs for a book."""
+    from fastapi import HTTPException
+    from app.repositories.link_repo import LinkRepository
+
+    book_repo = BookRepository(db)
+    book = await book_repo.get_by_id(book_id)
+    if not book or book.author_id != current_user.id:
+        raise HTTPException(404, "Book not found")
+
+    if "buy_url" in body:
+        book.buy_url = str(body["buy_url"])[:1000] if body["buy_url"] else None
+    if "preview_url" in body:
+        book.preview_url = str(body["preview_url"])[:1000] if body["preview_url"] else None
+
+    link_repo = LinkRepository(db)
+    await link_repo.upsert_for_book(
+        current_user.id,
+        book_id,
+        {
+            "purchase_url": book.buy_url,
+            "preview_url": book.preview_url,
+        },
+    )
+    await db.commit()
+    return {"message": "Smart link updated"}

app/admin/routers/qa.py

@@ -0,0 +1,268 @@
+"""admin/routers/qa.py — Custom Q&A training data routes.
+
+Routes:
+  GET    /{slug}/qa
+  POST   /{slug}/qa
+  POST   /{slug}/qa/import
+  GET    /{slug}/qa/export
+  PUT    /{slug}/qa/{qa_id}
+  DELETE /{slug}/qa/{qa_id}
+"""
+
+from fastapi import APIRouter, Depends, File, UploadFile
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db, get_current_author_scoped
+
+router = APIRouter()
+
+
+@router.get("/{author_slug}/qa")
+async def list_qa(
+    author_slug: str,
+    book_id: str | None = None,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """List all custom Q&A pairs for the author."""
+    from sqlalchemy import select
+    from app.models.custom_qa import CustomQA
+
+    query = (
+        select(CustomQA)
+        .where(CustomQA.author_id == current_user.id)
+        .order_by(CustomQA.priority.desc(), CustomQA.created_at.desc())
+    )
+    if book_id:
+        query = query.where(CustomQA.book_id == book_id)
+
+    result = await db.execute(query)
+    items = result.scalars().all()
+    return {
+        "qa_pairs": [
+            {
+                "id": qa.id,
+                "book_id": qa.book_id,
+                "question": qa.question,
+                "answer": qa.answer,
+                "priority": qa.priority,
+                "is_active": qa.is_active,
+                "match_count": qa.match_count,
+                "match_threshold": qa.match_threshold,
+                "category": qa.category,
+                "created_at": qa.created_at.isoformat() if qa.created_at else None,
+            }
+            for qa in items
+        ],
+        "total": len(items),
+    }
+
+
+@router.post("/{author_slug}/qa", status_code=201)
+async def create_qa(
+    author_slug: str,
+    body: dict,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new custom Q&A pair."""
+    from sqlalchemy import select, func
+    from app.models.custom_qa import CustomQA
+    from fastapi import HTTPException
+
+    count = await db.scalar(
+        select(func.count()).where(CustomQA.author_id == current_user.id)
+    ) or 0
+    if count >= 500:
+        raise HTTPException(400, "Maximum 500 Q&A pairs allowed")
+
+    question = str(body.get("question", "")).strip()
+    answer = str(body.get("answer", "")).strip()
+    if not question or not answer:
+        raise HTTPException(400, "Both question and answer are required")
+    if len(question) > 500:
+        raise HTTPException(400, "Question must be under 500 characters")
+    if len(answer) > 2000:
+        raise HTTPException(400, "Answer must be under 2000 characters")
+
+    qa = CustomQA(
+        author_id=current_user.id,
+        book_id=body.get("book_id"),
+        question=question,
+        answer=answer,
+        priority=int(body.get("priority", 0)),
+        category=body.get("category"),
+        match_threshold=float(body.get("match_threshold", 0.85)),
+    )
+    db.add(qa)
+    await db.commit()
+    return {"id": qa.id, "message": "Q&A pair created"}
+
+
+@router.post("/{author_slug}/qa/import")
+async def import_qa_csv(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+    file: UploadFile = File(...),
+):
+    """Bulk import Q&A pairs from CSV (columns: question,answer,category,priority)."""
+    import csv
+    import io
+    from sqlalchemy import select, func
+    from app.models.custom_qa import CustomQA
+    from fastapi import HTTPException
+
+    contents = await file.read()
+    text = contents.decode("utf-8-sig")
+    reader = csv.DictReader(io.StringIO(text))
+
+    if not reader.fieldnames or "question" not in reader.fieldnames or "answer" not in reader.fieldnames:
+        raise HTTPException(400, "CSV must have 'question' and 'answer' columns")
+
+    current_count = await db.scalar(
+        select(func.count()).where(CustomQA.author_id == current_user.id)
+    ) or 0
+
+    imported = 0
+    skipped = 0
+    errors = []
+
+    for i, row in enumerate(reader, 1):
+        if current_count + imported >= 500:
+            errors.append(f"Row {i}: Limit of 500 Q&A pairs reached")
+            break
+
+        q = (row.get("question") or "").strip()
+        a = (row.get("answer") or "").strip()
+        if not q or not a:
+            skipped += 1
+            continue
+        if len(q) > 500 or len(a) > 2000:
+            errors.append(f"Row {i}: Question or answer too long")
+            skipped += 1
+            continue
+
+        qa = CustomQA(
+            author_id=current_user.id,
+            question=q[:500],
+            answer=a[:2000],
+            category=(row.get("category") or "").strip()[:50] or None,
+            priority=int(row.get("priority") or 0),
+        )
+        db.add(qa)
+        imported += 1
+
+    await db.commit()
+    return {
+        "imported": imported,
+        "skipped": skipped,
+        "errors": errors[:10],
+        "message": f"Imported {imported} Q&A pairs",
+    }
+
+
+@router.get("/{author_slug}/qa/export")
+async def export_qa_csv(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Export all Q&A pairs as CSV."""
+    import csv
+    import io
+    from sqlalchemy import select
+    from app.models.custom_qa import CustomQA
+    from fastapi.responses import StreamingResponse
+
+    result = await db.execute(
+        select(CustomQA)
+        .where(CustomQA.author_id == current_user.id)
+        .order_by(CustomQA.priority.desc())
+    )
+    items = result.scalars().all()
+
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow(["question", "answer", "category", "priority", "is_active", "match_count"])
+    for qa in items:
+        writer.writerow([qa.question, qa.answer, qa.category or "", qa.priority, qa.is_active, qa.match_count])
+
+    output.seek(0)
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": "attachment; filename=qa_pairs.csv"},
+    )
+
+
+@router.put("/{author_slug}/qa/{qa_id}")
+async def update_qa(
+    author_slug: str,
+    qa_id: str,
+    body: dict,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update an existing Q&A pair."""
+    from sqlalchemy import select
+    from app.models.custom_qa import CustomQA
+    from fastapi import HTTPException
+
+    result = await db.execute(
+        select(CustomQA).where(CustomQA.id == qa_id, CustomQA.author_id == current_user.id)
+    )
+    qa = result.scalar_one_or_none()
+    if not qa:
+        raise HTTPException(404, "Q&A pair not found")
+
+    if "question" in body:
+        q = str(body["question"]).strip()
+        if not q or len(q) > 500:
+            raise HTTPException(400, "Question must be 1-500 characters")
+        qa.question = q
+    if "answer" in body:
+        a = str(body["answer"]).strip()
+        if not a or len(a) > 2000:
+            raise HTTPException(400, "Answer must be 1-2000 characters")
+        qa.answer = a
+    if "priority" in body:
+        qa.priority = int(body["priority"])
+    if "is_active" in body:
+        qa.is_active = bool(body["is_active"])
+    if "category" in body:
+        qa.category = body["category"]
+    if "book_id" in body:
+        qa.book_id = body["book_id"]
+    if "match_threshold" in body:
+        t = float(body["match_threshold"])
+        if not (0.5 <= t <= 1.0):
+            raise HTTPException(400, "Threshold must be between 0.5 and 1.0")
+        qa.match_threshold = t
+
+    await db.commit()
+    return {"message": "Q&A pair updated"}
+
+
+@router.delete("/{author_slug}/qa/{qa_id}")
+async def delete_qa(
+    author_slug: str,
+    qa_id: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a Q&A pair."""
+    from sqlalchemy import select
+    from app.models.custom_qa import CustomQA
+    from fastapi import HTTPException
+
+    result = await db.execute(
+        select(CustomQA).where(CustomQA.id == qa_id, CustomQA.author_id == current_user.id)
+    )
+    qa = result.scalar_one_or_none()
+    if not qa:
+        raise HTTPException(404, "Q&A pair not found")
+
+    await db.delete(qa)
+    await db.commit()
+    return {"message": "Q&A pair deleted"}

app/admin/routers/settings.py

@@ -0,0 +1,268 @@
+"""admin/routers/settings.py — Author settings and account management.
+
+Routes:
+  POST /{slug}/password
+  GET  /{slug}/widget-config
+  PUT  /{slug}/widget-config
+  GET  /{slug}/profile
+  PUT  /{slug}/profile
+  GET  /{slug}/personality
+  PUT  /{slug}/personality
+  GET  /{slug}/notifications
+  PUT  /{slug}/notifications
+  GET  /{slug}/embed-token
+  GET  /{slug}/token-usage
+"""
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db, get_current_author_scoped
+from app.schemas.admin import PasswordChangeRequest, ProfileUpdate, WidgetConfigUpdate
+
+router = APIRouter()
+
+
+@router.post("/{author_slug}/password")
+async def change_password(
+    author_slug: str,
+    body: PasswordChangeRequest,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Self-service password change. R-010: Validates via Pydantic schema."""
+    import bcrypt
+    from fastapi import HTTPException
+
+    try:
+        valid = bcrypt.checkpw(body.current_password.encode(), current_user.password_hash.encode())
+    except Exception:
+        valid = False
+    if not valid:
+        raise HTTPException(400, "Current password is incorrect")
+
+    current_user.password_hash = bcrypt.hashpw(
+        body.new_password.encode(), bcrypt.gensalt(12)
+    ).decode()
+    await db.commit()
+    return {"message": "Password updated"}
+
+
+@router.get("/{author_slug}/widget-config")
+async def get_widget_config(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+):
+    """Return current widget configuration."""
+    return {
+        "bot_name": current_user.bot_name,
+        "welcome_message": current_user.welcome_message,
+        "theme": current_user.widget_theme,
+        "position": current_user.widget_position,
+        "auto_open_delay": current_user.widget_auto_open_delay,
+        "is_active": current_user.chatbot_is_active,
+    }
+
+
+@router.put("/{author_slug}/widget-config")
+async def update_widget_config(
+    author_slug: str,
+    body: WidgetConfigUpdate,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update widget configuration. R-029: Validated via Pydantic schema."""
+    update_map = {
+        "bot_name": "bot_name",
+        "welcome_message": "welcome_message",
+        "theme": "widget_theme",
+        "position": "widget_position",
+        "auto_open_delay": "widget_auto_open_delay",
+        "is_active": "chatbot_is_active",
+    }
+    for field_name, attr in update_map.items():
+        val = getattr(body, field_name, None)
+        if val is not None:
+            setattr(current_user, attr, val)
+    await db.commit()
+    return {"message": "Widget config updated"}
+
+
+@router.get("/{author_slug}/profile")
+async def get_profile(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+):
+    """Return current author profile."""
+    return {
+        "full_name": current_user.full_name or "",
+        "email": current_user.email,
+        "website": current_user.website_url or "",
+        "bio": current_user.bio or "",
+        "timezone": current_user.timezone,
+    }
+
+
+@router.put("/{author_slug}/profile")
+async def update_profile(
+    author_slug: str,
+    body: ProfileUpdate,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update author profile. R-029: Validated via Pydantic schema."""
+    if body.full_name is not None:
+        current_user.full_name = body.full_name
+    if body.website is not None:
+        current_user.website_url = body.website
+    if body.bio is not None:
+        current_user.bio = body.bio
+    if body.timezone is not None:
+        current_user.timezone = body.timezone
+    await db.commit()
+    return {"message": "Profile updated"}
+
+
+@router.get("/{author_slug}/personality")
+async def get_personality(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+):
+    """Return bot personality settings."""
+    return {
+        "response_style": current_user.response_style,
+        "fallback_message": current_user.fallback_message,
+        "out_of_scope_message": current_user.out_of_scope_message,
+        "welcome_message": current_user.welcome_message,
+    }
+
+
+@router.put("/{author_slug}/personality")
+async def update_personality(
+    author_slug: str,
+    body: dict,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update bot personality settings."""
+    from fastapi import HTTPException
+
+    valid_styles = ["balanced", "formal", "casual", "enthusiastic"]
+    if "response_style" in body:
+        style = str(body["response_style"])
+        if style not in valid_styles:
+            raise HTTPException(400, f"Invalid style. Must be one of: {valid_styles}")
+        current_user.response_style = style
+    if "fallback_message" in body:
+        current_user.fallback_message = str(body["fallback_message"])[:500]
+    if "out_of_scope_message" in body:
+        current_user.out_of_scope_message = str(body["out_of_scope_message"])[:500]
+    await db.commit()
+    return {"message": "Personality settings updated"}
+
+
+@router.get("/{author_slug}/notifications")
+async def get_notifications(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+):
+    """Return notification preferences."""
+    return {
+        "weekly_digest": current_user.notify_weekly_digest,
+        "token_alerts": current_user.notify_token_alerts,
+        "new_conversation": current_user.notify_new_conversation,
+        "subscription_expiry": current_user.notify_subscription_expiry,
+    }
+
+
+@router.put("/{author_slug}/notifications")
+async def update_notifications(
+    author_slug: str,
+    body: dict,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Update notification preferences."""
+    mapping = {
+        "weekly_digest": "notify_weekly_digest",
+        "token_alerts": "notify_token_alerts",
+        "new_conversation": "notify_new_conversation",
+        "subscription_expiry": "notify_subscription_expiry",
+    }
+    for key, attr in mapping.items():
+        if key in body:
+            setattr(current_user, attr, bool(body[key]))
+    await db.commit()
+    return {"message": "Notification preferences updated"}
+
+
+@router.get("/{author_slug}/embed-token")
+async def get_embed_token(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Return the active subscription token for embedding the widget."""
+    from datetime import datetime, timezone
+    from sqlalchemy import select
+    from app.models.client_access import ClientAccess
+    from app.core.access.token_crypto import create_subscription_token
+    from app.services.token_budget import tokens_remaining
+
+    now = datetime.now(timezone.utc)
+    now_naive = now.replace(tzinfo=None)
+
+    result = await db.execute(
+        select(ClientAccess)
+        .where(
+            ClientAccess.author_id == current_user.id,
+            ClientAccess.is_revoked == False,
+            ClientAccess.expires_at > now_naive,
+        )
+        .order_by(ClientAccess.expires_at.desc())
+        .limit(1)
+    )
+    access = result.scalar_one_or_none()
+    if not access:
+        return {
+            "active": False,
+            "token": None,
+            "message": "No active subscription. Contact your administrator to activate your chatbot.",
+        }
+
+    token = create_subscription_token(
+        author_id=current_user.id,
+        grant_id=access.id,
+        granted_at=access.granted_at,
+        expires_at=access.expires_at,
+    )
+
+    exp = access.expires_at
+    if exp and exp.tzinfo is not None:
+        exp = exp.replace(tzinfo=None)
+    days_remaining = max(0, (exp - now_naive).days) if exp else 0
+
+    return {
+        "active": True,
+        "token": token,
+        "grant_id": access.id,
+        "plan": access.plan,
+        "expires_at": access.expires_at.isoformat(),
+        "days_remaining": days_remaining,
+        "tokens_remaining": tokens_remaining(access),
+    }
+
+
+@router.get("/{author_slug}/token-usage")
+async def get_token_usage(
+    author_slug: str,
+    current_user=Depends(get_current_author_scoped),
+    db: AsyncSession = Depends(get_db),
+):
+    """Return token budget and consumption for the active subscription."""
+    from app.repositories.access_repo import AccessRepository
+    from app.services.token_budget import usage_summary_or_empty
+
+    access_repo = AccessRepository(db)
+    access = await access_repo.get_active_for_author(current_user.id)
+    return usage_summary_or_empty(access)

app/services/pipeline/__init__.py

@@ -0,0 +1,17 @@
+"""services/pipeline/__init__.py — Public API for the RAG pipeline package.
+
+Callers import from here. The internal module structure is an implementation detail.
+
+Usage:
+    from app.services.pipeline import run_pipeline, PipelineResult, invalidate_book_cache
+"""
+
+from app.services.pipeline.core import run_pipeline
+from app.services.pipeline.handlers import PipelineResult
+from app.services.pipeline.cache import invalidate_book_cache
+
+__all__ = [
+    "run_pipeline",
+    "PipelineResult",
+    "invalidate_book_cache",
+]

app/services/pipeline/cache.py

@@ -0,0 +1,52 @@
+"""pipeline/cache.py — LRU answer cache.
+
+Keyed on MD5(author_id + book_id + normalized query).
+Max 256 slots. Evicts LRU on overflow.
+NOT cached: purchase_intent, complaint, greeting (personal / time-sensitive).
+"""
+from __future__ import annotations
+
+import hashlib
+from collections import OrderedDict
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from app.services.pipeline.core import PipelineResult
+
+_CACHE_MAX = 256
+_answer_cache: OrderedDict = OrderedDict()
+
+
+def cache_key(author_id: str, book_id: str | None, query: str) -> str:
+    """Generate a stable MD5 cache key."""
+    raw = f"{author_id}:{book_id or ''}:{query.lower().strip()}"
+    return hashlib.md5(raw.encode()).hexdigest()
+
+
+def cache_get(key: str) -> PipelineResult | None:
+    """Return cached result or None. Promotes the key to most-recently-used."""
+    if key in _answer_cache:
+        _answer_cache.move_to_end(key)
+        return _answer_cache[key]
+    return None
+
+
+def cache_set(key: str, result: PipelineResult) -> None:
+    """Store a result. Evicts least-recently-used entry when over capacity."""
+    _answer_cache[key] = result
+    _answer_cache.move_to_end(key)
+    if len(_answer_cache) > _CACHE_MAX:
+        _answer_cache.popitem(last=False)
+
+
+def invalidate_book_cache(author_id: str, book_id: str) -> int:  # noqa: ARG001
+    """Remove ALL cached answers for this author when a book changes.
+
+    Called by the ingest pipeline on re-upload to prevent stale answers.
+
+    Returns:
+        Number of cache entries removed.
+    """
+    count = len(_answer_cache)
+    _answer_cache.clear()
+    return count

app/services/pipeline/core.py

@@ -0,0 +1,364 @@
+"""pipeline/core.py — The 12-step RAG pipeline orchestrator.
+
+This is the single entry point for ALL chatbot response generation.
+Every chat message flows through all 12 steps in sequence.
+
+RULE: No step may be skipped.
+RULE: Every step failure must be handled gracefully — never crash the user's session.
+RULE: Token usage is tracked and returned for budget accounting.
+
+Pipeline Steps:
+  1.  Boundary check (query)
+  2.  Intent classification
+  3.  Book resolution (select or show selector)
+  4.  Query rewriting
+  5.  Vector retrieval (ChromaDB)
+  6.  Cross-encoder re-ranking
+  6.5 Chunk deduplication
+  7.  Context assembly (token-aware)
+  8.  LLM generation
+  9.  Faithfulness check (NLI guardrail)
+  10. Response scope check (leak prevention)
+  11. Upsell strategy injection
+  12. Response formatting + link injection
+"""
+
+import time
+
+import structlog
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import get_settings
+from app.models.user import User
+from app.repositories.book_repo import BookRepository
+from app.services.context_builder import build_context
+from app.services.faithfulness import check_faithfulness
+from app.services.formatter import ResponseFormatter
+from app.services.guardrails import (
+    check_boundary,
+    is_response_safe,
+    sanitize_user_input,
+    scrub_unsafe_response,
+)
+from app.services.intent import classify_intent
+from app.services.prompter import (
+    HALLUCINATION_FALLBACK_RESPONSE,
+    JAILBREAK_RESPONSE,
+    NO_CONTEXT_RESPONSE,
+    OFF_TOPIC_RESPONSE,
+    get_response_style_instruction,
+    MASTER_SYSTEM_PROMPT,
+)
+from app.services.reranker import rerank_chunks
+from app.services.rewriter import rewrite_query
+from app.services.session_core.manager import SessionContext
+from app.services.upsell_engine import UpsellEngine
+from app.services.vector_store import retrieve_chunks
+
+from app.services.pipeline.cache import cache_get, cache_key, cache_set
+from app.services.pipeline.dedup import deduplicate_chunks
+from app.services.pipeline.guards import (
+    is_book_selection_turn,
+    is_catalog_question,
+    is_full_story_request,
+    is_greeting,
+)
+from app.services.pipeline.handlers import (
+    PipelineResult,
+    book_selected_response,
+    book_selector_response,
+    books_list_response,
+    boundary_response,
+    catalog_response,
+    full_story_response,
+    greeting_response,
+    no_books_response,
+    no_context_response,
+    piracy_response,
+)
+from app.services.pipeline.helpers import (
+    call_llm,
+    check_custom_qa,
+    find_book,
+    format_history,
+    get_book_links,
+    resolve_book,
+    selected_book_title,
+)
+
+logger = structlog.get_logger(__name__)
+cfg = get_settings()
+
+_upsell_engine = UpsellEngine()
+_formatter = ResponseFormatter()
+
+
+async def run_pipeline(
+    query: str,
+    author: User,
+    session_context: SessionContext,
+    db: AsyncSession,
+) -> PipelineResult:
+    """Execute the full 12-step RAG pipeline for one chat turn.
+
+    Args:
+        query: The user's raw message text.
+        author: The author whose catalog is being queried.
+        session_context: Current session state (history, selected book, interest).
+        db: Active database session.
+
+    Returns:
+        PipelineResult with formatted response and all metadata for logging.
+    """
+    start_ms = time.monotonic()
+    log = logger.bind(author_id=author.id, turn=session_context.turn_count)
+
+    # ── Step 0: Sanitize input ────────────────────────────────────────────────
+    query = sanitize_user_input(query)
+    if not query:
+        return boundary_response(
+            "I didn't catch that — try asking about one of the books!",
+            start_ms,
+            "empty_input",
+        )
+
+    # ── Step 1: Boundary Check ────────────────────────────────────────────────
+    violation_type, _ = check_boundary(query)
+    if violation_type == "jailbreak_attempt":
+        return boundary_response(
+            JAILBREAK_RESPONSE.format(
+                bot_name=author.bot_name,
+                author_name=author.full_name or "the author",
+            ),
+            start_ms,
+            "jailbreak_attempt",
+        )
+    if violation_type == "piracy_request":
+        return await piracy_response(author, session_context, db, start_ms)
+    if violation_type == "off_topic":
+        return boundary_response(
+            OFF_TOPIC_RESPONSE.format(author_name=author.full_name or "the author"),
+            start_ms,
+            "off_topic",
+        )
+
+    # ── Step 1.5: Custom Q&A short-circuit ───────────────────────────────────
+    qa_match = await check_custom_qa(query, author.id, db)
+    if qa_match:
+        elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+        return PipelineResult(
+            response={"text": qa_match["answer"], "links": [], "has_links": False},
+            intent="custom_qa",
+            intent_confidence=qa_match["score"],
+            response_ms=elapsed_ms,
+            hallucination_detected=False,
+        )
+
+    # ── Step 2: Intent Classification ─────────────────────────────────────────
+    intent_result = await classify_intent(query, session_context.history)
+    log.debug("Intent classified", intent=intent_result.intent, source=intent_result.source)
+
+    if intent_result.intent == "jailbreak_attempt":
+        return boundary_response(
+            JAILBREAK_RESPONSE.format(
+                bot_name=author.bot_name,
+                author_name=author.full_name or "the author",
+            ),
+            start_ms,
+            "jailbreak_attempt",
+        )
+
+    # ── Step 3: Book Resolution ───────────────────────────────────────────────
+    book_repo = BookRepository(db)
+    active_books = await book_repo.list_active_for_author(author.id)
+
+    if not active_books:
+        return no_books_response(start_ms)
+
+    # Short-circuit: greetings and catalog questions
+    if intent_result.intent == "greeting" or is_greeting(query):
+        return greeting_response(author, active_books, session_context, start_ms)
+
+    if intent_result.intent in ("meta", "comparison") or is_catalog_question(query):
+        return await catalog_response(author, active_books, session_context, db, start_ms)
+
+    # Book just selected — warm intro
+    if is_book_selection_turn(query, session_context.selected_book_id, active_books):
+        book = find_book(active_books, session_context.selected_book_id)
+        if book:
+            return await book_selected_response(book, author.id, db, start_ms)
+
+    # Full story / spoiler request
+    if intent_result.intent == "full_story_request" or is_full_story_request(query):
+        book = find_book(active_books, session_context.selected_book_id) or active_books[0]
+        return await full_story_response(book, author.id, db, start_ms)
+
+    # Multiple books without selection
+    if len(active_books) > 1 and not session_context.selected_book_id:
+        return books_list_response(
+            "Select a book below to ask about it.",
+            active_books,
+            start_ms,
+            intent="comparison",
+        )
+
+    # Resolve target book for retrieval
+    target_book_id = await resolve_book(intent_result, session_context, active_books, author.id)
+
+    if (
+        target_book_id is None
+        and len(active_books) > 1
+        and intent_result.book_confidence < cfg.RAG_BOOK_CONFIDENCE_THRESHOLD
+        and session_context.selected_book_id is None
+    ):
+        return book_selector_response(active_books, start_ms)
+
+    search_book_id = target_book_id or session_context.selected_book_id
+
+    # ── Cache Lookup (before any API calls) ───────────────────────────────────
+    if intent_result.intent not in ("purchase_intent", "complaint", "greeting"):
+        ck = cache_key(author.id, search_book_id, query)
+        cached = cache_get(ck)
+        if cached is not None:
+            log.debug("Cache hit", key=ck[:8])
+            return cached
+
+    # ── Step 4: Query Rewriting ───────────────────────────────────────────────
+    query_variations = await rewrite_query(query, session_context.history)
+
+    # ── Step 5: Vector Retrieval ──────────────────────────────────────────────
+    raw_chunks = await retrieve_chunks(
+        queries=query_variations,
+        author_id=author.id,
+        book_id=search_book_id,
+        top_k=cfg.RAG_RETRIEVAL_TOP_K,
+    )
+
+    if not raw_chunks:
+        log.warning("No chunks retrieved")
+        return await no_context_response(query, author, active_books, session_context, db, start_ms)
+
+    # ── Step 6: Re-ranking ────────────────────────────────────────────────────
+    top_chunks = await rerank_chunks(
+        query=query,
+        chunks=raw_chunks,
+        top_n=cfg.RAG_RERANK_TOP_N,
+        min_score=cfg.RAG_RERANK_MIN_SCORE,
+    )
+
+    if not top_chunks:
+        log.warning("Re-ranker filtered all chunks — using top retrieval results")
+        top_chunks = raw_chunks[: cfg.RAG_RERANK_TOP_N]
+
+    if not top_chunks:
+        return await no_context_response(query, author, active_books, session_context, db, start_ms)
+
+    # ── Step 6.5: Chunk Deduplication ────────────────────────────────────────
+    top_chunks = deduplicate_chunks(top_chunks)
+
+    # ── Step 7: Context Assembly ──────────────────────────────────────────────
+    context_str, context_tokens = build_context(top_chunks)
+
+    # ── Step 8: LLM Generation ───────────────────────────────────────────────
+    history_str = format_history(session_context.history)
+    interest_tags_str = ", ".join(session_context.interest_tags[:10]) or "None detected yet"
+    book_title = selected_book_title(active_books, session_context.selected_book_id)
+
+    style = author.response_style or "balanced"
+    system_prompt = MASTER_SYSTEM_PROMPT.format(
+        bot_name=author.bot_name,
+        author_name=author.full_name or "the author",
+        book_title=book_title,
+        interest_score=f"{session_context.interest_score:.1f}",
+        interest_tags=interest_tags_str,
+        context=context_str,
+        history=history_str,
+        response_style=style,
+        tone_instruction=get_response_style_instruction(style),
+    )
+
+    user_content = query
+    if is_full_story_request(query):
+        user_content = (
+            f"{query}\n\n"
+            "[Reminder: Max 2 sentences. Do NOT summarize the plot. Tease only.]"
+        )
+
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_content},
+    ]
+
+    raw_response, prompt_tokens, completion_tokens = await call_llm(messages)
+
+    # ── Step 9: Faithfulness Check ────────────────────────────────────────────
+    is_faithful, faithfulness_score = await check_faithfulness(raw_response, top_chunks)
+    hallucination_detected = not is_faithful
+
+    if hallucination_detected:
+        log.warning("Hallucination detected", score=faithfulness_score)
+        stricter_messages = messages + [
+            {"role": "assistant", "content": raw_response},
+            {"role": "user", "content": "Reply using ONLY the retrieved context. Max 2 sentences."},
+        ]
+        raw_response, p2, c2 = await call_llm(stricter_messages, temperature=0.3)
+        prompt_tokens += p2
+        completion_tokens += c2
+
+        is_faithful2, faithfulness_score = await check_faithfulness(raw_response, top_chunks)
+        if not is_faithful2:
+            raw_response = HALLUCINATION_FALLBACK_RESPONSE.format(book_title=book_title)
+
+    # ── Step 10: Output Safety Check ──────────────────────────────────────────
+    safe_fallback = NO_CONTEXT_RESPONSE.format(book_title=book_title)
+    raw_response = scrub_unsafe_response(raw_response, safe_fallback)
+
+    if not is_response_safe(raw_response)[0]:
+        raw_response = JAILBREAK_RESPONSE.format(
+            bot_name=author.bot_name,
+            author_name=author.full_name or "the author",
+        )
+
+    # ── Step 11: Upsell Strategy ──────────────────────────────────────────────
+    effective_intent = "full_story_request" if is_full_story_request(query) else intent_result.intent
+    strategy = _upsell_engine.select_strategy(effective_intent, session_context)
+    show_link = _upsell_engine.should_include_link(effective_intent, session_context, strategy)
+
+    top_book_id = search_book_id or (top_chunks[0].book_id if top_chunks else None)
+    purchase_url, preview_url = await get_book_links(top_book_id, author.id, db)
+
+    # ── Step 12: Format Response ──────────────────────────────────────────────
+    # Hook text removed — the buy button IS the CTA. Text ends naturally.
+    formatted = _formatter.format(
+        response_text=raw_response,
+        upsell_hook=None,
+        purchase_url=purchase_url,
+        preview_url=preview_url,
+        show_link=show_link and bool(purchase_url),
+    )
+
+    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+    log.info("Pipeline complete", ms=elapsed_ms, faithfulness=faithfulness_score)
+
+    result = PipelineResult(
+        response=formatted,
+        intent=intent_result.intent,
+        intent_confidence=intent_result.confidence,
+        faithfulness_score=faithfulness_score,
+        hallucination_detected=hallucination_detected,
+        boundary_triggered=False,
+        upsell_strategy=strategy,
+        link_shown=formatted["has_links"],
+        prompt_tokens=prompt_tokens,
+        completion_tokens=completion_tokens,
+        response_ms=elapsed_ms,
+        top_book_ids=list({c.book_id for c in top_chunks}),
+    )
+
+    # Cache for future identical questions
+    if intent_result.intent not in ("purchase_intent", "complaint", "greeting"):
+        ck = cache_key(author.id, search_book_id, query)
+        cache_set(ck, result)
+        log.debug("Answer cached", key=ck[:8])
+
+    return result

app/services/pipeline/dedup.py

@@ -0,0 +1,47 @@
+"""pipeline/dedup.py — Chunk deduplication by word-overlap ratio.
+
+Removes near-duplicate chunks that arise from overlapping sliding-window
+chunking. Prevents the LLM from seeing the same content repeated, which
+wastes context tokens and can cause repetitive answers.
+
+Source: adapted from RAG 1.2 pattern, book-domain tuned.
+"""
+
+
+def deduplicate_chunks(chunks: list, similarity_threshold: float = 0.82) -> list:
+    """Remove near-duplicate chunks based on word overlap ratio.
+
+    Uses a min-overlap Jaccard variant: overlap / min(len_a, len_b).
+    This catches cases where one chunk is a subset of another.
+
+    Args:
+        chunks: List of chunk objects with a .text attribute or dict 'text' key.
+        similarity_threshold: Overlap ratio at or above which a chunk is a duplicate.
+                              0.82 removes near-identical windows while preserving
+                              legitimately similar passages about the same topic.
+
+    Returns:
+        Deduplicated list, preserving original order.
+    """
+    if len(chunks) <= 1:
+        return chunks
+
+    def get_words(chunk) -> set[str]:
+        text = chunk.text if hasattr(chunk, "text") else chunk.get("text", "")
+        return set(text.lower().split())
+
+    unique = [chunks[0]]
+    for candidate in chunks[1:]:
+        cw = get_words(candidate)
+        if not cw:
+            unique.append(candidate)
+            continue
+        is_dup = any(
+            len(cw & get_words(existing)) / min(len(cw), max(len(get_words(existing)), 1))
+            >= similarity_threshold
+            for existing in unique
+        )
+        if not is_dup:
+            unique.append(candidate)
+
+    return unique

app/services/pipeline/guards.py

@@ -0,0 +1,87 @@
+"""pipeline/guards.py — Lightweight query guard detectors.
+
+Pure Python, zero API cost. Used by both the pipeline core and the
+intent classifier. Single source of truth — never duplicated elsewhere.
+"""
+
+
+# ── Full story / Spoiler ──────────────────────────────────────────────────────
+
+_FULL_STORY_PHRASES: tuple[str, ...] = (
+    "complete story", "full story", "whole story", "entire story", "entire book",
+    "whole book", "full plot", "whole plot", "summarize the book", "summary of the book",
+    "tell me everything", "what happens in the book", "what happens in the story",
+    "end of the book", "how does it end", "how does the book end", "full summary",
+    "complete summary", "recap the book", "recap the story",
+)
+
+
+def is_full_story_request(query: str) -> bool:
+    """Return True if the query asks for the complete plot / ending / full summary."""
+    q = query.lower()
+    return any(phrase in q for phrase in _FULL_STORY_PHRASES)
+
+
+# ── Catalog / Book list ───────────────────────────────────────────────────────
+
+_CATALOG_PHRASES: tuple[str, ...] = (
+    "uploaded book", "your books", "what books", "which books", "list book",
+    "books do you", "books you have", "books available", "about the books",
+    "tell me about book", "tell me about your book", "tell me about the books",
+    "what is the book", "what's the book", "in the catalog", "in your catalog",
+    "show me the book", "show me your book",
+)
+
+_CATALOG_EXACT: frozenset[str] = frozenset({
+    "books", "tell me about books", "about books", "the books",
+})
+
+
+def is_catalog_question(query: str) -> bool:
+    """Return True if the query is asking about the author's book catalog."""
+    q = query.lower()
+    if any(phrase in q for phrase in _CATALOG_PHRASES):
+        return True
+    return q in _CATALOG_EXACT
+
+
+# ── Book selection turn ───────────────────────────────────────────────────────
+
+def is_book_selection_turn(
+    query: str,
+    selected_book_id: str | None,
+    books: list,
+) -> bool:
+    """Return True if this turn is the reader selecting a book by name.
+
+    Used to trigger the warm book-intro response instead of Q&A retrieval.
+    """
+    if not selected_book_id:
+        return False
+    book = next((b for b in books if b.id == selected_book_id), None)
+    if not book:
+        return False
+    q = query.lower().strip().strip("\"'")
+    title_lower = book.title.lower()
+    if q == title_lower:
+        return True
+    if q.startswith("tell me about") and title_lower in q:
+        return True
+    return q.startswith("i'm interested in") and title_lower in q
+
+
+# ── Greeting ─────────────────────────────────────────────────────────────────
+# NOTE: Intentionally kept here as the SINGLE source of truth.
+# Import this function anywhere greeting detection is needed.
+# Do NOT redefine _is_greeting in other modules.
+
+_GREETINGS: frozenset[str] = frozenset({
+    "hi", "hello", "hey", "hiya", "howdy", "yo", "sup",
+    "good morning", "good afternoon", "good evening", "good day",
+})
+
+
+def is_greeting(query: str) -> bool:
+    """Return True if the query is a simple greeting with no book content."""
+    q = query.strip().lower().rstrip("!.?")
+    return q in _GREETINGS or (len(q) <= 12 and q.startswith(("hi ", "hey ", "hello ")))

app/services/pipeline/handlers.py

@@ -0,0 +1,280 @@
+"""pipeline/handlers.py — Short-circuit response handlers.
+
+Each function handles a specific case that bypasses full RAG retrieval.
+All functions return a PipelineResult and are responsible for formatting
+their own response using the formatter and upsell engine.
+
+RULE: Handlers never call the LLM. They are fast, deterministic exits.
+"""
+
+import time
+from dataclasses import dataclass, field
+
+import structlog
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.user import User
+from app.repositories.book_repo import BookRepository
+from app.services.formatter import ResponseFormatter
+from app.services.prompter import (
+    BOOK_SELECTED_RESPONSE,
+    CATALOG_RESPONSE,
+    FULL_STORY_RESPONSE,
+    GREETING_RESPONSE,
+    NO_CONTEXT_RESPONSE,
+    PIRACY_RESPONSE,
+)
+from app.services.session_core.manager import SessionContext
+from app.services.upsell_engine import UpsellEngine
+from app.services.pipeline.guards import is_catalog_question
+from app.services.pipeline.helpers import (
+    book_hook,
+    book_selector_items,
+    book_tease,
+    find_book,
+    get_book_links,
+    selected_book_title,
+)
+
+logger = structlog.get_logger(__name__)
+
+_formatter = ResponseFormatter()
+_upsell_engine = UpsellEngine()
+
+
+# ── PipelineResult (defined here, re-exported via __init__) ──────────────────
+
+@dataclass
+class PipelineResult:
+    """Full result from one RAG pipeline execution."""
+    response: dict
+    intent: str = "question"
+    intent_confidence: float = 0.7
+    faithfulness_score: float = 1.0
+    hallucination_detected: bool = False
+    boundary_triggered: bool = False
+    upsell_strategy: str | None = None
+    link_shown: bool = False
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    response_ms: int = 0
+    top_book_ids: list[str] = field(default_factory=list)
+
+
+# ── Shared Formatter Utilities ────────────────────────────────────────────────
+
+async def build_purchase_response(
+    text: str,
+    book_id: str | None,
+    author_id: str,
+    db: AsyncSession,
+    *,
+    force_link: bool = False,
+    upsell_hook: str | None = None,
+) -> dict:
+    """Format a response dict that may include a purchase button."""
+    purchase_url, preview_url = await get_book_links(book_id, author_id, db)
+    show = force_link or bool(purchase_url)
+    return _formatter.format(
+        response_text=text,
+        upsell_hook=upsell_hook,
+        purchase_url=purchase_url,
+        preview_url=preview_url,
+        show_link=show and bool(purchase_url),
+    )
+
+
+def books_list_response(
+    text: str,
+    books: list,
+    start_ms: float,
+    intent: str = "greeting",
+) -> PipelineResult:
+    """Return a PipelineResult that shows the book selector widget."""
+    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+    formatted = _formatter.format_book_selector(book_selector_items(books), intro=text)
+    return PipelineResult(
+        response=formatted,
+        intent=intent,
+        response_ms=elapsed_ms,
+    )
+
+
+def boundary_response(
+    text: str,
+    start_ms: float,
+    violation_type: str,
+) -> PipelineResult:
+    """Return a simple boundary violation response (no links, no retrieval)."""
+    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+    return PipelineResult(
+        response={"text": text, "links": [], "has_links": False},
+        boundary_triggered=True,
+        intent=violation_type,
+        response_ms=elapsed_ms,
+    )
+
+
+# ── Specific Handler Functions ────────────────────────────────────────────────
+
+def no_books_response(start_ms: float) -> PipelineResult:
+    """No books in the catalog yet."""
+    return PipelineResult(
+        response={
+            "text": "The book catalog is being set up. Check back soon!",
+            "links": [],
+            "has_links": False,
+        },
+        response_ms=int((time.monotonic() - start_ms) * 1000),
+    )
+
+
+def book_selector_response(books: list, start_ms: float) -> PipelineResult:
+    """Show the book selector when the user's intent is ambiguous."""
+    return books_list_response(
+        "Which book are you curious about?",
+        books,
+        start_ms,
+        intent="comparison",
+    )
+
+
+def greeting_response(
+    author: User,
+    books: list,
+    session_context: SessionContext,
+    start_ms: float,
+) -> PipelineResult:
+    """Warm greeting — shows book selector or re-engages with selected book."""
+    if session_context.selected_book_id:
+        book = find_book(books, session_context.selected_book_id)
+        title = book.title if book else "your book"
+        text = f"Hello again! Still exploring {title}? Ask me anything — I'm here for it."
+        return PipelineResult(
+            response={"text": text, "links": [], "has_links": False},
+            intent="greeting",
+            response_ms=int((time.monotonic() - start_ms) * 1000),
+        )
+    return books_list_response(GREETING_RESPONSE, books, start_ms, intent="greeting")
+
+
+async def piracy_response(
+    author: User,
+    session_context: SessionContext,
+    db: AsyncSession,
+    start_ms: float,
+) -> PipelineResult:
+    """Anti-piracy handler — shows buy button instead of free download."""
+    book_repo = BookRepository(db)
+    books = await book_repo.list_active_for_author(author.id)
+    book_title = selected_book_title(books, session_context.selected_book_id)
+    book = find_book(books, session_context.selected_book_id) or (books[0] if books else None)
+    text = PIRACY_RESPONSE.format(book_title=book_title)
+    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+
+    if book:
+        formatted = await build_purchase_response(text, book.id, author.id, db, force_link=True)
+        return PipelineResult(
+            response=formatted,
+            boundary_triggered=True,
+            intent="piracy_request",
+            response_ms=elapsed_ms,
+            link_shown=formatted["has_links"],
+        )
+    return boundary_response(text, start_ms, "piracy_request")
+
+
+async def catalog_response(
+    author: User,
+    books: list,
+    session_context: SessionContext,
+    db: AsyncSession,
+    start_ms: float,
+) -> PipelineResult:
+    """Show book list, or re-engage with already-selected book."""
+    if session_context.selected_book_id:
+        book = find_book(books, session_context.selected_book_id)
+        if book:
+            return await book_selected_response(book, author.id, db, start_ms)
+    return books_list_response(CATALOG_RESPONSE, books, start_ms, intent="meta")
+
+
+async def book_selected_response(
+    book,
+    author_id: str,
+    db: AsyncSession,
+    start_ms: float,
+) -> PipelineResult:
+    """Warm intro response when a reader first selects a book."""
+    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+    text = BOOK_SELECTED_RESPONSE.format(book_title=book.title, hook=book_hook(book))
+    formatted = await build_purchase_response(text, book.id, author_id, db)
+    return PipelineResult(
+        response=formatted,
+        intent="question",
+        response_ms=elapsed_ms,
+        link_shown=formatted["has_links"],
+    )
+
+
+async def full_story_response(
+    book,
+    author_id: str,
+    db: AsyncSession,
+    start_ms: float,
+) -> PipelineResult:
+    """Anti-spoiler handler — teases one hook and shows the buy button."""
+    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+    text = FULL_STORY_RESPONSE.format(book_title=book.title, hook=book_tease(book))
+    formatted = await build_purchase_response(
+        text, book.id, author_id, db, force_link=True,
+        upsell_hook=_upsell_engine.build_hook("DIRECT_CTA"),
+    )
+    return PipelineResult(
+        response=formatted,
+        intent="full_story_request",
+        response_ms=elapsed_ms,
+        link_shown=formatted["has_links"],
+    )
+
+
+async def no_context_response(
+    query: str,
+    author: User,
+    books: list,
+    session_context: SessionContext,
+    db: AsyncSession,
+    start_ms: float,
+) -> PipelineResult:
+    """Fallback when retrieval returns no usable chunks."""
+    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+    book_title = selected_book_title(books, session_context.selected_book_id)
+
+    if len(books) == 1:
+        book = books[0]
+        book_is_ready = (
+            book.status in ("ready", "active")
+            or (book.chunk_count and book.chunk_count > 0 and book.chroma_collection_id)
+        )
+        if not book_is_ready:
+            text = (
+                f"{book.title} is still being indexed — give it a minute and ask again. "
+                "I'll be able to answer detailed questions once processing finishes."
+            )
+            return PipelineResult(
+                response={"text": text, "links": [], "has_links": False},
+                intent="question",
+                response_ms=elapsed_ms,
+            )
+
+    if is_catalog_question(query) and not session_context.selected_book_id:
+        return await catalog_response(author, books, session_context, db, start_ms)
+
+    default_robotic = "I want to give you the most accurate answer"
+    fallback = (author.fallback_message or "").strip()
+    text = fallback if (fallback and default_robotic not in fallback) else NO_CONTEXT_RESPONSE.format(book_title=book_title)
+
+    return PipelineResult(
+        response={"text": text, "links": [], "has_links": False},
+        response_ms=elapsed_ms,
+    )

app/services/pipeline/helpers.py

@@ -0,0 +1,249 @@
+"""pipeline/helpers.py — Pure utility functions for the RAG pipeline.
+
+All functions here are stateless. They take explicit arguments and return
+values with no side effects. This makes them independently testable.
+"""
+
+import structlog
+from openai import AsyncOpenAI
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import get_settings
+from app.models.user import User
+from app.repositories.link_repo import LinkRepository
+from app.services.guardrails import sanitize_history_line
+from app.services.intent import IntentResult
+from app.services.session_core.manager import SessionContext
+
+logger = structlog.get_logger(__name__)
+cfg = get_settings()
+
+
+# ── LLM Call ─────────────────────────────────────────────────────────────────
+
+async def call_llm(
+    messages: list[dict],
+    temperature: float | None = None,
+) -> tuple[str, int, int]:
+    """Call OpenAI chat completions and return response + token counts.
+
+    Args:
+        messages: List of message dicts for the API call.
+        temperature: Optional temperature override (defaults to config value).
+
+    Returns:
+        Tuple of (response_text, prompt_tokens, completion_tokens).
+    """
+    client = AsyncOpenAI(api_key=cfg.OPENAI_API_KEY)
+    response = await client.chat.completions.create(
+        model=cfg.OPENAI_CHAT_MODEL,
+        messages=messages,
+        max_tokens=cfg.RAG_MAX_RESPONSE_TOKENS,
+        temperature=temperature if temperature is not None else cfg.RAG_TEMPERATURE,
+    )
+    content = response.choices[0].message.content or ""
+    usage = response.usage
+    return content, usage.prompt_tokens, usage.completion_tokens
+
+
+# ── Book Resolution ───────────────────────────────────────────────────────────
+
+async def resolve_book(
+    intent_result: IntentResult,
+    session_context: SessionContext,
+    active_books: list,
+    author_id: str,
+) -> str | None:
+    """Determine the target book UUID for vector retrieval.
+
+    Args:
+        intent_result: Classified intent with optional book_reference.
+        session_context: Current session state.
+        active_books: All active books for this author.
+        author_id: Author UUID (unused, reserved for future cross-author search).
+
+    Returns:
+        Book UUID to search, or None for cross-book search.
+    """
+    # Query explicitly references a known book title
+    if (
+        intent_result.book_reference
+        and intent_result.book_confidence >= cfg.RAG_BOOK_CONFIDENCE_THRESHOLD
+    ):
+        ref_lower = intent_result.book_reference.lower()
+        for book in active_books:
+            if ref_lower in book.title.lower() or book.title.lower() in ref_lower:
+                return book.id
+
+    # Single-book catalog: always use the only book
+    if len(active_books) == 1:
+        return active_books[0].id
+
+    return None
+
+
+# ── History Formatting ────────────────────────────────────────────────────────
+
+def format_history(history: list[dict]) -> str:
+    """Format conversation history for the system prompt.
+
+    Args:
+        history: List of message dicts with 'role' and 'content' keys.
+
+    Returns:
+        Formatted string suitable for injection into the system prompt.
+    """
+    if not history:
+        return "This is the start of the conversation."
+    lines = []
+    for msg in history[-6:]:
+        role = "Visitor" if msg["role"] == "user" else "You"
+        content = sanitize_history_line(msg.get("content", ""))
+        if content:
+            lines.append(f"{role}: {content}")
+    return "\n".join(lines)
+
+
+# ── Link Fetching ─────────────────────────────────────────────────────────────
+
+async def get_book_links(
+    book_id: str | None,
+    author_id: str,
+    db: AsyncSession,
+) -> tuple[str | None, str | None]:
+    """Fetch purchase and preview URLs for a book.
+
+    Tries the LinkRepository first (normalized), falls back to book.buy_url.
+
+    Args:
+        book_id: UUID of the book to look up.
+        author_id: UUID of the author (used for ownership validation).
+        db: Active async database session.
+
+    Returns:
+        Tuple of (purchase_url | None, preview_url | None).
+    """
+    if not book_id:
+        return None, None
+    try:
+        link_repo = LinkRepository(db)
+        link = await link_repo.get_for_book(book_id, author_id)
+        if link and (link.purchase_url or link.preview_url):
+            return link.purchase_url, link.preview_url
+
+        from app.repositories.book_repo import BookRepository
+        book_repo = BookRepository(db)
+        book = await book_repo.get_by_id(book_id)
+        if book and book.author_id == author_id:
+            return book.buy_url, book.preview_url
+    except Exception:
+        pass
+    return None, None
+
+
+# ── Book List Utilities ───────────────────────────────────────────────────────
+
+def find_book(books: list, book_id: str | None):
+    """Return the book object with the given ID, or None."""
+    if not book_id:
+        return None
+    return next((b for b in books if b.id == book_id), None)
+
+
+def selected_book_title(books: list, selected_book_id: str | None) -> str:
+    """Return the title of the selected book, or a sensible fallback."""
+    book = find_book(books, selected_book_id)
+    if book:
+        return book.title
+    if len(books) == 1:
+        return books[0].title
+    return "the books"
+
+
+def book_selector_items(books: list) -> list[dict]:
+    """Build the list of book selector items for the widget UI."""
+    items = []
+    for book in books:
+        tagline = book.tagline
+        if not tagline and book.status != "ready":
+            tagline = "Getting ready..."
+        items.append({
+            "id": book.id,
+            "title": book.title,
+            "tagline": tagline,
+            "cover_path": book.cover_path,
+        })
+    return items
+
+
+def book_hook(book) -> str:
+    """One-line hook — tagline only, never a plot excerpt."""
+    if book.tagline:
+        return book.tagline.strip()
+    if book.status != "ready":
+        return "Still getting ready — but worth the wait."
+    return "A story you'll want to experience firsthand."
+
+
+def book_tease(book) -> str:
+    """Ultra-short tease for anti-spoiler responses."""
+    if book.tagline:
+        return book.tagline.strip().rstrip(".")
+    return "a journey worth reading for yourself"
+
+
+# ── Custom Q&A Lookup ─────────────────────────────────────────────────────────
+
+async def check_custom_qa(
+    query: str,
+    author_id: str,
+    db: AsyncSession,
+) -> dict | None:
+    """Check custom Q&A pairs for a fuzzy match using Jaccard similarity.
+
+    If a match exceeds the pair's configured threshold, increments match_count
+    and returns the answer.
+
+    Args:
+        query: User's raw query.
+        author_id: Author UUID to scope the search.
+        db: Active database session.
+
+    Returns:
+        Dict with 'answer' and 'score' keys, or None if no match.
+    """
+    from sqlalchemy import select
+    from app.models.custom_qa import CustomQA
+
+    result = await db.execute(
+        select(CustomQA)
+        .where(CustomQA.author_id == author_id, CustomQA.is_active == True)
+        .order_by(CustomQA.priority.desc())
+    )
+    qa_pairs = result.scalars().all()
+    if not qa_pairs:
+        return None
+
+    query_words = set(query.lower().split())
+    best_match = None
+    best_score = 0.0
+
+    for qa in qa_pairs:
+        q_words = set(qa.question.lower().split())
+        if not q_words or not query_words:
+            continue
+        intersection = query_words & q_words
+        union = query_words | q_words
+        jaccard = len(intersection) / len(union) if union else 0
+
+        if jaccard >= qa.match_threshold and jaccard > best_score:
+            best_score = jaccard
+            best_match = qa
+
+    if best_match:
+        best_match.match_count = (best_match.match_count or 0) + 1
+        await db.commit()
+        logger.info("Custom Q&A match", qa_id=best_match.id, score=best_score)
+        return {"answer": best_match.answer, "score": best_score}
+
+    return None

app/services/rag_pipeline.py

@@ -1,908 +1,14 @@
-"""Author RAG Chatbot SaaS — Master RAG Pipeline (12 Steps).
+"""app/services/rag_pipeline.py — Compatibility shim.
 
-This is the single entry point for ALL chatbot response generation.
-Every chat message flows through all 12 steps in sequence.
+This module has been refactored into the services/pipeline/ package.
+This shim re-exports everything so existing imports continue to work
+during the transition period.
 
-RULE: No step may be skipped.
-RULE: Every step failure must be handled gracefully — never crash the user's session.
-RULE: Token usage is tracked and returned for budget accounting.
-
-Pipeline Steps:
-  1.  Boundary check (query)
-  2.  Intent classification
-  3.  Book resolution (select or show selector)
-  4.  Query rewriting
-  5.  Vector retrieval (ChromaDB)
-  6.  Cross-encoder re-ranking
-  7.  Context assembly (token-aware)
-  8.  LLM generation (streaming)
-  9.  Faithfulness check (NLI guardrail)
-  10. Response scope check (leak prevention)
-  11. Upsell strategy injection
-  12. Response formatting + link injection
+DEPRECATED: Import directly from app.services.pipeline instead.
 """
 
-import time
-from dataclasses import dataclass, field
-from typing import AsyncGenerator
-
-import structlog
-from openai import AsyncOpenAI
-from redis.asyncio import Redis
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.config import get_settings
-from app.services.context_builder import build_context
-from app.services.formatter import ResponseFormatter
-from app.services.guardrails import (
-    check_boundary,
-    is_response_safe,
-    sanitize_user_input,
-    sanitize_history_line,
-    scrub_unsafe_response,
-)
-from app.services.faithfulness import check_faithfulness
-from app.services.intent import classify_intent
-from app.services.prompter import (
-    MASTER_SYSTEM_PROMPT,
-    JAILBREAK_RESPONSE, OFF_TOPIC_RESPONSE, PIRACY_RESPONSE,
-    NO_CONTEXT_RESPONSE, HALLUCINATION_FALLBACK_RESPONSE,
-    GREETING_RESPONSE, CATALOG_RESPONSE, BOOK_SELECTED_RESPONSE,
-    FULL_STORY_RESPONSE,
-    get_response_style_instruction,
-)
-from app.services.reranker import rerank_chunks
-from app.services.vector_store import retrieve_chunks
-from app.services.rewriter import rewrite_query
-from app.services.upsell_engine import UpsellEngine
-from app.services.session_core.manager import SessionContext, SessionManager
-from app.models.user import User
-from app.repositories.book_repo import BookRepository
-from app.repositories.link_repo import LinkRepository
-from app.utils.token_counter import count_messages_tokens
-
-logger = structlog.get_logger(__name__)
-cfg = get_settings()
-
-_upsell_engine = UpsellEngine()
-_formatter = ResponseFormatter()
-
-# ── LRU Answer Cache (from RAG 1.2 proven pattern) ───────────────────────────
-# Keyed on MD5 of author_id + book_id + normalized query.
-# Saves repeated identical questions from different readers of the same book.
-# NOT cached: greetings, purchase_intent (links change), complaints.
-import hashlib
-from collections import OrderedDict
-
-_CACHE_MAX = 256
-_answer_cache: OrderedDict = OrderedDict()
-
-
-def _cache_key(author_id: str, book_id: str | None, query: str) -> str:
-    raw = f"{author_id}:{book_id or ''}:{query.lower().strip()}"
-    return hashlib.md5(raw.encode()).hexdigest()
-
-
-def _cache_get(key: str) -> PipelineResult | None:
-    if key in _answer_cache:
-        _answer_cache.move_to_end(key)
-        return _answer_cache[key]
-    return None
-
-
-def _cache_set(key: str, result: PipelineResult) -> None:
-    _answer_cache[key] = result
-    _answer_cache.move_to_end(key)
-    if len(_answer_cache) > _CACHE_MAX:
-        _answer_cache.popitem(last=False)  # Evict LRU
-
-
-def invalidate_book_cache(author_id: str, book_id: str) -> int:
-    """Remove all cached answers for a specific book (call on re-upload)."""
-    prefix = f"{author_id}:{book_id}:"
-    to_delete = [k for k in _answer_cache if k.startswith(hashlib.md5(prefix.encode()).hexdigest()[:8])]
-    # Simpler: clear whole cache for this author when a book changes
-    to_delete = [k for k in list(_answer_cache.keys())]
-    for k in to_delete:
-        del _answer_cache[k]
-    return len(to_delete)
-
-
-# ── Chunk Deduplication (from RAG 1.2 proven pattern) ────────────────────────
-# Removes near-duplicate chunks by word overlap ratio.
-# Prevents LLM from seeing same information repeated across overlapping windows.
-
-def _deduplicate_chunks(chunks: list, similarity_threshold: float = 0.82) -> list:
-    """Remove near-duplicate chunks based on word overlap ratio.
-
-    Args:
-        chunks: List of chunk objects with .text attribute or dict with 'text' key.
-        similarity_threshold: Jaccard-style overlap ratio above which a chunk is a duplicate.
-
-    Returns:
-        Deduplicated list of chunks.
-    """
-    if len(chunks) <= 1:
-        return chunks
-
-    def get_words(chunk) -> set[str]:
-        text = chunk.text if hasattr(chunk, 'text') else chunk.get('text', '')
-        return set(text.lower().split())
-
-    unique = [chunks[0]]
-    for candidate in chunks[1:]:
-        cw = get_words(candidate)
-        is_dup = False
-        for existing in unique:
-            ew = get_words(existing)
-            if not cw or not ew:
-                continue
-            overlap = len(cw & ew) / min(len(cw), len(ew))
-            if overlap >= similarity_threshold:
-                is_dup = True
-                break
-        if not is_dup:
-            unique.append(candidate)
-
-    removed = len(chunks) - len(unique)
-    if removed > 0:
-        logger.debug("Chunk deduplication removed %d near-duplicates", removed)
-    return unique
-
-
-
-@dataclass
-class PipelineResult:
-    """Full result from one RAG pipeline execution."""
-
-    response: dict                         # Formatted response dict
-    intent: str = "question"
-    intent_confidence: float = 0.7
-    faithfulness_score: float = 1.0
-    hallucination_detected: bool = False
-    boundary_triggered: bool = False
-    upsell_strategy: str | None = None
-    link_shown: bool = False
-    prompt_tokens: int = 0
-    completion_tokens: int = 0
-    response_ms: int = 0
-    top_book_ids: list[str] = field(default_factory=list)
-
-
-async def _check_custom_qa(
-    query: str,
-    author_id: str,
-    db: AsyncSession,
-) -> dict | None:
-    """Check custom Q&A pairs for a fuzzy match. Returns dict or None.
-
-    Uses simple word overlap (Jaccard similarity) for fast matching.
-    If a match exceeds the pair's threshold, increments match_count and returns.
-    """
-    from sqlalchemy import select
-    from app.models.custom_qa import CustomQA
-
-    result = await db.execute(
-        select(CustomQA)
-        .where(CustomQA.author_id == author_id, CustomQA.is_active == True)
-        .order_by(CustomQA.priority.desc())
-    )
-    qa_pairs = result.scalars().all()
-    if not qa_pairs:
-        return None
-
-    query_words = set(query.lower().split())
-    best_match = None
-    best_score = 0.0
-
-    for qa in qa_pairs:
-        q_words = set(qa.question.lower().split())
-        if not q_words or not query_words:
-            continue
-        intersection = query_words & q_words
-        union = query_words | q_words
-        jaccard = len(intersection) / len(union) if union else 0
-
-        if jaccard >= qa.match_threshold and jaccard > best_score:
-            best_score = jaccard
-            best_match = qa
-
-    if best_match:
-        # Increment match count
-        best_match.match_count = (best_match.match_count or 0) + 1
-        await db.commit()
-        logger.info("Custom Q&A match", qa_id=best_match.id, score=best_score)
-        return {"answer": best_match.answer, "score": best_score}
-
-    return None
-
-
-async def run_pipeline(
-    query: str,
-    author: User,
-    session_context: SessionContext,
-    db: AsyncSession,
-) -> PipelineResult:
-    """Execute the full 12-step RAG pipeline for one chat turn.
-
-    Args:
-        query: The user's raw message text.
-        author: The author whose catalog is being queried.
-        session_context: Current session state (history, selected book, interest).
-        db: Active database session.
-
-    Returns:
-        PipelineResult with formatted response and all metadata for logging.
-    """
-    start_ms = time.monotonic()
-    log = logger.bind(author_id=author.id, turn=session_context.turn_count)
-
-    # ── Step 0: Sanitize input ───────────────────────────────────────────────
-    query = sanitize_user_input(query)
-    if not query:
-        return _boundary_response(
-            "I didn't catch that — try asking about one of the books!",
-            start_ms,
-            "empty_input",
-        )
-
-    # ── Step 1: Boundary Check ─────────────────────────────────────────────────
-    violation_type, _ = check_boundary(query)
-    if violation_type == "jailbreak_attempt":
-        return _boundary_response(
-            JAILBREAK_RESPONSE.format(
-                bot_name=author.bot_name,
-                author_name=author.full_name or "the author",
-            ),
-            start_ms,
-            "jailbreak_attempt",
-        )
-    if violation_type == "piracy_request":
-        return await _piracy_response(author, session_context, db, start_ms)
-    if violation_type == "off_topic":
-        return _boundary_response(
-            OFF_TOPIC_RESPONSE.format(author_name=author.full_name or "the author"),
-            start_ms,
-            "off_topic",
-        )
-
-    # ── Step 1.5: Custom Q&A Check (short-circuit) ────────────────────────────
-    qa_match = await _check_custom_qa(query, author.id, db)
-    if qa_match:
-        elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-        return PipelineResult(
-            response={"text": qa_match["answer"], "links": [], "has_links": False},
-            intent="custom_qa",
-            intent_confidence=qa_match["score"],
-            response_ms=elapsed_ms,
-            hallucination_detected=False,
-        )
-
-    # ── Step 2: Intent Classification ─────────────────────────────────────────
-    intent_result = await classify_intent(query, session_context.history)
-    log.debug("Intent classified", intent=intent_result.intent)
-
-    if intent_result.intent == "jailbreak_attempt":
-        return _boundary_response(
-            JAILBREAK_RESPONSE.format(
-                bot_name=author.bot_name,
-                author_name=author.full_name or "the author",
-            ),
-            start_ms,
-            "jailbreak_attempt",
-        )
-
-    # ── Step 3: Book Resolution ────────────────────────────────────────────────
-    book_repo = BookRepository(db)
-    active_books = await book_repo.list_active_for_author(author.id)
-
-    if not active_books:
-        return _no_books_response(start_ms)
-
-    # Short-circuit: greetings and catalog questions → show clickable book list
-    if intent_result.intent == "greeting" or _is_greeting(query):
-        return _greeting_response(author, active_books, session_context, start_ms)
-
-    if intent_result.intent in ("meta", "comparison") or _is_catalog_question(query):
-        return await _catalog_response(author, active_books, session_context, db, start_ms)
-
-    # Book just selected — warm intro, then user asks freely
-    if _is_book_selection_turn(query, session_context.selected_book_id, active_books):
-        book = _find_book(active_books, session_context.selected_book_id)
-        if book:
-            return await _book_selected_response(book, author.id, db, start_ms)
-
-    # Full story / spoiler requests — never dump the plot
-    if intent_result.intent == "full_story_request" or _is_full_story_request(query):
-        book = _find_book(active_books, session_context.selected_book_id) or active_books[0]
-        return await _full_story_response(book, author.id, db, start_ms)
-
-    # Multiple books: require a selection before Q&A
-    if len(active_books) > 1 and not session_context.selected_book_id:
-        return _books_list_response(
-            "Select a book below to ask about it.",
-            active_books,
-            start_ms,
-            intent="comparison",
-        )
-
-    # Resolve which book to search
-    target_book_id = await _resolve_book(
-        intent_result, session_context, active_books, author.id
-    )
-
-    # If book confidence is too low and multiple books exist → show selector
-    if (
-        target_book_id is None
-        and len(active_books) > 1
-        and intent_result.book_confidence < cfg.RAG_BOOK_CONFIDENCE_THRESHOLD
-        and session_context.selected_book_id is None
-    ):
-        return _book_selector_response(active_books, start_ms)
-
-    # Use all books if still no specific book resolved
-    search_book_id = target_book_id or session_context.selected_book_id
-
-    # ── Step 4: Query Rewriting ────────────────────────────────────────────────
-    query_variations = await rewrite_query(query, session_context.history)
-
-    # ── Step 5: Vector Retrieval ───────────────────────────────────────────────
-    raw_chunks = await retrieve_chunks(
-        queries=query_variations,
-        author_id=author.id,
-        book_id=search_book_id,
-        top_k=cfg.RAG_RETRIEVAL_TOP_K,
-    )
-
-    if not raw_chunks:
-        log.warning("No chunks retrieved")
-        return await _no_context_response(query, author, active_books, session_context, db, start_ms)
-
-    # ── Step 6: Re-ranking ────────────────────────────────────────────────────
-    top_chunks = await rerank_chunks(
-        query=query,
-        chunks=raw_chunks,
-        top_n=cfg.RAG_RERANK_TOP_N,
-        min_score=cfg.RAG_RERANK_MIN_SCORE,
-    )
-
-    if not top_chunks:
-        log.warning("Re-ranker filtered all chunks — using top retrieval results")
-        top_chunks = raw_chunks[: cfg.RAG_RERANK_TOP_N]
-
-    if not top_chunks:
-        return await _no_context_response(query, author, active_books, session_context, db, start_ms)
-
-    # ── Step 6.5: Deduplicate near-identical chunks ───────────────────────────
-    top_chunks = _deduplicate_chunks(top_chunks)
-
-    # ── Step 7: Context Assembly ─────────────────────────────────────────────���─
-    context_str, context_tokens = build_context(top_chunks)
-
-    # ── Step 8: LLM Generation ────────────────────────────────────────────────
-    history_str = _format_history(session_context.history)
-    interest_tags_str = ", ".join(session_context.interest_tags[:10]) or "None detected yet"
-    book_title = _selected_book_title(active_books, session_context.selected_book_id)
-
-    style = author.response_style or "balanced"
-    system_prompt = MASTER_SYSTEM_PROMPT.format(
-        bot_name=author.bot_name,
-        author_name=author.full_name or "the author",
-        book_title=book_title,
-        interest_score=f"{session_context.interest_score:.1f}",
-        interest_tags=interest_tags_str,
-        context=context_str,
-        history=history_str,
-        response_style=style,
-        tone_instruction=get_response_style_instruction(style),
-    )
-
-    user_content = query
-    if _is_full_story_request(query):
-        user_content = (
-            f"{query}\n\n"
-            "[Reminder: Max 2 sentences. Do NOT summarize the plot. Tease only.]"
-        )
-
-    messages = [
-        {"role": "system", "content": system_prompt},
-        {"role": "user", "content": user_content},
-    ]
-
-    raw_response, prompt_tokens, completion_tokens = await _call_llm(messages)
-
-    # ── Step 9: Faithfulness Check ────────────────────────────────────────────
-    is_faithful, faithfulness_score = await check_faithfulness(raw_response, top_chunks)
-    hallucination_detected = not is_faithful
-
-    if hallucination_detected:
-        log.warning("Hallucination detected", score=faithfulness_score)
-        # Retry once with stricter instruction
-        stricter_messages = messages + [
-            {"role": "assistant", "content": raw_response},
-            {"role": "user", "content": "Reply using ONLY the retrieved context. Max 2 sentences."},
-        ]
-        raw_response, p2, c2 = await _call_llm(stricter_messages, temperature=0.3)
-        prompt_tokens += p2
-        completion_tokens += c2
-
-        is_faithful2, faithfulness_score = await check_faithfulness(raw_response, top_chunks)
-        if not is_faithful2:
-            book_title = _selected_book_title(active_books, session_context.selected_book_id)
-            raw_response = HALLUCINATION_FALLBACK_RESPONSE.format(book_title=book_title)
-
-    # ── Step 10: Output safety check ──────────────────────────────────────────
-    safe_fallback = NO_CONTEXT_RESPONSE.format(
-        book_title=_selected_book_title(active_books, session_context.selected_book_id)
-    )
-    raw_response = scrub_unsafe_response(raw_response, safe_fallback)
-
-    if not is_response_safe(raw_response)[0]:
-        raw_response = JAILBREAK_RESPONSE.format(
-            bot_name=author.bot_name,
-            author_name=author.full_name or "the author",
-        )
-
-    # ── Step 11: Upsell Strategy ──────────────────────────────────────────────
-    effective_intent = intent_result.intent
-    if _is_full_story_request(query):
-        effective_intent = "full_story_request"
-
-    strategy = _upsell_engine.select_strategy(effective_intent, session_context)
-    show_link = _upsell_engine.should_include_link(effective_intent, session_context, strategy)
-
-    top_book_id = search_book_id or (top_chunks[0].book_id if top_chunks else None)
-    purchase_url, preview_url = await _get_book_links(top_book_id, author.id, db)
-
-    # ── Step 12: Format Response ───────────────────────────────────────────────
-    # Hook text removed from body — the buy button IS the CTA.
-    # Text ends naturally; button appears below without redundant pitch text.
-    formatted = _formatter.format(
-        response_text=raw_response,
-        upsell_hook=None,                          # No hook text in body
-        purchase_url=purchase_url,
-        preview_url=preview_url,
-        show_link=show_link and bool(purchase_url),
-    )
-
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    log.info("Pipeline complete", ms=elapsed_ms, faithfulness=faithfulness_score)
-
-    result = PipelineResult(
-        response=formatted,
-        intent=intent_result.intent,
-        intent_confidence=intent_result.confidence,
-        faithfulness_score=faithfulness_score,
-        hallucination_detected=hallucination_detected,
-        boundary_triggered=False,
-        upsell_strategy=strategy,
-        link_shown=formatted["has_links"],
-        prompt_tokens=prompt_tokens,
-        completion_tokens=completion_tokens,
-        response_ms=elapsed_ms,
-        top_book_ids=list({c.book_id for c in top_chunks}),
-    )
-
-    # Cache non-personal, non-purchase results (identical questions answered instantly)
-    if intent_result.intent not in ("purchase_intent", "complaint", "greeting"):
-        cache_key = _cache_key(
-            author.id,
-            session_context.selected_book_id,
-            query,
-        )
-        _cache_set(cache_key, result)
-        log.debug("Answer cached", key=cache_key[:8])
-
-    return result
-
-
-# ─── Private Helpers ──────────────────────────────────────────────────────────
-
-async def _call_llm(
-    messages: list[dict],
-    temperature: float | None = None,
-) -> tuple[str, int, int]:
-    """Call OpenAI chat completions and return response + token counts.
-
-    Args:
-        messages: List of message dicts for the API call.
-        temperature: Optional temperature override.
-
-    Returns:
-        Tuple of (response_text, prompt_tokens, completion_tokens).
-    """
-    client = AsyncOpenAI(api_key=cfg.OPENAI_API_KEY)
-    response = await client.chat.completions.create(
-        model=cfg.OPENAI_CHAT_MODEL,
-        messages=messages,
-        max_tokens=cfg.RAG_MAX_RESPONSE_TOKENS,
-        temperature=temperature or cfg.RAG_TEMPERATURE,
-    )
-    content = response.choices[0].message.content or ""
-    usage = response.usage
-    return content, usage.prompt_tokens, usage.completion_tokens
-
-
-async def _resolve_book(
-    intent_result,
-    session_context: SessionContext,
-    active_books: list,
-    author_id: str,
-) -> str | None:
-    """Determine the target book for retrieval.
-
-    Args:
-        intent_result: Classified intent with book reference.
-        session_context: Current session state.
-        active_books: All active books for this author.
-        author_id: UUID of the author.
-
-    Returns:
-        Book UUID to search, or None for cross-book search.
-    """
-    # If query explicitly references a book by name, use that
-    if intent_result.book_reference and intent_result.book_confidence >= cfg.RAG_BOOK_CONFIDENCE_THRESHOLD:
-        ref_lower = intent_result.book_reference.lower()
-        for book in active_books:
-            if ref_lower in book.title.lower() or book.title.lower() in ref_lower:
-                return book.id
-
-    # If only one book, always use it
-    if len(active_books) == 1:
-        return active_books[0].id
-
-    return None
-
-
-def _format_history(history: list[dict]) -> str:
-    """Format conversation history for the system prompt.
-
-    Args:
-        history: List of message dicts.
-
-    Returns:
-        Formatted string.
-    """
-    if not history:
-        return "This is the start of the conversation."
-    lines = []
-    for msg in history[-6:]:
-        role = "Visitor" if msg["role"] == "user" else "You"
-        content = sanitize_history_line(msg.get("content", ""))
-        if content:
-            lines.append(f"{role}: {content}")
-    return "\n".join(lines)
-
-
-async def _get_book_links(
-    book_id: str | None,
-    author_id: str,
-    db: AsyncSession,
-) -> tuple[str | None, str | None]:
-    """Fetch purchase and preview URLs for a book.
-
-    Args:
-        book_id: UUID of the book.
-        author_id: UUID of the author.
-        db: Database session.
-
-    Returns:
-        Tuple of (purchase_url | None, preview_url | None).
-    """
-    if not book_id:
-        return None, None
-    try:
-        link_repo = LinkRepository(db)
-        link = await link_repo.get_for_book(book_id, author_id)
-        if link and (link.purchase_url or link.preview_url):
-            return link.purchase_url, link.preview_url
-
-        from app.repositories.book_repo import BookRepository
-
-        book_repo = BookRepository(db)
-        book = await book_repo.get_by_id(book_id)
-        if book and book.author_id == author_id:
-            return book.buy_url, book.preview_url
-    except Exception:
-        pass
-    return None, None
-
-
-def _boundary_response(text: str, start_ms: float, violation_type: str) -> PipelineResult:
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    return PipelineResult(
-        response={"text": text, "links": [], "has_links": False},
-        boundary_triggered=True,
-        intent=violation_type,
-        response_ms=elapsed_ms,
-    )
-
-
-_CATALOG_PHRASES = (
-    "uploaded book", "your books", "what books", "which books", "list book",
-    "books do you", "books you have", "books available", "about the books",
-    "tell me about book", "tell me about your book", "tell me about the books",
-    "what is the book", "what's the book", "in the catalog", "in your catalog",
-    "show me the book", "show me your book",
-)
-
-
-def _find_book(books: list, book_id: str | None):
-    if not book_id:
-        return None
-    return next((b for b in books if b.id == book_id), None)
-
-
-def _selected_book_title(books: list, selected_book_id: str | None) -> str:
-    book = _find_book(books, selected_book_id)
-    if book:
-        return book.title
-    if len(books) == 1:
-        return books[0].title
-    return "the books"
-
-
-def _book_selector_items(books: list) -> list[dict]:
-    items = []
-    for book in books:
-        tagline = book.tagline
-        if not tagline and book.status != "ready":
-            tagline = "Getting ready..."
-        items.append({
-            "id": book.id,
-            "title": book.title,
-            "tagline": tagline,
-            "cover_path": book.cover_path,
-        })
-    return items
-
-
-def _books_list_response(
-    text: str,
-    books: list,
-    start_ms: float,
-    intent: str = "greeting",
-) -> PipelineResult:
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    formatted = _formatter.format_book_selector(_book_selector_items(books), intro=text)
-    return PipelineResult(
-        response=formatted,
-        intent=intent,
-        response_ms=elapsed_ms,
-    )
-
-
-def _book_hook(book) -> str:
-    """One-line hook — tagline only, never a plot excerpt."""
-    if book.tagline:
-        return book.tagline.strip()
-    if book.status != "ready":
-        return "Still getting ready — but worth the wait."
-    return "A story you'll want to experience firsthand."
-
-
-def _book_tease(book) -> str:
-    """Ultra-short tease for anti-spoiler responses."""
-    if book.tagline:
-        return book.tagline.strip().rstrip(".")
-    return "a journey worth reading for yourself"
-
-
-_FULL_STORY_PHRASES = (
-    "complete story", "full story", "whole story", "entire story", "entire book",
-    "whole book", "full plot", "whole plot", "summarize the book", "summary of the book",
-    "tell me everything", "what happens in the book", "what happens in the story",
-    "end of the book", "how does it end", "how does the book end", "full summary",
-    "complete summary", "recap the book", "recap the story",
+from app.services.pipeline import (          # noqa: F401
+    run_pipeline,
+    PipelineResult,
+    invalidate_book_cache,
 )
-
-
-def _is_full_story_request(query: str) -> bool:
-    q = query.lower()
-    return any(phrase in q for phrase in _FULL_STORY_PHRASES)
-
-
-async def _build_purchase_response(
-    text: str,
-    book_id: str | None,
-    author_id: str,
-    db: AsyncSession,
-    *,
-    force_link: bool = False,
-    upsell_hook: str | None = None,
-) -> dict:
-    purchase_url, preview_url = await _get_book_links(book_id, author_id, db)
-    show = force_link or bool(purchase_url)
-    return _formatter.format(
-        response_text=text,
-        upsell_hook=upsell_hook,
-        purchase_url=purchase_url,
-        preview_url=preview_url,
-        show_link=show and bool(purchase_url),
-    )
-
-
-async def _full_story_response(book, author_id: str, db: AsyncSession, start_ms: float) -> PipelineResult:
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    text = FULL_STORY_RESPONSE.format(book_title=book.title, hook=_book_tease(book))
-    formatted = await _build_purchase_response(
-        text, book.id, author_id, db, force_link=True,
-        upsell_hook=_upsell_engine.build_hook("DIRECT_CTA"),
-    )
-    return PipelineResult(
-        response=formatted,
-        intent="full_story_request",
-        response_ms=elapsed_ms,
-        link_shown=formatted["has_links"],
-    )
-
-
-def _is_book_selection_turn(query: str, selected_book_id: str | None, books: list) -> bool:
-    if not selected_book_id:
-        return False
-    book = _find_book(books, selected_book_id)
-    if not book:
-        return False
-    q = query.lower().strip().strip("\"'")
-    title_lower = book.title.lower()
-    if q == title_lower:
-        return True
-    if q.startswith("tell me about") and title_lower in q:
-        return True
-    return q.startswith("i'm interested in") and title_lower in q
-
-_GREETINGS = frozenset({
-    "hi", "hello", "hey", "hiya", "howdy", "yo", "sup",
-    "good morning", "good afternoon", "good evening", "good day",
-})
-
-
-def _is_greeting(query: str) -> bool:
-    q = query.strip().lower().rstrip("!.?")
-    return q in _GREETINGS or (len(q) <= 12 and q.startswith(("hi ", "hey ", "hello ")))
-
-
-def _is_catalog_question(query: str) -> bool:
-    q = query.lower()
-    if any(phrase in q for phrase in _CATALOG_PHRASES):
-        return True
-    return q in ("books", "tell me about books", "about books", "the books")
-
-
-def _greeting_response(
-    author: User,
-    books: list,
-    session_context: SessionContext,
-    start_ms: float,
-) -> PipelineResult:
-    if session_context.selected_book_id:
-        book = _find_book(books, session_context.selected_book_id)
-        title = book.title if book else "your book"
-        text = f"Hello again! Still exploring {title}? Ask me anything — I'm here for it."
-        return PipelineResult(
-            response={"text": text, "links": [], "has_links": False},
-            intent="greeting",
-            response_ms=int((time.monotonic() - start_ms) * 1000),
-        )
-
-    text = GREETING_RESPONSE
-    return _books_list_response(text, books, start_ms, intent="greeting")
-
-
-async def _piracy_response(
-    author: User,
-    session_context: SessionContext,
-    db: AsyncSession,
-    start_ms: float,
-) -> PipelineResult:
-    book_repo = BookRepository(db)
-    books = await book_repo.list_active_for_author(author.id)
-    book_title = _selected_book_title(books, session_context.selected_book_id)
-    book = _find_book(books, session_context.selected_book_id) or (books[0] if books else None)
-    text = PIRACY_RESPONSE.format(book_title=book_title)
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    if book:
-        formatted = await _build_purchase_response(text, book.id, author.id, db, force_link=True)
-        return PipelineResult(
-            response=formatted,
-            boundary_triggered=True,
-            intent="piracy_request",
-            response_ms=elapsed_ms,
-            link_shown=formatted["has_links"],
-        )
-    return _boundary_response(text, start_ms, "piracy_request")
-
-
-async def _catalog_response(
-    author: User,
-    books: list,
-    session_context: SessionContext,
-    db: AsyncSession,
-    start_ms: float,
-) -> PipelineResult:
-    if session_context.selected_book_id:
-        book = _find_book(books, session_context.selected_book_id)
-        if book:
-            return await _book_selected_response(book, author.id, db, start_ms)
-
-    text = CATALOG_RESPONSE
-    return _books_list_response(text, books, start_ms, intent="meta")
-
-
-async def _book_selected_response(
-    book,
-    author_id: str,
-    db: AsyncSession,
-    start_ms: float,
-) -> PipelineResult:
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    text = BOOK_SELECTED_RESPONSE.format(book_title=book.title, hook=_book_hook(book))
-    formatted = await _build_purchase_response(text, book.id, author_id, db)
-    return PipelineResult(
-        response=formatted,
-        intent="question",
-        response_ms=elapsed_ms,
-        link_shown=formatted["has_links"],
-    )
-
-
-async def _no_context_response(
-    query: str,
-    author: User,
-    books: list,
-    session_context: SessionContext,
-    db: AsyncSession,
-    start_ms: float,
-) -> PipelineResult:
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    book_title = _selected_book_title(books, session_context.selected_book_id)
-
-    if len(books) == 1:
-        book = books[0]
-        # Book is answerable if embeddings exist in ChromaDB — status field may be stale
-        book_is_ready = (
-            book.status in ("ready", "active")
-            or (book.chunk_count and book.chunk_count > 0 and book.chroma_collection_id)
-        )
-        if not book_is_ready:
-            text = (
-                f"{book.title} is still being indexed — give it a minute and ask again. "
-                "I'll be able to answer detailed questions once processing finishes."
-            )
-            return PipelineResult(
-                response={"text": text, "links": [], "has_links": False},
-                intent="question",
-                response_ms=elapsed_ms,
-            )
-
-    if _is_catalog_question(query) and not session_context.selected_book_id:
-        return await _catalog_response(author, books, session_context, db, start_ms)
-
-    default_robotic = "I want to give you the most accurate answer"
-    fallback = (author.fallback_message or "").strip()
-    if fallback and default_robotic not in fallback:
-        text = fallback
-    else:
-        text = NO_CONTEXT_RESPONSE.format(book_title=book_title)
-
-    return PipelineResult(
-        response={"text": text, "links": [], "has_links": False},
-        response_ms=elapsed_ms,
-    )
-
-
-def _no_books_response(start_ms: float) -> PipelineResult:
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    return PipelineResult(
-        response={"text": "The book catalog is being set up. Check back soon!", "links": [], "has_links": False},
-        response_ms=elapsed_ms,
-    )
-
-
-def _book_selector_response(books: list, start_ms: float) -> PipelineResult:
-    return _books_list_response(
-        "Which book are you curious about?",
-        books,
-        start_ms,
-        intent="comparison",
-    )