# Serpex Haystack Integration
[](https://pypi.org/project/serpex-haystack)
[](https://pypi.org/project/serpex-haystack)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/divyeshradadiya/serpex-haystack/actions/workflows/ci.yml)
[](https://github.com/psf/black)
[Serpex](https://serpex.dev) integration for [Haystack](https://haystack.deepset.ai/) - bringing powerful multi-engine web search capabilities to your Haystack pipelines.
## Overview
Serpex is a unified web search API that provides access to multiple search engines including Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex. This integration allows you to seamlessly incorporate web search results into your Haystack RAG (Retrieval-Augmented Generation) pipelines and AI applications.
### Key Features
- 🔍 **Multi-Engine Support**: Switch between Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex
- ⚡ **High Performance**: Fast and reliable API with automatic retries
- 🎯 **Rich Results**: Get organic search results with titles, snippets, and URLs
- 🕒 **Time Filters**: Filter results by day, week, month, or year
- 🔒 **Type-Safe**: Fully typed with comprehensive type hints
- 📝 **Haystack Native**: Seamless integration with Haystack 2.0+ components
## Installation
```bash
pip install serpex-haystack
```
## Quick Start
### Get Your API Key
Sign up at [Serpex.dev](https://serpex.dev) to get your free API key.
### Basic Usage
```python
from haystack import Pipeline
from haystack.components.builders import PromptBuilder
from haystack.components.generators import OpenAIGenerator
from haystack.utils import Secret
from haystack_integrations.components.websearch.serpex import SerpexWebSearch
# Create a web search component
web_search = SerpexWebSearch(
api_key=Secret.from_env_var("SERPEX_API_KEY"),
engine="google", # or "bing", "duckduckgo", "brave", "yahoo", "yandex"
)
# Use it standalone
results = web_search.run(query="What is Haystack AI?")
for doc in results["documents"]:
print(f"Title: {doc.meta['title']}")
print(f"URL: {doc.meta['url']}")
print(f"Snippet: {doc.content}\n")
```
### RAG Pipeline Example
```python
from haystack import Pipeline
from haystack.components.builders import PromptBuilder
from haystack.components.generators import OpenAIGenerator
from haystack.utils import Secret
from haystack_integrations.components.websearch.serpex import SerpexWebSearch
# Create a simple RAG pipeline with web search
prompt_template = """
Based on the following search results, answer the question.
Search Results:
{% for doc in documents %}
- {{ doc.meta.title }}: {{ doc.content }}
Source: {{ doc.meta.url }}
{% endfor %}
Question: {{ query }}
Answer:
"""
pipe = Pipeline()
pipe.add_component("search", SerpexWebSearch(api_key=Secret.from_env_var("SERPEX_API_KEY")))
pipe.add_component("prompt", PromptBuilder(template=prompt_template))
pipe.add_component("llm", OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")))
pipe.connect("search.documents", "prompt.documents")
pipe.connect("prompt", "llm")
# Run the pipeline
result = pipe.run({
"search": {"query": "Latest developments in AI agents"},
"prompt": {"query": "Latest developments in AI agents"}
})
print(result["llm"]["replies"][0])
```
## Advanced Features
### Multiple Search Engines
```python
# Use different engines for different queries
google_search = SerpexWebSearch(engine="google")
bing_search = SerpexWebSearch(engine="bing")
duckduckgo_search = SerpexWebSearch(engine="duckduckgo")
```
### Time Range Filtering
```python
# Get only recent results
recent_results = web_search.run(
query="AI news",
time_range="week" # Options: "day", "week", "month", "year", "all"
)
```
### Runtime Configuration Override
```python
# Override settings at runtime
results = web_search.run(
query="Python tutorials",
engine="duckduckgo", # Override default engine
)
```
### Error Handling with Retries
The component includes built-in retry logic with exponential backoff:
```python
web_search = SerpexWebSearch(
api_key=Secret.from_env_var("SERPEX_API_KEY"),
timeout=10.0, # Request timeout in seconds
retry_attempts=3 # Number of retry attempts
)
```
## Component Reference
### SerpexWebSearch
A Haystack component for fetching web search results via the Serpex API.
#### Parameters
- **api_key** (`Secret`, optional): Serpex API key. Defaults to `SERPEX_API_KEY` environment variable.
- **engine** (`str`, optional): Search engine to use. Options: `"auto"`, `"google"`, `"bing"`, `"duckduckgo"`, `"brave"`, `"yahoo"`, `"yandex"`. Defaults to `"google"`.
- **timeout** (`float`, optional): Request timeout in seconds. Defaults to `10.0`.
- **retry_attempts** (`int`, optional): Number of retry attempts. Defaults to `2`.
#### Inputs
- **query** (`str`): The search query string.
- **engine** (`str`, optional): Override the default search engine.
- **time_range** (`str`, optional): Filter by time range (`"all"`, `"day"`, `"week"`, `"month"`, `"year"`).
#### Outputs
- **documents** (`List[Document]`): List of Haystack Document objects containing search results.
Each document includes:
- **content**: The search result snippet
- **meta**:
- `title`: Result title
- `url`: Result URL
- `position`: Position in search results
- `query`: Original search query
- `engine`: Search engine used
## Examples
Check out the [examples](examples/) directory for more use cases:
- [Basic Search](examples/basic_search.py)
- [RAG Pipeline](examples/rag_pipeline.py)
- [Multi-Engine Comparison](examples/multi_engine.py)
- [Agent with Web Search](examples/agent_example.py)
## Why Serpex?
- **🌐 Multi-Engine Access**: One API for all major search engines
- **⚡ Fast & Reliable**: Optimized infrastructure with 99.9% uptime
- **💰 Cost-Effective**: Competitive pricing with generous free tier
- **📊 Rich Metadata**: Comprehensive result data including positions, timestamps, and more
- **🔒 Secure**: Enterprise-grade security and data privacy
- **🚀 Scalable**: Handle thousands of requests per second
## Documentation
- [Serpex API Documentation](https://docs.serpex.dev)
- [Haystack Documentation](https://docs.haystack.deepset.ai)
- [Integration Examples](examples/)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Development Setup
```bash
# Clone the repository
git clone https://github.com/divyeshradadiya/serpex-haystack.git
cd serpex-haystack
# Install with development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
ruff check .
black --check .
# Run type checking
mypy src/
```
## License
This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
## Support
- 📧 Email: support@serpex.dev
- 💬 Discord: [Join our community](https://discord.com/channels/1417759329385316383/1421004675343319102)
- 🐛 Issues: [GitHub Issues](https://github.com/divyeshradadiya/serpex-haystack/issues)
- 📖 Docs: [docs.serpex.dev](https://serpex.dev/docs)
## Acknowledgments
Built with ❤️ for the Haystack community by [Divyesh Radadiya](https://github.com/divyeshradadiya)
---
**Note**: This is a community-maintained integration. For Serpex API support, visit [serpex.dev](https://serpex.dev).
Raw data
{
"_id": null,
"home_page": null,
"name": "serpex-haystack",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, bing-search, duckduckgo, google-search, haystack, llm, nlp, search-api, serpex, web-search",
"author": null,
"author_email": "Divyesh Radadiya <divyeshradadiya0@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8b/0c/ab242e0282f02f787b9b3fe24b9cc5dd2fa7c84283515251b7eeffda7ed1/serpex_haystack-1.0.0.tar.gz",
"platform": null,
"description": "# Serpex Haystack Integration\n\n[](https://pypi.org/project/serpex-haystack)\n[](https://pypi.org/project/serpex-haystack)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/divyeshradadiya/serpex-haystack/actions/workflows/ci.yml)\n[](https://github.com/psf/black)\n\n[Serpex](https://serpex.dev) integration for [Haystack](https://haystack.deepset.ai/) - bringing powerful multi-engine web search capabilities to your Haystack pipelines.\n\n## Overview\n\nSerpex is a unified web search API that provides access to multiple search engines including Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex. This integration allows you to seamlessly incorporate web search results into your Haystack RAG (Retrieval-Augmented Generation) pipelines and AI applications.\n\n### Key Features\n\n- \ud83d\udd0d **Multi-Engine Support**: Switch between Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex\n- \u26a1 **High Performance**: Fast and reliable API with automatic retries\n- \ud83c\udfaf **Rich Results**: Get organic search results with titles, snippets, and URLs\n- \ud83d\udd52 **Time Filters**: Filter results by day, week, month, or year\n- \ud83d\udd12 **Type-Safe**: Fully typed with comprehensive type hints\n- \ud83d\udcdd **Haystack Native**: Seamless integration with Haystack 2.0+ components\n\n## Installation\n\n```bash\npip install serpex-haystack\n```\n\n## Quick Start\n\n### Get Your API Key\n\nSign up at [Serpex.dev](https://serpex.dev) to get your free API key.\n\n### Basic Usage\n\n```python\nfrom haystack import Pipeline\nfrom haystack.components.builders import PromptBuilder\nfrom haystack.components.generators import OpenAIGenerator\nfrom haystack.utils import Secret\nfrom haystack_integrations.components.websearch.serpex import SerpexWebSearch\n\n# Create a web search component\nweb_search = SerpexWebSearch(\n api_key=Secret.from_env_var(\"SERPEX_API_KEY\"),\n engine=\"google\", # or \"bing\", \"duckduckgo\", \"brave\", \"yahoo\", \"yandex\"\n)\n\n# Use it standalone\nresults = web_search.run(query=\"What is Haystack AI?\")\nfor doc in results[\"documents\"]:\n print(f\"Title: {doc.meta['title']}\")\n print(f\"URL: {doc.meta['url']}\")\n print(f\"Snippet: {doc.content}\\n\")\n```\n\n### RAG Pipeline Example\n\n```python\nfrom haystack import Pipeline\nfrom haystack.components.builders import PromptBuilder\nfrom haystack.components.generators import OpenAIGenerator\nfrom haystack.utils import Secret\nfrom haystack_integrations.components.websearch.serpex import SerpexWebSearch\n\n# Create a simple RAG pipeline with web search\nprompt_template = \"\"\"\nBased on the following search results, answer the question.\n\nSearch Results:\n{% for doc in documents %}\n- {{ doc.meta.title }}: {{ doc.content }}\n Source: {{ doc.meta.url }}\n{% endfor %}\n\nQuestion: {{ query }}\n\nAnswer:\n\"\"\"\n\npipe = Pipeline()\npipe.add_component(\"search\", SerpexWebSearch(api_key=Secret.from_env_var(\"SERPEX_API_KEY\")))\npipe.add_component(\"prompt\", PromptBuilder(template=prompt_template))\npipe.add_component(\"llm\", OpenAIGenerator(api_key=Secret.from_env_var(\"OPENAI_API_KEY\")))\n\npipe.connect(\"search.documents\", \"prompt.documents\")\npipe.connect(\"prompt\", \"llm\")\n\n# Run the pipeline\nresult = pipe.run({\n \"search\": {\"query\": \"Latest developments in AI agents\"},\n \"prompt\": {\"query\": \"Latest developments in AI agents\"}\n})\n\nprint(result[\"llm\"][\"replies\"][0])\n```\n\n## Advanced Features\n\n### Multiple Search Engines\n\n```python\n# Use different engines for different queries\ngoogle_search = SerpexWebSearch(engine=\"google\")\nbing_search = SerpexWebSearch(engine=\"bing\")\nduckduckgo_search = SerpexWebSearch(engine=\"duckduckgo\")\n```\n\n### Time Range Filtering\n\n```python\n# Get only recent results\nrecent_results = web_search.run(\n query=\"AI news\",\n time_range=\"week\" # Options: \"day\", \"week\", \"month\", \"year\", \"all\"\n)\n```\n\n### Runtime Configuration Override\n\n```python\n# Override settings at runtime\nresults = web_search.run(\n query=\"Python tutorials\",\n engine=\"duckduckgo\", # Override default engine\n)\n```\n\n### Error Handling with Retries\n\nThe component includes built-in retry logic with exponential backoff:\n\n```python\nweb_search = SerpexWebSearch(\n api_key=Secret.from_env_var(\"SERPEX_API_KEY\"),\n timeout=10.0, # Request timeout in seconds\n retry_attempts=3 # Number of retry attempts\n)\n```\n\n## Component Reference\n\n### SerpexWebSearch\n\nA Haystack component for fetching web search results via the Serpex API.\n\n#### Parameters\n\n- **api_key** (`Secret`, optional): Serpex API key. Defaults to `SERPEX_API_KEY` environment variable.\n- **engine** (`str`, optional): Search engine to use. Options: `\"auto\"`, `\"google\"`, `\"bing\"`, `\"duckduckgo\"`, `\"brave\"`, `\"yahoo\"`, `\"yandex\"`. Defaults to `\"google\"`.\n- **timeout** (`float`, optional): Request timeout in seconds. Defaults to `10.0`.\n- **retry_attempts** (`int`, optional): Number of retry attempts. Defaults to `2`.\n\n#### Inputs\n\n- **query** (`str`): The search query string.\n- **engine** (`str`, optional): Override the default search engine.\n- **time_range** (`str`, optional): Filter by time range (`\"all\"`, `\"day\"`, `\"week\"`, `\"month\"`, `\"year\"`).\n\n#### Outputs\n\n- **documents** (`List[Document]`): List of Haystack Document objects containing search results.\n\nEach document includes:\n- **content**: The search result snippet\n- **meta**:\n - `title`: Result title\n - `url`: Result URL\n - `position`: Position in search results\n - `query`: Original search query\n - `engine`: Search engine used\n\n## Examples\n\nCheck out the [examples](examples/) directory for more use cases:\n\n- [Basic Search](examples/basic_search.py)\n- [RAG Pipeline](examples/rag_pipeline.py)\n- [Multi-Engine Comparison](examples/multi_engine.py)\n- [Agent with Web Search](examples/agent_example.py)\n\n## Why Serpex?\n\n- **\ud83c\udf10 Multi-Engine Access**: One API for all major search engines\n- **\u26a1 Fast & Reliable**: Optimized infrastructure with 99.9% uptime\n- **\ud83d\udcb0 Cost-Effective**: Competitive pricing with generous free tier\n- **\ud83d\udcca Rich Metadata**: Comprehensive result data including positions, timestamps, and more\n- **\ud83d\udd12 Secure**: Enterprise-grade security and data privacy\n- **\ud83d\ude80 Scalable**: Handle thousands of requests per second\n\n## Documentation\n\n- [Serpex API Documentation](https://docs.serpex.dev)\n- [Haystack Documentation](https://docs.haystack.deepset.ai)\n- [Integration Examples](examples/)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/divyeshradadiya/serpex-haystack.git\ncd serpex-haystack\n\n# Install with development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run linting\nruff check .\nblack --check .\n\n# Run type checking\nmypy src/\n```\n\n## License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udce7 Email: support@serpex.dev\n- \ud83d\udcac Discord: [Join our community](https://discord.com/channels/1417759329385316383/1421004675343319102)\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/divyeshradadiya/serpex-haystack/issues)\n- \ud83d\udcd6 Docs: [docs.serpex.dev](https://serpex.dev/docs)\n\n## Acknowledgments\n\nBuilt with \u2764\ufe0f for the Haystack community by [Divyesh Radadiya](https://github.com/divyeshradadiya)\n\n---\n\n**Note**: This is a community-maintained integration. For Serpex API support, visit [serpex.dev](https://serpex.dev).\n",
"bugtrack_url": null,
"license": null,
"summary": "Haystack integration for Serpex web search - supporting Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://docs.serpex.dev",
"Homepage": "https://serpex.dev",
"Issues": "https://github.com/divyeshradadiya/serpex-haystack/issues",
"Repository": "https://github.com/divyeshradadiya/serpex-haystack"
},
"split_keywords": [
"ai",
" bing-search",
" duckduckgo",
" google-search",
" haystack",
" llm",
" nlp",
" search-api",
" serpex",
" web-search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5b77d3d43782106611220470a52554b261b510f7c17932cc75e676e191a9c85a",
"md5": "86f51abcd5b5dcd26ae7cce7f5469669",
"sha256": "de987d036eb4ed2dabfc42e764971cfc3883cbf573b56bd3966c5aab1ce32b3f"
},
"downloads": -1,
"filename": "serpex_haystack-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86f51abcd5b5dcd26ae7cce7f5469669",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11894,
"upload_time": "2025-11-08T13:41:58",
"upload_time_iso_8601": "2025-11-08T13:41:58.092732Z",
"url": "https://files.pythonhosted.org/packages/5b/77/d3d43782106611220470a52554b261b510f7c17932cc75e676e191a9c85a/serpex_haystack-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8b0cab242e0282f02f787b9b3fe24b9cc5dd2fa7c84283515251b7eeffda7ed1",
"md5": "ba522985d095560f2d6d30c71eccf4dc",
"sha256": "037e58e8f470f2602aaa3f8e6237cf84622ad59d8bfa56c7d88d466e417aa522"
},
"downloads": -1,
"filename": "serpex_haystack-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ba522985d095560f2d6d30c71eccf4dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11724,
"upload_time": "2025-11-08T13:41:59",
"upload_time_iso_8601": "2025-11-08T13:41:59.591877Z",
"url": "https://files.pythonhosted.org/packages/8b/0c/ab242e0282f02f787b9b3fe24b9cc5dd2fa7c84283515251b7eeffda7ed1/serpex_haystack-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-08 13:41:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "divyeshradadiya",
"github_project": "serpex-haystack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "serpex-haystack"
}
JSON
