Add suggested questions display

[manavgup]

Priority

🟡 Medium

Description

Show auto-generated questions as clickable chips after upload.

Current State

Backend generates but UI doesn't show

Files to Create

• frontend/src/components/collections/SuggestedQuestions.tsx

Acceptance Criteria

• Display as clickable chips
• Click to populate search
• Show generation progress
• Refresh button
• Category grouping

Effort

3-5 days

Related Issues

#250

[manavgup]

@claude build a detailed plan to address this.

[claude]

Claude finished @manavgup's task —— View job

---

Planning Implementation for Suggested Questions Display

Task List

• Read project guidelines (CLAUDE.md)
• Analyze backend API for suggested questions
• Explore frontend architecture and existing components
• Understand search functionality integration
• Review Carbon Design System usage patterns
• Create detailed implementation plan
• Document component architecture
• Define testing strategy

---

Implementation Plan for Suggested Questions Feature

Overview

Backend already generates suggested questions via QuestionService and stores them in the database. The backend exposes API endpoints at /api/collections/{collection_id}/questions. The frontend needs to display these questions as clickable chips that populate the search interface.

Backend Analysis

Existing API Endpoints:

• GET /api/collections/{collection_id}/questions - Retrieve all questions for a collection
• POST /api/collections/{collection_id}/questions - Create a new question
• DELETE /api/collections/{collection_id}/questions/{question_id} - Delete a specific question
• DELETE /api/collections/{collection_id}/questions - Delete all questions for a collection

Data Model:

interface SuggestedQuestion {
  id: string;
  collection_id: string;
  question: string;
  created_at: string;
  question_metadata?: Record<string, any>;
}

Backend Services:

• QuestionService handles generation with Chain of Thought (CoT) support
• Generates up to 15 questions per collection (configurable via max_questions_per_collection)
• Questions are ranked by relevance and quality
• Supports category grouping via metadata

Frontend Implementation Plan

Phase 1: API Integration (1 day)

File: frontend/src/services/apiClient.ts

Add TypeScript interfaces and API methods:

interface SuggestedQuestion {
  id: string;
  collection_id: string;
  question: string;
  created_at: string;
  question_metadata?: Record<string, any>;
}

// Add to ApiClient class:
async getCollectionQuestions(collectionId: string): Promise<SuggestedQuestion[]>
async deleteQuestion(collectionId: string, questionId: string): Promise<void>
async regenerateQuestions(collectionId: string): Promise<SuggestedQuestion[]>

Phase 2: SuggestedQuestions Component (2 days)

File: frontend/src/components/collections/SuggestedQuestions.tsx

Component Structure:

interface SuggestedQuestionsProps {
  collectionId: string;
  onQuestionClick: (question: string) => void;
  maxVisible?: number;
  showRefreshButton?: boolean;
  enableCategoryGrouping?: boolean;
}

Features to Implement:

1. Display as Clickable Chips

   • Use Heroicons and Tailwind (consistent with existing codebase - Carbon Design System not heavily used)
   • Responsive grid layout (3-4 chips per row on desktop, 2 on tablet, 1 on mobile)
   • Hover effects to indicate interactivity
   • Accessibility: keyboard navigation support

2. Click to Populate Search

   • onQuestionClick callback to parent component
   • Integrate with search interface's query state
   • Optionally auto-submit search on click

3. Show Generation Progress

   • Loading skeleton while fetching questions
   • Spinner for refresh/regeneration operations
   • Empty state when no questions exist
   • Error state with retry option

4. Refresh Button

   • Icon button (circular arrows) to regenerate questions
   • Confirmation modal: "This will delete existing questions and generate new ones"
   • Loading state during regeneration
   • Success/error notifications

5. Category Grouping

   • Parse question_metadata.category field
   • Group questions by category (e.g., "Overview", "Technical", "Analytical")
   • Collapsible sections per category
   • Default categories if metadata not present

UI Design (Tailwind + Heroicons):

• Container: Light gray background (bg-gray-50) with rounded corners (rounded-lg)
• Section header: "Suggested Questions" with count badge
• Chips: Interactive pills with primary color (bg-blue-600 hover:bg-blue-700)
• Refresh button: Ghost button style positioned in header
• Categories: Accordion-style sections with chevron icons

Phase 3: Integration with CollectionDetail (1 day)

File: frontend/src/components/collections/LightweightCollectionDetail.tsx

Changes Needed:

1. Import Component:

   import SuggestedQuestions from './SuggestedQuestions';

2. Add State Management:

   const [suggestedQuestions, setSuggestedQuestions] = useState<SuggestedQuestion[]>([]);
   const [questionsLoading, setQuestionsLoading] = useState(false);

3. Fetch Questions on Load:

   useEffect(() => {
     if (collection?.id) {
       loadSuggestedQuestions(collection.id);
     }
   }, [collection?.id]);
   
   const loadSuggestedQuestions = async (collectionId: string) => {
     setQuestionsLoading(true);
     try {
       const questions = await apiClient.getCollectionQuestions(collectionId);
       setSuggestedQuestions(questions);
     } catch (error) {
       console.error('Error loading questions:', error);
       addNotification('error', 'Failed to load suggested questions');
     } finally {
       setQuestionsLoading(false);
     }
   };

4. Add Component to UI:

   • Position: Below collection metadata, above documents list
   • Pass navigation handler to populate search on question click

5. Handle Question Click:

   const handleQuestionClick = (question: string) => {
     navigate(`/search`, { 
       state: { 
         collectionId: collection.id,
         collectionName: collection.name,
         initialQuery: question
       }
     });
   };

Phase 4: Integration with Search Interface (0.5 days)

File: frontend/src/components/search/LightweightSearchInterface.tsx

Changes Needed:

1. Handle Initial Query from Navigation:

   useEffect(() => {
     if (location.state?.initialQuery) {
       setQuery(location.state.initialQuery);
       // Optionally auto-submit search
       if (location.state.autoSubmit) {
         handleSearch(location.state.initialQuery);
       }
     }
   }, [location.state]);

2. Optional: Display Questions in Search Sidebar

   • Add <SuggestedQuestions> component to search interface
   • Allow users to refine searches with related questions
   • Update questions based on current search context

Phase 5: Testing (1 day)

Unit Tests:

• SuggestedQuestions.test.tsx:
  • Renders questions correctly
  • Handles click events
  • Shows loading states
  • Handles empty/error states
  • Category grouping logic

Integration Tests:

• Test API integration with mock backend
• Test navigation flow: collection → question click → search
• Test refresh/regenerate functionality
• Test error handling and recovery

E2E Tests (optional):

• Full user flow: upload documents → view collection → click suggested question → see search results

Acceptance Criteria Checklist

• Display as clickable chips

  • Questions rendered as interactive chips
  • Responsive layout (mobile, tablet, desktop)
  • Keyboard accessibility

• Click to populate search

  • Clicking question navigates to search interface
  • Question text populates search input
  • Optional auto-submit configurable

• Show generation progress

  • Loading skeleton during initial fetch
  • Spinner during regeneration
  • Empty state with helpful message
  • Error state with retry option

• Refresh button

  • Visible and functional refresh button
  • Confirmation before regeneration
  • Loading state during operation
  • Success/error notifications

• Category grouping

  • Questions grouped by category metadata
  • Collapsible category sections
  • Default grouping when no categories

Technical Decisions

1. Component Library: Continue using Heroicons + Tailwind CSS

   • Consistent with existing codebase patterns
   • Lightweight and performant
   • Easy customization

2. State Management: Local component state with React hooks

   • No need for Redux/Context for this isolated feature
   • Pass data via props and callbacks

3. API Calls: Use existing apiClient service

   • Centralized error handling
   • Consistent with existing patterns

4. Styling: Tailwind CSS utility classes

   • Maintain consistency with existing components
   • Responsive utilities for mobile-first design

5. Error Handling:

   • Graceful degradation when questions unavailable
   • User-friendly error messages via NotificationContext
   • Retry mechanisms for failed operations

File Structure

frontend/src/
├── components/
│   └── collections/
│       ├── SuggestedQuestions.tsx          # New component
│       ├── SuggestedQuestions.test.tsx     # New tests
│       ├── LightweightCollectionDetail.tsx # Modified
│       └── LightweightCollections.tsx      # No changes
├── services/
│   └── apiClient.ts                        # Modified (add question methods)
└── types/
    └── index.ts                            # Optional: shared types

Estimated Timeline

• Day 1: API integration + component scaffold
• Day 2: Core UI implementation (chips, click handlers, loading states)
• Day 3: Refresh functionality + category grouping
• Day 4: Integration with CollectionDetail and Search
• Day 5: Testing, polish, and documentation

Total: 5 days (as estimated in issue)

Dependencies

• No new npm packages required
• Existing dependencies sufficient:
  • React 18
  • Heroicons
  • Tailwind CSS
  • Axios

Potential Challenges & Solutions

1. Challenge: Questions not generated for new collections

   • Solution: Add trigger to generate questions on document upload completion
   • Alternative: Display "Generate Questions" button when none exist

2. Challenge: Stale questions after document updates

   • Solution: Add logic to mark questions as stale, prompt user to refresh
   • Alternative: Auto-regenerate questions after significant document changes

3. Challenge: Large number of questions overwhelming UI

   • Solution: Implement "Show More" expansion with initial limit (6-8 visible)
   • Alternative: Pagination or virtual scrolling for 15+ questions

4. Challenge: Category metadata inconsistent or missing

   • Solution: Implement fallback grouping algorithm (question type detection)
   • Alternative: Simple chronological display without grouping

Related Backend Context

From analyzing the backend code:

• Question Generation: Questions are auto-generated during document processing via QuestionService.suggest_questions()
• Generation Strategy: Uses stratified sampling across documents for better coverage
• Chain of Thought: 40% of questions use CoT reasoning for complex multi-step queries
• Validation: Questions are validated, ranked, and deduplicated before storage
• Limits: Max 15 questions per collection (configurable in settings)
• Repository: QuestionRepository handles all database operations

Next Steps

This plan is ready for review. If approved, I can:

1. Start implementing the component following this plan
2. Adjust any architectural decisions based on feedback
3. Add additional features or modify requirements
4. Create a more detailed mockup/wireframe if needed

Please review and let me know how you'd like to proceed!

---

Branch: claude/issue-291-20251005-1027 | [Job Run](https://github.com/manavgup/rag_modulo/actions/runs/${{ github.run_id }})

[manavgup]

Closing as duplicate of #283. Both issues track the same goal of improving test coverage. All test coverage work is being tracked in #283.

[manavgup]

Duplicate of #283

[manavgup]

Closing as duplicate of #283. Both issues track the same goal of improving test coverage. All test coverage work is being tracked in #283.