ALwrity/docs/ALwrity Researcher/RESEARCH_COMPONENT_INTEGRATION.md

Research Component Integration Guide

Date: 2025-01-29
Status: Updated for Intent-Driven Research Architecture

---

📋 Overview

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.

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

---

🏗️ 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

Component Structure

frontend/src/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
├── hooks/
│   ├── 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

---

🔌 Integration

Basic Integration

import { ResearchWizard } from '../components/Research';

function MyComponent() {
  return (
    <ResearchWizard
      onComplete={(results) => {
        console.log('Research complete:', results);
        // Use results in your component
      }}
      onCancel={() => {
        console.log('Research cancelled');
      }}
    />
  );
}

With Initial Data

<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
/>

Blog Writer Integration

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

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

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

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

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:

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:

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

// 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

// 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

// 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

<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

// 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