valyu-js 2.1.7 → 2.2.1

package/README.md

@@ -50,6 +50,116 @@ console.log(response);
 
 ## API Reference
 
+### DeepResearch Method
+
+The `deepresearch` namespace provides access to Valyu's AI-powered research agent that conducts comprehensive, multi-step research with citations and cost tracking.
+
+```javascript
+// Create a research task
+const task = await valyu.deepresearch.create({
+    input: "What are the latest developments in quantum computing?",
+    model: "lite",                      // "lite" (fast, Haiku) or "heavy" (thorough, Sonnet)
+    outputFormats: ["markdown", "pdf"]  // Output formats
+});
+
+// Wait for completion with progress updates
+const result = await valyu.deepresearch.wait(task.deepresearch_id, {
+    onProgress: (status) => {
+        if (status.progress) {
+            console.log(`Step ${status.progress.current_step}/${status.progress.total_steps}`);
+        }
+    }
+});
+
+console.log(result.output);  // Markdown report
+console.log(result.pdf_url); // PDF download URL
+```
+
+#### DeepResearch Methods
+
+| Method | Description |
+|--------|-------------|
+| `create(options)` | Create a new research task |
+| `status(taskId)` | Get current status of a task |
+| `wait(taskId, options?)` | Wait for task completion with polling |
+| `stream(taskId, callbacks)` | Stream real-time updates |
+| `list(options)` | List all your research tasks |
+| `update(taskId, instruction)` | Add follow-up instruction to running task |
+| `cancel(taskId)` | Cancel a running task |
+| `delete(taskId)` | Delete a task |
+| `togglePublic(taskId, isPublic)` | Make task publicly accessible |
+
+#### DeepResearch Create Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `input` | `string` | *required* | Research query or task description |
+| `model` | `"lite" \| "heavy"` | `"lite"` | Research model - lite (fast) or heavy (thorough) |
+| `outputFormats` | `("markdown" \| "pdf")[]` | `["markdown"]` | Output formats for the report |
+| `strategy` | `string` | - | Natural language research strategy |
+| `search` | `object` | - | Search configuration (type, sources) |
+| `urls` | `string[]` | - | URLs to extract and analyze |
+| `files` | `FileAttachment[]` | - | PDF/image files to analyze |
+| `mcpServers` | `MCPServerConfig[]` | - | MCP tool server configurations |
+| `codeExecution` | `boolean` | `true` | Enable/disable code execution |
+| `previousReports` | `string[]` | - | Previous report IDs for context (max 3) |
+| `webhookUrl` | `string` | - | HTTPS webhook URL for completion notification |
+| `metadata` | `Record<string, any>` | - | Custom metadata key-value pairs |
+
+#### DeepResearch Examples
+
+**Basic Research:**
+```javascript
+const task = await valyu.deepresearch.create({
+    input: "Summarize recent AI safety research",
+    model: "lite"
+});
+
+const result = await valyu.deepresearch.wait(task.deepresearch_id);
+console.log(result.output);
+```
+
+**With Custom Sources:**
+```javascript
+const task = await valyu.deepresearch.create({
+    input: "Latest transformer architecture improvements",
+    search: {
+        searchType: "proprietary",
+        includedSources: ["valyu/valyu-arxiv"]
+    },
+    model: "heavy",
+    outputFormats: ["markdown", "pdf"]
+});
+```
+
+**Streaming Updates:**
+```javascript
+await valyu.deepresearch.stream(task.deepresearch_id, {
+    onProgress: (current, total) => {
+        console.log(`Progress: ${current}/${total}`);
+    },
+    onMessage: (message) => {
+        console.log("Agent:", message);
+    },
+    onComplete: (result) => {
+        console.log("Complete! Cost:", result.usage.total_cost);
+    }
+});
+```
+
+**With File Analysis:**
+```javascript
+const task = await valyu.deepresearch.create({
+    input: "Analyze these research papers and provide key insights",
+    files: [{
+        data: "data:application/pdf;base64,...",
+        filename: "paper.pdf",
+        mediaType: "application/pdf"
+    }],
+    urls: ["https://arxiv.org/abs/2103.14030"]
+});
+```
+
 ### Search Method
 
 The `search()` method is the core of the Valyu SDK. It accepts a query string as the first parameter, followed by optional configuration parameters.

package/dist/index.d.mts

@@ -6,14 +6,14 @@ type ResponseLength = "short" | "medium" | "large" | "max" | number;
 interface SearchResult {
     title: string;
     url: string;
-    content: string;
+    content: string | object | any[];
     description?: string;
     source: string;
-    price: number;
+    source_type?: string;
+    data_type?: DataType;
+    date?: string;
     length: number;
     relevance_score?: number;
-    data_type?: DataType;
-    source_type?: string;
     publication_date?: string;
     id?: string;
     image_url?: Record<string, string>;
@@ -95,6 +95,7 @@ interface AnswerOptions {
     startDate?: string;
     endDate?: string;
     fastMode?: boolean;
+    streaming?: boolean;
 }
 interface SearchMetadata {
     tx_ids: string[];
@@ -109,6 +110,7 @@ interface Cost {
     total_deduction_dollars: number;
     search_deduction_dollars: number;
     ai_deduction_dollars: number;
+    contents_deduction_dollars?: number;
 }
 interface AnswerSuccessResponse {
     success: true;
@@ -126,10 +128,208 @@ interface AnswerErrorResponse {
     error: string;
 }
 type AnswerResponse = AnswerSuccessResponse | AnswerErrorResponse;
+type AnswerStreamChunkType = "search_results" | "content" | "metadata" | "done" | "error";
+interface AnswerStreamChunk {
+    type: AnswerStreamChunkType;
+    search_results?: SearchResult[];
+    content?: string;
+    finish_reason?: string;
+    ai_tx_id?: string;
+    original_query?: string;
+    data_type?: "structured" | "unstructured";
+    search_metadata?: SearchMetadata;
+    ai_usage?: AIUsage;
+    cost?: Cost;
+    error?: string;
+}
+type DeepResearchMode = "lite" | "heavy";
+type DeepResearchStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+type DeepResearchOutputFormat = "markdown" | "pdf" | Record<string, any>;
+type DeepResearchOutputType = "markdown" | "json";
+type ImageType = "chart" | "ai_generated";
+type ChartType = "line" | "bar" | "area";
+interface FileAttachment {
+    data: string;
+    filename: string;
+    mediaType: string;
+    context?: string;
+}
+interface MCPServerConfig {
+    url: string;
+    name?: string;
+    toolPrefix?: string;
+    auth?: {
+        type: "bearer" | "header" | "none";
+        token?: string;
+        headers?: Record<string, string>;
+    };
+    allowedTools?: string[];
+}
+interface DeepResearchSearchConfig {
+    searchType?: "all" | "web" | "proprietary";
+    includedSources?: string[];
+}
+interface DeepResearchCreateOptions {
+    input: string;
+    model?: DeepResearchMode;
+    outputFormats?: DeepResearchOutputFormat[];
+    strategy?: string;
+    search?: DeepResearchSearchConfig;
+    urls?: string[];
+    files?: FileAttachment[];
+    mcpServers?: MCPServerConfig[];
+    codeExecution?: boolean;
+    previousReports?: string[];
+    webhookUrl?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface Progress {
+    current_step: number;
+    total_steps: number;
+}
+interface ChartDataPoint {
+    x: string | number;
+    y: number;
+}
+interface ChartDataSeries {
+    name: string;
+    data: ChartDataPoint[];
+}
+interface ImageMetadata {
+    image_id: string;
+    image_type: ImageType;
+    deepresearch_id: string;
+    title: string;
+    description?: string;
+    image_url: string;
+    s3_key: string;
+    created_at: number;
+    chart_type?: ChartType;
+    x_axis_label?: string;
+    y_axis_label?: string;
+    data_series?: ChartDataSeries[];
+}
+interface DeepResearchSource {
+    title: string;
+    url: string;
+    snippet?: string;
+    description?: string;
+    source?: string;
+    org_id?: string;
+    price?: number;
+    id?: string;
+    doc_id?: number;
+    doi?: string;
+    category?: string;
+    source_id?: number;
+    word_count?: number;
+}
+interface DeepResearchUsage {
+    search_cost: number;
+    contents_cost: number;
+    ai_cost: number;
+    compute_cost: number;
+    total_cost: number;
+}
+interface DeepResearchCreateResponse {
+    success: boolean;
+    deepresearch_id?: string;
+    status?: DeepResearchStatus;
+    model?: DeepResearchMode;
+    created_at?: string;
+    metadata?: Record<string, string | number | boolean>;
+    public?: boolean;
+    webhook_secret?: string;
+    message?: string;
+    error?: string;
+}
+interface DeepResearchStatusResponse {
+    success: boolean;
+    deepresearch_id?: string;
+    status?: DeepResearchStatus;
+    query?: string;
+    mode?: DeepResearchMode;
+    output_formats?: DeepResearchOutputFormat[];
+    created_at?: number;
+    public?: boolean;
+    progress?: Progress;
+    messages?: any[];
+    completed_at?: number;
+    output?: string | Record<string, any>;
+    output_type?: DeepResearchOutputType;
+    pdf_url?: string;
+    images?: ImageMetadata[];
+    sources?: DeepResearchSource[];
+    usage?: DeepResearchUsage;
+    error?: string;
+}
+interface DeepResearchTaskListItem {
+    deepresearch_id: string;
+    query: string;
+    status: DeepResearchStatus;
+    created_at: number;
+    public?: boolean;
+}
+interface DeepResearchListResponse {
+    success: boolean;
+    data?: DeepResearchTaskListItem[];
+    error?: string;
+}
+interface DeepResearchUpdateResponse {
+    success: boolean;
+    message?: string;
+    deepresearch_id?: string;
+    error?: string;
+}
+interface DeepResearchCancelResponse {
+    success: boolean;
+    message?: string;
+    deepresearch_id?: string;
+    error?: string;
+}
+interface DeepResearchDeleteResponse {
+    success: boolean;
+    message?: string;
+    deepresearch_id?: string;
+    error?: string;
+}
+interface DeepResearchTogglePublicResponse {
+    success: boolean;
+    message?: string;
+    deepresearch_id?: string;
+    public?: boolean;
+    error?: string;
+}
+interface WaitOptions {
+    pollInterval?: number;
+    maxWaitTime?: number;
+    onProgress?: (status: DeepResearchStatusResponse) => void;
+}
+interface StreamCallback {
+    onMessage?: (message: any) => void;
+    onProgress?: (current: number, total: number) => void;
+    onComplete?: (result: DeepResearchStatusResponse) => void;
+    onError?: (error: Error) => void;
+}
+interface ListOptions {
+    apiKeyId: string;
+    limit?: number;
+}
 
 declare class Valyu {
     private baseUrl;
     private headers;
+    deepresearch: {
+        create: (options: DeepResearchCreateOptions) => Promise<DeepResearchCreateResponse>;
+        status: (taskId: string) => Promise<DeepResearchStatusResponse>;
+        wait: (taskId: string, options?: WaitOptions) => Promise<DeepResearchStatusResponse>;
+        stream: (taskId: string, callback: StreamCallback) => Promise<void>;
+        list: (options: ListOptions) => Promise<DeepResearchListResponse>;
+        update: (taskId: string, instruction: string) => Promise<DeepResearchUpdateResponse>;
+        cancel: (taskId: string) => Promise<DeepResearchCancelResponse>;
+        delete: (taskId: string) => Promise<DeepResearchDeleteResponse>;
+        togglePublic: (taskId: string, isPublic: boolean) => Promise<DeepResearchTogglePublicResponse>;
+    };
     constructor(apiKey?: string, baseUrl?: string);
     /**
      * Validates date format (YYYY-MM-DD)
@@ -187,6 +387,42 @@ declare class Valyu {
      * @returns Promise resolving to content extraction results
      */
     contents(urls: string[], options?: ContentsOptions): Promise<ContentsResponse>;
+    /**
+     * DeepResearch: Create a new research task
+     */
+    private _deepresearchCreate;
+    /**
+     * DeepResearch: Get task status
+     */
+    private _deepresearchStatus;
+    /**
+     * DeepResearch: Wait for task completion with polling
+     */
+    private _deepresearchWait;
+    /**
+     * DeepResearch: Stream real-time updates
+     */
+    private _deepresearchStream;
+    /**
+     * DeepResearch: List all tasks
+     */
+    private _deepresearchList;
+    /**
+     * DeepResearch: Add follow-up instruction
+     */
+    private _deepresearchUpdate;
+    /**
+     * DeepResearch: Cancel task
+     */
+    private _deepresearchCancel;
+    /**
+     * DeepResearch: Delete task
+     */
+    private _deepresearchDelete;
+    /**
+     * DeepResearch: Toggle public flag
+     */
+    private _deepresearchTogglePublic;
     /**
      * Get AI-powered answers using the Valyu Answer API
      * @param query - The question or query string
@@ -201,9 +437,30 @@ declare class Valyu {
      * @param options.startDate - Start date filter (YYYY-MM-DD format)
      * @param options.endDate - End date filter (YYYY-MM-DD format)
      * @param options.fastMode - Fast mode for quicker but shorter results (default: false)
-     * @returns Promise resolving to answer response
+     * @param options.streaming - Enable streaming mode (default: false)
+     * @returns Promise resolving to answer response, or AsyncGenerator for streaming
+     */
+    answer(query: string, options?: AnswerOptions): Promise<AnswerResponse | AsyncGenerator<AnswerStreamChunk, void, unknown>>;
+    /**
+     * Validate answer parameters
+     */
+    private validateAnswerParams;
+    /**
+     * Build payload for answer API
+     */
+    private buildAnswerPayload;
+    /**
+     * Fetch answer (non-streaming mode)
+     */
+    private fetchAnswer;
+    /**
+     * Stream answer using SSE
+     */
+    private streamAnswer;
+    /**
+     * Create an error generator for streaming errors
      */
-    answer(query: string, options?: AnswerOptions): Promise<AnswerResponse>;
+    private createErrorGenerator;
 }
 
-export { type AIUsage, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerSuccessResponse, type ContentResponseLength, type ContentResult, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type ExtractEffort, type FeedbackResponse, type FeedbackSentiment, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchType, Valyu };
+export { type AIUsage, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions };