kunthawat/ALwrity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

AI Analysis and Content Strategy fixes. Enhanced Strategy Routes refactoring.

Browse Source
This commit is contained in:
ajaysi
2026-01-10 19:32:50 +05:30
parent 0b63ae7fc1
commit 8193cdba67
298 changed files with 45678 additions and 10952 deletions
Download Patch File Download Diff File Expand all files Collapse all files

565
docs/ALwrity Researcher/CODEBASE_ORGANIZATION_AND_SERVICE_REUSABILITY.md Normal file
View File

@@ -0,0 +1,565 @@
# Codebase Organization & Service Reusability Analysis
**Date**: 2025-01-29
**Status**: Comprehensive Codebase Structure Analysis
---
## 📋 Overview
This document provides a comprehensive analysis of:
1. **Codebase Organization**: How features are organized across folders
2. **Service Architecture**: How Exa, Tavily, and Google Search services are structured
3. **Reusability Analysis**: Whether these services are reusable or tightly integrated
---
## 🏗️ Codebase Organization
### High-Level Structure
```
AI-Writer/
├── backend/
│ ├── api/ # API endpoints (FastAPI routers)
│ ├── services/ # Business logic & service layer
│ ├── models/ # Database models & schemas
│ ├── middleware/ # Request/response middleware
│ ├── utils/ # Utility functions
│ └── database/ # Database migrations
│
├── frontend/
│ └── src/
│ ├── components/ # React components
│ ├── services/ # Frontend API clients
│ ├── hooks/ # React hooks
│ └── utils/ # Frontend utilities
│
└── docs/ # Documentation
```
---
## 📁 Feature Organization by Folder
### Backend Services (`backend/services/`)
#### **Research Services** (`backend/services/research/`)
**Purpose**: Core research engine and provider services
```
research/
├── core/ # Core research engine (standalone)
│ ├── research_engine.py # Main orchestrator
│ ├── research_context.py # Unified input schema
│ └── parameter_optimizer.py # AI-driven parameter optimization
│
├── intent/ # Intent-driven research
│ ├── unified_research_analyzer.py # Single AI call for intent+queries+params
│ ├── intent_aware_analyzer.py # Result analysis based on intent
│ └── ...
│
├── trends/ # Google Trends integration
│ └── google_trends_service.py
│
├── exa_service.py # ⭐ Reusable Exa API service
├── tavily_service.py # ⭐ Reusable Tavily API service
├── google_search_service.py # ⭐ Reusable Google Search service
│
├── research_persona_service.py # Persona generation/retrieval
└── research_persona_prompt_builder.py
```
**Key Features**:
- Standalone research engine (`ResearchEngine`)
- Provider services (Exa, Tavily, Google)
- Intent-driven research system
- Research persona system
---
#### **Blog Writer Services** (`backend/services/blog_writer/`)
**Purpose**: Blog content generation
```
blog_writer/
├── core/
│ └── blog_writer_service.py # Main blog generation service
│
├── research/ # Blog-specific research providers
│ ├── research_service.py # Blog research orchestrator
│ ├── exa_provider.py # Blog-specific Exa wrapper
│ ├── tavily_provider.py # Blog-specific Tavily wrapper
│ ├── google_provider.py # Blog-specific Google wrapper
│ └── research_strategies.py # Research strategies per mode
│
├── outline/ # Outline generation
├── content/ # Content generation
└── seo/ # SEO optimization
```
**Key Features**:
- Uses `services.research` services (reusable)
- Has blog-specific wrappers for providers
- Research strategies for different blog modes
---
#### **Other Feature Services**
| Service Folder | Purpose | Research Integration |
|---------------|---------|---------------------|
| `podcast/` | Podcast generation | Can use Research Engine |
| `story_writer/` | Story generation | Can use Research Engine |
| `youtube/` | YouTube content | Can use Research Engine |
| `linkedin/` | LinkedIn content | Uses GoogleSearchService |
| `onboarding/` | User onboarding | Uses ExaService for competitor discovery |
| `content_planning/` | Content planning | Can use Research Engine |
| `scheduler/` | Task scheduling | Can use Research Engine |
---
### Backend API (`backend/api/`)
#### **Research API** (`backend/api/research/`)
**Purpose**: Research endpoints
```
api/research/
├── router.py # Main router
└── handlers/
├── providers.py # Provider status endpoints
├── research.py # Traditional research endpoints
├── intent.py # Intent-driven endpoints
└── projects.py # My Projects endpoints
```
**Endpoints**:
- `POST /api/research/intent/analyze` - Intent analysis
- `POST /api/research/intent/research` - Intent-driven research
- `POST /api/research/execute` - Traditional research
- `GET /api/research/config` - Configuration
---
#### **Other API Modules**
| API Folder | Purpose | Research Integration |
|-----------|---------|---------------------|
| `blog_writer/` | Blog endpoints | Uses blog_writer services |
| `podcast/` | Podcast endpoints | Can use Research Engine |
| `story_writer/` | Story endpoints | Can use Research Engine |
| `onboarding_utils/` | Onboarding utilities | Uses ExaService for competitor discovery |
---
### Frontend Components (`frontend/src/components/`)
#### **Research Components** (`frontend/src/components/Research/`)
**Purpose**: Research UI components
```
Research/
├── ResearchWizard.tsx # Main wizard orchestrator
├── steps/
│ ├── ResearchInput.tsx # Step 1: Input + Intent & Options
│ ├── StepProgress.tsx # Step 2: Progress/polling
│ ├── StepResults.tsx # Step 3: Results display
│ └── components/ # Sub-components
│ ├── IntentConfirmationPanel.tsx
│ ├── IntentResultsDisplay.tsx
│ └── ...
├── hooks/
│ ├── useResearchWizard.ts # Wizard state management
│ ├── useResearchExecution.ts # Research execution
│ └── useIntentResearch.ts # Intent research flow
└── types/
├── research.types.ts # Research types
└── intent.types.ts # Intent types
```
---
## 🔌 Service Architecture: Exa, Tavily, Google Search
### Service Design Pattern
All three services follow a **similar design pattern**:
1. **Standalone Service Classes**: Each service is a self-contained class
2. **Lazy Initialization**: Services check for API keys on initialization
3. **Error Handling**: Graceful degradation when API keys are missing
4. **Standardized Interface**: Similar method signatures across services
---
### 1. ExaService (`backend/services/research/exa_service.py`)
**Design**: ✅ **Reusable Service**
```python
class ExaService:
"""
Service for competitor discovery and analysis using the Exa API.
Uses neural search to find semantically similar websites and content.
"""
def __init__(self):
"""Initialize with API credentials from environment."""
self.api_key = os.getenv("EXA_API_KEY")
self.exa = None
self.enabled = False
self._try_initialize()
async def discover_competitors(...) -> Dict[str, Any]:
"""Discover competitors for a given website."""
async def discover_social_media_accounts(...) -> Dict[str, Any]:
"""Discover social media accounts."""
async def analyze_competitor_content(...) -> Dict[str, Any]:
"""Analyze competitor content."""
```
**Key Features**:
- ✅ **Standalone**: No dependencies on Research Engine
- ✅ **Reusable**: Can be imported by any module
- ✅ **Focused**: Primarily for competitor discovery
- ✅ **Flexible**: Supports various search parameters
**Current Usage**:
1. **Research Engine**: Uses for research queries
2. **Onboarding**: Uses for competitor discovery (Step 3)
3. **Blog Writer**: Uses via blog-specific wrapper (`exa_provider.py`)
---
### 2. TavilyService (`backend/services/research/tavily_service.py`)
**Design**: ✅ **Reusable Service**
```python
class TavilyService:
"""
Service for web search and research using the Tavily API.
Provides AI-powered search with real-time information retrieval.
"""
def __init__(self):
"""Initialize with API credentials from environment."""
self.api_key = os.getenv("TAVILY_API_KEY")
self.base_url = "https://api.tavily.com"
self.enabled = False
self._try_initialize()
async def search(...) -> Dict[str, Any]:
"""Execute a search query using Tavily API."""
async def search_industry_trends(...) -> Dict[str, Any]:
"""Search for current industry trends."""
async def discover_competitors(...) -> Dict[str, Any]:
"""Discover competitors using Tavily search."""
```
**Key Features**:
- ✅ **Standalone**: No dependencies on Research Engine
- ✅ **Reusable**: Can be imported by any module
- ✅ **Flexible**: Supports various search parameters (topic, depth, time_range, etc.)
- ✅ **Real-time**: Optimized for current information
**Current Usage**:
1. **Research Engine**: Uses for research queries
2. **Blog Writer**: Uses via blog-specific wrapper (`tavily_provider.py`)
---
### 3. GoogleSearchService (`backend/services/research/google_search_service.py`)
**Design**: ✅ **Reusable Service**
```python
class GoogleSearchService:
"""
Service for conducting real industry research using Google Custom Search API.
Provides current, relevant industry information for content grounding.
"""
def __init__(self):
"""Initialize with API credentials from environment."""
self.api_key = os.getenv("GOOGLE_SEARCH_API_KEY")
self.search_engine_id = os.getenv("GOOGLE_SEARCH_ENGINE_ID")
self.enabled = False
async def search_industry_trends(...) -> List[Dict[str, Any]]:
"""Search for current industry trends and insights."""
```
**Key Features**:
- ✅ **Standalone**: No dependencies on Research Engine
- ✅ **Reusable**: Can be imported by any module
- ✅ **Focused**: Industry trend research
- ✅ **Credibility Scoring**: Built-in source credibility assessment
**Current Usage**:
1. **Research Engine**: Uses as fallback provider
2. **LinkedIn Service**: Uses for industry research
---
## 🔄 Reusability Analysis
### ✅ **Services ARE Reusable**
All three services (Exa, Tavily, Google Search) are **designed to be reusable**:
#### **Evidence of Reusability**:
1. **Standalone Design**:
- No dependencies on Research Engine
- Self-contained initialization
- Independent error handling
2. **Multiple Usage Points**:
```python
# Used in Research Engine
from services.research.exa_service import ExaService
# Used in Onboarding
from services.research.exa_service import ExaService
# Used in Blog Writer (via wrapper)
from services.research.tavily_service import TavilyService
# Used in LinkedIn Service
from services.research import GoogleSearchService
```
3. **Standardized Interface**:
- Similar method signatures
- Consistent return formats
- Environment-based configuration
4. **Export Structure**:
```python
# backend/services/research/__init__.py
from .google_search_service import GoogleSearchService
from .exa_service import ExaService
from .tavily_service import TavilyService
__all__ = [
"GoogleSearchService",
"ExaService",
"TavilyService",
# ... other exports
]
```
---
### ⚠️ **Integration Patterns**
While services are reusable, they are used in different ways:
#### **1. Direct Usage** (Most Reusable)
```python
# Direct import and use
from services.research.exa_service import ExaService
exa = ExaService()
result = await exa.discover_competitors(user_url)
```
**Used By**:
- Onboarding (competitor discovery)
- Research Engine (research queries)
---
#### **2. Wrapper Pattern** (Blog Writer)
```python
# Blog Writer uses wrappers for blog-specific logic
from services.research.tavily_service import TavilyService
class TavilyResearchProvider:
def __init__(self):
self.tavily = TavilyService() # Reuses service
async def search(self, prompt, topic, ...):
# Blog-specific logic + TavilyService
return await self.tavily.search(...)
```
**Why Wrappers?**:
- Blog-specific research strategies
- Blog-specific result formatting
- Blog-specific error handling
- Maintains compatibility with existing blog writer code
**Location**: `backend/services/blog_writer/research/tavily_provider.py`
---
#### **3. Engine Orchestration** (Research Engine)
```python
# Research Engine orchestrates providers
from services.research.exa_service import ExaService
from services.research.tavily_service import TavilyService
from services.research.google_search_service import GoogleSearchService
class ResearchEngine:
def __init__(self):
self._exa_provider = ExaService()
self._tavily_provider = TavilyService()
self._google_provider = GoogleSearchService()
async def research(self, context: ResearchContext):
# Orchestrates providers based on priority
if self.exa_available:
return await self._exa_provider.search(...)
elif self.tavily_available:
return await self._tavily_provider.search(...)
else:
return await self._google_provider.search_industry_trends(...)
```
**Why Orchestration?**:
- Provider priority management
- Fallback logic
- Unified interface for all tools
- Research persona integration
---
## 📊 Service Reusability Matrix
| Service | Standalone | Reusable | Current Usage | Integration Pattern |
|---------|-----------|----------|---------------|-------------------|
| **ExaService** | ✅ Yes | ✅ Yes | Research Engine, Onboarding, Blog Writer | Direct + Wrapper |
| **TavilyService** | ✅ Yes | ✅ Yes | Research Engine, Blog Writer | Direct + Wrapper |
| **GoogleSearchService** | ✅ Yes | ✅ Yes | Research Engine, LinkedIn Service | Direct |
---
## 🎯 Key Insights
### ✅ **Services Are Reusable**
1. **No Tight Coupling**: Services don't depend on Research Engine
2. **Standardized Interface**: Consistent method signatures
3. **Multiple Usage Points**: Used across different modules
4. **Environment-Based Config**: No hardcoded dependencies
### ⚠️ **Integration Patterns Vary**
1. **Direct Usage**: Simple import and use (most reusable)
2. **Wrapper Pattern**: Blog-specific wrappers (maintains compatibility)
3. **Engine Orchestration**: Research Engine coordinates providers (unified interface)
### 🔄 **Architecture Evolution**
**Current State**:
- Services are reusable ✅
- Research Engine provides unified interface ✅
- Blog Writer uses wrappers for compatibility ✅
**Future Recommendations**:
- Consider migrating Blog Writer to use Research Engine directly
- Standardize on Research Engine for all tools
- Keep services as low-level building blocks
---
## 📝 Usage Examples
### Example 1: Direct Usage (Onboarding)
```python
# backend/api/onboarding_utils/step3_research_service.py
from services.research.exa_service import ExaService
exa_service = ExaService()
result = await exa_service.discover_competitors(
user_url=user_url,
num_results=10,
industry_context=industry
)
```
### Example 2: Wrapper Pattern (Blog Writer)
```python
# backend/services/blog_writer/research/tavily_provider.py
from services.research.tavily_service import TavilyService
class TavilyResearchProvider:
def __init__(self):
self.tavily = TavilyService() # Reuses service
async def search(self, research_prompt, topic, industry, ...):
# Blog-specific query building
query = self._build_blog_query(research_prompt, topic, industry)
# Use TavilyService
result = await self.tavily.search(
query=query,
topic="general",
search_depth="advanced",
max_results=config.max_sources
)
# Blog-specific result formatting
return self._format_blog_results(result)
```
### Example 3: Engine Orchestration (Research Engine)
```python
# backend/services/research/core/research_engine.py
from services.research.exa_service import ExaService
from services.research.tavily_service import TavilyService
class ResearchEngine:
def __init__(self):
self._exa_provider = ExaService()
self._tavily_provider = TavilyService()
async def research(self, context: ResearchContext, user_id: str):
# Get optimized config
config = self.optimizer.optimize(context)
# Execute based on provider priority
if config.provider == ResearchProvider.EXA:
return await self._execute_exa_research(context, config, user_id)
elif config.provider == ResearchProvider.TAVILY:
return await self._execute_tavily_research(context, config, user_id)
else:
return await self._execute_google_research(context, config, user_id)
```
---
## ✅ Conclusion
### **Services ARE Reusable** ✅
- **ExaService**: ✅ Reusable, used in Research Engine, Onboarding, Blog Writer
- **TavilyService**: ✅ Reusable, used in Research Engine, Blog Writer
- **GoogleSearchService**: ✅ Reusable, used in Research Engine, LinkedIn Service
### **Integration Patterns**:
1. **Direct Usage**: Simple import and use (most reusable)
2. **Wrapper Pattern**: Blog-specific wrappers (maintains compatibility)
3. **Engine Orchestration**: Research Engine coordinates providers (unified interface)
### **Architecture Benefits**:
- ✅ **Modularity**: Services are independent building blocks
- ✅ **Reusability**: Can be used by any module
- ✅ **Flexibility**: Different integration patterns for different needs
- ✅ **Maintainability**: Changes to services don't break consumers
---
**Status**: Services are well-designed for reusability with flexible integration patterns 🚀

142
docs/ALwrity Researcher/DRAFT_PERSISTENCE_FIXES.md Normal file
View File

@@ -0,0 +1,142 @@
# Draft Persistence Fixes
## Issues Fixed
### 1. Draft Not Restoring on Page Refresh
**Problem**: When the page refreshed after clicking "Intent & Options", the intent analysis and queries were lost.
**Root Causes**:
- Draft restoration in `useResearchExecution` wasn't properly validating the restored data
- Timing issues between wizard state restoration and execution hook restoration
- Missing error handling for invalid draft data
**Fixes Applied**:
- Enhanced draft restoration with proper type validation
- Added comprehensive logging to track restoration process
- Improved error handling for invalid draft formats
- Ensured `intentAnalysis` is properly restored with all queries
### 2. Drafts Not Saving Immediately
**Problem**: Drafts were debounced (5-second delay), causing loss if page refreshed quickly.
**Root Causes**:
- Database saves were debounced to reduce API calls
- Critical saves (intent analysis completion) weren't prioritized
**Fixes Applied**:
- Removed debounce for critical saves (intent analysis completion)
- Immediate save when user clicks "Intent & Options"
- Immediate save when user confirms intent
- Debounce still applies for non-critical updates
### 3. Drafts Not Visible in Projects
**Problem**: User couldn't see drafts in "My Projects".
**Status Logic**:
- `"draft"` - Only keywords entered, no intent analysis
- `"in_progress"` - Intent analysis completed (after "Intent & Options")
- `"completed"` - Research results available
**Note**: After clicking "Intent & Options", projects are saved with status `"in_progress"`, not `"draft"`. This is correct behavior - they should appear in the projects list.
**To View Projects**:
- Projects are saved to database with status based on completion
- Use `/api/research/projects` endpoint to list projects
- Filter by `status=draft` for drafts, `status=in_progress` for active projects
- Currently, there's no UI component to display research projects (similar to PodcastMaker's ProjectList)
## Changes Made
### Frontend Changes
1. **`frontend/src/utils/researchDraftManager.ts`**:
- Removed debounce for critical saves (intent analysis completion)
- Added logging for save operations
- Immediate database save when intent analysis completes
2. **`frontend/src/components/Research/hooks/useResearchExecution.ts`**:
- Enhanced draft restoration with type validation
- Added comprehensive logging
- Improved error handling for invalid draft data
- Immediate save on intent confirmation
3. **`frontend/src/components/Research/hooks/useResearchWizard.ts`**:
- Enhanced logging for draft restoration
- Better validation of restored draft data
4. **`frontend/src/components/Research/ResearchWizard.tsx`**:
- Added draft restoration check
- Enhanced logging for debugging
5. **`frontend/src/components/Research/steps/components/IntentConfirmationPanel/IntentConfirmationPanel.tsx`**:
- Added validation to prevent execution with zero queries
- Better error handling
### Backend Changes
No backend changes needed - the save endpoint already handles drafts correctly.
## How Draft Persistence Works
### Save Flow
1. **User enters keywords** → Saved to localStorage only
2. **User clicks "Intent & Options"** → Intent analysis completes
- Saved to localStorage immediately
- Saved to database immediately (critical save, no debounce)
- Status: `"in_progress"`
3. **User confirms intent** → Confirmed intent saved
- Saved to localStorage immediately
- Saved to database immediately (critical save)
- Status: `"in_progress"`
4. **Research completes** → Results saved
- Saved to localStorage immediately
- Saved to database immediately
- Status: `"completed"`
### Restore Flow
1. **Page loads** → `useResearchWizard` restores wizard state from draft
2. **Execution hook initializes** → `useResearchExecution` restores intent analysis, confirmed intent, and results
3. **UI renders** → IntentConfirmationPanel shows restored intent analysis with queries
### Storage Keys
- `alwrity_research_draft` - Complete draft data (localStorage)
- `alwrity_research_draft_id` - Project UUID for updates (localStorage)
- `alwrity_last_draft_db_save` - Timestamp for debouncing (localStorage)
## Testing
To verify drafts are working:
1. **Enter keywords and click "Intent & Options"**
- Check browser console for: `[ResearchDraftManager] ✅ Draft saved to database`
- Check localStorage for `alwrity_research_draft`
2. **Refresh the page**
- Check console for: `[useResearchExecution] ✅ Restored intent analysis from draft`
- IntentConfirmationPanel should show with queries
3. **Check projects list**
- Projects with `intent_analysis` have status `"in_progress"`
- Use API endpoint: `GET /api/research/projects?status=in_progress`
## Future Improvements
1. **Add Research Projects List UI**:
- Create `ResearchProjectList` component (similar to `PodcastMaker/ProjectList`)
- Display drafts, in-progress, and completed projects
- Allow users to resume drafts
2. **Auto-save on Field Changes**:
- Save draft when user modifies intent fields
- Debounced saves for non-critical changes
3. **Draft Expiration**:
- Auto-archive old drafts (e.g., 30 days)
- Clear localStorage drafts after successful completion
4. **Better Error Recovery**:
- Retry failed database saves
- Show user notification if draft save fails

212
docs/ALwrity Researcher/EXA_API_OPTIONS_AUDIT.md Normal file
View File

@@ -0,0 +1,212 @@
# Exa API Options Audit
**Date**: 2025-01-29
**Status**: Comparison of Current Implementation vs Exa API Documentation
---
## 📊 Summary
This document compares our current Exa implementation with the official Exa API documentation to identify missing options and configuration gaps.
---
## ✅ Currently Supported Options
### Main Search Parameters
1. ✅ **`type`** - Search type (auto, neural, fast, deep)
- **Frontend**: `exa_search_type` dropdown
- **Backend**: `config.exa_search_type` → `type` parameter
- **Status**: Fully supported
2. ✅ **`category`** - Content category filter
- **Frontend**: `exa_category` dropdown
- **Backend**: `config.exa_category` → `category` parameter
- **Status**: Fully supported
3. ✅ **`numResults`** - Number of results (5-100)
- **Frontend**: `exa_num_results` input (5-25 limit shown, but API supports up to 100)
- **Backend**: Uses `config.max_sources` (capped at 25), should use `config.exa_num_results`
- **Status**: Partially supported (needs to use `exa_num_results` instead of `max_sources`)
4. ✅ **`includeDomains`** - Domain inclusion filter
- **Frontend**: `exa_include_domains` text input
- **Backend**: `config.exa_include_domains` → `include_domains` parameter
- **Status**: Fully supported
5. ✅ **`excludeDomains`** - Domain exclusion filter
- **Frontend**: `exa_exclude_domains` text input
- **Backend**: `config.exa_exclude_domains` → `exclude_domains` parameter
- **Status**: Fully supported
### Contents Parameters (Currently Hardcoded)
6. ⚠️ **`text`** - Full page text retrieval
- **Current**: Hardcoded to `{'max_characters': 1000}`
- **Should be**: Configurable via `exa_text_max_characters` and `exa_text_include_html`
- **Status**: Needs configuration
7. ⚠️ **`highlights`** - Text snippets extraction
- **Current**: Hardcoded to `{'num_sentences': 2, 'highlights_per_url': 3}`
- **Should be**: Configurable via `exa_highlights_num_sentences`, `exa_highlights_per_url`, `exa_highlights_query`
- **Status**: Needs configuration (we have `exa_highlights` boolean but not the detailed config)
8. ⚠️ **`summary`** - Webpage summary
- **Current**: Hardcoded to `{'query': f"Key insights about {topic}"}`
- **Should be**: Configurable via `exa_summary_query` and `exa_summary_schema`
- **Status**: Needs configuration
9. ⚠️ **`context`** - Context string for RAG
- **Current**: Not used (we have `exa_context` boolean in config but not applied)
- **Should be**: Configurable via `exa_context` (boolean) or `exa_context_max_characters` (object)
- **Status**: Partially supported (config exists but not used)
---
## ❌ Missing Options
### Date Filters
10. ❌ **`startPublishedDate`** - Filter by publish date (start)
- **Frontend**: We have `exa_date_filter` but it's not being used
- **Backend**: Not passed to Exa API
- **Status**: Config exists but not implemented
11. ❌ **`endPublishedDate`** - Filter by publish date (end)
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
12. ❌ **`startCrawlDate`** - Filter by crawl date (start)
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
13. ❌ **`endCrawlDate`** - Filter by crawl date (end)
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
### Text Filters
14. ❌ **`includeText`** - Text that must be present in results
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
15. ❌ **`excludeText`** - Text that must not be present in results
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
### Advanced Options
16. ❌ **`userLocation`** - Two-letter ISO country code
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
17. ❌ **`moderation`** - Content moderation filter
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
18. ❌ **`additionalQueries`** - Additional queries for deep search
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing (only works with `type="deep"`)
### Contents Advanced Options
19. ❌ **`livecrawl`** - Live crawling options (never, fallback, preferred, always)
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
20. ❌ **`livecrawlTimeout`** - Timeout for live crawling (ms)
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
21. ❌ **`subpages`** - Number of subpages to crawl
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
22. ❌ **`subpageTarget`** - Term to find specific subpages
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
23. ❌ **`extras`** - Extra parameters (links, imageLinks)
- **Frontend**: Not exposed
- **Backend**: Not implemented
- **Status**: Missing
---
## 🔧 Implementation Gaps
### 1. Date Filter Not Applied
- **Issue**: `exa_date_filter` exists in config but is not passed to Exa API
- **Fix**: Map `exa_date_filter` → `startPublishedDate` in `exa_provider.py`
### 2. Context Not Applied
- **Issue**: `exa_context` boolean exists but is not used
- **Fix**: Apply `context` parameter based on `exa_context` value
### 3. Num Results Uses Wrong Field
- **Issue**: Uses `config.max_sources` instead of `config.exa_num_results`
- **Fix**: Use `config.exa_num_results` if available, fallback to `max_sources`
### 4. Contents Parameters Hardcoded
- **Issue**: `text`, `highlights`, `summary` are hardcoded
- **Fix**: Make them configurable via ResearchConfig
---
## 📋 Recommended Priority
### Priority 1: Fix Existing Config Not Applied
1. ✅ Apply `exa_date_filter` → `startPublishedDate`
2. ✅ Apply `exa_context` → `context`
3. ✅ Use `exa_num_results` instead of `max_sources`
### Priority 2: Make Contents Configurable
4. ✅ Make `text.max_characters` configurable
5. ✅ Make `highlights` configurable (num_sentences, highlights_per_url, query)
6. ✅ Make `summary.query` configurable
### Priority 3: Add Common Date Filters
7. ✅ Add `endPublishedDate` support
8. ✅ Add `startCrawlDate` / `endCrawlDate` support (if needed)
### Priority 4: Add Text Filters (If Needed)
9. ✅ Add `includeText` / `excludeText` support (if needed)
### Priority 5: Advanced Options (Low Priority)
10. ✅ Add `userLocation`, `moderation`, `livecrawl`, `subpages`, `extras` (if needed)
---
## 🎯 Current Status
**Total Exa API Options**: ~23 options
**Currently Supported**: 5 fully, 4 partially
**Missing**: 14 options
**Hardcoded**: 3 options (text, highlights, summary)
**Recommendation**: Focus on Priority 1 and 2 to make existing config work and make contents configurable.
---
## ✅ Recent Fixes (2025-01-29)
### Fixed Critical Issues
1. ✅ **Updated `type` enum**: Removed `deep`, added `keyword` and `fast` to match latest API
2. ✅ **Updated `category` enum**: Removed `movie` and `song`, kept `linkedin profile`
3. ✅ **Applied `exa_date_filter`**: Now maps to `start_published_date` parameter
4. ✅ **Applied `exa_context`**: Now properly passed to Exa API when enabled
5. ✅ **Fixed `exa_num_results`**: Now uses `exa_num_results` instead of `max_sources`, supports up to 100 results
6. ✅ **Updated frontend**: Added `fast` option, updated category list, increased num_results limit to 100
### Updated Files
- `backend/services/research/intent/unified_research_analyzer.py` - Updated AI prompt enum values
- `backend/services/blog_writer/research/exa_provider.py` - Applied date filter, context, and num_results
- `frontend/src/components/Research/steps/utils/constants.ts` - Updated search types and categories
- `frontend/src/components/Research/steps/components/ExaOptions.tsx` - Updated num_results limit and type handling

159
docs/ALwrity Researcher/EXA_INTEGRATION_ENHANCEMENTS.md Normal file
View File

@@ -0,0 +1,159 @@
# Exa Integration Enhancements
**Date**: 2025-01-29
**Status**: Enhanced based on Exa documentation
---
## Overview
Enhanced ALwrity's Exa integration based on comprehensive Exa documentation to provide better search type selection, improved tooltips, and support for advanced features like Deep search.
---
## Key Enhancements
### 1. Enhanced Search Type Tooltips
Updated tooltips to match Exa's official documentation with accurate latency and use case information:
- **Fast**: <500ms - Speed-critical applications, real-time apps, voice agents
- **Auto (Default)**: ~1000ms - Best of all worlds, intelligently combines methods
- **Deep**: ~5000ms - Comprehensive research, agentic workflows, multi-hop queries
- **Neural**: Variable - Semantic similarity, exploratory searches
- **Keyword**: Fastest - Traditional search, exact keyword matching
### 2. Updated AI Prompt
Enhanced the `unified_research_analyzer.py` prompt to better understand:
- **Latency-quality tradeoffs**: When to use Fast vs Auto vs Deep
- **Search type selection guidelines**: Based on use case (SimpleQA, FRAMES, MultiLoKo, etc.)
- **Deep search requirements**: Context=true required, additionalQueries support
- **Livecrawl options**: When to use fallback vs preferred for freshness
### 3. Added Deep Search Support
- Added 'deep' to search type options
- Updated frontend types to support 'deep'
- Enhanced tooltips to explain Deep search capabilities
- Added guidance on when Deep search is appropriate
### 4. Improved Tooltip Content
All Exa options now have comprehensive tooltips that include:
- Clear descriptions
- When to use
- Latency information (for search types)
- Quality characteristics
- Best practices
- AI recommendations (when available)
---
## Search Type Selection Guidelines
Based on Exa documentation, the AI now understands:
### Fast Search (<500ms)
- **Use for**: SimpleQA-style factual QA, real-time applications, voice agents, autocomplete
- **Characteristics**: Streamlined models, good factual accuracy
- **Best for**: Speed-critical applications
### Auto Search (~1000ms) - Default
- **Use for**: General-purpose research, production workloads, versatile queries
- **Characteristics**: Intelligently combines multiple methods, reranker adapts to query
- **Best for**: Most use cases when unsure which method is best
### Deep Search (~5000ms)
- **Use for**: Agentic workflows (FRAMES, MultiLoKo, BrowseComp), complex research, multi-hop queries
- **Characteristics**: Query expansion, rich contextual summaries, comprehensive coverage
- **Requirements**: context=true for detailed summaries
- **Best for**: When comprehensive coverage > speed
### Neural Search
- **Use for**: Exploratory searches, semantic similarity, finding related concepts
- **Characteristics**: Embeddings-based 'next-link prediction', understands meaning
- **Note**: Also incorporated into Fast and Auto search types
### Keyword Search
- **Use for**: Exact keyword matching, specific terms, brands
- **Characteristics**: Traditional search, fastest, max 10 results
- **Best for**: Precise keyword searches
---
## Backend Changes
### Updated AI Prompt (`unified_research_analyzer.py`)
1. **Enhanced search type descriptions** with latency and use case information
2. **Added Deep search guidelines** including:
- When to use Deep search
- Requirements (context=true)
- Additional queries support
3. **Added livecrawl options** with latency impact information
4. **Improved provider selection logic** based on query characteristics
### Schema Updates
Added support for:
- `type: "deep"` in exa_config
- `additionalQueries: []` for Deep search query variations
- `livecrawl: "fallback|never|preferred|always"` for freshness control
---
## Frontend Changes
### Updated Components
1. **ExaOptions.tsx**:
- Added 'deep' to search type options
- Updated tooltip function to show latency and quality info
- Enhanced tooltip content for all search types
2. **constants.ts**:
- Updated `exaSearchTypes` to include 'deep'
- Improved labels with latency information
3. **blogWriterApi.ts**:
- Updated `exa_search_type` type to include 'deep'
4. **exaTooltips.ts**:
- Completely revamped search type tooltips with:
- Accurate latency information
- Quality characteristics
- When to use guidance
- Best practices
---
## User Experience Improvements
1. **Better Education**: Users now understand the latency-quality tradeoffs
2. **Informed Decisions**: Tooltips help users choose the right search type
3. **AI Guidance**: The AI prompt better understands when to use each search type
4. **Comprehensive Coverage**: Support for all Exa search types including Deep
---
## Next Steps (Future Enhancements)
1. **Add UI for additionalQueries**: Allow users to provide query variations for Deep search
2. **Add livecrawl selector**: UI control for livecrawl options
3. **Performance monitoring**: Track actual latency vs expected for each search type
4. **Cost transparency**: Show cost implications of different search types
5. **Auto-optimization**: Suggest search type based on user's latency requirements
---
## References
- [Exa Documentation: How Exa Search Works](https://docs.exa.ai/reference/how-exa-search-works)
- [Exa Documentation: How to Evaluate Exa Search](https://docs.exa.ai/reference/how-to-evaluate-exa-search)
- [Exa API Reference: Search](https://docs.exa.ai/reference/search)
---
**Status**: Enhanced - Better search type selection, improved tooltips, Deep search support

116
docs/ALwrity Researcher/EXA_TAVILY_OPTIONS_DISPLAY_REVIEW.md Normal file
View File

@@ -0,0 +1,116 @@
# Exa & Tavily Options Display Review
**Date**: 2025-01-29
**Status**: Code Review & Fix
---
## 🔍 Code Review: How Many Times Are Options Shown?
### Issue Found: Duplicate Display
After clicking "Intent & Options", Exa and Tavily options were being shown **TWICE**:
1. **`AdvancedProviderOptionsSection`** (Inside `IntentConfirmationPanel`)
- Location: `frontend/src/components/Research/steps/components/IntentConfirmationPanel/AdvancedProviderOptionsSection.tsx`
- Shows: Provider-specific options (Exa OR Tavily based on selected provider)
- Context: AI-optimized settings with justifications
- Visibility: Only when `showAdvancedOptions` is true (toggle button)
2. **`AdvancedOptionsSection`** (Legacy, in `ResearchInput`)
- Location: `frontend/src/components/Research/steps/components/AdvancedOptionsSection.tsx`
- Shows: BOTH Exa AND Tavily options regardless of provider
- Context: Legacy advanced options (no AI justifications)
- Visibility: Always shown when `advanced` prop is true
### Problem
When user clicks "Intent & Options":
- `IntentConfirmationPanel` appears with `AdvancedProviderOptionsSection` (shows Exa if provider is Exa)
- `ResearchInput` also shows `AdvancedOptionsSection` (shows BOTH Exa AND Tavily)
- **Result**: User sees Exa options twice, and Tavily options once (even if not selected)
### Solution
**Removed** the legacy `AdvancedOptionsSection` from `ResearchInput.tsx` because:
- `AdvancedProviderOptionsSection` in `IntentConfirmationPanel` is superior (has AI justifications)
- It's provider-aware (only shows selected provider's options)
- It's contextually placed within the intent confirmation flow
- The legacy component was redundant
---
## ✅ After Fix
### Single Display Location
**`AdvancedProviderOptionsSection`** (Inside `IntentConfirmationPanel`)
- Shows: Only the selected provider's options (Exa OR Tavily)
- Context: AI-optimized settings with justifications
- Visibility: Toggle-able via "Show Advanced Options" button
- User Experience: Clean, focused, provider-specific
### Display Flow
```
User clicks "Intent & Options"
↓
IntentConfirmationPanel appears
↓
User can toggle "Show Advanced Options"
↓
AdvancedProviderOptionsSection shows:
- Provider selector (Exa/Tavily/Google)
- Selected provider's options only
- AI justifications for each option
```
---
## 📊 Summary
**Before Fix:**
- Exa options shown: **2 times** (once in IntentConfirmationPanel, once in ResearchInput)
- Tavily options shown: **2 times** (once in IntentConfirmationPanel, once in ResearchInput)
- Total duplication: **Yes**
**After Fix:**
- Exa options shown: **1 time** (only in IntentConfirmationPanel when Exa is selected)
- Tavily options shown: **1 time** (only in IntentConfirmationPanel when Tavily is selected)
- Total duplication: **No**
---
## 🎯 Additional Improvements
### Detailed Tooltips Added
All Exa options now have comprehensive tooltips that educate users:
1. **Content Category** - Explains each category with examples
2. **Search Algorithm** - Detailed explanation of auto/keyword/neural/fast with when to use
3. **Number of Results** - Recommendations for different result counts (1-10, 11-25, 26-50, 51-100)
4. **Start Date Filter** - When and how to use date filtering
5. **Extract Highlights** - Benefits and use cases
6. **Return Context String** - RAG applications and AI processing benefits
7. **Include Domains** - When to use and format examples
8. **Exclude Domains** - When to use and format examples
Each tooltip includes:
- Clear description
- When to use
- Examples
- Format instructions
- AI recommendation (if available)
---
## ✅ Files Changed
1. **Removed**: `AdvancedOptionsSection` from `ResearchInput.tsx`
2. **Added**: `exaTooltips.ts` - Comprehensive tooltip definitions
3. **Updated**: `ExaOptions.tsx` - All options now have detailed tooltips
---
**Status**: Fixed - No more duplication, comprehensive tooltips added

352
docs/ALwrity Researcher/EXA_TAVILY_OPTIONS_INFERENCE_GUIDE.md Normal file
View File

@@ -0,0 +1,352 @@
# Exa & Tavily Options Inference Guide
**Date**: 2025-01-29
**Status**: Current Implementation Review
---
## Overview
When a user clicks "Intent & Options" button, the system uses AI to infer optimal Exa and Tavily API settings based on the user's research intent. This document explains how these options are generated.
---
## Flow: Intent & Options Button Click
```
User clicks "Intent & Options"
↓
Frontend: intentResearchApi.analyzeIntent()
↓
Backend: /api/research/intent/analyze
↓
UnifiedResearchAnalyzer.analyze()
↓
Single LLM Call with unified_prompt_builder.py
↓
LLM Returns:
- ResearchIntent (with purpose, depth, focus_areas, also_answering, etc.)
- ResearchQueries (4-8 diverse queries)
- exa_config (optimized Exa settings with justifications)
- tavily_config (optimized Tavily settings with justifications)
- recommended_provider
↓
Backend maps to optimized_config
↓
Frontend receives AnalyzeIntentResponse with optimized_config
↓
Frontend applies optimized_config to ResearchConfig
↓
User sees optimized Exa/Tavily options in AdvancedProviderOptionsSection
```
---
## How Options Are Inferred
### 1. Time Sensitivity Rules
**Based on**: `intent.time_sensitivity` field
| Time Sensitivity | Exa Settings | Tavily Settings |
|-----------------|--------------|-----------------|
| **real_time** | `startPublishedDate = current year`, `type = "auto" or "fast"` | `time_range = "day" or "week"`, `topic = "news"` |
| **recent** | `startPublishedDate = current year or last 6 months` | `time_range = "month" or "week"` |
| **historical** | No date filters, `type = "deep" or "neural"` | `time_range = "year" or null`, `topic = "general"` |
| **evergreen** | No date filters, `type = "deep"` | `time_range = null`, `topic = "general"` |
**Example**:
- User input: "Latest AI trends in 2025"
- Time sensitivity inferred: `real_time`
- Exa: `startPublishedDate = "2025-01-01"`, `type = "fast"`
- Tavily: `time_range = "week"`, `topic = "news"`
---
### 2. Content Type Based on Focus Areas
**Based on**: `intent.focus_areas` field
| Focus Area Keywords | Exa Category | Exa Type | Tavily Topic |
|---------------------|-------------|----------|--------------|
| "academic", "research", "studies" | `"research paper"` | `"deep" or "neural"` | `"general"` |
| | `includeDomains = ["arxiv.org", "nature.com", "pubmed.ncbi.nlm.nih.gov"]` | | |
| "companies", "competitors", "business" | `"company"` | `"auto" or "deep"` | `"general"` |
| "news", "trends", "current events" | `"news"` (if using Exa) | `"auto"` | `"news"` |
| | | | `search_depth = "advanced"` |
| "social", "twitter", "social media" | `"tweet"` | `"auto"` | `"general"` |
| "github", "code", "technical" | `"github"` | `"auto" or "deep"` | `"general"` |
**Example**:
- User input: "AI research papers on transformer architectures"
- Focus areas inferred: `["academic", "research"]`
- Exa: `category = "research paper"`, `type = "deep"`, `includeDomains = ["arxiv.org", "nature.com"]`
- Tavily: `topic = "general"`
---
### 3. Depth-Based Settings
**Based on**: `intent.depth` field (overview, detailed, expert)
| Depth Level | Exa Settings | Tavily Settings |
|-------------|--------------|-----------------|
| **expert** | `type = "deep"`, `context = true`, `contextMaxCharacters = 15000+`, `numResults = 20-50` | `search_depth = "advanced"`, `chunks_per_source = 3`, `max_results = 15-20` |
| **detailed** | `type = "auto" or "deep"`, `context = true`, `contextMaxCharacters = 10000+`, `numResults = 10-20` | `search_depth = "advanced" or "basic"`, `chunks_per_source = 3`, `max_results = 10-15` |
| **overview** | `type = "auto" or "fast"`, `numResults = 5-10` | `search_depth = "basic" or "fast"`, `max_results = 5-10` |
**Example**:
- User input: "Comprehensive analysis of quantum computing"
- Depth inferred: `expert`
- Exa: `type = "deep"`, `context = true`, `contextMaxCharacters = 15000`, `numResults = 30`
- Tavily: `search_depth = "advanced"`, `chunks_per_source = 3`, `max_results = 15`
---
### 4. Query-Specific Settings
**Based on**: Primary query characteristics
| Query Type | Exa Settings | Tavily Settings |
|------------|--------------|-----------------|
| **Comprehensive** (addresses multiple secondary questions/focus areas) | `type = "deep"`, `context = true`, `contextMaxCharacters = 15000+` | `search_depth = "advanced"`, `chunks_per_source = 3` |
| **Simple factual** | `type = "fast"`, `numResults = 5-10` | `search_depth = "ultra-fast"`, `max_results = 5` |
| **Time-sensitive** | Apply time filters based on urgency | Apply time_range based on urgency |
| **Content-specific** | Match category to content type | Match topic to content type |
**Example**:
- Primary query: "What are the best practices for React performance optimization?"
- Query type: Comprehensive (needs detailed analysis)
- Exa: `type = "deep"`, `context = true`, `contextMaxCharacters = 12000`
- Tavily: `search_depth = "advanced"`, `chunks_per_source = 3`
---
### 5. Also Answering Topics Considerations
**Based on**: `intent.also_answering` field
**Rules**:
- If also_answering topics need different time ranges:
- Use broader `time_range` in Tavily (e.g., "year" instead of "month")
- Don't apply strict date filters in Exa
- If also_answering topics need different sources:
- Consider including additional domains in `includeDomains`
- Use more comprehensive search (`type = "deep"` in Exa)
**Example**:
- Primary: "Latest AI trends"
- Also answering: ["Historical AI development", "Future predictions"]
- Exa: No strict date filters, `type = "deep"` for comprehensive coverage
- Tavily: `time_range = "year"` to cover historical and recent
---
### 6. Provider Selection Logic
**Based on**: Combined analysis of all intent fields
**Use EXA when**:
- Primary query needs semantic understanding
- Focus areas include "academic", "research", "companies"
- Depth = "expert" or "detailed"
- Need comprehensive context (`context = true`)
- Query targets specific content types (research papers, companies, GitHub)
**Use TAVILY when**:
- Time sensitivity = "real_time" or "recent"
- Focus areas include "news", "trends", "current events"
- Need quick AI-generated answers
- Primary query is about recent developments
- Query needs real-time information
**Example**:
- User input: "Latest news about AI regulation"
- Provider selected: **Tavily** (real-time news focus)
- Tavily: `topic = "news"`, `search_depth = "advanced"`, `time_range = "week"`
---
## Exa Config Options Generated
The AI generates these Exa options with justifications:
### Core Options
- **`type`**: `"auto" | "fast" | "deep" | "neural" | "keyword"`
- Justification references: query complexity, depth, time sensitivity
- **`category`**: `"company" | "research paper" | "news" | "linkedin profile" | "github" | "tweet" | "personal site" | "pdf" | "financial report"`
- Justification references: focus_areas, content type needed
- **`numResults`**: `1-100`
- Justification references: depth, query complexity, secondary questions count
- **`includeDomains`**: Array of domain strings
- Justification references: focus_areas, content type requirements
- **`startPublishedDate`**: Date string (YYYY-MM-DD)
- Justification references: time_sensitivity, query time requirements
### Content Options
- **`highlights`**: `true | false`
- Justification: Whether snippets are needed for quick scanning
- **`context`**: `true | false` (required for `type = "deep"`)
- Justification: Whether full context needed for RAG/AI processing
- **`contextMaxCharacters`**: Number (if context = true)
- Justification: Depth requirements, query complexity
### Advanced Options (if applicable)
- **`additionalQueries`**: Array of query strings (only for `type = "deep"`)
- Justification: Query variations needed for comprehensive coverage
- **`livecrawl`**: `"never" | "fallback" | "preferred" | "always"`
- Justification: Freshness requirements based on time_sensitivity
---
## Tavily Config Options Generated
The AI generates these Tavily options with justifications:
### Core Options
- **`topic`**: `"general" | "news" | "finance"`
- Justification references: focus_areas, content type
- **`search_depth`**: `"basic" | "advanced" | "fast" | "ultra-fast"`
- Justification references: depth, query complexity, speed requirements
- **`include_answer`**: `true | false | "basic" | "advanced"`
- Justification: Whether AI-generated answer is needed
- **`time_range`**: `"day" | "week" | "month" | "year" | null`
- Justification references: time_sensitivity, query time requirements
- **`max_results`**: `0-20`
- Justification references: depth, query complexity
### Advanced Options
- **`chunks_per_source`**: `1-3` (only for `search_depth = "advanced"`)
- Justification: Depth requirements, comprehensive coverage needs
- **`include_raw_content`**: `true | false | "markdown" | "text"`
- Justification: Whether full content needed for analysis
- **`country`**: Country code (only for `topic = "general"`)
- Justification: Geographic relevance based on target_audience
---
## Example: Complete Inference Flow
### User Input
```
Keywords: "AI marketing tools for small businesses"
Purpose: create_content (user-selected)
Content Output: blog_post (user-selected)
Depth: detailed (user-selected)
```
### AI Inference
```
Intent:
- primary_question: "What are the best AI marketing tools for small businesses?"
- secondary_questions: ["What are the pricing models?", "What features do they offer?"]
- focus_areas: ["tools", "small business", "marketing automation"]
- also_answering: ["How to choose the right tool", "Implementation best practices"]
- time_sensitivity: "recent"
- depth: "detailed"
Recommended Provider: EXA (needs comprehensive analysis, not just news)
Exa Config:
- type: "auto"
justification: "Balanced speed and quality for comprehensive tool research"
- category: null (general search)
justification: "Tools can be found across multiple content types"
- numResults: 15
justification: "Detailed depth requires more sources to cover tools, pricing, and features"
- includeDomains: []
justification: "No specific domain restrictions needed"
- startPublishedDate: "2024-01-01"
justification: "Recent time sensitivity requires current year data"
- highlights: true
justification: "Snippets help quickly identify relevant tools"
- context: true
justification: "Detailed depth requires full context for comprehensive analysis"
- contextMaxCharacters: 10000
justification: "Detailed depth needs substantial context per source"
Tavily Config:
- topic: "general"
justification: "General topic covers tools and business content"
- search_depth: "advanced"
justification: "Detailed depth requires comprehensive search"
- include_answer: true
justification: "AI-generated answers provide quick insights"
- time_range: "year"
justification: "Recent time sensitivity with also_answering topics needing broader coverage"
- max_results: 12
justification: "Detailed depth requires multiple sources"
- chunks_per_source: 3
justification: "Detailed depth needs comprehensive content per source"
```
---
## Key Files
### Backend
1. **`backend/services/research/intent/unified_prompt_builder.py`**
- Contains all optimization rules (lines 155-275)
- Defines how intent fields map to Exa/Tavily settings
2. **`backend/services/research/intent/unified_schema_builder.py`**
- Defines JSON schema for exa_config and tavily_config (lines 67-124)
- Specifies all available options and their types
3. **`backend/services/research/intent/unified_result_parser.py`**
- Extracts exa_config and tavily_config from LLM response (lines 205-206)
4. **`backend/api/research/handlers/intent.py`**
- Maps exa_config/tavily_config to optimized_config (lines 124-155)
- Returns optimized_config in AnalyzeIntentResponse
### Frontend
1. **`frontend/src/components/Research/types/intent.types.ts`**
- Defines OptimizedConfig interface (lines 224-280)
- Includes all Exa/Tavily options with justifications
2. **`frontend/src/components/Research/steps/components/IntentConfirmationPanel/AdvancedProviderOptionsSection.tsx`**
- Displays optimized Exa/Tavily options
- Shows AI justifications for each option
3. **`frontend/src/components/Research/steps/ResearchInput.tsx`**
- Applies optimized_config to ResearchConfig (lines 464-512)
---
## Current Implementation Status
### ✅ Fully Implemented
- Time sensitivity → Exa/Tavily date filters
- Focus areas → Exa category / Tavily topic
- Depth → Exa type / Tavily search_depth
- Query characteristics → Provider selection
- Also answering → Broader time ranges
### ⚠️ Partially Implemented
- Some Exa options are inferred but not all are exposed in UI
- Some Tavily options are inferred but not all are exposed in UI
- Advanced options (livecrawl, additionalQueries) are in schema but rarely used
### 📋 Options Available in Schema (May Not All Be Used)
**Exa Options**:
- ✅ type, category, numResults, includeDomains, startPublishedDate, highlights, context
- ⚠️ excludeDomains, contextMaxCharacters, additionalQueries, livecrawl
**Tavily Options**:
- ✅ topic, search_depth, include_answer, time_range, max_results, chunks_per_source
- ⚠️ start_date, end_date, include_raw_content, country, include_images, include_image_descriptions, include_favicon, auto_parameters
---
## References
- `docs/ALwrity Researcher/EXA_INTEGRATION_ENHANCEMENTS.md` - Exa search types and latency
- `docs/ALwrity Researcher/EXA_API_OPTIONS_AUDIT.md` - Complete Exa API options comparison
- `docs/ALwrity Researcher/EXA_TAVILY_OPTIONS_DISPLAY_REVIEW.md` - UI display review
- `docs/ALwrity Researcher/INTENT_DRIVEN_RESEARCH_IMPLEMENTATION_STATUS.md` - Implementation status
---
**Status**: Current implementation infers Exa and Tavily options based on comprehensive intent analysis with detailed justifications.

1146
docs/ALwrity Researcher/INTENT_DRIVEN_RESEARCH_GUIDE.md
View File

File diff suppressed because it is too large Load Diff

244
docs/ALwrity Researcher/INTENT_DRIVEN_RESEARCH_IMPLEMENTATION_STATUS.md Normal file
View File

@@ -0,0 +1,244 @@
# Intent-Driven Research Implementation Status
**Date**: 2025-01-29
**Status**: ✅ Comprehensive Implementation Complete
---
## 📊 Implementation Status Summary
After comprehensive codebase review, **all proposed enhancements are already implemented**. The system has a robust architecture with intent field linking, query deduplication, and generalized analysis.
---
## ✅ Already Implemented Features
### 1. ResearchIntent Model Enhancements ✅
**Location**: `backend/models/research_intent_models.py`
- ✅ `also_answering: List[str]` field (lines 206-209)
- ✅ All intent fields properly defined
- ✅ Frontend types synchronized (`frontend/src/components/Research/types/intent.types.ts`)
### 2. ResearchQuery Intent Field Links ✅
**Location**: `backend/models/research_intent_models.py`
- ✅ `addresses_primary_question: bool` (line 267-270)
- ✅ `addresses_secondary_questions: List[str]` (line 271-274)
- ✅ `targets_focus_areas: List[str]` (line 275-278)
- ✅ `covers_also_answering: List[str]` (line 279-282)
- ✅ `justification: Optional[str]` (line 283-286)
### 3. Query Deduplication Logic ✅
**Location**: `backend/services/research/intent/query_deduplicator.py`
- ✅ Semantic similarity checking (Jaccard similarity >80%)
- ✅ Merges queries with same purpose/provider
- ✅ Preserves primary query (always kept)
- ✅ Limits to 8 queries maximum
- ✅ Merges intent field links when deduplicating
**Key Features**:
- Exact duplicate detection
- Semantic similarity (80% threshold)
- Priority-based sorting
- Intent field link merging
### 4. Unified Prompt Builder - Query Linking ✅
**Location**: `backend/services/research/intent/unified_prompt_builder.py`
- ✅ Primary query generation (lines 78-81)
- ✅ Secondary query mapping (lines 83-87)
- ✅ Focus area queries (lines 89-94)
- ✅ Also answering queries (lines 96-99)
- ✅ Deduplication rules (lines 101-108)
- ✅ Query-to-intent linking instructions (lines 110-115)
**Prompt Structure**:
```
1. PRIMARY QUERY (priority 5, addresses_primary_question: true)
2. SECONDARY QUERY MAPPING (priority 4, links to secondary_questions)
3. FOCUS AREA QUERIES (priority 3-4, links to focus_areas)
4. ALSO ANSWERING QUERIES (priority 2-3, links to also_answering)
5. DEDUPLICATION RULES (merge similar queries)
6. QUERY-TO-INTENT LINKING (explicit field mapping)
```
### 5. Provider Settings Optimization ✅
**Location**: `backend/services/research/intent/unified_prompt_builder.py` (lines 120-205)
- ✅ Optimized based on primary query characteristics
- ✅ Considers secondary questions for comprehensive coverage
- ✅ Uses focus areas for content type selection
- ✅ Considers also_answering topics for time ranges/sources
- ✅ Time sensitivity rules
- ✅ Depth-based settings
- ✅ Query-specific optimizations
**Optimization Rules**:
1. Time sensitivity → date filters, provider selection
2. Focus areas → category/topic selection (academic → research paper, etc.)
3. Depth + secondary questions → search depth, context settings
4. Primary query needs → comprehensive vs. speed optimization
5. Also answering topics → broader time ranges, additional domains
### 6. Intent-Aware Analysis Prompt ✅
**Location**: `backend/services/research/intent/intent_prompt_builder.py` (lines 370-582)
- ✅ Generalized approach (line 399: "Use a **generalized approach**")
- ✅ Primary question handling (line 403)
- ✅ Secondary questions handling (line 405)
- ✅ Focus areas prioritization (lines 407-411)
- ✅ Also answering natural inclusion (line 413)
- ✅ Contextual linking (lines 421-425)
- ✅ `focus_areas_coverage` output (lines 440-443)
- ✅ `also_answering_coverage` output (lines 444-447)
**Key Features**:
- Natural, non-forced extraction
- All intent fields considered
- Coverage tracking for focus areas and also_answering
- Generalized approach prevents over-optimization
### 7. Result Models with Coverage Fields ✅
**Location**: `backend/models/research_intent_models.py`
- ✅ `secondary_answers: Dict[str, str]` (line 336-339)
- ✅ `focus_areas_coverage: Dict[str, Optional[str]]` (line 340-343)
- ✅ `also_answering_coverage: Dict[str, Optional[str]]` (line 344-347)
### 8. Schema and Parsing ✅
**Location**: `backend/services/research/intent/unified_schema_builder.py`
- ✅ Query linking fields in JSON schema (lines 55-58)
- ✅ `also_answering` in intent schema (line 32)
**Location**: `backend/services/research/intent/unified_result_parser.py`
- ✅ Parses intent field links (lines 59-62)
- ✅ Parses `also_answering` (line 37)
---
## 🎯 Architecture Quality
### Strengths
1. **Comprehensive Intent Linking**: Queries explicitly linked to all intent aspects
2. **Smart Deduplication**: Prevents redundant queries while preserving coverage
3. **Generalized Analysis**: Natural extraction without over-optimization
4. **Provider Optimization**: Settings tied to queries and intent fields
5. **Coverage Tracking**: Explicit tracking of focus areas and also_answering
### Current Flow
```
User Input
↓
UnifiedResearchAnalyzer (single LLM call)
├─ Intent Inference
├─ Query Generation (with intent field links)
└─ Provider Optimization (based on intent fields)
↓
Query Deduplication
├─ Semantic similarity check
├─ Intent field link merging
└─ Priority-based selection
↓
Research Execution
↓
IntentAwareAnalyzer
├─ Generalized extraction
├─ Focus areas prioritization
├─ Also answering natural inclusion
└─ Coverage tracking
↓
Structured Results
├─ Primary answer
├─ Secondary answers
├─ Focus areas coverage
├─ Also answering coverage
└─ Deliverables
```
---
## 📝 What Was Recently Fixed
### 1. Confidence Score Over-Optimization ✅
- **Issue**: Prompt was pushing for high confidence scores, reducing quality
- **Fix**: Reverted to quality-focused approach
- **Status**: Fixed in `unified_prompt_builder.py`
### 2. TypeScript Type Synchronization ✅
- **Issue**: Frontend types missing `also_answering`
- **Fix**: Added `also_answering: string[]` to `ResearchIntent` interface
- **Status**: Fixed in `frontend/src/components/Research/types/intent.types.ts`
### 3. Component Props ✅
- **Issue**: `ExpandableDetails` missing required props
- **Fix**: Added `intent` and `onUpdateField` props
- **Status**: Fixed in `IntentConfirmationPanel.tsx`
---
## 🔍 Verification Checklist
- [x] `also_answering` in ResearchIntent model
- [x] Query intent field links in ResearchQuery model
- [x] Query deduplication logic implemented
- [x] Unified prompt includes query linking instructions
- [x] Provider settings optimized based on intent fields
- [x] Analysis prompt uses generalized approach
- [x] Coverage fields in result models
- [x] Schema includes all linking fields
- [x] Parser handles all linking fields
- [x] Frontend types synchronized
---
## 🚀 No Additional Implementation Needed
**All proposed enhancements are already implemented and working.**
The system has:
- ✅ Complete intent field linking
- ✅ Smart query deduplication
- ✅ Generalized analysis approach
- ✅ Provider optimization tied to intent
- ✅ Coverage tracking for all intent aspects
---
## 📚 Related Documentation
- **Architecture**: `.cursor/rules/researcher-architecture.mdc`
- **Guide**: `INTENT_DRIVEN_RESEARCH_GUIDE.md`
- **API Reference**: `INTENT_RESEARCH_API_REFERENCE.md`
- **Current Architecture**: `CURRENT_ARCHITECTURE_OVERVIEW.md`
---
## ✅ Conclusion
The intent-driven research system is **fully implemented** with all proposed enhancements. The architecture is robust, well-structured, and follows best practices:
1. **Intent field linking** ensures queries are contextually connected
2. **Deduplication** prevents redundancy while maintaining coverage
3. **Generalized analysis** provides natural, high-quality extraction
4. **Provider optimization** aligns settings with research needs
5. **Coverage tracking** ensures all intent aspects are addressed
**Status**: ✅ Production Ready
---
**Last Updated**: 2025-01-29

105
docs/ALwrity Researcher/PROMPT_QUALITY_ISSUE_ANALYSIS.md Normal file
View File

@@ -0,0 +1,105 @@
# Prompt Quality Issue Analysis
**Date**: 2025-01-29
**Issue**: Quality degradation after prompt builder changes
**Status**: Investigating
---
## 🔍 Problem Statement
User reports that after changes to `unified_prompt_builder.py`, the quality of AI-generated research intent and Exa/Tavily options has significantly degraded. Previously getting great results, now getting poor quality.
---
## 📊 Current Prompt Analysis
### Prompt Length & Complexity
**Current Unified Prompt**: ~500 lines
- Very detailed instructions
- Multiple "CRITICAL" sections
- Extensive provider options documentation
- Complex query linking rules
- Detailed optimization rules
**Potential Issues**:
1. **Prompt Too Long**: ~500 lines may be overwhelming the LLM
2. **Too Many Constraints**: Multiple "CRITICAL" sections may conflict
3. **Over-Prescriptive**: Too many rules may confuse rather than guide
4. **Information Overload**: Provider options table is very detailed
---
## 🔄 What Changed Recently
Based on conversation history, recent changes include:
1. **Added keyword emphasis** - "MUST include user's actual keywords"
2. **Removed confidence optimization** - Reverted confidence instructions
3. **Added query linking rules** - Explicit linking to intent fields
4. **Enhanced provider optimization** - More detailed rules
---
## 🎯 Key Differences: Original vs Current
### Original Intent Prompt (Simple, Working)
- ~200 lines
- Clear, focused instructions
- Simple confidence scoring
- Straightforward query generation
- Basic provider selection
### Current Unified Prompt (Complex, Degraded)
- ~500 lines
- Multiple "CRITICAL" sections
- Complex query linking
- Extensive provider documentation
- Detailed optimization rules
---
## 💡 Hypothesis
**The prompt may be too complex**, causing the LLM to:
1. Get confused by conflicting instructions
2. Focus on wrong aspects (too many rules)
3. Produce lower quality due to information overload
4. Miss the core task (intent inference) due to complexity
---
## 🔧 Recommended Fixes
### Option 1: Simplify the Prompt (Recommended)
- Reduce prompt length by 50%
- Remove redundant instructions
- Simplify provider documentation
- Focus on core task: intent inference + query generation
### Option 2: Split Back to Separate Calls
- Use original `intent_prompt_builder.py` for intent
- Use separate query generation
- Use separate parameter optimization
- Trade-off: More LLM calls but better quality
### Option 3: Hybrid Approach
- Keep unified call but simplify prompt
- Remove detailed provider documentation (reference only)
- Focus on clear, concise instructions
- Let LLM infer more, prescribe less
---
## 📝 Next Steps
1. Review original working prompt structure
2. Identify what made it work well
3. Simplify current prompt while keeping essential features
4. Test with same inputs that previously worked
5. Compare quality before/after
---
**Status**: Ready for prompt simplification

609
docs/ALwrity Researcher/RESEARCHER_CODEBASE_REVIEW.md Normal file
View File

@@ -0,0 +1,609 @@
# Research Engine Codebase Review & Understanding
**Date**: 2025-01-29
**Status**: Comprehensive Codebase Review Summary
---
## 📋 Executive Summary
The ALwrity Research Engine is a **fully functional, production-ready intent-driven research system** that has evolved from a traditional keyword-based search to an AI-powered research assistant. The system uses a unified analyzer approach to reduce LLM calls by 50% while providing hyper-personalized research experiences based on user onboarding data.
---
## 🏗️ Architecture Overview
### Current Architecture (Intent-Driven)
```
User Input → UnifiedResearchAnalyzer (Single AI Call)
├── Intent Inference
├── Query Generation (4-8 queries)
└── Parameter Optimization (Exa/Tavily)
↓
Research Execution (Exa → Tavily → Google)
↓
IntentAwareAnalyzer (Result Analysis)
↓
Structured Deliverables (Statistics, Quotes, Case Studies, etc.)
```
### Key Architectural Principles
1. **Unified Analysis**: Single LLM call for intent + queries + params (50% reduction)
2. **Intent-Driven**: Understand user goals before searching
3. **Hyper-Personalization**: Leverage research persona from onboarding data
4. **Provider Priority**: Exa → Tavily → Google (semantic → real-time → fallback)
5. **Subscription-Aware**: All AI calls go through `llm_text_gen` with `user_id`
---
## 📁 Code Structure
### Backend Structure
```
backend/services/research/
├── core/
│ ├── research_engine.py # Main orchestrator (standalone)
│ ├── research_context.py # Unified input schema
│ └── parameter_optimizer.py # DEPRECATED (use unified analyzer)
│
├── intent/
│ ├── unified_research_analyzer.py # ⭐ Unified AI analyzer (intent + queries + params)
│ ├── intent_aware_analyzer.py # Result analysis based on intent
│ ├── unified_prompt_builder.py # LLM prompt builders
│ ├── unified_schema_builder.py # JSON schema builders
│ ├── unified_result_parser.py # Result parsing utilities
│ ├── query_deduplicator.py # Query deduplication logic
│ ├── research_intent_inference.py # Legacy (use unified)
│ └── intent_query_generator.py # Legacy (use unified)
│
├── trends/
│ ├── google_trends_service.py # Google Trends integration
│ └── rate_limiter.py # Rate limiting for Trends API
│
├── research_persona_service.py # Research persona generation/retrieval
├── research_persona_prompt_builder.py # Persona generation prompts
├── exa_service.py # Exa API integration
├── tavily_service.py # Tavily API integration
└── google_search_service.py # Google/Gemini grounding
backend/api/research/
├── router.py # Main router
└── handlers/
├── providers.py # Provider status endpoints
├── research.py # Traditional research endpoints
├── intent.py # Intent-driven endpoints
└── projects.py # My Projects endpoints
```
### Frontend Structure
```
frontend/src/components/Research/
├── ResearchWizard.tsx # Main wizard orchestrator (3 steps)
├── steps/
│ ├── ResearchInput.tsx # Step 1: Input + Intent & Options
│ ├── StepProgress.tsx # Step 2: Progress/polling
│ ├── StepResults.tsx # Step 3: Results display
│ ├── components/
│ │ ├── ResearchInputHeader.tsx # Header with Advanced toggle
│ │ ├── ResearchInputContainer.tsx # Main input with Intent & Options button
│ │ ├── IntentConfirmationPanel.tsx # Intent display/edit panel
│ │ ├── IntentResultsDisplay.tsx # Tabbed results (Summary, Deliverables, Sources, Analysis)
│ │ ├── AdvancedOptionsSection.tsx # Exa/Tavily options
│ │ ├── ProviderChips.tsx # Provider availability display
│ │ ├── PersonalizationIndicator.tsx # UI indicator for personalization
│ │ ├── PersonalizationBadge.tsx # Badge-style indicator
│ │ └── ... (other components)
│ ├── hooks/
│ │ ├── useResearchConfig.ts # Config + persona loading
│ │ ├── useKeywordExpansion.ts # Keyword expansion with persona
│ │ └── useResearchAngles.ts # Research angles generation
│ └── utils/
│ ├── placeholders.ts # Personalized placeholders
│ └── industryDefaults.ts # Industry-specific defaults
└── hooks/
├── useResearchWizard.ts # Wizard state management
├── useResearchExecution.ts # Research execution orchestration
└── useIntentResearch.ts # Intent research flow
```
---
## 🔑 Key Components
### 1. UnifiedResearchAnalyzer ⭐
**Location**: `backend/services/research/intent/unified_research_analyzer.py`
**Purpose**: Single AI call that performs:
- Intent inference (what user wants)
- Query generation (4-8 targeted queries)
- Parameter optimization (Exa/Tavily settings with justifications)
**Key Features**:
- Reduces LLM calls from 2-3 to 1 (50% reduction)
- Provides justifications for all parameter decisions
- Uses research persona for context
- Returns structured `ResearchIntent`, `ResearchQuery[]`, and `OptimizedConfig`
**Usage Pattern**:
```python
from services.research.intent.unified_research_analyzer import UnifiedResearchAnalyzer
analyzer = UnifiedResearchAnalyzer()
result = await analyzer.analyze(
user_input=user_input,
keywords=keywords,
research_persona=research_persona,
competitor_data=competitor_data,
industry=industry,
target_audience=target_audience,
user_id=user_id, # Required for subscription checks
)
```
### 2. IntentAwareAnalyzer
**Location**: `backend/services/research/intent/intent_aware_analyzer.py`
**Purpose**: Analyzes raw research results based on user intent to extract specific deliverables
**Key Features**:
- Extracts statistics, quotes, case studies, trends, comparisons
- Structures results by deliverable type
- Provides credibility scores for sources
- Identifies gaps and follow-up queries
**Usage Pattern**:
```python
from services.research.intent.intent_aware_analyzer import IntentAwareAnalyzer
analyzer = IntentAwareAnalyzer()
result = await analyzer.analyze(
raw_results=exa_tavily_results,
intent=research_intent,
research_persona=research_persona,
user_id=user_id, # Required for subscription checks
)
```
### 3. ResearchEngine
**Location**: `backend/services/research/core/research_engine.py`
**Purpose**: Orchestrates provider calls with priority order
**Provider Priority**:
1. **Exa** (Primary): Semantic understanding, academic papers, competitor research
2. **Tavily** (Secondary): Real-time news, trending topics, quick facts
3. **Google** (Fallback): Basic factual queries via Gemini grounding
### 4. ResearchPersonaService
**Location**: `backend/services/research/research_persona_service.py`
**Purpose**: Generates and retrieves research persona from onboarding data
**Persona Sources**:
- Core persona (onboarding step 1)
- Website analysis (onboarding step 2): `writing_style`, `content_characteristics`, `content_type`, `style_patterns`, `crawl_result`
- Competitor analysis (onboarding step 3)
**Features**:
- Caches persona (7-day TTL)
- Provides persona defaults for UI pre-filling
- Generates personalized presets, keywords, and research angles
---
## 🔌 API Endpoints
### Intent-Driven Endpoints (Current - Recommended)
1. **POST `/api/research/intent/analyze`**
- Analyzes user input to understand intent
- Generates queries and optimizes parameters
- Returns intent, queries, and optimized config
- **Performance**: 2-5 seconds (single LLM call)
2. **POST `/api/research/intent/research`**
- Executes research based on confirmed intent
- Returns structured deliverables
- **Performance**: 10-30 seconds (depends on provider and query count)
### Traditional Endpoints (Fallback)
3. **POST `/api/research/execute`** - Synchronous research execution
4. **POST `/api/research/start`** - Asynchronous research execution
5. **GET `/api/research/status/{task_id}`** - Poll async research status
### Configuration Endpoints
6. **GET `/api/research/config`** - Provider availability + persona defaults
7. **GET `/api/research/providers/status`** - Provider availability only
8. **GET `/api/research/persona-defaults`** - Persona defaults only
---
## 🔄 Research Flow
### Intent-Driven Research Flow (Current)
```
1. User Input
User enters: "AI marketing tools"
↓
2. Intent Analysis (UnifiedResearchAnalyzer)
POST /api/research/intent/analyze
├── Fetches Research Persona (if enabled)
├── Fetches Competitor Data (if enabled)
└── Single LLM Call:
├── Intent Inference
├── Query Generation (4-8 queries)
└── Parameter Optimization (Exa/Tavily)
↓
3. Intent Confirmation (Frontend)
IntentConfirmationPanel displays:
├── Inferred intent (editable)
├── Suggested queries (selectable)
└── AI-optimized settings with justifications
↓
4. Research Execution
POST /api/research/intent/research
├── ResearchEngine executes queries (Exa → Tavily → Google)
└── Returns raw results
↓
5. Intent-Aware Analysis
IntentAwareAnalyzer analyzes results:
├── Extracts statistics, quotes, case studies
├── Structures by deliverable type
└── Returns IntentDrivenResearchResult
↓
6. Results Display
IntentResultsDisplay shows:
├── Summary Tab
├── Deliverables Tab
├── Sources Tab
└── Analysis Tab
```
---
## 🎯 Key Features Implemented
### ✅ Completed Features
1. **Intent-Driven Research Architecture**
- UnifiedResearchAnalyzer (single AI call)
- IntentAwareAnalyzer (result analysis)
- 3-Step Wizard (ResearchInput → StepProgress → StepResults)
- IntentConfirmationPanel (review/edit intent)
2. **Google Trends Integration**
- Phase 1: Core Google Trends service
- Phase 2: Hybrid approach (automatic + on-demand)
- Phase 3: Enhanced UI with charts, export functionality
- Integrated into intent-driven research flow
3. **Research Persona System**
- Persona generation from onboarding data
- Persona defaults for UI pre-filling
- Caching (7-day TTL)
- UI indicators showing personalization
4. **My Projects Feature**
- Auto-save research projects upon completion
- Asset Library integration
- Restore functionality with full state persistence
5. **UI/UX Enhancements**
- QueryEditor redesign
- Google Trends keywords with chip-based UI
- Industry-specific placeholders
- Time-sensitive query handling
- Personalization indicators
---
## 📊 Data Models
### ResearchIntent
```python
class ResearchIntent:
primary_question: str
secondary_questions: List[str]
purpose: ResearchPurpose # learn, create_content, make_decision, etc.
content_output: ContentOutput # blog, podcast, video, etc.
expected_deliverables: List[ExpectedDeliverable]
depth: ResearchDepthLevel # overview, detailed, expert
focus_areas: List[str]
perspective: Optional[str]
time_sensitivity: str
confidence: float
confidence_reason: Optional[str]
great_example: Optional[str]
needs_clarification: bool
clarifying_questions: List[str]
```
### ResearchQuery
```python
class ResearchQuery:
query: str
purpose: ExpectedDeliverable
provider: str # "exa" | "tavily"
priority: int # 1-5
expected_results: str
justification: Optional[str]
```
### IntentDrivenResearchResult
```python
class IntentDrivenResearchResult:
primary_answer: str
secondary_answers: Dict[str, str]
statistics: List[StatisticWithCitation]
expert_quotes: List[ExpertQuote]
case_studies: List[CaseStudySummary]
trends: List[TrendAnalysis]
comparisons: List[ComparisonTable]
best_practices: List[str]
step_by_step: List[str]
pros_cons: Optional[ProsCons]
definitions: Dict[str, str]
examples: List[str]
predictions: List[str]
executive_summary: str
key_takeaways: List[str]
suggested_outline: List[str]
sources: List[SourceWithRelevance]
confidence: float
gaps_identified: List[str]
follow_up_queries: List[str]
```
---
## 🎨 UI Components
### ResearchWizard
**Purpose**: Main wizard orchestrator
**Steps**:
1. **ResearchInput**: Input + Intent & Options button
2. **StepProgress**: Progress/polling for async research
3. **StepResults**: Tabbed results display
### IntentConfirmationPanel
**Purpose**: Shows inferred intent and allows editing
**Features**:
- Displays inferred intent (editable)
- Shows suggested queries (selectable)
- Displays AI-optimized settings with justifications
- Advanced options for manual override
### IntentResultsDisplay
**Purpose**: Tabbed results display
**Tabs**:
- **Summary**: AI-generated overview
- **Deliverables**: Extracted statistics, quotes, case studies, etc.
- **Sources**: Citations with credibility scores
- **Analysis**: Deep insights based on intent
---
## 🔐 Security & Subscription
### Authentication
All endpoints require JWT authentication via `get_current_user` dependency.
### Subscription Checks
All LLM calls must pass `user_id` for subscription and pre-flight validation:
```python
result = llm_text_gen(
prompt=prompt,
json_struct=schema,
user_id=user_id # Required
)
```
### Rate Limiting
- Subject to subscription tier limits
- Provider APIs (Exa/Tavily/Google) have their own rate limits
---
## 📈 Performance
### Intent Analysis
- **Typical Time**: 2-5 seconds
- **LLM Calls**: 1 (unified analyzer)
- **Caching**: Research persona cached (7-day TTL)
### Research Execution
- **Typical Time**: 10-30 seconds
- **Depends On**: Provider, query count, result count
- **Async Support**: Yes (via `/api/research/start`)
### Result Analysis
- **Typical Time**: 5-10 seconds
- **LLM Calls**: 1 (intent-aware analyzer)
---
## 🔗 Integration Points
### Blog Writer Integration
Research Engine can be imported by Blog Writer:
```python
from services.research.core.research_engine import ResearchEngine
from services.research.core.research_context import ResearchContext
context = ResearchContext(
query=blog_topic,
keywords=blog_keywords,
goal=ResearchGoal.FACTUAL,
depth=ResearchDepth.COMPREHENSIVE,
)
engine = ResearchEngine()
result = await engine.research(context, user_id=user_id)
```
### Frontend Integration
Research Wizard can be reused in other tools:
```tsx
import { ResearchWizard } from '@/components/Research/ResearchWizard';
<ResearchWizard
onComplete={(results) => {
// Use results in blog/video generation
}}
initialKeywords={blogTopic}
initialIndustry={userIndustry}
/>
```
---
## ✅ Best Practices
1. **Always use UnifiedResearchAnalyzer** for new intent-driven research
2. **Always pass user_id** to all LLM calls
3. **Always use IntentAwareAnalyzer** for result analysis
4. **Check provider availability** before using providers
5. **Provide justifications** for all AI-driven settings
6. **Allow user overrides** in Advanced Options
7. **Never fallback to "General"** - always use persona defaults
---
## 🚫 Common Pitfalls to Avoid
1. ❌ **Rule-Based Parameter Optimization**: Always use AI-driven optimization via `UnifiedResearchAnalyzer`
2. ❌ **Missing `user_id`**: Always pass `user_id` to `llm_text_gen` for subscription checks
3. ❌ **Breaking Changes**: Never modify Research Engine in a way that breaks existing tools (Blog Writer, etc.)
4. ❌ **Hardcoded Defaults**: Always use persona defaults, never hardcode "General" values
5. ❌ **Multiple LLM Calls**: Use unified analyzer instead of separate intent + query + params calls
6. ❌ **Ignoring Provider Availability**: Always check provider availability before using
7. ❌ **Missing Justifications**: Every AI-driven setting must have a justification for UI display
---
## 📋 Pending Items & TODOs
### From Code Review
1. **File Upload Logic** (ResearchInput.tsx:396)
- TODO: Implement file upload logic for research input
- Status: Not started (low priority)
### Documentation Gaps
1. **Intent-Driven Research Documentation**
- ✅ Comprehensive guide created (`INTENT_DRIVEN_RESEARCH_GUIDE.md`)
- ✅ API reference created (`INTENT_RESEARCH_API_REFERENCE.md`)
- ✅ Architecture overview created (`CURRENT_ARCHITECTURE_OVERVIEW.md`)
2. **Outdated Documentation**
- ⚠️ Some docs still reference old 4-step wizard
- ⚠️ Need to update implementation guides
- See `DOCUMENTATION_REVIEW_AND_UPDATE_PLAN.md` for details
---
## 🎯 Suggested Next Steps
### Priority 1: Documentation Updates (High Value, Low Effort)
1. Update outdated implementation documentation
2. Create integration examples
3. Update component documentation
### Priority 2: Dashboard Alert System Integration (Medium Value, Medium Effort)
1. Research cost alerts
2. Research efficiency alerts
3. Integration with billing dashboard alerts
### Priority 3: Feature Enhancements (Variable Value, Variable Effort)
1. File upload for research input
2. Research templates
3. Research comparison
4. Advanced export options
### Priority 4: Performance & Optimization (Low Value, High Effort)
1. Research result caching
2. Batch research operations
---
## 📚 Related Documentation
### Current & Accurate
- ✅ **CURRENT_ARCHITECTURE_OVERVIEW.md** - Single source of truth
- ✅ **INTENT_DRIVEN_RESEARCH_GUIDE.md** - Comprehensive guide
- ✅ **INTENT_RESEARCH_API_REFERENCE.md** - Complete API docs
- ✅ **.cursor/rules/researcher-architecture.mdc** - Authoritative rules
- ✅ **PHASE2_IMPLEMENTATION_SUMMARY.md** - Persona enhancements
- ✅ **PHASE3_AND_UI_INDICATORS_IMPLEMENTATION.md** - Phase 3 features
- ✅ **RESEARCH_PERSONA_DATA_SOURCES.md** - Persona data sources
### Outdated (Historical Reference Only)
- ⚠️ **RESEARCH_WIZARD_IMPLEMENTATION.md** - Describes old 4-step wizard
- ⚠️ **RESEARCH_COMPONENT_INTEGRATION.md** - Mentions old architecture
- ⚠️ **PHASE1_IMPLEMENTATION_REVIEW.md** - Missing intent-driven research
- ⚠️ **RESEARCH_IMPROVEMENTS_SUMMARY.md** - Missing intent-driven research
- ⚠️ **COMPLETE_IMPLEMENTATION_SUMMARY.md** - Missing intent-driven research
---
## ✅ Conclusion
The Research Engine is **fully functional and production-ready**. The system has evolved from a traditional keyword-based search to an AI-powered intent-driven research assistant with:
- **50% reduction in LLM calls** (unified analyzer)
- **Hyper-personalization** based on onboarding data
- **Structured deliverables** (statistics, quotes, case studies, etc.)
- **Provider optimization** (Exa → Tavily → Google)
- **UI indicators** showing personalization
- **My Projects** integration with Asset Library
**Main Gaps**:
1. Documentation updates (some outdated docs)
2. Alert system integration (cost/efficiency alerts)
3. Feature enhancements (file upload, templates, etc.)
**Recommended Focus**: Start with documentation updates (high value, low effort) followed by alert system integration (improves user experience and cost transparency).
---
**Status**: Codebase Review Complete - System is Production-Ready 🚀

342
docs/ALwrity Researcher/RESEARCHER_CURRENT_STATUS_AND_NEXT_STEPS.md Normal file
View File

@@ -0,0 +1,342 @@
# Researcher: Current Status & Next Steps
**Date**: 2025-01-29
**Status**: Implementation Review & Planning
---
## 📊 Executive Summary
The Researcher feature has undergone significant enhancements and is now a fully functional intent-driven research system. This document reviews completed work, current state, and suggests next steps.
---
## ✅ Completed Features
### 1. **Intent-Driven Research Architecture** ✅
- **UnifiedResearchAnalyzer**: Single AI call for intent inference, query generation, and parameter optimization
- **IntentAwareAnalyzer**: Analyzes results based on user intent to extract specific deliverables
- **3-Step Wizard**: ResearchInput → StepProgress → StepResults
- **IntentConfirmationPanel**: Allows users to review and edit AI-inferred intent before execution
### 2. **Google Trends Integration** ✅
- **Phase 1**: Core Google Trends service with interest over time, interest by region, related topics/queries
- **Phase 2**: Hybrid approach (automatic + on-demand), parallel execution with core research
- **Phase 3**: Enhanced UI with charts, export functionality, keyword suggestions
- **Integration**: Seamlessly integrated into intent-driven research flow
### 3. **Research Persona System** ✅
- **Persona Generation**: AI-generated research persona based on user data
- **Persona Defaults**: Pre-fills industry, target audience, and research preferences
- **Caching**: Prevents unnecessary regeneration, maintains single persona per user
- **UI Indicators**: Visual indicators showing when persona data is being used
### 4. **My Projects Feature** ✅
- **Auto-Save**: Automatically saves research projects upon completion
- **Asset Library Integration**: Projects stored in unified Asset Library
- **Restore Functionality**: Users can restore previous research projects
- **State Persistence**: Full state restoration including intent analysis and results
### 5. **UI/UX Enhancements** ✅
- **QueryEditor**: Redesigned for better readability and professional styling
- **Google Trends Keywords**: Improved display with chip-based UI
- **Placeholder Messages**: Enhanced industry-specific placeholders
- **Time-Sensitive Queries**: Dynamic date context injection to prevent outdated results
- **Contrast Fixes**: Resolved white-on-white text issues
### 6. **Component Refactoring** ✅
- **IntentConfirmationPanel**: Refactored into modular components
- **Folder Structure**: Organized components into logical folders
- **Best Practices**: Follows React best practices and maintainability standards
---
## 🔄 Current Architecture
### Backend Flow
```
User Input → UnifiedResearchAnalyzer (intent + queries + params)
→ Research Execution (Exa → Tavily → Google)
→ IntentAwareAnalyzer (result analysis)
→ IntentDrivenResearchResult
```
### Frontend Flow
```
ResearchInput → Intent & Options Button
→ IntentConfirmationPanel (review/edit)
→ Research Execution
→ StepProgress (polling)
→ StepResults (tabbed display)
```
### Key Components
- **ResearchWizard**: Main orchestrator
- **ResearchInput**: Step 1 - Input with Intent & Options
- **StepProgress**: Step 2 - Progress/polling
- **StepResults**: Step 3 - Results display
- **IntentConfirmationPanel**: Intent review/edit panel
- **IntentResultsDisplay**: Tabbed results (Summary, Deliverables, Sources, Analysis)
---
## 📋 Pending Items & TODOs
### From Code Review
1. **File Upload Logic** (ResearchInput.tsx:396)
- TODO: Implement file upload logic for research input
- Status: Not started
### Documentation Gaps
1. **Intent-Driven Research Documentation**
- Missing comprehensive guide for intent-driven research
- Need API reference documentation
- Need integration examples
2. **Current Architecture Documentation**
- Some docs still reference old 4-step wizard
- Need to update implementation guides
- Need to create current architecture overview
---
## 🎯 Suggested Next Steps
### Priority 1: Documentation Updates (High Value, Low Effort)
#### 1.1 Update Implementation Documentation
**Why**: Documentation is outdated and references old architecture
**Effort**: 2-3 days
**Impact**: High - helps new developers understand current system
**Tasks**:
- Update `RESEARCH_WIZARD_IMPLEMENTATION.md` to reflect 3-step wizard
- Update `RESEARCH_COMPONENT_INTEGRATION.md` to remove strategy pattern references
- Create `INTENT_DRIVEN_RESEARCH_GUIDE.md` with comprehensive flow documentation
- Create `CURRENT_ARCHITECTURE_OVERVIEW.md` as single source of truth
#### 1.2 Create API Reference
**Why**: Developers need clear API documentation
**Effort**: 1 day
**Impact**: Medium - improves developer experience
**Tasks**:
- Document `/api/research/intent/analyze` endpoint
- Document `/api/research/intent/research` endpoint
- Document request/response schemas
- Provide example requests/responses
### Priority 2: Dashboard Alert System Integration (Medium Value, Medium Effort)
#### 2.1 Research Cost Alerts
**Why**: Users should be notified about research operation costs
**Effort**: 2-3 days
**Impact**: High - improves cost transparency
**Integration Points**:
- Use existing `UsageAlert` system
- Trigger alerts for:
- High-cost research operations (>$0.10)
- Research velocity warnings (spending rate)
- Cost optimization recommendations (from Priority 3 billing features)
- Budget threshold warnings (50%, 80%, 95%)
**Implementation**:
```typescript
// In research execution
if (estimatedCost > 0.10) {
await createUsageAlert({
type: 'research_cost_warning',
title: 'High-Cost Research Operation',
message: `This research operation will cost approximately ${formatCurrency(estimatedCost)}`,
severity: 'warning'
});
}
```
#### 2.2 Research Efficiency Alerts
**Why**: Notify users about inefficient research patterns
**Effort**: 2-3 days
**Impact**: Medium - helps users optimize usage
**Alert Types**:
- Failed research operations (wasted costs)
- High token usage patterns
- Provider availability issues
- Research optimization recommendations
#### 2.3 Integration with Billing Dashboard Alerts
**Why**: Unified alert system across all features
**Effort**: 1-2 days
**Impact**: Medium - consistent user experience
**Tasks**:
- Extend `UsageAlerts` component to show research-specific alerts
- Add research alert filtering
- Integrate cost optimization recommendations as alerts
- Add alert actions (e.g., "View Optimization Tips")
### Priority 3: Feature Enhancements (Variable Value, Variable Effort)
#### 3.1 File Upload for Research Input
**Why**: Users may want to upload documents for research
**Effort**: 3-5 days
**Impact**: Medium - adds flexibility
**Tasks**:
- Implement file upload UI
- Add document parsing (PDF, DOCX, TXT)
- Extract keywords/topics from documents
- Integrate with research input
#### 3.2 Research Templates
**Why**: Users often research similar topics
**Effort**: 2-3 days
**Impact**: Medium - improves efficiency
**Tasks**:
- Create template system for common research types
- Save research configurations as templates
- Quick-start from templates
#### 3.3 Research Comparison
**Why**: Compare research results over time
**Effort**: 3-4 days
**Impact**: Low-Medium - nice-to-have feature
**Tasks**:
- Store research snapshots
- Compare research results side-by-side
- Track changes over time
#### 3.4 Advanced Export Options
**Why**: Users need various export formats
**Effort**: 2-3 days
**Impact**: Medium - improves usability
**Tasks**:
- Export to Word/PDF
- Export to Markdown
- Export to JSON/CSV
- Custom export templates
### Priority 4: Performance & Optimization (Low Value, High Effort)
#### 4.1 Research Result Caching
**Why**: Avoid redundant research for similar queries
**Effort**: 3-5 days
**Impact**: Medium - reduces costs and improves speed
**Tasks**:
- Implement query similarity detection
- Cache research results
- Smart cache invalidation
- Cache hit/miss indicators
#### 4.2 Batch Research Operations
**Why**: Research multiple topics efficiently
**Effort**: 4-6 days
**Impact**: Low-Medium - specialized use case
**Tasks**:
- Multi-topic research input
- Batch execution
- Progress tracking per topic
- Consolidated results view
---
## 🔗 Integration Opportunities
### 1. Billing Dashboard Integration
**Status**: Partially integrated (My Projects in Asset Library)
**Next Steps**:
- Add research cost breakdown to billing dashboard
- Show research-specific usage metrics
- Integrate cost optimization recommendations
### 2. Alert System Integration
**Status**: Not integrated
**Next Steps**:
- Use existing `UsageAlert` system for research alerts
- Add research-specific alert types
- Integrate with `UsageAlerts` component
### 3. Asset Library Integration
**Status**: ✅ Completed (My Projects)
**Enhancements**:
- Add research project search/filtering
- Add research project tags/categories
- Add research project sharing (future)
---
## 📊 Metrics & Monitoring
### Current Metrics Tracked
- Research execution time
- Provider usage (Exa, Tavily, Google)
- Token usage
- Cost per research operation
- Success/failure rates
### Suggested Additional Metrics
- Research query effectiveness (result quality)
- User satisfaction (implicit - completion rates)
- Research pattern analysis (time of day, frequency)
- Cost efficiency trends
---
## 🐛 Known Issues
### Minor Issues
1. **File Upload TODO**: Not implemented (low priority)
2. **Documentation**: Outdated in some areas (addressed in Priority 1)
### No Critical Issues
✅ All major functionality is working correctly
✅ No blocking bugs identified
---
## 🎯 Recommended Immediate Actions
### Week 1-2: Documentation
1. Update implementation documentation
2. Create intent-driven research guide
3. Create API reference
### Week 3-4: Alert Integration
1. Integrate research cost alerts
2. Add research efficiency alerts
3. Integrate with billing dashboard alerts
### Week 5+: Feature Enhancements
1. Implement file upload (if needed)
2. Add research templates (if needed)
3. Enhance export options (if needed)
---
## 📝 Notes
- **Architecture Rule File**: `.cursor/rules/researcher-architecture.mdc` is the authoritative source
- **Current State**: System is production-ready and fully functional
- **Documentation**: Main gap is in implementation documentation, not architecture
- **Alert System**: Ready for integration, just needs research-specific alert types
---
## ✅ Conclusion
The Researcher feature is **fully functional and production-ready**. The main gaps are:
1. **Documentation updates** (Priority 1)
2. **Alert system integration** (Priority 2)
3. **Feature enhancements** (Priority 3+)
**Recommended Focus**: Start with documentation updates (high value, low effort) followed by alert system integration (improves user experience and cost transparency).
---
**Status**: Review Complete - Ready for Next Steps

151
docs/ALwrity Researcher/RESEARCH_API_SEPARATION.md Normal file
View File

@@ -0,0 +1,151 @@
# Research API Separation of Concerns
**Date**: 2025-01-29
**Status**: Completed
---
## Overview
Properly separated Research API types from Blog Writer API to ensure clean separation of concerns. Research components now use dedicated `researchApi.ts` instead of `blogWriterApi.ts`.
---
## Problem
Research components were importing types from `blogWriterApi.ts`, which violated separation of concerns:
- Research is a standalone engine used by multiple tools (Blog Writer, Podcast Maker, YouTube Creator, etc.)
- Mixing research types with blog writer types created confusion and tight coupling
- Made it difficult to maintain and extend research functionality independently
---
## Solution
### Created Dedicated Research API File
**`frontend/src/services/researchApi.ts`** - New dedicated file containing:
- `ResearchMode` - Research depth levels
- `ResearchProvider` - Provider types (google, exa, tavily)
- `SourceType` - Source categories
- `DateRange` - Date filter options
- `ResearchSource` - Source data structure
- `ResearchConfig` - Complete research configuration (Exa, Tavily options)
- `ResearchResponse` - Generic research response interface
- `ResearchRequest` - Research request interface
### Updated All Research Components
All Research components now import from `researchApi.ts`:
**Updated Files:**
1. `ExaOptions.tsx` - Uses `ResearchConfig` from `researchApi.ts`
2. `TavilyOptions.tsx` - Uses `ResearchConfig` from `researchApi.ts`
3. `ResearchInput.tsx` - Uses `ResearchProvider`, `ResearchMode` from `researchApi.ts`
4. `AdvancedProviderOptionsSection.tsx` - Uses `ResearchProvider` from `researchApi.ts`
5. `useResearchWizard.ts` - Uses `ResearchMode`, `ResearchConfig`, `ResearchResponse` from `researchApi.ts`
6. `research.types.ts` - Uses `ResearchResponse`, `ResearchMode`, `ResearchConfig` from `researchApi.ts`
7. `StepResults.tsx` - Uses `ResearchResponse` from `researchApi.ts` (casts to `BlogResearchResponse` when needed)
8. `AdvancedOptionsSection.tsx` - Uses `ResearchConfig` from `researchApi.ts`
9. `useResearchConfig.ts` - Uses `ResearchProvider` from `researchApi.ts`
10. `StepOptions.tsx` - Uses `ResearchProvider` from `researchApi.ts`
11. `researchModeSuggester.ts` - Uses `ResearchMode` from `researchApi.ts`
### Backward Compatibility
**`frontend/src/services/blogWriterApi.ts`** - Maintains backward compatibility:
- Re-exports research types from `researchApi.ts` for existing blog writer code
- `BlogResearchResponse` extends `ResearchResponse` (adds blog-specific fields like `search_widget`, `grounding_metadata`)
- Blog Writer components continue to work without changes
### Adapter Pattern
**`BlogWriterAdapter.tsx`** - Uses `BlogResearchResponse`:
- This is correct - it's an adapter that bridges Research and Blog Writer
- Adapters are allowed to use both APIs as they translate between domains
---
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Research Engine │
│ (Standalone, used by multiple tools) │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ researchApi.ts │ │
│ │ - ResearchConfig │ │
│ │ - ResearchResponse │ │
│ │ - ResearchMode, ResearchProvider │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
│ extends
▼
┌─────────────────────────────────────────────────────────┐
│ Blog Writer │
│ (Uses Research Engine) │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ blogWriterApi.ts │ │
│ │ - BlogResearchResponse extends ResearchResponse │ │
│ │ - Blog-specific fields (search_widget, etc.) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
---
## Benefits
1. **Clear Separation**: Research types are separate from Blog Writer types
2. **Reusability**: Research API can be used by Podcast Maker, YouTube Creator, etc.
3. **Maintainability**: Changes to research don't affect blog writer and vice versa
4. **Type Safety**: Proper TypeScript types ensure compile-time safety
5. **Backward Compatibility**: Existing blog writer code continues to work
---
## Migration Status
✅ **Completed:**
- Created `researchApi.ts` with all research types
- Updated all Research components to use `researchApi.ts`
- Updated `researchEngineApi.ts` to use `ResearchResponse`
- Maintained backward compatibility in `blogWriterApi.ts`
- `BlogResearchResponse` properly extends `ResearchResponse`
⚠️ **Future Work:**
- Update blog writer components to import from `researchApi.ts` directly (currently using re-exports)
- Consider creating adapter components for other tools (Podcast Maker, YouTube Creator)
---
## File Structure
```
frontend/src/services/
├── researchApi.ts ← NEW: Dedicated research types
├── researchEngineApi.ts ← Updated: Uses researchApi.ts
└── blogWriterApi.ts ← Updated: Re-exports + BlogResearchResponse extends ResearchResponse
frontend/src/components/Research/
├── steps/
│ ├── components/
│ │ ├── ExaOptions.tsx ← Uses researchApi.ts
│ │ ├── TavilyOptions.tsx ← Uses researchApi.ts
│ │ └── AdvancedOptionsSection.tsx ← Uses researchApi.ts
│ ├── hooks/
│ │ └── useResearchConfig.ts ← Uses researchApi.ts
│ └── utils/
│ └── researchModeSuggester.ts ← Uses researchApi.ts
├── types/
│ └── research.types.ts ← Uses researchApi.ts
└── integrations/
└── BlogWriterAdapter.tsx ← Uses blogWriterApi.ts (adapter, correct)
```
---
**Status**: ✅ Separation of concerns achieved - Research API is now independent from Blog Writer API

755
docs/ALwrity Researcher/RESEARCH_COMPONENT_INTEGRATION.md
View File

@@ -1,335 +1,492 @@
# Research Component Integration Guide
## Overview
**Date**: 2025-01-29
**Status**: Updated for Intent-Driven Research Architecture
The modular Research component has been implemented as a standalone, testable wizard that can be integrated into the blog writer or used independently. This document outlines the architecture, usage, and integration steps.
---
## Architecture
## 📋 Overview
### Backend Strategy Pattern
The Research component is a standalone, intent-driven research system that can be integrated into any part of the application. This guide explains how to integrate and use the Research component.
The research service now supports multiple research modes through a strategy pattern:
**Key Features**:
- Intent-driven research (AI infers user goals)
- Standalone and reusable
- 3-step wizard interface
- Provider optimization (Exa → Tavily → Google)
- Research persona integration
- Google Trends integration
```python
# Research modes
- Basic: Quick keyword-focused analysis
- Comprehensive: Full analysis with all components
- Targeted: Customizable components based on config
---
# Strategy implementation
backend/services/blog_writer/research/research_strategies.py
- ResearchStrategy (base class)
- BasicResearchStrategy
- ComprehensiveResearchStrategy
- TargetedResearchStrategy
## 🏗️ Architecture
### Intent-Driven Research Flow
```
User Input
↓
UnifiedResearchAnalyzer (Single AI Call)
├── Intent Inference
├── Query Generation
└── Parameter Optimization
↓
Research Execution (Exa → Tavily → Google)
↓
IntentAwareAnalyzer
├── Result Analysis
└── Deliverable Extraction
↓
IntentDrivenResearchResult
```
### Frontend Component Structure
### Component Structure
```
frontend/src/components/Research/
├── index.tsx # Main exports
├── ResearchWizard.tsx # Main wizard container
├── ResearchWizard.tsx # Main wizard orchestrator
├── steps/
│ ├── StepKeyword.tsx # Step 1: Keyword input
│ ├── StepOptions.tsx # Step 2: Mode selection
│ ├── StepProgress.tsx # Step 3: Progress display
│ └── StepResults.tsx # Step 4: Results display
│ ├── ResearchInput.tsx # Step 1: Input + Intent & Options
│ ├── StepProgress.tsx # Step 2: Progress/polling
│ ├── StepResults.tsx # Step 3: Results display
│ └── components/ # Sub-components
├── hooks/
│ ├── useResearchWizard.ts # Wizard state management
│ └── useResearchExecution.ts # API calls and polling
├── types/
│ └── research.types.ts # TypeScript interfaces
└── utils/
└── researchUtils.ts # Utility functions
│ ├── useResearchWizard.ts # Wizard state management
│ ├── useResearchExecution.ts # API calls and polling
│ └── useIntentResearch.ts # Intent-driven research flow
└── types/
├── research.types.ts # Wizard state types
└── intent.types.ts # Intent-driven types
```
## Test Page
---
A dedicated test page is available at `/research-test` for testing the research wizard independently.
**Features:**
- Quick preset keywords for testing
- Debug panel with JSON export
- Performance metrics display
- Cache state visualization
## Usage
### Standalone Usage
```typescript
import { ResearchWizard } from '../components/Research';
<ResearchWizard
onComplete={(results) => {
console.log('Research complete:', results);
}}
onCancel={() => {
console.log('Cancelled');
}}
initialKeywords={['AI', 'marketing']}
initialIndustry="Technology"
/>
```
### Integration with Blog Writer
The component is designed to be easily integrated into the BlogWriter research phase:
**Current Implementation:**
- Uses CopilotKit sidebar for research input
- Displays results in `ResearchResults` component
- Manual fallback via `ManualResearchForm`
**Proposed Integration:**
Replace the CopilotKit/manual form with the wizard:
```typescript
// In BlogWriter.tsx
{currentPhase === 'research' && (
<ResearchWizard
onComplete={(results) => setResearch(results)}
onCancel={() => navigate('blog-writer')}
/>
)}
```
## Backend API Changes
### New Models
The `BlogResearchRequest` model now supports:
```python
class BlogResearchRequest(BaseModel):
keywords: List[str]
topic: Optional[str] = None
industry: Optional[str] = None
target_audience: Optional[str] = None
tone: Optional[str] = None
word_count_target: Optional[int] = 1500
persona: Optional[PersonaInfo] = None
research_mode: Optional[ResearchMode] = ResearchMode.BASIC # NEW
config: Optional[ResearchConfig] = None # NEW
```
### Backward Compatibility
The API remains backward compatible:
- If `research_mode` is not provided, defaults to `BASIC`
- If `config` is not provided, defaults to standard configuration
- Existing requests continue to work unchanged
## Research Modes
### Basic Mode
- Quick keyword analysis
- Primary & secondary keywords
- Current trends overview
- Top 5 content angles
- Key statistics
### Comprehensive Mode
- All basic features plus:
- Expert quotes & opinions
- Competitor analysis
- Market forecasts
- Best practices & case studies
- Content gaps identification
### Targeted Mode
- Selectable components:
- Statistics
- Expert quotes
- Competitors
- Trends
- Always includes: Keywords & content angles
## Configuration Options
### ResearchConfig Model
```python
class ResearchConfig(BaseModel):
mode: ResearchMode = ResearchMode.BASIC
date_range: Optional[DateRange] = None
source_types: List[SourceType] = []
max_sources: int = 10
include_statistics: bool = True
include_expert_quotes: bool = True
include_competitors: bool = True
include_trends: bool = True
```
### Date Range Options
- `last_week`
- `last_month`
- `last_3_months`
- `last_6_months`
- `last_year`
- `all_time`
### Source Types
- `web` - Web articles
- `academic` - Academic papers
- `news` - News articles
- `industry` - Industry reports
- `expert` - Expert opinions
## Caching
The research component uses the existing cache infrastructure:
- Cache keys include research mode
- Cache is shared across basic/comprehensive/targeted modes
- Cache invalidation handled automatically
## Testing
### Test the Wizard
1. Navigate to `/research-test`
2. Use quick presets or enter custom keywords
3. Select research mode
4. Monitor progress
5. Review results
6. Export JSON for analysis
### Integration Testing
To test integration with BlogWriter:
1. Start backend: `python start_alwrity_backend.py`
2. Navigate to `/blog-writer` (current implementation)
3. Or navigate to `/research-test` (new wizard)
4. Compare results and UI
## Migration Path
### Phase 1: Parallel Testing (Current)
- `/research-test` - New wizard available
- `/blog-writer` - Current implementation unchanged
- Users can test both
### Phase 2: Integration
1. Add wizard as option in BlogWriter
2. A/B test user preference
3. Monitor performance metrics
### Phase 3: Replacement (Optional)
1. Replace CopilotKit/manual form with wizard
2. Remove old implementation
3. Update documentation
## API Endpoints
All existing endpoints remain unchanged:
```
POST /api/blog/research/start
- Supports new research_mode and config parameters
- Backward compatible with existing requests
GET /api/blog/research/status/{task_id}
- No changes required
```
## Benefits
1. **Modularity**: Component works standalone
2. **Testability**: Dedicated test page for experimentation
3. **Backward Compatibility**: Existing functionality unchanged
4. **Progressive Enhancement**: Can add features incrementally
5. **Reusability**: Can be used in other parts of the app
## Future Enhancements
Potential future improvements:
1. **Multi-stage Research**: Sequential research with refinement
2. **Source Quality Validation**: Advanced credibility scoring
3. **Interactive Query Builder**: Dynamic search refinement
4. **Advanced Prompting**: Few-shot examples, reasoning chains
5. **Custom Strategy Plugins**: User-defined research strategies
## Troubleshooting
### Research Results Not Showing
Check:
1. Backend logs for API errors
2. Network tab for failed requests
3. Browser console for JavaScript errors
4. Verify user authentication
### Cache Issues
Clear cache:
```typescript
import { researchCache } from '../services/researchCache';
researchCache.clearCache();
```
### Type Errors
Ensure all imports are correct:
```typescript
import {
ResearchWizard,
useResearchWizard,
WizardState
} from '../components/Research';
import {
BlogResearchRequest,
BlogResearchResponse,
ResearchMode,
ResearchConfig
} from '../services/blogWriterApi';
```
## Examples
## 🔌 Integration
### Basic Integration
```typescript
import { ResearchWizard } from './components/Research';
import { BlogResearchResponse } from './services/blogWriterApi';
const MyComponent: React.FC = () => {
const [results, setResults] = useState<BlogResearchResponse | null>(null);
import { ResearchWizard } from '../components/Research';
function MyComponent() {
return (
<ResearchWizard
onComplete={(res) => setResults(res)}
onCancel={() => console.log('Cancelled')}
onComplete={(results) => {
console.log('Research complete:', results);
// Use results in your component
}}
onCancel={() => {
console.log('Research cancelled');
}}
/>
);
};
}
```
### Advanced Integration with Custom Config
### With Initial Data
```typescript
const request: BlogResearchRequest = {
keywords: ['AI', 'automation'],
industry: 'Technology',
research_mode: 'targeted',
config: {
mode: 'targeted',
include_statistics: true,
include_competitors: true,
include_trends: false,
<ResearchWizard
initialKeywords={['AI marketing tools']}
initialIndustry="Technology"
initialTargetAudience="Marketing professionals"
initialResearchMode="comprehensive"
initialConfig={{
provider: 'exa',
max_sources: 20,
}
};
include_statistics: true,
include_expert_quotes: true
}}
initialResults={savedResults} // For restoring saved projects
/>
```
## Support
### Blog Writer Integration
For issues or questions:
1. Check this documentation
2. Review test page examples
3. Inspect backend logs
4. Check frontend console
```typescript
import { BlogWriterAdapter } from '../components/Research/integrations/BlogWriterAdapter';
function BlogWriter() {
const [researchData, setResearchData] = useState(null);
return (
<>
<BlogWriterAdapter
onResearchComplete={(data) => {
setResearchData(data);
// Use research data for blog generation
}}
/>
{/* Rest of blog writer UI */}
</>
);
}
```
---
## 🔄 Research Flow
### Step 1: Research Input
**User provides**:
- Keywords/topic
- Industry (optional, pre-filled from persona)
- Target audience (optional, pre-filled from persona)
**Component triggers**:
- Intent analysis when user clicks "Intent & Options"
- Shows `IntentConfirmationPanel` with AI-inferred intent
### Step 2: Intent Confirmation
**User reviews**:
- Primary research question
- Generated research queries
- Optimized provider settings
- Google Trends keywords (if applicable)
**User can**:
- Edit primary question
- Toggle deliverables
- Select/edit queries
- Review provider settings
**Component executes**:
- Research with selected queries
- Shows progress
- Auto-navigates to results
### Step 3: Results Display
**Component shows**:
- Summary tab (AI-generated overview)
- Deliverables tab (statistics, quotes, case studies, trends)
- Sources tab (citations with credibility scores)
- Analysis tab (deep insights)
---
## 🔌 API Integration
### Intent Analysis Endpoint
```typescript
POST /api/research/intent/analyze
Request:
{
"keywords": "AI marketing tools",
"industry": "Technology",
"target_audience": "Marketing professionals"
}
Response:
{
"success": true,
"intent": {
"primary_question": "What are the latest AI-powered marketing automation tools?",
"research_goals": ["identify tools", "compare features", "analyze trends"],
"deliverables": ["statistics", "expert_quotes", "case_studies"],
"industry": "Technology",
"target_audience": "Marketing professionals"
},
"queries": [
{
"query": "AI marketing automation platforms 2025",
"provider": "exa",
"justification": "Exa is best for finding company/product information"
}
],
"optimized_config": {
"provider": "exa",
"exa_category": "company",
"provider_justification": "Exa excels at finding company and product information"
},
"trends_config": {
"keywords": ["AI marketing", "marketing automation"],
"enabled": true
}
}
```
### Intent-Driven Research Endpoint
```typescript
POST /api/research/intent/research
Request:
{
"intent": {...},
"queries": [...],
"config": {...}
}
Response:
{
"success": true,
"result": {
"summary": "Comprehensive overview...",
"deliverables": {
"statistics": [
{
"value": "85%",
"description": "of marketers use AI tools",
"citation": {...}
}
],
"expert_quotes": [...],
"case_studies": [...],
"trends": [...]
},
"sources": [...],
"analysis": "Deep insights based on intent..."
}
}
```
---
## 🎨 Customization
### Custom Styling
```typescript
import { ResearchWizard } from '../components/Research';
import { ThemeProvider, createTheme } from '@mui/material';
const customTheme = createTheme({
// Your custom theme
});
<ThemeProvider theme={customTheme}>
<ResearchWizard {...props} />
</ThemeProvider>
```
### Custom Hooks
```typescript
import { useResearchWizard, useResearchExecution } from '../components/Research';
function CustomResearchComponent() {
const wizard = useResearchWizard();
const execution = useResearchExecution();
// Custom logic here
return <div>Custom UI</div>;
}
```
---
## 🔧 Backend Services
### UnifiedResearchAnalyzer
**Location**: `backend/services/research/intent/unified_research_analyzer.py`
**Purpose**: Single AI call for intent inference, query generation, and parameter optimization
**Usage**:
```python
from backend.services.research.intent.unified_research_analyzer import UnifiedResearchAnalyzer
analyzer = UnifiedResearchAnalyzer()
result = await analyzer.analyze(
user_input="AI marketing tools",
industry="Technology",
target_audience="Marketing professionals",
user_id="user_123"
)
```
### IntentAwareAnalyzer
**Location**: `backend/services/research/intent/intent_aware_analyzer.py`
**Purpose**: Analyzes raw research results based on user intent
**Usage**:
```python
from backend.services.research.intent.intent_aware_analyzer import IntentAwareAnalyzer
analyzer = IntentAwareAnalyzer()
result = await analyzer.analyze(
raw_results={...},
intent=research_intent,
user_id="user_123"
)
```
---
## 📝 Type Definitions
### Research Types
```typescript
// research.types.ts
export interface WizardState {
currentStep: number;
keywords: string[];
industry: string;
target_audience: string;
research_mode: ResearchMode;
config: ResearchConfig;
results: BlogResearchResponse | null;
}
export interface ResearchWizardProps {
onComplete?: (results: BlogResearchResponse) => void;
onCancel?: () => void;
initialKeywords?: string[];
initialIndustry?: string;
initialTargetAudience?: string;
initialResearchMode?: ResearchMode;
initialConfig?: ResearchConfig;
initialResults?: BlogResearchResponse | null;
}
```
### Intent Types
```typescript
// intent.types.ts
export interface ResearchIntent {
primary_question: string;
research_goals: string[];
deliverables: string[];
industry: string;
target_audience: string;
}
export interface ResearchQuery {
query: string;
provider: 'exa' | 'tavily' | 'google';
justification?: string;
}
export interface IntentDrivenResearchResult {
summary: string;
deliverables: {
statistics: StatisticWithCitation[];
expert_quotes: ExpertQuote[];
case_studies: CaseStudySummary[];
trends: TrendAnalysis[];
};
sources: Source[];
analysis: string;
}
```
---
## 🧪 Testing
### Standalone Testing
Navigate to `/research-test` for isolated testing:
- Test research flow
- Debug intent analysis
- Review results
- Export data
### Integration Testing
1. Import `ResearchWizard` in your component
2. Test with various initial data
3. Verify `onComplete` callback
4. Check error handling
---
## 🚀 Best Practices
### 1. Always Provide Initial Data When Available
```typescript
// Good: Pre-fill from user data
<ResearchWizard
initialIndustry={userProfile.industry}
initialTargetAudience={userProfile.targetAudience}
/>
// Avoid: Empty wizard when data is available
<ResearchWizard />
```
### 2. Handle Results Properly
```typescript
<ResearchWizard
onComplete={(results) => {
// Save results
saveResearchResults(results);
// Use in your component
setResearchData(results);
// Navigate if needed
navigate('/blog-writer', { state: { research: results } });
}}
/>
```
### 3. Use Research Persona
```typescript
// Research persona automatically pre-fills:
// - Industry
// - Target audience
// - Research preferences
// - Provider settings
// No additional code needed - it's automatic!
```
---
## 🔄 Migration from Old Architecture
### Old Architecture (Deprecated)
- 4-step wizard (StepKeyword → StepOptions → StepProgress → StepResults)
- Strategy pattern (Basic/Comprehensive/Targeted modes)
- Rule-based parameter optimization
### New Architecture
- 3-step wizard (ResearchInput → StepProgress → StepResults)
- Intent-driven (AI infers intent)
- Unified AI analyzer (single call)
- AI-optimized parameters
### Migration Steps
1. Replace old wizard components with `ResearchWizard`
2. Remove mode selection UI (handled by AI)
3. Update API calls to use intent-driven endpoints
4. Update result handling for new result structure
---
## 📚 Additional Resources
- **Architecture Rules**: `.cursor/rules/researcher-architecture.mdc`
- **Implementation Guide**: `RESEARCH_WIZARD_IMPLEMENTATION.md`
- **Intent-Driven Guide**: `INTENT_DRIVEN_RESEARCH_GUIDE.md`
- **Current Architecture**: `CURRENT_ARCHITECTURE_OVERVIEW.md`
---
## ✅ Implementation Status
- ✅ Intent-driven research implemented
- ✅ UnifiedResearchAnalyzer working
- ✅ IntentAwareAnalyzer working
- ✅ Google Trends integrated
- ✅ Research persona integrated
- ✅ My Projects feature (auto-save)
- ✅ Component refactoring complete
---
**Status**: Current and Accurate

459
docs/ALwrity Researcher/RESEARCH_TEMPLATES_IMPROVEMENT_PLAN.md Normal file
View File

@@ -0,0 +1,459 @@
# Research Templates Improvement Plan
**Date**: 2025-01-29
**Status**: Planning & Implementation Guide
---
## 📊 Current State: Research Presets
### What We Have
- **AI-Generated Presets**: Generated from research persona based on user's onboarding data
- **Rule-Based Presets**: Fallback presets when persona doesn't exist
- **Quick Start Presets**: Displayed in ResearchTest page sidebar
- **Preset Structure**: Includes name, keywords, industry, target audience, research mode, config, icon, gradient
### Current Limitations
1. **No User-Created Templates**: Users can't save their own research configurations
2. **No Template Management**: No way to edit, delete, or organize templates
3. **No Template Sharing**: Can't share templates with team members
4. **No Template Categories**: All presets shown together, no organization
5. **No Template Analytics**: Can't see which templates are used most
6. **Limited Customization**: Presets are static, can't be modified after creation
7. **No Template Library**: No community or pre-built templates
---
## 🎯 Proposed Improvements: Research Templates System
### Phase 1: User-Created Templates (High Priority)
#### 1.1 Save Research as Template
**Feature**: Allow users to save any research configuration as a reusable template
**Implementation**:
```typescript
interface ResearchTemplate {
id: string;
name: string;
description?: string;
keywords: string;
industry: string;
target_audience: string;
research_mode: ResearchMode;
config: ResearchConfig;
icon?: string;
gradient?: string;
category?: string;
tags?: string[];
created_at: string;
updated_at: string;
usage_count: number;
is_favorite: boolean;
is_public: boolean; // For future sharing
}
```
**UI Components**:
- "Save as Template" button in IntentConfirmationPanel (after research completes)
- Template name input dialog
- Template description (optional)
- Category/tag selection
**Backend**:
- New endpoint: `POST /api/research/templates/save`
- Store templates in database (new `research_templates` table)
- Associate with user_id
#### 1.2 Template Library UI
**Feature**: Display user's saved templates alongside AI-generated presets
**UI Components**:
- Template cards with name, description, usage count
- "Use Template" button
- "Edit Template" button
- "Delete Template" button
- "Favorite" toggle
- Search/filter templates
**Layout**:
```
┌─────────────────────────────────────┐
│ Quick Start Templates │
├─────────────────────────────────────┤
│ [AI Preset 1] [AI Preset 2] ... │
│ │
│ My Templates (5) │
│ [Template 1] [Template 2] ... │
│ │
│ + Create New Template │
└─────────────────────────────────────┘
```
#### 1.3 Template Management
**Feature**: Edit, delete, duplicate, and organize templates
**Actions**:
- **Edit**: Modify template name, keywords, config
- **Delete**: Remove template with confirmation
- **Duplicate**: Create copy of template
- **Favorite**: Mark frequently used templates
- **Category**: Organize into categories (e.g., "Marketing", "Technical", "Competitive Analysis")
---
### Phase 2: Enhanced Template Features (Medium Priority)
#### 2.1 Template Categories & Tags
**Feature**: Organize templates with categories and tags
**Categories**:
- Content Marketing
- Competitive Analysis
- Industry Trends
- Technical Research
- Product Research
- Custom categories
**Tags**:
- Multiple tags per template
- Filter by tags
- Tag suggestions based on keywords
#### 2.2 Template Analytics
**Feature**: Track template usage and effectiveness
**Metrics**:
- Usage count (how many times used)
- Last used date
- Success rate (research completion)
- Average research time
- Most popular templates
**UI**:
- Show usage stats on template cards
- "Most Used" section
- "Recently Used" section
#### 2.3 Smart Template Suggestions
**Feature**: AI suggests templates based on user behavior
**Logic**:
- Suggest templates based on:
- Similar keywords used before
- Same industry/audience
- Time of day/week patterns
- Recent research topics
**UI**:
- "Suggested for You" section
- "Based on your recent research" badge
---
### Phase 3: Advanced Template Features (Low Priority)
#### 3.1 Template Sharing
**Feature**: Share templates with team members or community
**Implementation**:
- Public/private toggle
- Share link generation
- Team workspace templates
- Template marketplace (future)
#### 3.2 Template Variables
**Feature**: Templates with placeholders that users can fill
**Example**:
```typescript
{
name: "Competitive Analysis: {company}",
keywords: "Research {company} marketing strategies and product positioning",
// User fills in {company} when using template
}
```
**UI**:
- Variable input dialog when using template
- Pre-fill common variables from user data
#### 3.3 Template Workflows
**Feature**: Chain multiple templates together
**Use Case**:
1. Run "Industry Trends" template
2. Then run "Competitive Analysis" template
3. Then run "Content Ideas" template
**UI**:
- "Create Workflow" button
- Drag-and-drop template ordering
- Save workflow as single template
---
## 🏗️ Implementation Plan
### Step 1: Database Schema
```sql
CREATE TABLE research_templates (
id VARCHAR(100) PRIMARY KEY,
user_id VARCHAR(100) NOT NULL,
name VARCHAR(200) NOT NULL,
description TEXT,
keywords TEXT NOT NULL,
industry VARCHAR(100),
target_audience VARCHAR(200),
research_mode VARCHAR(20),
config JSON NOT NULL,
icon VARCHAR(10),
gradient VARCHAR(200),
category VARCHAR(100),
tags JSON,
usage_count INT DEFAULT 0,
is_favorite BOOLEAN DEFAULT FALSE,
is_public BOOLEAN DEFAULT FALSE,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
last_used_at DATETIME,
INDEX idx_user_id (user_id),
INDEX idx_category (category),
INDEX idx_created_at (created_at)
);
```
### Step 2: Backend API Endpoints
```python
# backend/api/research/router.py
@router.post("/templates/save")
async def save_research_template(
request: SaveTemplateRequest,
current_user: Dict = Depends(get_current_user)
):
"""Save current research configuration as template"""
pass
@router.get("/templates")
async def get_user_templates(
current_user: Dict = Depends(get_current_user),
category: Optional[str] = None,
favorite_only: bool = False
):
"""Get user's saved templates"""
pass
@router.put("/templates/{template_id}")
async def update_template(
template_id: str,
request: UpdateTemplateRequest,
current_user: Dict = Depends(get_current_user)
):
"""Update existing template"""
pass
@router.delete("/templates/{template_id}")
async def delete_template(
template_id: str,
current_user: Dict = Depends(get_current_user)
):
"""Delete template"""
pass
@router.post("/templates/{template_id}/use")
async def use_template(
template_id: str,
current_user: Dict = Depends(get_current_user)
):
"""Use template and increment usage count"""
pass
```
### Step 3: Frontend Components
#### 3.1 TemplateCard Component
```typescript
interface TemplateCardProps {
template: ResearchTemplate;
onUse: (template: ResearchTemplate) => void;
onEdit: (template: ResearchTemplate) => void;
onDelete: (templateId: string) => void;
onToggleFavorite: (templateId: string) => void;
}
```
#### 3.2 TemplateLibrary Component
```typescript
interface TemplateLibraryProps {
aiPresets: ResearchPreset[];
userTemplates: ResearchTemplate[];
onUseTemplate: (template: ResearchTemplate | ResearchPreset) => void;
onCreateTemplate: () => void;
}
```
#### 3.3 SaveTemplateDialog Component
```typescript
interface SaveTemplateDialogProps {
open: boolean;
onClose: () => void;
onSave: (template: Partial<ResearchTemplate>) => void;
initialData: {
keywords: string;
industry: string;
target_audience: string;
research_mode: ResearchMode;
config: ResearchConfig;
};
}
```
### Step 4: Integration Points
#### 4.1 IntentConfirmationPanel
- Add "Save as Template" button after research configuration is confirmed
- Show template icon if current config matches a saved template
#### 4.2 ResearchTest Page
- Replace "Quick Start Presets" with "Template Library"
- Show AI presets + user templates
- Add "Create Template" button
#### 4.3 ResearchWizard
- Accept template as initial data
- Pre-fill all fields from template
- Track template usage
---
## 📋 Implementation Checklist
### Phase 1: Core Template System
- [ ] Create database schema for `research_templates`
- [ ] Create Pydantic models for templates
- [ ] Implement backend API endpoints (save, get, update, delete, use)
- [ ] Create frontend TypeScript interfaces
- [ ] Build TemplateCard component
- [ ] Build TemplateLibrary component
- [ ] Build SaveTemplateDialog component
- [ ] Integrate "Save as Template" in IntentConfirmationPanel
- [ ] Update ResearchTest page to show templates
- [ ] Add template usage tracking
### Phase 2: Enhanced Features
- [ ] Add category system
- [ ] Add tag system
- [ ] Implement template search/filter
- [ ] Add template analytics (usage count, last used)
- [ ] Add favorite functionality
- [ ] Add template sorting (most used, recently used, alphabetical)
### Phase 3: Advanced Features
- [ ] Template sharing (public/private)
- [ ] Template variables/placeholders
- [ ] Template workflows
- [ ] Template marketplace (future)
---
## 🎨 UI/UX Design Considerations
### Template Card Design
```
┌─────────────────────────────────┐
│ 📊 Competitive Analysis ⭐ │
│ │
│ Research top competitors in... │
│ │
│ Marketing • B2B SaaS │
│ │
│ Used 12 times • Last: 2d ago │
│ │
│ [Use] [Edit] [Delete] │
└─────────────────────────────────┘
```
### Template Library Layout
```
┌─────────────────────────────────────────┐
│ Template Library │
├─────────────────────────────────────────┤
│ [Search templates...] │
│ │
│ Categories: [All] [Marketing] [Tech] │
│ │
│ ┌─ AI-Generated Presets ───────────┐ │
│ │ [Preset 1] [Preset 2] [Preset 3] │ │
│ └───────────────────────────────────┘ │
│ │
│ ┌─ My Templates (5) ────────────────┐ │
│ │ [Template 1] [Template 2] ... │ │
│ └───────────────────────────────────┘ │
│ │
│ [+ Create New Template] │
└─────────────────────────────────────────┘
```
---
## 🔄 Migration from Presets to Templates
### Backward Compatibility
- Keep AI-generated presets as "read-only templates"
- Show presets in same UI as templates
- Allow users to "Save Preset as Template" to customize
### Data Migration
- No migration needed (presets are generated on-demand)
- Templates are new feature, doesn't affect existing presets
---
## 📊 Success Metrics
### Adoption Metrics
- % of users who create at least one template
- Average templates per user
- Template usage rate (templates used / total research operations)
### Engagement Metrics
- Most used templates
- Template reuse rate
- Time saved (estimated based on template usage)
### Quality Metrics
- Research completion rate with templates vs without
- User satisfaction with templates
- Template effectiveness (research quality)
---
## 🚀 Quick Win: Minimal Viable Template System
### MVP Features (Can implement in 2-3 days)
1. **Save Template**: Button in IntentConfirmationPanel
2. **Template List**: Show user templates in ResearchTest sidebar
3. **Use Template**: Click template to pre-fill research wizard
4. **Delete Template**: Remove template with confirmation
### MVP Database
- Simple table with: id, user_id, name, keywords, industry, target_audience, research_mode, config, created_at
### MVP UI
- Simple template cards in sidebar
- "Save as Template" button
- Basic template list
---
## ✅ Next Steps
1. **Review & Approve**: Get feedback on template system design
2. **Start with MVP**: Implement minimal viable template system
3. **Iterate**: Add features based on user feedback
4. **Scale**: Add advanced features (sharing, workflows, etc.)
---
**Status**: Ready for Implementation

664
docs/ALwrity Researcher/RESEARCH_WIZARD_IMPLEMENTATION.md
View File

@@ -1,346 +1,434 @@
# Research Wizard Implementation Summary
# Research Wizard Implementation Guide
## Implementation Complete
A modular, pluggable research component has been successfully implemented with wizard-based UI that can be tested independently and integrated into the blog writer.
**Date**: 2025-01-29
**Status**: Updated for Intent-Driven Research Architecture
---
## Backend Implementation
## 📋 Overview
### 1. Research Models (blog_models.py)
The Research Wizard is a 3-step, intent-driven research system that uses AI to infer user intent, generate targeted queries, and optimize research parameters before executing research operations.
**New Enums:**
- `ResearchMode`: `BASIC`, `COMPREHENSIVE`, `TARGETED`
- `SourceType`: `WEB`, `ACADEMIC`, `NEWS`, `INDUSTRY`, `EXPERT`
- `DateRange`: `LAST_WEEK` through `ALL_TIME`
**New Models:**
```python
class ResearchConfig(BaseModel):
mode: ResearchMode = ResearchMode.BASIC
date_range: Optional[DateRange] = None
source_types: List[SourceType] = []
max_sources: int = 10
include_statistics: bool = True
include_expert_quotes: bool = True
include_competitors: bool = True
include_trends: bool = True
```
**Enhanced BlogResearchRequest:**
- Added `research_mode: Optional[ResearchMode]`
- Added `config: Optional[ResearchConfig]`
- **Backward compatible** - defaults to existing behavior
### 2. Strategy Pattern (research_strategies.py)
**New file:** `backend/services/blog_writer/research/research_strategies.py`
**Three Strategy Classes:**
1. **BasicResearchStrategy**: Quick keyword-focused analysis
2. **ComprehensiveResearchStrategy**: Full analysis with all components
3. **TargetedResearchStrategy**: Customizable components based on config
**Factory Function:**
```python
get_strategy_for_mode(mode: ResearchMode) -> ResearchStrategy
```
### 3. Service Integration (research_service.py)
**Key Changes:**
- Imports strategy factory and models
- Uses strategy pattern in both `research()` and `research_with_progress()` methods
- Automatically selects strategy based on `research_mode`
- Backward compatible - defaults to BASIC if not specified
**Line Changes:**
```python
# Lines 88-96: Determine research mode and get appropriate strategy
research_mode = request.research_mode or ResearchMode.BASIC
config = request.config or ResearchConfig(mode=research_mode)
strategy = get_strategy_for_mode(research_mode)
logger.info(f"Using research mode: {research_mode.value}")
# Build research prompt based on strategy
research_prompt = strategy.build_research_prompt(topic, industry, target_audience, config)
```
**Key Features**:
- Intent-driven research (AI infers what user wants to research)
- 3-step wizard flow
- Unified AI analyzer (single call for intent + queries + params)
- Provider optimization (Exa → Tavily → Google)
- Research persona integration
- Google Trends integration
---
## Frontend Implementation
## 🏗️ Architecture
### 4. Component Structure
**New Directory:** `frontend/src/components/Research/`
### Current 3-Step Wizard Flow
```
Research/
├── index.tsx # Main exports
├── ResearchWizard.tsx # Main wizard container
Step 1: ResearchInput
├── User enters keywords/topic
├── Selects industry & target audience
├── Clicks "Intent & Options" button
└── Shows IntentConfirmationPanel
Step 2: StepProgress (Auto-navigated)
├── Research execution in progress
├── Polling for completion
└── Auto-navigates to Step 3 on completion
Step 3: StepResults
├── IntentResultsDisplay (tabbed view)
│ ├── Summary tab
│ ├── Deliverables tab
│ ├── Sources tab
│ └── Analysis tab
└── Legacy results (fallback)
```
### Component Structure
```
frontend/src/components/Research/
├── ResearchWizard.tsx # Main wizard orchestrator
├── steps/
│ ├── StepKeyword.tsx # Step 1: Keyword input
│ ├── StepOptions.tsx # Step 2: Mode selection (3 cards)
│ ├── StepProgress.tsx # Step 3: Progress display
│ └── StepResults.tsx # Step 4: Results display
│ ├── ResearchInput.tsx # Step 1: Input + Intent & Options
│ ├── StepProgress.tsx # Step 2: Progress/polling
│ ├── StepResults.tsx # Step 3: Results display
│ └── components/
│ ├── ResearchInputHeader.tsx # Header with Advanced toggle
│ ├── ResearchInputContainer.tsx # Main input with Intent & Options button
│ ├── IntentConfirmationPanel/ # Intent review/edit panel
│ │ ├── IntentConfirmationPanel.tsx
│ │ ├── IntentHeader.tsx
│ │ ├── PrimaryQuestionEditor.tsx
│ │ ├── IntentSummaryGrid.tsx
│ │ ├── DeliverablesSelector.tsx
│ │ ├── ResearchQueriesSection.tsx
│ │ ├── TrendsConfigSection.tsx
│ │ └── AdvancedProviderOptionsSection.tsx
│ ├── IntentResultsDisplay.tsx # Tabbed results (Summary, Deliverables, Sources, Analysis)
│ ├── AdvancedOptionsSection.tsx # Exa/Tavily options
│ ├── ProviderChips.tsx # Provider availability display
│ └── ...
├── hooks/
│ ├── useResearchWizard.ts # Wizard state management
│ └── useResearchExecution.ts # API calls and polling
├── types/
│ └── research.types.ts # TypeScript interfaces
├── utils/
│ └── researchUtils.ts # Utility functions
└── integrations/
└── BlogWriterAdapter.tsx # Blog writer integration adapter
│ ├── useResearchWizard.ts # Wizard state management
│ ├── useResearchExecution.ts # API calls and polling
│ └── useIntentResearch.ts # Intent-driven research flow
└── types/
├── research.types.ts # Wizard state types
└── intent.types.ts # Intent-driven types
```
### 5. Wizard Components
**ResearchWizard.tsx:**
- Main container with progress bar
- Step indicators (Setup → Options → Research → Results)
- Navigation footer with Back/Next buttons
- Responsive layout
**StepKeyword.tsx:**
- Keywords textarea
- Industry dropdown (16 options)
- Target audience input
- Validation for keyword requirements
**StepOptions.tsx:**
- Three mode cards (Basic, Comprehensive, Targeted)
- Visual selection feedback
- Feature lists per mode
- Hover effects
**StepProgress.tsx:**
- Real-time progress updates
- Progress messages display
- Cancel button
- Auto-advance to results on completion
**StepResults.tsx:**
- Displays research results using existing `ResearchResults` component
- Export JSON button
- Start new research button
### 6. Hooks
**useResearchWizard.ts:**
- State management for wizard steps
- localStorage persistence
- Step navigation (next/back)
- Validation per step
- Reset functionality
**useResearchExecution.ts:**
- Research execution via API
- Cache checking
- Polling integration
- Error handling
- Progress tracking
### 7. Test Page (ResearchTest.tsx)
**Location:** `frontend/src/pages/ResearchTest.tsx`
**Route:** `/research-test`
**Features:**
- Quick preset buttons (3 samples)
- Debug panel with JSON export
- Performance metrics display
- Cache state visualization
- Research statistics summary
**Sample Presets:**
1. AI Marketing Tools
2. Small Business SEO
3. Content Strategy
### 8. Type Definitions
**research.types.ts:**
- `WizardState`
- `WizardStepProps`
- `ResearchWizardProps`
- `ModeCardInfo`
**blogWriterApi.ts:**
- `ResearchMode` type union
- `SourceType` type union
- `DateRange` type union
- `ResearchConfig` interface
- Updated `BlogResearchRequest` interface
---
## Integration
## 🔄 Research Flow
### 9. Blog Writer API (blogWriterApi.ts)
### Step 1: ResearchInput
**Enhanced Interface:**
**Purpose**: User provides research topic and triggers intent analysis
**User Actions**:
1. Enter keywords/topic in textarea
2. Select industry (optional, pre-filled from persona)
3. Select target audience (optional, pre-filled from persona)
4. Click "Intent & Options" button (enabled after 2+ words)
**What Happens**:
```typescript
export interface BlogResearchRequest {
keywords: string[];
topic?: string;
industry?: string;
target_audience?: string;
tone?: string;
word_count_target?: number;
persona?: PersonaInfo;
research_mode?: ResearchMode; // NEW
config?: ResearchConfig; // NEW
// User clicks "Intent & Options"
onClick={() => {
execution.analyzeIntent(state.keywords, state.industry, state.target_audience);
}}
```
**Backend Call**:
- `POST /api/research/intent/analyze`
- `UnifiedResearchAnalyzer` analyzes input
- Returns: `ResearchIntent`, `ResearchQuery[]`, `OptimizedConfig`
**UI Update**:
- Shows `IntentConfirmationPanel` below input
- Displays inferred intent, queries, and optimized config
### Step 2: IntentConfirmationPanel
**Purpose**: User reviews and edits AI-inferred intent before execution
**Components**:
- **PrimaryQuestionEditor**: Editable primary research question
- **IntentSummaryGrid**: Quick summary (industry, audience, mode, deliverables)
- **DeliverablesSelector**: Toggle specific deliverables (statistics, quotes, case studies, etc.)
- **ResearchQueriesSection**: List of generated queries (selectable, editable)
- **TrendsConfigSection**: Google Trends keywords (if applicable)
- **AdvancedProviderOptionsSection**: Exa/Tavily options with AI justifications
**User Actions**:
1. Review inferred intent
2. Edit primary question (optional)
3. Toggle deliverables (optional)
4. Select/edit queries (optional)
5. Review provider settings (optional)
6. Click "Research" button
**What Happens**:
```typescript
// User clicks "Research"
onExecute={async (selectedQueries) => {
const result = await execution.executeIntentResearch(state, selectedQueries);
if (result?.success) {
onUpdate({ currentStep: 3 }); // Navigate to results
}
}}
```
**Backend Call**:
- `POST /api/research/intent/research`
- Executes selected queries via Exa/Tavily/Google
- `IntentAwareAnalyzer` analyzes results based on intent
- Returns: `IntentDrivenResearchResult`
**UI Update**:
- Shows `StepProgress` (auto-navigated)
- Polls for completion
- Auto-navigates to Step 3 on completion
### Step 3: StepResults
**Purpose**: Display research results in organized tabs
**Components**:
- **IntentResultsDisplay**: Tabbed view for intent-driven results
- **Summary Tab**: AI-generated overview
- **Deliverables Tab**: Extracted statistics, quotes, case studies, trends
- **Sources Tab**: Citations with credibility scores
- **Analysis Tab**: Deep insights based on intent
- **Legacy Results**: Fallback for non-intent-driven research
**User Actions**:
- Browse results in different tabs
- Export results (future)
- Start new research
- Save research project (auto-saved)
---
## 🔌 Backend Integration
### API Endpoints
#### 1. Intent Analysis
```python
POST /api/research/intent/analyze
Request:
{
"keywords": "AI marketing tools",
"industry": "Technology",
"target_audience": "Marketing professionals"
}
Response:
{
"success": true,
"intent": {
"primary_question": "...",
"research_goals": [...],
"deliverables": [...],
"industry": "...",
"target_audience": "..."
},
"queries": [
{
"query": "...",
"provider": "exa",
"justification": "..."
}
],
"optimized_config": {
"provider": "exa",
"exa_category": "company",
"provider_justification": "..."
},
"trends_config": {
"keywords": [...],
"enabled": true
}
}
```
### 10. App Routing (App.tsx)
#### 2. Intent-Driven Research
```python
POST /api/research/intent/research
**New Route:**
```typescript
<Route path="/research-test" element={<ResearchTest />} />
Request:
{
"intent": {...},
"queries": [...],
"config": {...}
}
Response:
{
"success": true,
"result": {
"summary": "...",
"deliverables": {
"statistics": [...],
"expert_quotes": [...],
"case_studies": [...],
"trends": [...]
},
"sources": [...],
"analysis": "..."
}
}
```
### 11. Integration Adapter
### Backend Services
**BlogWriterAdapter.tsx:**
- Wrapper component for easy integration
- Usage examples included
- Clean interface for BlogWriter
#### UnifiedResearchAnalyzer
**Location**: `backend/services/research/intent/unified_research_analyzer.py`
**Purpose**: Single AI call for intent inference, query generation, and parameter optimization
**Key Method**:
```python
async def analyze(
user_input: str,
industry: Optional[str] = None,
target_audience: Optional[str] = None,
user_id: Optional[str] = None
) -> UnifiedResearchAnalysis:
"""
Analyzes user input and returns:
- Inferred research intent
- Generated research queries
- Optimized provider configuration
- Google Trends keywords (if applicable)
"""
```
#### IntentAwareAnalyzer
**Location**: `backend/services/research/intent/intent_aware_analyzer.py`
**Purpose**: Analyzes raw research results based on user intent
**Key Method**:
```python
async def analyze(
raw_results: Dict[str, Any],
intent: ResearchIntent,
user_id: Optional[str] = None
) -> IntentDrivenResearchResult:
"""
Analyzes raw results and extracts:
- Statistics with citations
- Expert quotes
- Case studies
- Trends
- Comparisons
- Based on user's research intent
"""
```
---
## Documentation
## 🎨 Frontend Hooks
### 12. Integration Guide
### useResearchWizard
**Location**: `frontend/src/components/Research/hooks/useResearchWizard.ts`
**File:** `docs/RESEARCH_COMPONENT_INTEGRATION.md`
**Purpose**: Manages wizard state (step, keywords, industry, config, results)
**Contents:**
- Architecture overview
- Usage examples
- Backend API details
- Research modes explained
- Configuration options
- Testing instructions
- Migration path
- Troubleshooting guide
**Key Methods**:
```typescript
const wizard = useResearchWizard(initialKeywords, ...);
wizard.state.currentStep; // Current step (1, 2, or 3)
wizard.state.keywords; // Research keywords
wizard.state.industry; // Selected industry
wizard.state.config; // Research configuration
wizard.state.results; // Research results
wizard.updateState({ ... }); // Update state
wizard.nextStep(); // Navigate to next step
wizard.previousStep(); // Navigate to previous step
```
### useResearchExecution
**Location**: `frontend/src/components/Research/hooks/useResearchExecution.ts`
**Purpose**: Handles API calls and research execution
**Key Methods**:
```typescript
const execution = useResearchExecution();
execution.analyzeIntent(keywords, industry, audience);
execution.intentAnalysis; // Result from intent analysis
execution.confirmIntent(intent); // Confirm/modify intent
execution.executeIntentResearch(state, queries); // Execute research
execution.isAnalyzingIntent; // Loading state
execution.isExecuting; // Execution state
```
### useIntentResearch
**Location**: `frontend/src/components/Research/hooks/useIntentResearch.ts`
**Purpose**: Manages intent-driven research flow
**Key Methods**:
```typescript
const intentResearch = useIntentResearch();
intentResearch.analyzeIntent(userInput);
intentResearch.confirmIntent(intent);
intentResearch.executeResearch(queries);
```
---
## Key Features
## 🔗 Integration Examples
### Research Modes
### Standalone Usage
```typescript
import { ResearchWizard } from '../components/Research';
**Basic Mode:**
- Quick keyword analysis
- Primary & secondary keywords
- Trends overview
- Top 5 content angles
- Key statistics
<ResearchWizard
onComplete={(results) => {
console.log('Research complete:', results);
}}
onCancel={() => {
console.log('Research cancelled');
}}
/>
```
**Comprehensive Mode:**
- All basic features
- Expert quotes & opinions
- Competitor analysis
- Market forecasts
- Best practices & case studies
- Content gaps identification
### With Initial Data
```typescript
<ResearchWizard
initialKeywords={['AI marketing tools']}
initialIndustry="Technology"
initialTargetAudience="Marketing professionals"
initialResearchMode="comprehensive"
initialConfig={{
provider: 'exa',
max_sources: 20,
include_statistics: true
}}
initialResults={savedResults} // For restoring saved projects
/>
```
**Targeted Mode:**
- Selectable components
- Customizable filters
- Date range options
- Source type filtering
### Blog Writer Integration
```typescript
// In BlogWriter component
import { BlogWriterAdapter } from '../components/Research/integrations/BlogWriterAdapter';
### User Experience
1. **Step-by-step wizard** with clear progress
2. **Visual mode selection** with cards
3. **Real-time progress** with live updates
4. **Comprehensive results** with export capability
5. **Error handling** with retry options
6. **Cache integration** for instant results
### Developer Experience
1. **Modular architecture** - standalone components
2. **Type safety** - full TypeScript interfaces
3. **Reusable hooks** - state and execution management
4. **Test page** - isolated testing environment
5. **Documentation** - comprehensive guides
<BlogWriterAdapter
onResearchComplete={(researchData) => {
// Use research data in blog generation
}}
/>
```
---
## Testing
## 🎯 Key Differences from Old Architecture
### Quick Test
### Old Architecture (Deprecated)
- **4-Step Wizard**: StepKeyword → StepOptions → StepProgress → StepResults
- **Mode Selection**: User manually selects Basic/Comprehensive/Targeted
- **Strategy Pattern**: Different strategies for different modes
- **Rule-Based**: Rule-based parameter optimization
1. Navigate to `http://localhost:3000/research-test`
2. Click "AI Marketing Tools" preset
3. Select "Comprehensive" mode
4. Watch progress updates
5. Review results with export
### Integration Test
1. Compare `/research-test` wizard UI
2. Compare `/blog-writer` current UI
3. Test both research workflows
4. Verify caching works across both
### Current Architecture
- **3-Step Wizard**: ResearchInput → StepProgress → StepResults
- **Intent-Driven**: AI infers intent, no manual mode selection
- **Unified Analyzer**: Single AI call for intent + queries + params
- **AI-Optimized**: AI-driven parameter optimization with justifications
---
## Backward Compatibility
## 📝 Notes
- Existing API calls continue working
- No breaking changes to BlogWriter
- Optional parameters default to current behavior
- Cache infrastructure shared
- All existing features preserved
- **Backward Compatibility**: Legacy research endpoints still work for non-intent-driven research
- **Research Persona**: Persona data pre-fills industry, audience, and suggests presets
- **Google Trends**: Automatically included when relevant to research topic
- **Auto-Save**: Research projects are automatically saved to Asset Library upon completion
---
## File Summary
## ✅ Implementation Status
**Backend (4 files):**
- Modified: `blog_models.py`, `research_service.py`
- Created: `research_strategies.py`
**Frontend (13 files):**
- Created: `ResearchWizard.tsx`, 4 step components, 2 hooks, types, utils, adapter, test page
- Modified: `App.tsx`, `blogWriterApi.ts`
**Documentation (2 files):**
- Created: `RESEARCH_COMPONENT_INTEGRATION.md`, `RESEARCH_WIZARD_IMPLEMENTATION.md`
- ✅ 3-step wizard implemented
- ✅ Intent-driven research flow working
- ✅ UnifiedResearchAnalyzer integrated
- ✅ IntentAwareAnalyzer integrated
- ✅ Google Trends integrated
- ✅ Research persona integration
- ✅ My Projects feature (auto-save)
- ✅ Component refactoring complete
---
## Next Steps
1. ✅ **Test the wizard** at `/research-test`
2. ✅ **Review integration guide** in docs
3. ⏳ **Integrate into BlogWriter** using adapter (optional)
4. ⏳ **Gather user feedback** on wizard vs CopilotKit UI
5. ⏳ **Add more presets** if needed
---
## Benefits Delivered
- Modular & Pluggable: Standalone component
- Testable: Dedicated test page
- Backward Compatible: No breaking changes
- Reusable: Can be used anywhere in the app
- Extensible: Easy to add new modes or features
- Documented: Comprehensive guides
- Type Safe: Full TypeScript support
- Production Ready: No linting errors
---
Implementation Date: Current Session
Status: Complete & Ready for Testing
**Status**: Current and Accurate