Feat/serpex tool integration

llama-index-core/llama_index/core/storage/docstore/keyval_docstore.py

@@ -395,7 +395,7 @@ def _remove_legacy_info(self, ref_doc_info_dict: dict) -> RefDocInfo:
 
         return RefDocInfo(
             metadata=ref_doc_info_dict.get("metadata", {}),
-            node_ids=ref_doc_info_dict.get("node_ids", [])
+            node_ids=ref_doc_info_dict.get("node_ids", []),
         )
 
     def get_ref_doc_info(self, ref_doc_id: str) -> Optional[RefDocInfo]:

llama-index-integrations/tools/llama-index-tools-serpex/.gitignore

@@ -0,0 +1,16 @@
+*.pyc
+__pycache__/
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.DS_Store

llama-index-integrations/tools/llama-index-tools-serpex/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SERPEX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llama-index-integrations/tools/llama-index-tools-serpex/Makefile

@@ -0,0 +1,20 @@
+.PHONY: format lint test clean
+
+format:
+	black .
+	ruff check --fix .
+
+lint:
+	ruff check .
+	mypy llama_index/tools/serpex
+
+test:
+	pytest tests/ -v
+
+test-coverage:
+	pytest --cov=llama_index.tools.serpex tests/ -v
+
+clean:
+	rm -rf build/ dist/ *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name '*.pyc' -delete

llama-index-integrations/tools/llama-index-tools-serpex/README.md

@@ -0,0 +1,84 @@
+# LlamaIndex Tools Integration: SERPEX
+
+This tool allows you to use SERPEX API to search the web and get real-time results from multiple search engines within your LlamaIndex application.
+
+## Installation
+
+```bash
+pip install llama-index-tools-serpex
+```
+
+## Usage
+
+```python
+from llama_index.tools.serpex import SerpexToolSpec
+from llama_index.agent.openai import OpenAIAgent
+
+# Initialize the tool
+serpex_tool = SerpexToolSpec(api_key="your_serpex_api_key")
+
+# Create agent with the tool
+agent = OpenAIAgent.from_tools(serpex_tool.to_tool_list(), verbose=True)
+
+# Use the agent
+response = agent.chat("What are the latest AI developments?")
+print(response)
+```
+
+### Advanced Usage
+
+```python
+# Use specific search engine
+serpex_tool = SerpexToolSpec(
+    api_key="your_api_key",
+    engine="google",  # or 'bing', 'duckduckgo', 'brave', etc.
+)
+
+# Search with time filter
+results = serpex_tool.search(
+    "recent AI news",
+    num_results=10,
+    time_range="day",  # 'day', 'week', 'month', 'year'
+)
+
+# Use different engines for different queries
+results = serpex_tool.search(
+    "privacy tools", engine="duckduckgo", num_results=5
+)
+```
+
+## API Key
+
+Get your API key from [SERPEX Dashboard](https://serpex.dev/dashboard).
+
+Set as environment variable:
+
+```bash
+export SERPEX_API_KEY=your_api_key
+```
+
+## Features
+
+- **Multiple Search Engines**: Auto-routing, Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex
+- **Real-time Results**: Get up-to-date search results via API
+- **Time Filtering**: Filter by day, week, month, or year
+- **Fast & Reliable**: 99.9% uptime SLA with global proxy network
+- **Structured Data**: Clean JSON responses optimized for AI applications
+- **Cost Effective**: Only 1 credit per request, failed requests free
+
+## Search Engines
+
+- `auto` - Automatically routes to the best available engine (default)
+- `google` - Google Search
+- `bing` - Microsoft Bing
+- `duckduckgo` - Privacy-focused DuckDuckGo
+- `brave` - Brave Search
+- `yahoo` - Yahoo Search
+- `yandex` - Yandex Search
+
+## Links
+
+- [SERPEX Website](https://serpex.dev)
+- [SERPEX Documentation](https://serpex.dev/docs)
+- [SERPEX Dashboard](https://serpex.dev/dashboard)
+- [LlamaIndex](https://llamaindex.ai)

llama-index-integrations/tools/llama-index-tools-serpex/examples/serpex_example.py

@@ -0,0 +1,114 @@
+"""Example usage of SERPEX tool with LlamaIndex."""
+
+import os
+
+from llama_index.tools.serpex import SerpexToolSpec
+
+# Set your API key (or use environment variable SERPEX_API_KEY)
+os.environ["SERPEX_API_KEY"] = "your_api_key_here"
+
+
+def basic_search_example():
+    """Basic search example."""
+    print("=" * 60)
+    print("Basic Search Example")
+    print("=" * 60)
+
+    # Initialize tool
+    tool = SerpexToolSpec()
+
+    # Perform search
+    results = tool.search("latest developments in artificial intelligence", num_results=5)
+
+    for doc in results:
+        print(doc.text)
+    print()
+
+
+def location_search_example():
+    """Location-based search example."""
+    print("=" * 60)
+    print("Location-Based Search Example")
+    print("=" * 60)
+
+    # Initialize tool
+    tool = SerpexToolSpec()
+
+    # Search with location
+    results = tool.search_with_location(
+        query="best Italian restaurants", location="San Francisco, CA", num_results=5
+    )
+
+    for doc in results:
+        print(doc.text)
+    print()
+
+
+def international_search_example():
+    """International search with country and language."""
+    print("=" * 60)
+    print("International Search Example")
+    print("=" * 60)
+
+    # Initialize tool
+    tool = SerpexToolSpec()
+
+    # Search with country and language
+    results = tool.search(
+        query="noticias de tecnología",
+        num_results=5,
+        gl="es",  # Spain
+        hl="es",  # Spanish
+    )
+
+    for doc in results:
+        print(doc.text)
+    print()
+
+
+def agent_example():
+    """Example with LlamaIndex agent."""
+    print("=" * 60)
+    print("Agent Example")
+    print("=" * 60)
+
+    try:
+        from llama_index.agent.openai import OpenAIAgent
+        from llama_index.llms.openai import OpenAI
+
+        # Initialize SERPEX tool
+        serpex_tool = SerpexToolSpec()
+
+        # Create agent
+        llm = OpenAI(model="gpt-4")
+        agent = OpenAIAgent.from_tools(serpex_tool.to_tool_list(), llm=llm, verbose=True)
+
+        # Ask question that requires web search
+        response = agent.chat(
+            "What are the latest features announced for LlamaIndex? Search the web for recent news."
+        )
+        print(response)
+
+    except ImportError:
+        print("OpenAI dependencies not installed. Install with:")
+        print("pip install llama-index-agent-openai llama-index-llms-openai")
+    print()
+
+
+def main():
+    """Run all examples."""
+    # Make sure API key is set
+    if not os.environ.get("SERPEX_API_KEY"):
+        print("Please set SERPEX_API_KEY environment variable")
+        print("Get your API key at: https://serpex.dev/dashboard")
+        return
+
+    # Run examples
+    basic_search_example()
+    location_search_example()
+    international_search_example()
+    agent_example()
+
+
+if __name__ == "__main__":
+    main()

llama-index-integrations/tools/llama-index-tools-serpex/llama_index/tools/serpex/__init__.py

@@ -0,0 +1,5 @@
+"""SERPEX tool for LlamaIndex."""
+
+from llama_index.tools.serpex.base import SerpexToolSpec
+
+__all__ = ["SerpexToolSpec"]