Research Agent Optimization

Scope

• •Project root: /home/bender/classwork/Thesis
• •Backend: backend/news_research_agent.py, backend/app/api/routes/research.py, backend/app/services/news_research.py
• •Frontend: frontend/app/search/page.tsx, frontend/lib/api.ts
• •Configuration: backend/app/core/config.py

Problem Statement

1. •Rate Limiting: Gemini API hits 429 quota exceeded errors during research and article analysis
2. •Web Search: DuckDuckGo tool integration has naming issues (not properly initialized)
3. •Unclear Progress: Research streaming shows generic "Still working..." instead of specific tool calls
4. •JSON in Response: Results show raw JSON blocks instead of formatted source cards
5. •Redundant API Calls: Multiple internal search calls without caching/deduplication

Required Outcomes

• •Graceful rate limit handling with exponential backoff and quota monitoring
• •Working web search tool with proper DuckDuckGo initialization
• •Verbose streaming events showing real tool execution (web_search, news_search, internal_news_search)
• •Research results rendered with inline source cards (not JSON blocks)
• •Optimized API calls: batch searches, cache semantic results, reuse internal knowledge base
• •Clear error messages when quota is exceeded

Workflow

1. API Call Optimization

• •Implement request batching in search_internal_news tool
• •Add caching layer for semantic search results (avoid duplicate queries within 5min window)
• •Combine web_search + news_search into single result set
• •Track API call counts per session and warn before quota exhaustion
• •Add exponential backoff retry logic (1s, 2s, 4s, 8s max)

Files:

• •backend/news_research_agent.py - tools and caching
• •backend/app/services/news_research.py - request batching helpers

2. Rate Limit & Quota Handling

• •Add try/catch wrapper around Gemini calls
• •Detect 429 errors and return user-friendly message ("API Rate Limit: ...please wait a moment...")
• •Add optional --skip-gemini-analysis mode for article analysis when quota is low
• •Log quota usage and remaining tokens
• •Set model to gemini-2.0-flash (faster, lower token cost) instead of gemini-2.0-flash-exp

Files:

• •backend/app/core/config.py - error handling wrapper, model selection
• •backend/app/api/routes/research.py - HTTP error responses
• •backend/news_research_agent.py - LLM call error handling

3. Web Search Tool Fix

• •Verify DuckDuckGo import: from duckduckgo_search import DDGS (not ddgs or DuckDuckGo)
• •Ensure web_search and news_search tools are properly bound to LLM
• •Add fallback to internal search if web search fails
• •Log tool execution with query and result count

Files:

• •backend/news_research_agent.py - tool definitions and error handling
• •Use exa-code to verify current DuckDuckGo API patterns

4. Streaming Progress Clarity

• •Expand SSE event types: tool_start includes tool name + query parameters
• •Map tool events to user-friendly messages:
  • •web_search("climate change") → "Searching web for: climate change..."
  • •news_search(keywords="COP30") → "Searching news for: COP30..."
  • •search_internal_news(query) → "Searching internal knowledge base..."
  • •fetch_article_content(url) → "Reading article: [title/domain]..."
• •Add timestamps and tool execution duration
• •Emit status updates every 3-5 seconds if no tool activity

Files:

• •backend/news_research_agent.py - streaming generator
• •backend/app/api/routes/research.py - SSE formatting

5. Frontend Result Rendering

• •Remove JSON blocks from response text
• •Render referenced articles in a "Sources" section below the answer
• •Use article cards: title, source, date, image thumbnail
• •Make cards clickable to open article detail modal
• •Group sources by retrieval method (semantic, web search, internal)

Files:

• •frontend/app/search/page.tsx - message rendering and sources grid
• •frontend/lib/api.ts - response parsing

6. Error Handling & User Feedback

• •Detect and handle:
  • •429 quota exceeded → "API Rate Limit: The AI service has reached its rate limit. Please wait a moment and try again."
  • •Connection timeout → "Request Timeout: The research took too long. Try a simpler query."
  • •Tool execution failure → "Tool [name] failed: [reason]. Continuing with alternative search..."
• •Add retry prompt on error (not automatic, user chooses)
• •Log all errors with request ID for debugging

Files:

• •backend/app/api/routes/research.py - error formatting
• •frontend/app/search/page.tsx - error UI and retry logic

Checks

API Optimization

• •Verify semantic search results are cached (no duplicate calls)
• •Check web_search and news_search return results (not empty)
• •Confirm tool execution logs show cache hits for repeated queries

Rate Limit Handling

• •Trigger 429 error and verify graceful fallback message displays
• •Confirm no stack traces shown to user
• •Check logs show quota status and retry timing

Web Search

• •Query "climate change" and verify web_search returns 5+ results
• •Confirm DuckDuckGo DDGS class is properly instantiated
• •Check news_search returns recent news articles

Streaming Clarity

• •Monitor SSE events for tool_start with query details
• •Verify timestamps increment correctly
• •Confirm "Still working..." message only shows after 30s inactivity

Frontend Rendering

• •Verify research answer is plain text (no JSON)
• •Check "Sources" section appears with article cards
• •Confirm card click opens article detail modal
• •Verify no duplicate sources (de-duplication working)

Error Scenarios

• •Submit invalid query and verify doesn't crash
• •Test with network disconnect and check timeout message
• •Simulate quota exceeded (403) and verify user sees rate limit message

Implementation Checklist

• • Add retry decorator with exponential backoff to Gemini client
• • Implement request cache in search_internal_news with 5min TTL
• • Fix DuckDuckGo tool initialization (verify DDGS import)
• • Update research_stream() to emit granular tool start/result events
• • Map tool events to human-readable status messages in API endpoint
• • Remove JSON block from final answer text
• • Add "Sources" section with article cards to frontend
• • Update error handling for 429 quota exceeded
• • Add streaming status animation to UI
• • Write tests for quota handling and web search integration