From eec18e0169e32324e62615c59d52c2dff2e4aae1 Mon Sep 17 00:00:00 2001 From: divyesh radadiya Date: Thu, 30 Oct 2025 20:04:13 +0530 Subject: [PATCH 1/2] docs: add Serpex integration docs (Python & JS) and update packages.yml --- pipeline/tools/partner_pkg_table.py | 3 +- reference/packages.yml | 11 ++ .../integrations/providers/serpex-js.mdx | 15 ++ .../integrations/tools/serpex_search_js.mdx | 135 ++++++++++++++++++ .../integrations/providers/serpex-python.mdx | 26 ++++ .../tools/serpex_search_python.mdx | 131 +++++++++++++++++ 6 files changed, 320 insertions(+), 1 deletion(-) create mode 100644 src/oss/javascript/integrations/providers/serpex-js.mdx create mode 100644 src/oss/javascript/integrations/tools/serpex_search_js.mdx create mode 100644 src/oss/python/integrations/providers/serpex-python.mdx create mode 100644 src/oss/python/integrations/tools/serpex_search_python.mdx diff --git a/pipeline/tools/partner_pkg_table.py b/pipeline/tools/partner_pkg_table.py index c44e8e214..8d5d9e7f3 100644 --- a/pipeline/tools/partner_pkg_table.py +++ b/pipeline/tools/partner_pkg_table.py @@ -12,6 +12,7 @@ """ from pathlib import Path +from typing import Optional import yaml @@ -64,7 +65,7 @@ def _get_type(package: dict) -> str: return "third-party" -def _enrich_package(p: dict) -> dict | None: +def _enrich_package(p: dict) -> Optional[dict]: """Enrich package metadata with additional fields. Args: diff --git a/reference/packages.yml b/reference/packages.yml index 111ac56e4..5321dddba 100644 --- a/reference/packages.yml +++ b/reference/packages.yml @@ -764,3 +764,14 @@ packages: path: libs/voyageai downloads: 30000 downloads_updated_at: "2025-10-27T00:06:25.073005+00:00" +- name: langchain-serpex-python + name_title: Serpex + repo: divyeshradadiya/langchain-serpex-python + js: langchain-serpex-js + downloads: 1000 + downloads_updated_at: "2025-10-30T00:00:00.000000+00:00" +- name: langchain-serpex-js + name_title: Serpex + repo: divyeshradadiya/langchain-serpex-js + downloads: 1000 + downloads_updated_at: "2025-10-30T00:00:00.000000+00:00" diff --git a/src/oss/javascript/integrations/providers/serpex-js.mdx b/src/oss/javascript/integrations/providers/serpex-js.mdx new file mode 100644 index 000000000..9ecb595bf --- /dev/null +++ b/src/oss/javascript/integrations/providers/serpex-js.mdx @@ -0,0 +1,15 @@ +--- +title: Serpex (JS/TS) +--- + +This page covers how to use the Serpex search APIs within LangChain (JavaScript/TypeScript). + +## Installation and Setup (JavaScript/TypeScript) +- Install the JS package with `npm install langchain-serpex-js` or `pnpm add langchain-serpex-js` +- Get a Serpex API key and set it as an environment variable (for example `SERPEX_API_KEY`). + +## Wrappers / Tools + +See the Serpex JS tool reference and examples here: [/oss/javascript/integrations/tools/serpex_search_js](/oss/javascript/integrations/tools/serpex_search_js) + +For usage with Agents and loading as tools, see the tools documentation: [/oss/javascript/integrations/tools](/oss/javascript/integrations/tools). diff --git a/src/oss/javascript/integrations/tools/serpex_search_js.mdx b/src/oss/javascript/integrations/tools/serpex_search_js.mdx new file mode 100644 index 000000000..91884f44f --- /dev/null +++ b/src/oss/javascript/integrations/tools/serpex_search_js.mdx @@ -0,0 +1,135 @@ +--- +title: Serpex Search +--- + +[SERPEX](https://serpex.dev) is a powerful multi-engine search API that provides access to search results from Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex, and other search engines in JSON format. It's designed for developers building AI applications, SEO tools, market research platforms, and data aggregation services. + +## Overview + +### Integration details + +| Class | Package | Local | Serializable | PY support | Package downloads | Package latest | +|-------|---------|-------|--------------|------------|------------------|----------------| +| [Serpex](https://github.com/divyeshradadiya/langchain-serpex-js) | [langchain-serpex-js](https://www.npmjs.com/package/langchain-serpex-js) | ✅ | ❌ | ✅ | ![NPM Downloads](https://img.shields.io/npm/dm/langchain-serpex-js) | ![NPM Version](https://img.shields.io/npm/v/langchain-serpex-js) | + +### Tool features + +| Returns artifact | Native async | Return data | Pricing | +|------------------|--------------|-------------|---------| +| ❌ | ✅ | title, URL, snippet, rich results | Free tier available | + +## Setup + +The integration lives in the `langchain-serpex-js` package. + +```bash +npm install langchain-serpex-js +``` + +### Credentials + +We also need to set our SERPEX API key. You can get an API key by visiting [serpex.dev](https://serpex.dev) and creating an account. + +```typescript +// In your environment +process.env.SERPEX_API_KEY = "your-serpex-api-key"; +``` + +## Instantiation + +Here we show how to instantiate an instance of the Serpex search tool. The tool accepts various parameters to customize the search. After instantiation we invoke the tool with a simple query. + +### Parameters + +- `apiKey` (string): Your SERPEX API key (required if not set as environment variable) +- `engine` (string): Search engine to use - "auto", "google", "bing", "duckduckgo", "brave", "yahoo", "yandex" (default: "auto") +- `category` (string): Search category - currently only "web" is supported (default: "web") +- `time_range` (string): Time filter - "all", "day", "week", "month", "year" (not supported by Brave) + +```typescript +import { Serpex } from "langchain-serpex-js"; + +const tool = new Serpex("your-serpex-api-key", { + engine: "google", + time_range: "month" +}); +``` + +## Invocation + +### Invoke directly with args + +The Serpex search tool accepts the following arguments during invocation: +`query` (required): A natural language search query + +```typescript +await tool.invoke({ query: "latest AI developments" }); +``` + +### Invoke with ToolCall + +We can also invoke the tool with a model-generated ToolCall, in which case a ToolMessage will be returned: + +```typescript +// This is usually generated by a model, but we'll create a tool call directly for demo purposes. +const modelGeneratedToolCall = { + args: { query: "quantum computing breakthroughs" }, + id: "1", + name: "serpex_search", + type: "tool_call", +}; + +const toolMsg = await tool.invoke(modelGeneratedToolCall); + +// The content is a JSON string of results +console.log(toolMsg.content.substring(0, 500)); +``` + +## Use within an agent + +We can use our tools directly with an agent executor by binding the tool to the agent. This gives the agent the ability to dynamically search for information. + +```typescript +import { ChatOpenAI } from "@langchain/openai"; +import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents"; +import { ChatPromptTemplate } from "@langchain/core/prompts"; +import { Serpex } from "langchain-serpex-js"; + +// Initialize the search tool +const searchTool = new Serpex("your-serpex-api-key", { + engine: "google", + time_range: "month" +}); + +// Initialize the LLM +const llm = new ChatOpenAI({ model: "gpt-4", temperature: 0 }); + +// Create an agent with the search tool +const prompt = ChatPromptTemplate.fromMessages([ + ["system", "You are a helpful assistant."], + ["human", "{input}"], + ["human", "{agent_scratchpad}"] +]); + +const agent = await createOpenAIFunctionsAgent({ + llm, + tools: [searchTool], + prompt +}); + +const executor = new AgentExecutor({ + agent, + tools: [searchTool] +}); + +// Run the agent +const result = await executor.invoke({ + input: "What are the latest developments in renewable energy?" +}); + +console.log(result); +``` + +## API reference + +For detailed documentation of all SERPEX API features and configurations head to the API reference: [serpex.dev/docs](https://serpex.dev/docs) \ No newline at end of file diff --git a/src/oss/python/integrations/providers/serpex-python.mdx b/src/oss/python/integrations/providers/serpex-python.mdx new file mode 100644 index 000000000..293b5bcc3 --- /dev/null +++ b/src/oss/python/integrations/providers/serpex-python.mdx @@ -0,0 +1,26 @@ +--- +title: Serpex +--- + +This page covers how to use the Serpex search APIs within LangChain. + +## Installation and Setup +- Install the Python package with `pip install langchain-serpex-python` +- Get a Serpex API key and set it as an environment variable (for example `SERPEX_API_KEY`). + +## Wrappers + +### Tool + +For usage examples and reference for the Serpex wrappers and tools, see [the Serpex tools page](/oss/python/integrations/tools/serpex_search_python). + +### Tool (Agent) + +You can also load Serpex as a Tool to use with an Agent: + +```python +from langchain_community.agent_toolkits.load_tools import load_tools +tools = load_tools(["serpex_search_python"]) +``` + +For more information on loading tools, see [the tools documentation](/oss/integrations/tools). diff --git a/src/oss/python/integrations/tools/serpex_search_python.mdx b/src/oss/python/integrations/tools/serpex_search_python.mdx new file mode 100644 index 000000000..e7149b7d8 --- /dev/null +++ b/src/oss/python/integrations/tools/serpex_search_python.mdx @@ -0,0 +1,131 @@ +--- +title: Serpex Search +--- + +[SERPEX](https://serpex.dev) is a powerful multi-engine search API that provides access to search results from Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex, and other search engines in JSON format. It's designed for developers building AI applications, SEO tools, market research platforms, and data aggregation services. + +## Overview + +### Integration details + +| Class | Package | Local | Serializable | JS support | Package downloads | Package latest | +|-------|----------|--------|--------------|-------------|------------------|----------------| +| [SerpexSearchResults](https://github.com/divyeshradadiya/langchain-serpex-python) | [langchain-serpex-python](https://pypi.org/project/langchain-serpex-python/) | ✅ | ❌ | ✅ | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain-serpex-python) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-serpex-python) | + +### Tool features + +| Returns artifact | Native async | Return data | Pricing | +|------------------|--------------|--------------|----------| +| ❌ | ✅ | title, URL, snippet, rich results | Free tier available | + +## Setup + +The integration lives in the `langchain-serpex-python` package. + +```python +pip install -qU langchain-serpex-python +``` + +### Credentials + +We also need to set our SERPEX API key. You can get an API key by visiting [serpex.dev](https://serpex.dev) and creating an account. + +```python +import getpass +import os + +if not os.environ.get("SERPEX_API_KEY"): + os.environ["SERPEX_API_KEY"] = getpass.getpass("SERPEX API key:\n") +``` + +## Instantiation + +Here we show how to instantiate an instance of the Serpex search tool. The tool accepts various parameters to customize the search. After instantiation we invoke the tool with a simple query. + +### Parameters + +- `api_key` (str): Your SERPEX API key (required if not set as environment variable) +- `engine` (str): Search engine to use - "auto", "google", "bing", "duckduckgo", "brave", "yahoo", "yandex" (default: "auto") +- `category` (str): Search category - currently only "web" is supported (default: "web") +- `time_range` (str): Time filter - "all", "day", "week", "month", "year" (not supported by Brave) + +```python +from langchain_serpex_python import SerpexSearchResults + +tool = SerpexSearchResults( + api_key="your-serpex-api-key", + engine="google", + time_range="month" +) +``` + +## Invocation + +### Invoke directly with args + +The Serpex search tool accepts the following arguments during invocation: +`query` (required): A natural language search query + +```python +tool.invoke({"query": "latest AI developments"}) +``` + +### Invoke with ToolCall + +We can also invoke the tool with a model-generated ToolCall, in which case a ToolMessage will be returned: + +```python +# This is usually generated by a model, but we'll create a tool call directly for demo purposes. +model_generated_tool_call = { + "args": {"query": "quantum computing breakthroughs"}, + "id": "1", + "name": "serpex_search", + "type": "tool_call", +} +tool_msg = tool.invoke(model_generated_tool_call) + +# The content is a JSON string of results +print(tool_msg.content[:500]) +``` + +## Use within an agent + +We can use our tools directly with an agent executor by binding the tool to the agent. This gives the agent the ability to dynamically search for information. + +```python +if not os.environ.get("OPENAI_API_KEY"): + os.environ["OPENAI_API_KEY"] = getpass.getpass("OPENAI_API_KEY:\n") + +# (output: false, echo: false) +# !pip install -qU langchain langchain-openai +from langchain.chat_models import init_chat_model + +model = init_chat_model(model="gpt-4o", model_provider="openai", temperature=0) + +# We will need to install langgraph: +# !pip install -qU langgraph + +from langchain_serpex_python import SerpexSearchResults +from langchain.agents import create_agent + +# Initialize Serpex Search Tool +serpex_search_tool = SerpexSearchResults( + api_key="your-serpex-api-key", + engine="google", + time_range="month" +) + +agent = create_agent(model, [serpex_search_tool]) + +user_input = "What are the latest developments in renewable energy?" + +for step in agent.stream( + {"messages": user_input}, + stream_mode="values", +): + step["messages"][-1].pretty_print() +``` + +## API reference + +For detailed documentation of all SERPEX API features and configurations head to the API reference: [serpex.dev/docs](https://serpex.dev/docs) \ No newline at end of file From 1d9d8204cbc5e1254b86ba5e10ef5be34865e75b Mon Sep 17 00:00:00 2001 From: divyesh radadiya Date: Mon, 3 Nov 2025 09:43:21 +0530 Subject: [PATCH 2/2] refactor(docs): update agent integration examples for Serpex in JavaScript and Python --- .../integrations/tools/serpex_search_js.mdx | 25 +++++-------------- .../integrations/providers/serpex-python.mdx | 11 -------- 2 files changed, 6 insertions(+), 30 deletions(-) diff --git a/src/oss/javascript/integrations/tools/serpex_search_js.mdx b/src/oss/javascript/integrations/tools/serpex_search_js.mdx index 91884f44f..f9678661f 100644 --- a/src/oss/javascript/integrations/tools/serpex_search_js.mdx +++ b/src/oss/javascript/integrations/tools/serpex_search_js.mdx @@ -87,12 +87,11 @@ console.log(toolMsg.content.substring(0, 500)); ## Use within an agent -We can use our tools directly with an agent executor by binding the tool to the agent. This gives the agent the ability to dynamically search for information. +We can use our tools directly with an agent by creating an agent with the tool. This gives the agent the ability to dynamically search for information. ```typescript import { ChatOpenAI } from "@langchain/openai"; -import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents"; -import { ChatPromptTemplate } from "@langchain/core/prompts"; +import { createAgent } from "langchain"; import { Serpex } from "langchain-serpex-js"; // Initialize the search tool @@ -105,26 +104,14 @@ const searchTool = new Serpex("your-serpex-api-key", { const llm = new ChatOpenAI({ model: "gpt-4", temperature: 0 }); // Create an agent with the search tool -const prompt = ChatPromptTemplate.fromMessages([ - ["system", "You are a helpful assistant."], - ["human", "{input}"], - ["human", "{agent_scratchpad}"] -]); - -const agent = await createOpenAIFunctionsAgent({ - llm, +const agent = createAgent({ + model: llm, tools: [searchTool], - prompt -}); - -const executor = new AgentExecutor({ - agent, - tools: [searchTool] }); // Run the agent -const result = await executor.invoke({ - input: "What are the latest developments in renewable energy?" +const result = await agent.invoke({ + messages: [{ role: "user", content: "What are the latest developments in renewable energy?" }] }); console.log(result); diff --git a/src/oss/python/integrations/providers/serpex-python.mdx b/src/oss/python/integrations/providers/serpex-python.mdx index 293b5bcc3..e3bbe4851 100644 --- a/src/oss/python/integrations/providers/serpex-python.mdx +++ b/src/oss/python/integrations/providers/serpex-python.mdx @@ -13,14 +13,3 @@ This page covers how to use the Serpex search APIs within LangChain. ### Tool For usage examples and reference for the Serpex wrappers and tools, see [the Serpex tools page](/oss/python/integrations/tools/serpex_search_python). - -### Tool (Agent) - -You can also load Serpex as a Tool to use with an Agent: - -```python -from langchain_community.agent_toolkits.load_tools import load_tools -tools = load_tools(["serpex_search_python"]) -``` - -For more information on loading tools, see [the tools documentation](/oss/integrations/tools).