ALwrity/docs/ALwrity Researcher/RESEARCH_API_SEPARATION.md

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