117 lines
4.5 KiB
TypeScript
117 lines
4.5 KiB
TypeScript
/**
|
|
* Research API Types and Interfaces
|
|
*
|
|
* Dedicated types for the Research Engine, separate from Blog Writer.
|
|
* This ensures proper separation of concerns.
|
|
*
|
|
* Author: ALwrity Team
|
|
* Version: 1.0
|
|
*/
|
|
|
|
// ============================================================================
|
|
// Core Research Types
|
|
// ============================================================================
|
|
|
|
export type ResearchMode = 'basic' | 'comprehensive' | 'targeted';
|
|
export type ResearchProvider = 'google' | 'exa' | 'tavily';
|
|
export type SourceType = 'web' | 'academic' | 'news' | 'industry' | 'expert';
|
|
export type DateRange = 'last_week' | 'last_month' | 'last_3_months' | 'last_6_months' | 'last_year' | 'all_time';
|
|
|
|
// ============================================================================
|
|
// Research Source
|
|
// ============================================================================
|
|
|
|
export interface ResearchSource {
|
|
title: string;
|
|
url: string;
|
|
excerpt?: string;
|
|
credibility_score?: number;
|
|
published_at?: string;
|
|
index?: number;
|
|
source_type?: string;
|
|
}
|
|
|
|
// ============================================================================
|
|
// Research Configuration
|
|
// ============================================================================
|
|
|
|
export interface ResearchConfig {
|
|
mode?: ResearchMode;
|
|
provider?: ResearchProvider;
|
|
date_range?: DateRange;
|
|
source_types?: SourceType[];
|
|
max_sources?: number;
|
|
include_statistics?: boolean;
|
|
include_expert_quotes?: boolean;
|
|
include_competitors?: boolean;
|
|
include_trends?: boolean;
|
|
|
|
// Exa-specific options
|
|
exa_category?: string;
|
|
exa_include_domains?: string[];
|
|
exa_exclude_domains?: string[];
|
|
exa_search_type?: 'auto' | 'keyword' | 'neural' | 'fast' | 'deep';
|
|
exa_num_results?: number;
|
|
exa_date_filter?: string; // ISO date string for startPublishedDate (e.g., "2025-01-01T00:00:00.000Z")
|
|
exa_end_published_date?: string; // ISO date string for endPublishedDate
|
|
exa_start_crawl_date?: string; // ISO date string for startCrawlDate
|
|
exa_end_crawl_date?: string; // ISO date string for endCrawlDate
|
|
exa_include_text?: string[]; // Text that must be present in webpage text (max 1 string, up to 5 words)
|
|
exa_exclude_text?: string[]; // Text that must not be present in webpage text (max 1 string, up to 5 words)
|
|
exa_highlights?: boolean;
|
|
exa_highlights_num_sentences?: number; // Number of sentences per highlight (default: 2)
|
|
exa_highlights_per_url?: number; // Number of highlights per URL (default: 3)
|
|
exa_context?: boolean | { maxCharacters?: number }; // Context string: boolean or object with maxCharacters
|
|
exa_context_max_characters?: number; // Max characters for context string (recommended: 10000+)
|
|
exa_text_max_characters?: number; // Max characters for full page text (default: 1000)
|
|
exa_summary_query?: string; // Custom query for LLM-generated summary
|
|
exa_additional_queries?: string[]; // Additional query variations for Deep search (only works with type="deep")
|
|
|
|
// Tavily-specific options
|
|
tavily_topic?: 'general' | 'news' | 'finance';
|
|
tavily_search_depth?: 'basic' | 'advanced';
|
|
tavily_include_domains?: string[];
|
|
tavily_exclude_domains?: string[];
|
|
tavily_include_answer?: boolean | 'basic' | 'advanced';
|
|
tavily_include_raw_content?: boolean | 'markdown' | 'text';
|
|
tavily_include_images?: boolean;
|
|
tavily_include_image_descriptions?: boolean;
|
|
tavily_include_favicon?: boolean;
|
|
tavily_time_range?: 'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y';
|
|
tavily_start_date?: string; // YYYY-MM-DD
|
|
tavily_end_date?: string; // YYYY-MM-DD
|
|
tavily_country?: string;
|
|
tavily_chunks_per_source?: number; // 1-3
|
|
tavily_auto_parameters?: boolean;
|
|
}
|
|
|
|
// ============================================================================
|
|
// Research Response (Generic)
|
|
// ============================================================================
|
|
|
|
export interface ResearchResponse {
|
|
success: boolean;
|
|
keywords?: string[];
|
|
sources: ResearchSource[];
|
|
keyword_analysis: Record<string, any>;
|
|
competitor_analysis: Record<string, any>;
|
|
suggested_angles: string[];
|
|
search_queries?: string[];
|
|
original_keywords?: string[];
|
|
error_message?: string;
|
|
}
|
|
|
|
// ============================================================================
|
|
// Research Request
|
|
// ============================================================================
|
|
|
|
export interface ResearchRequest {
|
|
keywords: string[];
|
|
topic?: string;
|
|
industry?: string;
|
|
target_audience?: string;
|
|
tone?: string;
|
|
research_mode?: ResearchMode;
|
|
config?: ResearchConfig;
|
|
}
|