tools-only Enhanced Citations: PDF Modal Fix
Version Implemented: 0.229.001
Overview
Fixed the PDF modal in enhanced citations to use server-side rendering instead of the old SAS URL approach that was causing authentication errors.
Problem Description
Original Error
ValueError: Either user_delegation_key or account_key must be provided.
at generate_blob_sas() in route_frontend_chats.py (view_pdf endpoint)
Root Cause
The enhanced citations were still delegating PDF display to the old /view_pdf endpoint in route_frontend_chats.py, which used SAS URL generation requiring storage account keys.
Impact
- PDF citations failed to load with 500 Internal Server Error
- Browser console showed SAS URL authentication errors
- Users experienced degraded citation experience for PDF documents
Solution: Direct PDF Endpoint with Server-Side Rendering
Approach
Created a dedicated /api/enhanced_citations/pdf endpoint that serves PDF content directly through server-side rendering, eliminating the need for SAS URLs.
Implementation Changes
1. Backend: New PDF Endpoint (route_enhanced_citations.py)
@app.route("/api/enhanced_citations/pdf", methods=["GET"])
@login_required
@user_required
@enabled_required("enable_enhanced_citations")
def get_enhanced_citation_pdf():
"""
Serve PDF file content directly for enhanced citations with page extraction
"""
2. PDF Content Processing Function
def serve_enhanced_citation_pdf_content(raw_doc, page_number):
"""
Serve PDF content with page extraction (±1 page logic from original view_pdf)
"""
Key Features:
- ✅ Page extraction logic (shows current page ±1 for context)
- ✅ Temporary file handling for PyMuPDF processing
- ✅ Proper PDF content type headers
- ✅ Custom
X-Sub-PDF-Pageheader for page information - ✅ Memory-efficient processing with automatic cleanup
3. Frontend: Direct PDF Modal Implementation (chat-enhanced-citations.js)
Before:
// Delegated to old implementation with SAS URLs
import('./chat-citations.js').then(module => {
module.showPdfModal(docId, pageNumber, citationId);
});
After:
// Direct server-side rendering approach
const pdfUrl = `/api/enhanced_citations/pdf?doc_id=${encodeURIComponent(docId)}&page=${encodeURIComponent(pageNumber)}`;
pdfFrame.src = pdfUrl;
New Features:
- ✅
createPdfModal()function for Bootstrap modal creation - ✅ Direct iframe embedding of server-rendered PDF
- ✅ Proper loading and error state handling
- ✅ Fallback to text citation on error
- ✅ Responsive modal design (Bootstrap modal-xl)
Technical Benefits
Security
- ✅ No SAS URL exposure or credential requirements
- ✅ Server-side access control through Flask decorators
- ✅ Consistent authentication with existing endpoints
Performance
- ✅ Direct content streaming without temporary URLs
- ✅ Proper caching headers (5-minute cache)
- ✅ Page extraction reduces PDF size for faster loading
- ✅ Memory-efficient temporary file handling
Reliability
- ✅ Uses existing blob storage client connections
- ✅ No dependency on storage account key configuration
- ✅ Robust error handling with graceful fallbacks
- ✅ Automatic cleanup of temporary resources
User Experience
- ✅ Seamless PDF viewing in modal without external redirects
- ✅ Context-aware page display (±1 page for better readability)
- ✅ Loading indicators and error messaging
- ✅ Responsive design for various screen sizes
Page Extraction Logic
The PDF endpoint implements intelligent page extraction:
- Single Page: Shows only the requested page
- With Context: Shows previous page + current + next page when available
- Page Numbering: Updates page numbers within the extracted PDF context
- Range Validation: Handles out-of-range page requests gracefully
# Page extraction logic
start_idx = current_idx
end_idx = current_idx
# Include previous page if exists
if current_idx > 0:
start_idx = current_idx - 1
# Include next page if exists
if current_idx < total_pages - 1:
end_idx = current_idx + 1
Error Handling
Graceful Degradation
- PDF loading errors automatically fall back to text citations
- Proper error messages shown to users via toast notifications
- Server-side errors logged for debugging
Validation
- Document ownership verification
- PDF file type validation
- Page range validation with meaningful error messages
Testing Results
Functional Test Coverage
Enhanced Citations PDF Modal Fix Test
=======================================================
🔍 Testing PDF Modal Server-Side Rendering... ✅
🔍 Testing Version Update... ✅
🔍 Testing Route Enhanced Citations Integrity... ✅
📊 Test Results: 3/3 tests passed
🎉 All tests passed!
Application Startup Verification
Enhanced citation routes found: 4
/api/enhanced_citations/image
/api/enhanced_citations/video
/api/enhanced_citations/audio
/api/enhanced_citations/pdf ← New PDF endpoint
✅ SUCCESS: PDF endpoint is properly registered!
Migration Impact
No Breaking Changes
- ✅ Existing enhanced citation functionality preserved
- ✅ Image, video, and audio citations unaffected
- ✅ Text citation fallback mechanism maintained
- ✅ User authentication and permissions unchanged
Immediate Benefits
- ✅ PDF citations now work without SAS URL errors
- ✅ Better user experience with modal PDF viewing
- ✅ Improved security through server-side rendering
- ✅ Consistent architecture across all citation types
Version Information
- Fixed in Version: 0.228.006
- Related Files:
route_enhanced_citations.py- Added dedicated PDF endpoint and processingchat-enhanced-citations.js- Direct PDF modal implementationtest_enhanced_citations_pdf_modal_fix.py- Functional test validation
Future Enhancements
The server-side PDF rendering enables:
- 🔄 PDF thumbnails and preview generation
- 📊 PDF analytics and usage tracking
- 🔒 Advanced access control and watermarking
- ⚡ PDF caching and optimization
- 🎯 Enhanced search within PDF content
Summary
The PDF modal fix completes the enhanced citations server-side rendering architecture by eliminating the last dependency on SAS URL generation. PDF documents now load seamlessly in modal viewers with intelligent page extraction, providing users with contextual document viewing while maintaining security and performance.