chore: import upstream snapshot with attribution

apps/sim/tools/parallel/deep_research.ts

@@ -0,0 +1,262 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { PlatformEvents } from '@/lib/core/telemetry'
+import type { ParallelDeepResearchParams } from '@/tools/parallel/types'
+import type { ToolConfig, ToolResponse } from '@/tools/types'
+
+const logger = createLogger('ParallelDeepResearchTool')
+
+export const deepResearchTool: ToolConfig<ParallelDeepResearchParams, ToolResponse> = {
+  id: 'parallel_deep_research',
+  name: 'Parallel AI Deep Research',
+  description:
+    'Conduct comprehensive deep research across the web using Parallel AI. Synthesizes information from multiple sources with citations. Can take up to 45 minutes to complete.',
+  version: '1.0.0',
+
+  hosting: {
+    envKeyPrefix: 'PARALLEL_API_KEY',
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'parallel_ai',
+    pricing: {
+      type: 'custom',
+      getCost: (params, _output) => {
+        // Parallel Task API: cost varies by processor
+        // https://docs.parallel.ai/resources/pricing
+        const processorCosts: Record<string, number> = {
+          lite: 0.005,
+          base: 0.01,
+          core: 0.025,
+          core2x: 0.05,
+          pro: 0.1,
+          ultra: 0.3,
+          ultra2x: 0.6,
+          ultra4x: 1.2,
+          ultra8x: 2.4,
+        }
+        const processor = (params.processor as string) || 'base'
+        const DEFAULT_PROCESSOR_COST = processorCosts.base
+        const knownCost = processorCosts[processor]
+        if (knownCost == null) {
+          logger.warn(
+            `Unknown Parallel processor "${processor}", using default processor cost $${DEFAULT_PROCESSOR_COST}`
+          )
+          PlatformEvents.hostedKeyUnknownModelCost({
+            toolId: 'parallel_deep_research',
+            modelName: processor,
+            defaultCost: DEFAULT_PROCESSOR_COST,
+          })
+        }
+        const cost = knownCost ?? DEFAULT_PROCESSOR_COST
+        return { cost, metadata: { processor, defaultProcessorCost: DEFAULT_PROCESSOR_COST } }
+      },
+    },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 10,
+    },
+  },
+
+  params: {
+    input: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Research query or question (up to 15,000 characters)',
+    },
+    processor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Processing tier: pro, ultra, pro-fast, ultra-fast (default: pro)',
+    },
+    include_domains: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Comma-separated list of domains to restrict research to (source policy)',
+    },
+    exclude_domains: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Comma-separated list of domains to exclude from research (source policy)',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Parallel AI API Key',
+    },
+  },
+
+  request: {
+    url: 'https://api.parallel.ai/v1/tasks/runs',
+    method: 'POST',
+    headers: (params) => ({
+      'Content-Type': 'application/json',
+      'x-api-key': params.apiKey,
+    }),
+    body: (params) => {
+      const body: Record<string, unknown> = {
+        input: params.input,
+        processor: params.processor || 'pro',
+        task_spec: {
+          output_schema: 'auto',
+        },
+      }
+
+      if (params.include_domains || params.exclude_domains) {
+        const sourcePolicy: Record<string, string[]> = {}
+
+        if (params.include_domains) {
+          sourcePolicy.include_domains = params.include_domains
+            .split(',')
+            .map((d) => d.trim())
+            .filter((d) => d.length > 0)
+        }
+
+        if (params.exclude_domains) {
+          sourcePolicy.exclude_domains = params.exclude_domains
+            .split(',')
+            .map((d) => d.trim())
+            .filter((d) => d.length > 0)
+        }
+
+        if (Object.keys(sourcePolicy).length > 0) {
+          body.source_policy = sourcePolicy
+        }
+      }
+
+      return body
+    },
+  },
+
+  transformResponse: async (response: Response) => {
+    if (!response.ok) {
+      const errorText = await response.text()
+      throw new Error(
+        `Parallel AI deep research task creation failed: ${response.status} - ${errorText}`
+      )
+    }
+
+    const data = await response.json()
+
+    return {
+      success: true,
+      output: {
+        run_id: data.run_id ?? null,
+        status: data.status ?? null,
+        message: `Research task ${data.status ?? 'created'}, waiting for completion...`,
+        content: {},
+        basis: [],
+      },
+    }
+  },
+
+  postProcess: async (result, params) => {
+    if (!result.success) {
+      return result
+    }
+
+    const runId = result.output.run_id
+    if (!runId) {
+      return {
+        ...result,
+        success: false,
+        error: 'No run_id returned from task creation',
+      }
+    }
+
+    logger.info(`Parallel AI deep research task ${runId} created, fetching results...`)
+
+    try {
+      const resultResponse = await fetch(
+        `https://api.parallel.ai/v1/tasks/runs/${String(runId).trim()}/result`,
+        {
+          method: 'GET',
+          headers: {
+            'x-api-key': params.apiKey,
+            'Content-Type': 'application/json',
+          },
+        }
+      )
+
+      if (!resultResponse.ok) {
+        const errorText = await resultResponse.text()
+        throw new Error(`Failed to get task result: ${resultResponse.status} - ${errorText}`)
+      }
+
+      const taskResult = await resultResponse.json()
+      logger.info(`Parallel AI deep research task ${runId} completed`)
+
+      const output = taskResult.output ?? {}
+      const status = taskResult.status ?? 'completed'
+
+      return {
+        success: true,
+        output: {
+          status,
+          run_id: runId,
+          message: 'Research completed successfully',
+          content: output.content ?? {},
+          basis: output.basis ?? [],
+        },
+      }
+    } catch (error: unknown) {
+      const errorMessage = getErrorMessage(error, 'Unknown error')
+      logger.error('Error fetching research task result:', {
+        message: errorMessage,
+        runId,
+      })
+
+      return {
+        ...result,
+        success: false,
+        error: `Error fetching research task result: ${errorMessage}`,
+      }
+    }
+  },
+
+  outputs: {
+    status: {
+      type: 'string',
+      description: 'Task status (completed, failed, running)',
+    },
+    run_id: {
+      type: 'string',
+      description: 'Unique ID for this research task',
+    },
+    message: {
+      type: 'string',
+      description: 'Status message',
+    },
+    content: {
+      type: 'object',
+      description: 'Research results (structured based on output_schema)',
+    },
+    basis: {
+      type: 'array',
+      description: 'Citations and sources with reasoning and confidence levels',
+      items: {
+        type: 'object',
+        properties: {
+          field: { type: 'string', description: 'Output field dot-notation path' },
+          reasoning: { type: 'string', description: 'Explanation for the result' },
+          citations: {
+            type: 'array',
+            description: 'Array of sources',
+            items: {
+              type: 'object',
+              properties: {
+                url: { type: 'string', description: 'Source URL' },
+                title: { type: 'string', description: 'Source title' },
+                excerpts: { type: 'array', description: 'Relevant excerpts from the source' },
+              },
+            },
+          },
+          confidence: { type: 'string', description: 'Confidence level (high, medium)' },
+        },
+      },
+    },
+  },
+}

apps/sim/tools/parallel/extract.ts

@@ -0,0 +1,160 @@
+import type { ParallelExtractParams } from '@/tools/parallel/types'
+import type { ToolConfig, ToolResponse } from '@/tools/types'
+
+export const extractTool: ToolConfig<ParallelExtractParams, ToolResponse> = {
+  id: 'parallel_extract',
+  name: 'Parallel AI Extract',
+  description:
+    'Extract targeted information from specific URLs using Parallel AI. Processes provided URLs to pull relevant content based on your objective.',
+  version: '1.0.0',
+
+  hosting: {
+    envKeyPrefix: 'PARALLEL_API_KEY',
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'parallel_ai',
+    pricing: {
+      type: 'custom',
+      getCost: (_params, output) => {
+        if (!Array.isArray(output.results)) {
+          throw new Error('Parallel extract response missing results array')
+        }
+        // Parallel Extract: $1 per 1,000 URLs = $0.001 per URL
+        // https://docs.parallel.ai/resources/pricing
+        const urlCount = output.results.length
+        const cost = urlCount * 0.001
+        return { cost, metadata: { urlCount } }
+      },
+    },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 30,
+    },
+  },
+
+  params: {
+    urls: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Comma-separated list of URLs to extract information from',
+    },
+    objective: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'What information to extract from the provided URLs',
+    },
+    excerpts: {
+      type: 'boolean',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Include relevant excerpts from the content (default: true)',
+    },
+    full_content: {
+      type: 'boolean',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Include full page content as markdown (default: false)',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Parallel AI API Key',
+    },
+  },
+
+  request: {
+    url: 'https://api.parallel.ai/v1beta/extract',
+    method: 'POST',
+    headers: (params) => ({
+      'Content-Type': 'application/json',
+      'x-api-key': params.apiKey,
+      'parallel-beta': 'search-extract-2025-10-10',
+    }),
+    body: (params) => {
+      const urlArray = params.urls
+        .split(',')
+        .map((url) => url.trim())
+        .filter((url) => url.length > 0)
+
+      const body: Record<string, unknown> = {
+        urls: urlArray,
+      }
+
+      if (params.objective) body.objective = params.objective
+      if (params.excerpts !== undefined) body.excerpts = params.excerpts
+      if (params.full_content !== undefined) body.full_content = params.full_content
+
+      return body
+    },
+  },
+
+  transformResponse: async (response: Response) => {
+    if (!response.ok) {
+      const errorText = await response.text()
+      throw new Error(`Parallel AI extract failed: ${response.status} - ${errorText}`)
+    }
+
+    const data = await response.json()
+
+    if (!data.results) {
+      return {
+        success: false,
+        error: 'No results returned from extraction',
+        output: {
+          results: [],
+          extract_id: data.extract_id ?? null,
+        },
+      }
+    }
+
+    return {
+      success: true,
+      output: {
+        extract_id: data.extract_id ?? null,
+        results: data.results.map((result: Record<string, unknown>) => ({
+          url: result.url ?? null,
+          title: result.title ?? null,
+          publish_date: result.publish_date ?? null,
+          excerpts: result.excerpts ?? [],
+          full_content: result.full_content ?? null,
+        })),
+      },
+    }
+  },
+
+  outputs: {
+    extract_id: {
+      type: 'string',
+      description: 'Unique identifier for this extraction request',
+    },
+    results: {
+      type: 'array',
+      description: 'Extracted information from the provided URLs',
+      items: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'The source URL' },
+          title: { type: 'string', description: 'The title of the page', optional: true },
+          publish_date: {
+            type: 'string',
+            description: 'Publication date (YYYY-MM-DD)',
+            optional: true,
+          },
+          excerpts: {
+            type: 'array',
+            description: 'Relevant text excerpts in markdown',
+            items: { type: 'string' },
+            optional: true,
+          },
+          full_content: {
+            type: 'string',
+            description: 'Full page content as markdown',
+            optional: true,
+          },
+        },
+      },
+    },
+  },
+}

apps/sim/tools/parallel/index.ts

@@ -0,0 +1,9 @@
+import { deepResearchTool } from '@/tools/parallel/deep_research'
+import { extractTool } from '@/tools/parallel/extract'
+import { searchTool } from '@/tools/parallel/search'
+
+export const parallelSearchTool = searchTool
+export const parallelExtractTool = extractTool
+export const parallelDeepResearchTool = deepResearchTool
+
+export * from './types'

apps/sim/tools/parallel/search.ts

@@ -0,0 +1,198 @@
+import type { ParallelSearchParams } from '@/tools/parallel/types'
+import type { ToolConfig, ToolResponse } from '@/tools/types'
+
+export const searchTool: ToolConfig<ParallelSearchParams, ToolResponse> = {
+  id: 'parallel_search',
+  name: 'Parallel AI Search',
+  description:
+    'Search the web using Parallel AI. Provides comprehensive search results with intelligent processing and content extraction.',
+  version: '1.0.0',
+
+  hosting: {
+    envKeyPrefix: 'PARALLEL_API_KEY',
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'parallel_ai',
+    pricing: {
+      type: 'custom',
+      getCost: (_params, output) => {
+        if (!Array.isArray(output.results)) {
+          throw new Error('Parallel search response missing results array')
+        }
+        // Parallel Search: $0.005 base (includes ≤10 results), +$0.001 per result beyond 10
+        // https://docs.parallel.ai/resources/pricing
+        const resultCount = output.results.length
+        const additionalResults = Math.max(0, resultCount - 10)
+        const cost = 0.005 + additionalResults * 0.001
+        return { cost, metadata: { resultCount, additionalResults } }
+      },
+    },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 30,
+    },
+  },
+
+  params: {
+    objective: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'The search objective or question to answer',
+    },
+    search_queries: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Comma-separated list of search queries to execute',
+    },
+    mode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Search mode: one-shot, agentic, or fast (default: one-shot)',
+    },
+    max_results: {
+      type: 'number',
+      required: false,
+      visibility: 'user-only',
+      description: 'Maximum number of results to return (default: 10)',
+    },
+    max_chars_per_result: {
+      type: 'number',
+      required: false,
+      visibility: 'user-only',
+      description: 'Maximum characters per result excerpt (minimum: 1000)',
+    },
+    include_domains: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Comma-separated list of domains to restrict search results to',
+    },
+    exclude_domains: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Comma-separated list of domains to exclude from search results',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Parallel AI API Key',
+    },
+  },
+
+  request: {
+    url: 'https://api.parallel.ai/v1beta/search',
+    method: 'POST',
+    headers: (params) => ({
+      'Content-Type': 'application/json',
+      'x-api-key': params.apiKey,
+      'parallel-beta': 'search-extract-2025-10-10',
+    }),
+    body: (params) => {
+      const body: Record<string, unknown> = {
+        objective: params.objective,
+      }
+
+      if (params.search_queries) {
+        if (Array.isArray(params.search_queries)) {
+          body.search_queries = params.search_queries
+        } else if (typeof params.search_queries === 'string') {
+          const queries = params.search_queries
+            .split(',')
+            .map((q: string) => q.trim())
+            .filter((q: string) => q.length > 0)
+          if (queries.length > 0) body.search_queries = queries
+        }
+      }
+
+      if (params.mode) body.mode = params.mode
+      if (params.max_results) body.max_results = Number(params.max_results)
+      if (params.max_chars_per_result) {
+        body.excerpts = { max_chars_per_result: Number(params.max_chars_per_result) }
+      }
+
+      const sourcePolicy: Record<string, string[]> = {}
+      if (params.include_domains) {
+        sourcePolicy.include_domains = params.include_domains
+          .split(',')
+          .map((d: string) => d.trim())
+          .filter((d: string) => d.length > 0)
+      }
+      if (params.exclude_domains) {
+        sourcePolicy.exclude_domains = params.exclude_domains
+          .split(',')
+          .map((d: string) => d.trim())
+          .filter((d: string) => d.length > 0)
+      }
+      if (Object.keys(sourcePolicy).length > 0) {
+        body.source_policy = sourcePolicy
+      }
+
+      return body
+    },
+  },
+
+  transformResponse: async (response: Response) => {
+    if (!response.ok) {
+      const errorText = await response.text()
+      throw new Error(`Parallel AI search failed: ${response.status} - ${errorText}`)
+    }
+
+    const data = await response.json()
+
+    if (!data.results) {
+      return {
+        success: false,
+        error: 'No results returned from search',
+        output: {
+          results: [],
+          search_id: data.search_id ?? null,
+        },
+      }
+    }
+
+    return {
+      success: true,
+      output: {
+        search_id: data.search_id ?? null,
+        results: data.results.map((result: Record<string, unknown>) => ({
+          url: result.url ?? null,
+          title: result.title ?? null,
+          publish_date: result.publish_date ?? null,
+          excerpts: result.excerpts ?? [],
+        })),
+      },
+    }
+  },
+
+  outputs: {
+    search_id: {
+      type: 'string',
+      description: 'Unique identifier for this search request',
+    },
+    results: {
+      type: 'array',
+      description: 'Search results with excerpts from relevant pages',
+      items: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'The URL of the search result' },
+          title: { type: 'string', description: 'The title of the search result' },
+          publish_date: {
+            type: 'string',
+            description: 'Publication date of the page (YYYY-MM-DD)',
+            optional: true,
+          },
+          excerpts: {
+            type: 'array',
+            description: 'LLM-optimized excerpts from the page',
+            items: { type: 'string' },
+          },
+        },
+      },
+    },
+  },
+}

apps/sim/tools/parallel/types.ts

@@ -0,0 +1,78 @@
+import type { ToolResponse } from '@/tools/types'
+
+export interface ParallelSearchParams {
+  objective: string
+  search_queries?: string[] | string
+  mode?: string
+  max_results?: number
+  max_chars_per_result?: number
+  include_domains?: string
+  exclude_domains?: string
+  apiKey: string
+}
+
+interface ParallelSearchResult {
+  url: string | null
+  title: string | null
+  publish_date?: string | null
+  excerpts: string[]
+}
+
+interface ParallelSearchResponse extends ToolResponse {
+  output: {
+    search_id: string | null
+    results: ParallelSearchResult[]
+  }
+}
+
+export interface ParallelExtractParams {
+  urls: string
+  objective?: string
+  excerpts?: boolean
+  full_content?: boolean
+  apiKey: string
+}
+
+interface ParallelExtractResult {
+  url: string | null
+  title?: string | null
+  publish_date?: string | null
+  excerpts?: string[]
+  full_content?: string | null
+}
+
+interface ParallelExtractResponse extends ToolResponse {
+  output: {
+    extract_id: string | null
+    results: ParallelExtractResult[]
+  }
+}
+
+export interface ParallelDeepResearchParams {
+  input: string
+  processor?: string
+  include_domains?: string
+  exclude_domains?: string
+  apiKey: string
+}
+
+interface ParallelDeepResearchBasis {
+  field: string
+  reasoning: string
+  citations: {
+    url: string
+    title: string
+    excerpts: string[]
+  }[]
+  confidence: string
+}
+
+interface ParallelDeepResearchResponse extends ToolResponse {
+  output: {
+    status: string
+    run_id: string
+    message: string
+    content: Record<string, unknown>
+    basis: ParallelDeepResearchBasis[]
+  }
+}