pi-web-providers 3.1.0 → 3.2.0

package/README.md

@@ -68,7 +68,7 @@ reported when the tool is actually called.
 | **Exa**        |   ✔    |    ✔     |   ✔    |    ✔     | `EXA_API_KEY`                                    |
 | **Firecrawl**  |   ✔    |    ✔     |        |          | `FIRECRAWL_API_KEY`                              |
 | **Gemini**     |   ✔    |          |   ✔    |    ✔     | `GOOGLE_API_KEY`                                 |
-| **Linkup**     |   ✔    |    ✔     |        |          | `LINKUP_API_KEY`                                 |
+| **Linkup**     |   ✔    |    ✔     |        |    ✔     | `LINKUP_API_KEY`                                 |
 | **Ollama**     |   ✔    |    ✔     |        |          | `OLLAMA_API_KEY`                                 |
 | **OpenAI**     |   ✔    |          |   ✔    |    ✔     | `OPENAI_API_KEY`                                 |
 | **Parallel**   |   ✔    |    ✔     |        |          | `PARALLEL_API_KEY`                               |
@@ -352,10 +352,17 @@ scope, or account ID is usually wrong.
 - SDK: `linkup-sdk`
 - Supports `web_search` via Linkup Search with fixed `searchResults` output
 - Supports `web_contents` via Linkup Fetch and always returns markdown
+- Supports `web_research` via Linkup's async Research API
 - Exposes search options `depth`, `includeImages`, `includeDomains`,
   `excludeDomains`, `fromDate`, and `toDate`
 - Exposes contents options `renderJs`, `includeRawHtml`, and `extractImages`
-- Good fit for a simple search-plus-markdown setup without extra provider wiring
+- Exposes research options `outputType`, `mode`, `reasoningDepth`,
+  `includeDomains`, `excludeDomains`, `fromDate`, `toDate`, and
+  `structuredOutputSchema`
+- Research defaults to `sourcedAnswer`; provide `structuredOutputSchema` for
+  structured output
+- Good fit for search, markdown extraction, and long-running sourced research
+  without extra provider wiring
 
 </details>
 

package/dist/index.js

@@ -4241,6 +4241,45 @@ var linkupContentsOptionsSchema = Type9.Object(
   },
   { description: "Linkup fetch options." }
 );
+var linkupResearchOptionsSchema = Type9.Object(
+  {
+    outputType: Type9.Optional(
+      literalUnion(["sourcedAnswer", "structured"], {
+        description: "Research output type. Defaults to 'sourcedAnswer' unless structuredOutputSchema is provided."
+      })
+    ),
+    mode: Type9.Optional(
+      literalUnion(["answer", "auto", "investigate", "research"], {
+        description: "Research mode. Use 'answer' for precise verified answers, 'investigate' for focused deep dives, 'research' for broad reports, or omit/auto to let Linkup classify the task."
+      })
+    ),
+    reasoningDepth: Type9.Optional(
+      literalUnion(["S", "M", "L", "XL"], {
+        description: "Reasoning depth. Higher values trade latency for more thorough investigation."
+      })
+    ),
+    includeDomains: Type9.Optional(
+      Type9.Array(Type9.String(), {
+        description: "Restrict research to these domains."
+      })
+    ),
+    excludeDomains: Type9.Optional(
+      Type9.Array(Type9.String(), { description: "Exclude these domains." })
+    ),
+    fromDate: Type9.Optional(
+      Type9.String({ description: "ISO date string for earliest result date." })
+    ),
+    toDate: Type9.Optional(
+      Type9.String({ description: "ISO date string for latest result date." })
+    ),
+    structuredOutputSchema: Type9.Optional(
+      Type9.Record(Type9.String(), Type9.Any(), {
+        description: "JSON schema object required when outputType is 'structured'."
+      })
+    )
+  },
+  { description: "Linkup research options." }
+);
 var linkupImplementation = {
   id: "linkup",
   label: "Linkup",
@@ -4251,6 +4290,8 @@ var linkupImplementation = {
         return linkupSearchOptionsSchema;
       case "contents":
         return linkupContentsOptionsSchema;
+      case "research":
+        return linkupResearchOptionsSchema;
       default:
         return void 0;
     }
@@ -4307,6 +4348,51 @@ var linkupImplementation = {
         })
       )
     };
+  },
+  async research(input, config, context, options) {
+    return await executeAsyncResearch({
+      providerLabel: linkupImplementation.label,
+      providerId: linkupImplementation.id,
+      context,
+      start: (researchContext) => linkupImplementation.startResearch(
+        input,
+        config,
+        researchContext,
+        options
+      ),
+      poll: (id, researchContext) => linkupImplementation.pollResearch(id, config, researchContext)
+    });
+  },
+  async startResearch(input, config, _context, options) {
+    const client = createClient4(config);
+    const defaults = asJsonObject(config.options?.research) ?? {};
+    const task = await client.research(
+      buildResearchParams(input, {
+        ...defaults,
+        ...options ?? {}
+      })
+    );
+    return { id: task.id };
+  },
+  async pollResearch(id, config, _context) {
+    const client = createClient4(config);
+    const task = await client.getResearch(id);
+    if (task.status === "completed") {
+      return {
+        status: "completed",
+        output: formatResearchTaskOutput(task)
+      };
+    }
+    if (task.status === "failed") {
+      return {
+        status: "failed",
+        error: task.error ?? "research failed"
+      };
+    }
+    return {
+      status: "in_progress",
+      statusText: task.status
+    };
   }
 };
 function buildSearchParams(query2, maxResults, options) {
@@ -4351,6 +4437,45 @@ function buildFetchParams(url2, options) {
     ...fetchOptions.extractImages !== void 0 ? { extractImages: fetchOptions.extractImages } : {}
   };
 }
+function buildResearchParams(input, options) {
+  const researchOptions = options;
+  if (researchOptions.q !== void 0 || researchOptions.query !== void 0 || researchOptions.input !== void 0) {
+    throw new Error(
+      "Linkup research options cannot override the managed input."
+    );
+  }
+  const outputType = researchOptions.outputType ?? (researchOptions.structuredOutputSchema !== void 0 ? "structured" : "sourcedAnswer");
+  if (outputType === "structured" && researchOptions.structuredOutputSchema === void 0) {
+    throw new Error(
+      "Linkup research outputType 'structured' requires structuredOutputSchema."
+    );
+  }
+  if (outputType === "sourcedAnswer" && researchOptions.structuredOutputSchema !== void 0) {
+    throw new Error(
+      "Linkup research structuredOutputSchema requires outputType 'structured'."
+    );
+  }
+  const commonParams = {
+    query: input,
+    ...researchOptions.includeDomains !== void 0 ? { includeDomains: researchOptions.includeDomains } : {},
+    ...researchOptions.excludeDomains !== void 0 ? { excludeDomains: researchOptions.excludeDomains } : {},
+    ...researchOptions.fromDate !== void 0 ? { fromDate: toDate(researchOptions.fromDate, "fromDate") } : {},
+    ...researchOptions.toDate !== void 0 ? { toDate: toDate(researchOptions.toDate, "toDate") } : {},
+    ...researchOptions.mode !== void 0 ? { mode: researchOptions.mode } : {},
+    ...researchOptions.reasoningDepth !== void 0 ? { reasoningDepth: researchOptions.reasoningDepth } : {}
+  };
+  if (outputType === "structured") {
+    return {
+      ...commonParams,
+      outputType,
+      structuredOutputSchema: researchOptions.structuredOutputSchema
+    };
+  }
+  return {
+    ...commonParams,
+    outputType
+  };
+}
 function createClient4(config) {
   const apiKey = resolveConfigValue(config.credentials?.api);
   if (!apiKey) {
@@ -4361,6 +4486,40 @@ function createClient4(config) {
     baseUrl: resolveConfigValue(config.baseUrl)
   });
 }
+function formatResearchTaskOutput(task) {
+  const output = task.output;
+  if (!output) {
+    return {
+      provider: linkupImplementation.id,
+      text: "Linkup research completed without textual output."
+    };
+  }
+  const outputRecord = asRecord2(output);
+  const inputRecord = asRecord2(task.input);
+  const outputType = inputRecord ? readString3(inputRecord.outputType) : void 0;
+  const answer = outputRecord ? readString3(outputRecord.answer) : void 0;
+  const sources = outputRecord ? readSources(outputRecord.sources) : [];
+  if (outputType !== "structured" && answer !== void 0) {
+    const lines = [answer];
+    if (sources.length > 0) {
+      lines.push("");
+      lines.push("Sources:");
+      for (const [index, source] of sources.entries()) {
+        lines.push(`${index + 1}. ${source.title}`);
+        lines.push(`   ${source.url}`);
+      }
+    }
+    return {
+      provider: linkupImplementation.id,
+      text: lines.join("\n").trimEnd(),
+      itemCount: sources.length
+    };
+  }
+  return {
+    provider: linkupImplementation.id,
+    text: formatJson(output)
+  };
+}
 function toSearchResult2(value) {
   const entry = asRecord2(value);
   if (!entry) {
@@ -4382,6 +4541,27 @@ function toSearchResult2(value) {
     metadata: Object.keys(metadata).length > 0 ? metadata : void 0
   };
 }
+function readSources(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((entry) => {
+    const source = asRecord2(entry);
+    if (!source) {
+      return [];
+    }
+    const url2 = readString3(source.url);
+    if (!url2) {
+      return [];
+    }
+    return [
+      {
+        title: readString3(source.name) ?? url2,
+        url: url2
+      }
+    ];
+  });
+}
 function asRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 }
@@ -4435,6 +4615,17 @@ var linkupProvider = defineProvider({
           input.options
         );
       }
+    }),
+    research: defineCapability({
+      options: linkupImplementation.getToolOptionsSchema?.("research"),
+      async execute(input, ctx) {
+        return await linkupImplementation.research(
+          input.input,
+          ctx.config,
+          ctx,
+          input.options
+        );
+      }
     })
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-providers",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Configurable web access extension for pi with per-tool provider routing and explicit provider option schemas for search, contents, quick grounded answers, and research.",
   "type": "module",
   "files": [
@@ -73,7 +73,7 @@
     "@tavily/core": "^0.7.3",
     "cloudflare": "^5.2.0",
     "exa-js": "^2.12.1",
-    "linkup-sdk": "^2.7.0",
+    "linkup-sdk": "^3.2.0",
     "openai": "^6.35.0",
     "parallel-web": "^0.4.1",
     "valyu-js": "^2.7.14"