├── .env.example
├── .gitignore
├── LICENSE
├── README.md
├── assets
├── evals.png
└── sentient-logo-narrow.png
├── evals
├── README.md
├── autograde_df.py
├── datasets
│ ├── frames_test_set.csv
│ └── simple_qa_test_set.csv
├── eval_gpt_web.py
├── eval_tasks.py
├── gpt_web_extract.py
└── grader_prompts.py
├── gradio_demo.py
├── pdm.lock
├── pyproject.toml
├── requirements.txt
├── src
└── opendeepsearch
│ ├── __init__.py
│ ├── context_building
│ ├── build_context.py
│ └── process_sources_pro.py
│ ├── context_scraping
│ ├── basic_web_scraper.py
│ ├── crawl4ai_scraper.py
│ ├── extraction_result.py
│ ├── fast_scraper.py
│ ├── strategy_factory.py
│ └── utils.py
│ ├── ods_agent.py
│ ├── ods_tool.py
│ ├── prompts.py
│ ├── ranking_models
│ ├── README.md
│ ├── base_reranker.py
│ ├── chunker.py
│ ├── infinity_rerank.py
│ └── jina_reranker.py
│ ├── serp_search
│ └── serp_search.py
│ └── wolfram_tool.py
└── tests
└── __init__.py
/.env.example:
--------------------------------------------------------------------------------
1 | # SEARXNG_INSTANCE_URL=http://searxng:8080
2 | # or
3 | # SERPER_API_KEY=
4 |
5 | JINA_API_KEY=
6 | WOLFRAM_ALPHA_APP_ID=
7 |
8 | ### Providers ###
9 | OPENAI_API_KEY=
10 | OPENAI_BASE_URL=
11 | ANTHROPIC_API_KEY=
12 | OPENROUTER_API_KEY=
13 |
14 | # LiteLLM model IDs for different tasks
15 | LITELLM_MODEL_ID=openrouter/google/gemini-2.0-flash-001
16 | LITELLM_SEARCH_MODEL_ID=openrouter/google/gemini-2.0-flash-001
17 | LITELLM_ORCHESTRATOR_MODEL_ID=openrouter/google/gemini-2.0-flash-001
18 | LITELLM_EVAL_MODEL_ID=gpt-4o-mini
19 | FIREWORKS_API_KEY=
20 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Byte-compiled / optimized / DLL files
2 | __pycache__/
3 | *.py[cod]
4 | *$py.class
5 |
6 | # C extensions
7 | *.so
8 | *.ipynb
9 | *.ipynb_checkpoints
10 | output/
11 |
12 | # Distribution / packaging
13 | .Python
14 | build/
15 | develop-eggs/
16 | dist/
17 | downloads/
18 | eggs/
19 | .eggs/
20 | lib/
21 | lib64/
22 | parts/
23 | sdist/
24 | var/
25 | wheels/
26 | share/python-wheels/
27 | *.egg-info/
28 | .installed.cfg
29 | *.egg
30 | MANIFEST
31 |
32 | # PyInstaller
33 | # Usually these files are written by a python script from a template
34 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
35 | *.manifest
36 | *.spec
37 |
38 | # Installer logs
39 | pip-log.txt
40 | pip-delete-this-directory.txt
41 |
42 | # Unit test / coverage reports
43 | htmlcov/
44 | .tox/
45 | .nox/
46 | .coverage
47 | .coverage.*
48 | .cache
49 | nosetests.xml
50 | coverage.xml
51 | *.cover
52 | *.py,cover
53 | .hypothesis/
54 | .pytest_cache/
55 | cover/
56 |
57 | # Translations
58 | *.mo
59 | *.pot
60 |
61 | # Django stuff:
62 | *.log
63 | local_settings.py
64 | db.sqlite3
65 | db.sqlite3-journal
66 |
67 | # Flask stuff:
68 | instance/
69 | .webassets-cache
70 |
71 | # Scrapy stuff:
72 | .scrapy
73 |
74 | # Sphinx documentation
75 | docs/_build/
76 |
77 | # PyBuilder
78 | .pybuilder/
79 | target/
80 |
81 | # Jupyter Notebook
82 | .ipynb_checkpoints
83 |
84 | # IPython
85 | profile_default/
86 | ipython_config.py
87 |
88 | # pyenv
89 | # For a library or package, you might want to ignore these files since the code is
90 | # intended to run in multiple environments; otherwise, check them in:
91 | # .python-version
92 |
93 | # pipenv
94 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
95 | # However, in case of collaboration, if having platform-specific dependencies or dependencies
96 | # having no cross-platform support, pipenv may install dependencies that don't work, or not
97 | # install all needed dependencies.
98 | #Pipfile.lock
99 |
100 | # poetry
101 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
102 | # This is especially recommended for binary packages to ensure reproducibility, and is more
103 | # commonly ignored for libraries.
104 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
105 | #poetry.lock
106 |
107 | # pdm
108 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
109 | #pdm.lock
110 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
111 | # in version control.
112 | # https://pdm-project.org/#use-with-ide
113 | .pdm.toml
114 | .pdm-python
115 | .pdm-build/
116 |
117 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
118 | __pypackages__/
119 |
120 | # Celery stuff
121 | celerybeat-schedule
122 | celerybeat.pid
123 |
124 | # SageMath parsed files
125 | *.sage.py
126 |
127 | # Environments
128 | .env
129 | .venv
130 | env/
131 | venv/
132 | ENV/
133 | env.bak/
134 | venv.bak/
135 |
136 | # Spyder project settings
137 | .spyderproject
138 | .spyproject
139 |
140 | # Rope project settings
141 | .ropeproject
142 |
143 | # mkdocs documentation
144 | /site
145 |
146 | # mypy
147 | .mypy_cache/
148 | .dmypy.json
149 | dmypy.json
150 |
151 | # Pyre type checker
152 | .pyre/
153 |
154 | # pytype static type analyzer
155 | .pytype/
156 |
157 | # Cython debug symbols
158 | cython_debug/
159 |
160 | # PyCharm
161 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
162 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
163 | # and can be added to the global gitignore or merged into this file. For a more nuclear
164 | # option (not recommended) you can uncomment the following to ignore the entire idea folder.
165 | #.idea/
166 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Apache License
2 | Version 2.0, January 2004
3 | http://www.apache.org/licenses/
4 |
5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6 |
7 | 1. Definitions.
8 |
9 | "License" shall mean the terms and conditions for use, reproduction,
10 | and distribution as defined by Sections 1 through 9 of this document.
11 |
12 | "Licensor" shall mean the copyright owner or entity authorized by
13 | the copyright owner that is granting the License.
14 |
15 | "Legal Entity" shall mean the union of the acting entity and all
16 | other entities that control, are controlled by, or are under common
17 | control with that entity. For the purposes of this definition,
18 | "control" means (i) the power, direct or indirect, to cause the
19 | direction or management of such entity, whether by contract or
20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
21 | outstanding shares, or (iii) beneficial ownership of such entity.
22 |
23 | "You" (or "Your") shall mean an individual or Legal Entity
24 | exercising permissions granted by this License.
25 |
26 | "Source" form shall mean the preferred form for making modifications,
27 | including but not limited to software source code, documentation
28 | source, and configuration files.
29 |
30 | "Object" form shall mean any form resulting from mechanical
31 | transformation or translation of a Source form, including but
32 | not limited to compiled object code, generated documentation,
33 | and conversions to other media types.
34 |
35 | "Work" shall mean the work of authorship, whether in Source or
36 | Object form, made available under the License, as indicated by a
37 | copyright notice that is included in or attached to the work
38 | (an example is provided in the Appendix below).
39 |
40 | "Derivative Works" shall mean any work, whether in Source or Object
41 | form, that is based on (or derived from) the Work and for which the
42 | editorial revisions, annotations, elaborations, or other modifications
43 | represent, as a whole, an original work of authorship. For the purposes
44 | of this License, Derivative Works shall not include works that remain
45 | separable from, or merely link (or bind by name) to the interfaces of,
46 | the Work and Derivative Works thereof.
47 |
48 | "Contribution" shall mean any work of authorship, including
49 | the original version of the Work and any modifications or additions
50 | to that Work or Derivative Works thereof, that is intentionally
51 | submitted to Licensor for inclusion in the Work by the copyright owner
52 | or by an individual or Legal Entity authorized to submit on behalf of
53 | the copyright owner. For the purposes of this definition, "submitted"
54 | means any form of electronic, verbal, or written communication sent
55 | to the Licensor or its representatives, including but not limited to
56 | communication on electronic mailing lists, source code control systems,
57 | and issue tracking systems that are managed by, or on behalf of, the
58 | Licensor for the purpose of discussing and improving the Work, but
59 | excluding communication that is conspicuously marked or otherwise
60 | designated in writing by the copyright owner as "Not a Contribution."
61 |
62 | "Contributor" shall mean Licensor and any individual or Legal Entity
63 | on behalf of whom a Contribution has been received by Licensor and
64 | subsequently incorporated within the Work.
65 |
66 | 2. Grant of Copyright License. Subject to the terms and conditions of
67 | this License, each Contributor hereby grants to You a perpetual,
68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69 | copyright license to reproduce, prepare Derivative Works of,
70 | publicly display, publicly perform, sublicense, and distribute the
71 | Work and such Derivative Works in Source or Object form.
72 |
73 | 3. Grant of Patent License. Subject to the terms and conditions of
74 | this License, each Contributor hereby grants to You a perpetual,
75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76 | (except as stated in this section) patent license to make, have made,
77 | use, offer to sell, sell, import, and otherwise transfer the Work,
78 | where such license applies only to those patent claims licensable
79 | by such Contributor that are necessarily infringed by their
80 | Contribution(s) alone or by combination of their Contribution(s)
81 | with the Work to which such Contribution(s) was submitted. If You
82 | institute patent litigation against any entity (including a
83 | cross-claim or counterclaim in a lawsuit) alleging that the Work
84 | or a Contribution incorporated within the Work constitutes direct
85 | or contributory patent infringement, then any patent licenses
86 | granted to You under this License for that Work shall terminate
87 | as of the date such litigation is filed.
88 |
89 | 4. Redistribution. You may reproduce and distribute copies of the
90 | Work or Derivative Works thereof in any medium, with or without
91 | modifications, and in Source or Object form, provided that You
92 | meet the following conditions:
93 |
94 | (a) You must give any other recipients of the Work or
95 | Derivative Works a copy of this License; and
96 |
97 | (b) You must cause any modified files to carry prominent notices
98 | stating that You changed the files; and
99 |
100 | (c) You must retain, in the Source form of any Derivative Works
101 | that You distribute, all copyright, patent, trademark, and
102 | attribution notices from the Source form of the Work,
103 | excluding those notices that do not pertain to any part of
104 | the Derivative Works; and
105 |
106 | (d) If the Work includes a "NOTICE" text file as part of its
107 | distribution, then any Derivative Works that You distribute must
108 | include a readable copy of the attribution notices contained
109 | within such NOTICE file, excluding those notices that do not
110 | pertain to any part of the Derivative Works, in at least one
111 | of the following places: within a NOTICE text file distributed
112 | as part of the Derivative Works; within the Source form or
113 | documentation, if provided along with the Derivative Works; or,
114 | within a display generated by the Derivative Works, if and
115 | wherever such third-party notices normally appear. The contents
116 | of the NOTICE file are for informational purposes only and
117 | do not modify the License. You may add Your own attribution
118 | notices within Derivative Works that You distribute, alongside
119 | or as an addendum to the NOTICE text from the Work, provided
120 | that such additional attribution notices cannot be construed
121 | as modifying the License.
122 |
123 | You may add Your own copyright statement to Your modifications and
124 | may provide additional or different license terms and conditions
125 | for use, reproduction, or distribution of Your modifications, or
126 | for any such Derivative Works as a whole, provided Your use,
127 | reproduction, and distribution of the Work otherwise complies with
128 | the conditions stated in this License.
129 |
130 | 5. Submission of Contributions. Unless You explicitly state otherwise,
131 | any Contribution intentionally submitted for inclusion in the Work
132 | by You to the Licensor shall be under the terms and conditions of
133 | this License, without any additional terms or conditions.
134 | Notwithstanding the above, nothing herein shall supersede or modify
135 | the terms of any separate license agreement you may have executed
136 | with Licensor regarding such Contributions.
137 |
138 | 6. Trademarks. This License does not grant permission to use the trade
139 | names, trademarks, service marks, or product names of the Licensor,
140 | except as required for reasonable and customary use in describing the
141 | origin of the Work and reproducing the content of the NOTICE file.
142 |
143 | 7. Disclaimer of Warranty. Unless required by applicable law or
144 | agreed to in writing, Licensor provides the Work (and each
145 | Contributor provides its Contributions) on an "AS IS" BASIS,
146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 | implied, including, without limitation, any warranties or conditions
148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 | PARTICULAR PURPOSE. You are solely responsible for determining the
150 | appropriateness of using or redistributing the Work and assume any
151 | risks associated with Your exercise of permissions under this License.
152 |
153 | 8. Limitation of Liability. In no event and under no legal theory,
154 | whether in tort (including negligence), contract, or otherwise,
155 | unless required by applicable law (such as deliberate and grossly
156 | negligent acts) or agreed to in writing, shall any Contributor be
157 | liable to You for damages, including any direct, indirect, special,
158 | incidental, or consequential damages of any character arising as a
159 | result of this License or out of the use or inability to use the
160 | Work (including but not limited to damages for loss of goodwill,
161 | work stoppage, computer failure or malfunction, or any and all
162 | other commercial damages or losses), even if such Contributor
163 | has been advised of the possibility of such damages.
164 |
165 | 9. Accepting Warranty or Additional Liability. While redistributing
166 | the Work or Derivative Works thereof, You may choose to offer,
167 | and charge a fee for, acceptance of support, warranty, indemnity,
168 | or other liability obligations and/or rights consistent with this
169 | License. However, in accepting such obligations, You may act only
170 | on Your own behalf and on Your sole responsibility, not on behalf
171 | of any other Contributor, and only if You agree to indemnify,
172 | defend, and hold each Contributor harmless for any liability
173 | incurred by, or claims asserted against, such Contributor by reason
174 | of your accepting any such warranty or additional liability.
175 |
176 | END OF TERMS AND CONDITIONS
177 |
178 | APPENDIX: How to apply the Apache License to your work.
179 |
180 | To apply the Apache License to your work, attach the following
181 | boilerplate notice, with the fields enclosed by brackets "[]"
182 | replaced with your own identifying information. (Don't include
183 | the brackets!) The text should be enclosed in the appropriate
184 | comment syntax for the file format. We also recommend that a
185 | file or class name and description of purpose be included on the
186 | same "printed page" as the copyright notice for easier
187 | identification within third-party archives.
188 |
189 | Copyright [yyyy] [name of copyright owner]
190 |
191 | Licensed under the Apache License, Version 2.0 (the "License");
192 | you may not use this file except in compliance with the License.
193 | You may obtain a copy of the License at
194 |
195 | http://www.apache.org/licenses/LICENSE-2.0
196 |
197 | Unless required by applicable law or agreed to in writing, software
198 | distributed under the License is distributed on an "AS IS" BASIS,
199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 | See the License for the specific language governing permissions and
201 | limitations under the License.
202 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # 🔍OpenDeepSearch: Democratizing Search with Open-source Reasoning Models and Reasoning Agents 🚀
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
12 |
23 |
24 |
32 |
33 |
36 |
37 | ## Description 📝
38 |
39 | OpenDeepSearch is a lightweight yet powerful search tool designed for seamless integration with AI agents. It enables deep web search and retrieval, optimized for use with Hugging Face's **[SmolAgents](https://github.com/huggingface/smolagents)** ecosystem.
40 |
41 |
42 |
43 |
', html)
161 |
162 |
163 | def clean_html(html: str, clean_svg: bool = False, clean_base64: bool = False):
164 | """Clean HTML content by removing various elements."""
165 | patterns = [
166 | SCRIPT_PATTERN,
167 | STYLE_PATTERN,
168 | META_PATTERN,
169 | COMMENT_PATTERN,
170 | LINK_PATTERN,
171 | IFRAME_PATTERN,
172 | NOSCRIPT_PATTERN,
173 | HEADER_PATTERN,
174 | FOOTER_PATTERN,
175 | NAV_PATTERN,
176 | FORM_PATTERN
177 | ]
178 |
179 | for pattern in patterns:
180 | html = re.sub(pattern, "", html, flags=re.IGNORECASE | re.MULTILINE | re.DOTALL)
181 |
182 | if clean_svg:
183 | html = replace_svg(html)
184 | if clean_base64:
185 | html = replace_base64_images(html)
186 |
187 | # Remove empty lines and excessive whitespace
188 | html = re.sub(r'\n\s*\n', '\n', html)
189 | html = re.sub(r'\s+', ' ', html)
190 |
191 | return html.strip()
192 |
193 | JSON_SCHEMA = """
194 | {
195 | "type": "object",
196 | "properties": {
197 | "title": {
198 | "type": "string"
199 | },
200 | "author": {
201 | "type": "string"
202 | },
203 | "date": {
204 | "type": "string"
205 | },
206 | "content": {
207 | "type": "string"
208 | }
209 | },
210 | "required": ["title", "author", "date", "content"]
211 | }
212 | """
--------------------------------------------------------------------------------
/src/opendeepsearch/ods_agent.py:
--------------------------------------------------------------------------------
1 | from typing import Optional, Dict, Any, Literal
2 | from opendeepsearch.serp_search.serp_search import create_search_api, SearchAPI
3 | from opendeepsearch.context_building.process_sources_pro import SourceProcessor
4 | from opendeepsearch.context_building.build_context import build_context
5 | from litellm import completion, utils
6 | from dotenv import load_dotenv
7 | import os
8 | from opendeepsearch.prompts import SEARCH_SYSTEM_PROMPT
9 | import asyncio
10 | import nest_asyncio
11 | load_dotenv()
12 |
13 | class OpenDeepSearchAgent:
14 | def __init__(
15 | self,
16 | model: Optional[str] = None, #We use LiteLLM to call the model
17 | system_prompt: Optional[str] = SEARCH_SYSTEM_PROMPT,
18 | search_provider: Literal["serper", "searxng"] = "serper",
19 | serper_api_key: Optional[str] = None,
20 | searxng_instance_url: Optional[str] = None,
21 | searxng_api_key: Optional[str] = None,
22 | source_processor_config: Optional[Dict[str, Any]] = None,
23 | temperature: float = 0.2, # Slight variation while maintaining reliability
24 | top_p: float = 0.3, # Focus on high-confidence tokens
25 | reranker: Optional[str] = "None", # Optional reranker identifier
26 | ):
27 | """
28 | Initialize an OpenDeepSearch agent that combines web search, content processing, and LLM capabilities.
29 |
30 | This agent performs web searches using either SerperAPI or SearXNG, processes the search results to extract
31 | relevant information, and uses a language model to generate responses based on the gathered context.
32 |
33 | Args:
34 | model (str): The identifier for the language model to use (compatible with LiteLLM).
35 | system_prompt (str, optional): Custom system prompt for the language model. If not provided,
36 | uses a default prompt that instructs the model to answer based on context.
37 | search_provider (str, optional): The search provider to use ('serper' or 'searxng'). Default is 'serper'.
38 | serper_api_key (str, optional): API key for SerperAPI. Required if search_provider is 'serper' and
39 | SERPER_API_KEY environment variable is not set.
40 | searxng_instance_url (str, optional): URL of the SearXNG instance. Required if search_provider is 'searxng'
41 | and SEARXNG_INSTANCE_URL environment variable is not set.
42 | searxng_api_key (str, optional): API key for SearXNG instance. Optional even if search_provider is 'searxng'.
43 | source_processor_config (Dict[str, Any], optional): Configuration dictionary for the
44 | SourceProcessor. Supports the following options:
45 | - strategies (List[str]): Content extraction strategies to use
46 | - filter_content (bool): Whether to enable content filtering
47 | - top_results (int): Number of top results to process
48 | temperature (float, default=0.2): Controls randomness in model outputs. Lower values make
49 | the output more focused and deterministic.
50 | top_p (float, default=0.3): Controls nucleus sampling for model outputs. Lower values make
51 | the output more focused on high-probability tokens.
52 | reranker (str, optional): Identifier for the reranker to use. If not provided,
53 | uses the default reranker from SourceProcessor.
54 | """
55 | # Initialize search API based on provider
56 | self.serp_search = create_search_api(
57 | search_provider=search_provider,
58 | serper_api_key=serper_api_key,
59 | searxng_instance_url=searxng_instance_url,
60 | searxng_api_key=searxng_api_key
61 | )
62 |
63 | # Update source_processor_config with reranker if provided
64 | if source_processor_config is None:
65 | source_processor_config = {}
66 | if reranker:
67 | source_processor_config['reranker'] = reranker
68 |
69 | # Initialize SourceProcessor with provided config or defaults
70 | self.source_processor = SourceProcessor(**source_processor_config)
71 |
72 | # Initialize LLM settings
73 | self.model = model if model is not None else os.getenv("LITELLM_SEARCH_MODEL_ID", os.getenv("LITELLM_MODEL_ID", "openrouter/google/gemini-2.0-flash-001"))
74 | self.temperature = temperature
75 | self.top_p = top_p
76 | self.system_prompt = system_prompt
77 |
78 | # Configure LiteLLM with OpenAI base URL if provided
79 | openai_base_url = os.environ.get("OPENAI_BASE_URL")
80 | if openai_base_url:
81 | utils.set_provider_config("openai", {"base_url": openai_base_url})
82 |
83 | async def search_and_build_context(
84 | self,
85 | query: str,
86 | max_sources: int = 2,
87 | pro_mode: bool = False
88 | ) -> str:
89 | """
90 | Performs a web search and builds a context from the search results.
91 |
92 | This method executes a search query, processes the returned sources, and builds a
93 | consolidated context, inspired by FreshPrompt in the FreshLLMs paper, that can be used for answering questions.
94 |
95 | Args:
96 | query (str): The search query to execute.
97 | max_sources (int, default=2): Maximum number of sources to process. If pro_mode
98 | is enabled, this overrides the top_results setting in source_processor_config
99 | when it's smaller.
100 | pro_mode (bool, default=False): When enabled, performs a deeper search and more
101 | thorough content processing.
102 |
103 | Returns:
104 | str: A formatted context string built from the processed search results.
105 | """
106 | # Get sources from SERP
107 | sources = self.serp_search.get_sources(query)
108 |
109 | # Process sources
110 | processed_sources = await self.source_processor.process_sources(
111 | sources,
112 | max_sources,
113 | query,
114 | pro_mode
115 | )
116 |
117 | # Build and return context
118 | return build_context(processed_sources)
119 |
120 | async def ask(
121 | self,
122 | query: str,
123 | max_sources: int = 2,
124 | pro_mode: bool = False,
125 | ) -> str:
126 | """
127 | Searches for information and generates an AI response to the query.
128 |
129 | This method combines web search, context building, and AI completion to provide
130 | informed answers to questions. It first gathers relevant information through search,
131 | then uses an LLM to generate a response based on the collected context.
132 |
133 | Args:
134 | query (str): The question or query to answer.
135 | max_sources (int, default=2): Maximum number of sources to include in the context.
136 | pro_mode (bool, default=False): When enabled, performs a more comprehensive search
137 | and analysis of sources.
138 |
139 | Returns:
140 | str: An AI-generated response that answers the query based on the gathered context.
141 | """
142 | # Get context from search results
143 | context = await self.search_and_build_context(query, max_sources, pro_mode)
144 | # Prepare messages for the LLM
145 | messages = [
146 | {"role": "system", "content": self.system_prompt},
147 | {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {query}"}
148 | ]
149 | # Get completion from LLM
150 | response = completion(
151 | model=self.model,
152 | messages=messages,
153 | temperature=self.temperature,
154 | top_p=self.top_p
155 | )
156 |
157 | return response.choices[0].message.content
158 |
159 | def ask_sync(
160 | self,
161 | query: str,
162 | max_sources: int = 2,
163 | pro_mode: bool = False,
164 | ) -> str:
165 | """
166 | Synchronous version of ask() method.
167 | """
168 | try:
169 | # Try getting the current event loop
170 | loop = asyncio.get_event_loop()
171 | if loop.is_running():
172 | # If we're in a running event loop (e.g., Jupyter), use nest_asyncio
173 | nest_asyncio.apply()
174 | except RuntimeError:
175 | # If there's no event loop, create a new one
176 | loop = asyncio.new_event_loop()
177 | asyncio.set_event_loop(loop)
178 |
179 | return loop.run_until_complete(self.ask(query, max_sources, pro_mode))
180 |
--------------------------------------------------------------------------------
/src/opendeepsearch/ods_tool.py:
--------------------------------------------------------------------------------
1 | from typing import Optional, Literal
2 | from smolagents import Tool
3 | from opendeepsearch.ods_agent import OpenDeepSearchAgent
4 |
5 | class OpenDeepSearchTool(Tool):
6 | name = "web_search"
7 | description = """
8 | Performs web search based on your query (think a Google search) then returns the final answer that is processed by an llm."""
9 | inputs = {
10 | "query": {
11 | "type": "string",
12 | "description": "The search query to perform",
13 | },
14 | }
15 | output_type = "string"
16 |
17 | def __init__(
18 | self,
19 | model_name: Optional[str] = None,
20 | reranker: str = "infinity",
21 | search_provider: Literal["serper", "searxng"] = "serper",
22 | serper_api_key: Optional[str] = None,
23 | searxng_instance_url: Optional[str] = None,
24 | searxng_api_key: Optional[str] = None
25 | ):
26 | super().__init__()
27 | self.search_model_name = model_name # LiteLLM model name
28 | self.reranker = reranker
29 | self.search_provider = search_provider
30 | self.serper_api_key = serper_api_key
31 | self.searxng_instance_url = searxng_instance_url
32 | self.searxng_api_key = searxng_api_key
33 |
34 | def forward(self, query: str):
35 | answer = self.search_tool.ask_sync(query, max_sources=2, pro_mode=True)
36 | return answer
37 |
38 | def setup(self):
39 | self.search_tool = OpenDeepSearchAgent(
40 | self.search_model_name,
41 | reranker=self.reranker,
42 | search_provider=self.search_provider,
43 | serper_api_key=self.serper_api_key,
44 | searxng_instance_url=self.searxng_instance_url,
45 | searxng_api_key=self.searxng_api_key
46 | )
47 |
--------------------------------------------------------------------------------
/src/opendeepsearch/prompts.py:
--------------------------------------------------------------------------------
1 | from smolagents import PromptTemplates
2 |
3 | SEARCH_SYSTEM_PROMPT = """
4 | You are an AI-powered search agent that takes in a user’s search query, retrieves relevant search results, and provides an accurate and concise answer based on the provided context.
5 |
6 | ## **Guidelines**
7 |
8 | ### 1. **Prioritize Reliable Sources**
9 | - Use **ANSWER BOX** when available, as it is the most likely authoritative source.
10 | - Prefer **Wikipedia** if present in the search results for general knowledge queries.
11 | - If there is a conflict between **Wikipedia** and the **ANSWER BOX**, rely on **Wikipedia**.
12 | - Prioritize **government (.gov), educational (.edu), reputable organizations (.org), and major news outlets** over less authoritative sources.
13 | - When multiple sources provide conflicting information, prioritize the most **credible, recent, and consistent** source.
14 |
15 | ### 2. **Extract the Most Relevant Information**
16 | - Focus on **directly answering the query** using the information from the **ANSWER BOX** or **SEARCH RESULTS**.
17 | - Use **additional information** only if it provides **directly relevant** details that clarify or expand on the query.
18 | - Ignore promotional, speculative, or repetitive content.
19 |
20 | ### 3. **Provide a Clear and Concise Answer**
21 | - Keep responses **brief (1–3 sentences)** while ensuring accuracy and completeness.
22 | - If the query involves **numerical data** (e.g., prices, statistics), return the **most recent and precise value** available.
23 | - If the source is available, then mention it in the answer to the question. If you're relying on the answer box, then do not mention the source if it's not there.
24 | - For **diverse or expansive queries** (e.g., explanations, lists, or opinions), provide a more detailed response when the context justifies it.
25 |
26 | ### 4. **Handle Uncertainty and Ambiguity**
27 | - If **conflicting answers** are present, acknowledge the discrepancy and mention the different perspectives if relevant.
28 | - If **no relevant information** is found in the context, explicitly state that the query could not be answered.
29 |
30 | ### 5. **Answer Validation**
31 | - Only return answers that can be **directly validated** from the provided context.
32 | - Do not generate speculative or outside knowledge answers. If the context does not contain the necessary information, state that the answer could not be found.
33 |
34 | ### 6. **Bias and Neutrality**
35 | - Maintain **neutral language** and avoid subjective opinions.
36 | - For controversial topics, present multiple perspectives if they are available and relevant.
37 | """
38 |
39 | REACT_PROMPT = PromptTemplates(system_prompt="""
40 | You are an expert assistant who can solve any task using tool calls. You will be given a task to solve as best you can.
41 | To do so, you have been given access to some tools.
42 |
43 | The tool call you write is an action: after the tool is executed, you will get the result of the tool call as an "observation".
44 | This Action/Observation can repeat N times, you should take several steps when needed.
45 |
46 | You can use the result of the previous action as input for the next action.
47 | The observation will always be a string: it can represent a file, like "image_1.jpg".
48 | Then you can use it as input for the next action. You can do it for instance as follows:
49 |
50 | Observation: "image_1.jpg"
51 |
52 | Action:
53 | {
54 | "name": "image_transformer",
55 | "arguments": {"image": "image_1.jpg"}
56 | }
57 |
58 | To provide the final answer to the task, use an action blob with "name": "final_answer" tool. It is the only way to complete the task, else you will be stuck on a loop. So your final output should look like this:
59 | Action:
60 | {
61 | "name": "final_answer",
62 | "arguments": {"answer": "insert your final answer here"}
63 | }
64 |
65 |
66 | Here are a few examples using notional tools:
67 | ---
68 | Task: "What historical event happened closest in time to the invention of the telephone: the American Civil War or the establishment of the Eiffel Tower?"
69 |
70 | Action:
71 | {
72 | "name": "web_search",
73 | "arguments": {"query": "year of telephone invention"}
74 | }
75 | Observation: "The telephone was invented in 1876."
76 |
77 | Action:
78 | {
79 | "name": "web_search",
80 | "arguments": {"query": "year American Civil War ended"}
81 | }
82 | Observation: "The American Civil War ended in 1865."
83 |
84 | Action:
85 | {
86 | "name": "web_search",
87 | "arguments": {"query": "year Eiffel Tower established"}
88 | }
89 | Observation: "The Eiffel Tower was completed in 1889."
90 |
91 | Action:
92 | {
93 | "name": "calculate",
94 | "arguments": {"expression": "|1876 - 1865| and |1889 - 1876|"}
95 | }
96 | Observation: "11 years (Civil War) and 13 years (Eiffel Tower)."
97 |
98 | Action:
99 | {
100 | "name": "final_answer",
101 | "arguments": {"answer": "The historical event closest in time to the invention of the telephone is the end of the American Civil War (11 years apart)."}
102 | }
103 |
104 | ---
105 | Task: "Which country has a higher population density: Japan or India?"
106 |
107 | Action:
108 | {
109 | "name": "web_search",
110 | "arguments": {"query": "population and area of Japan"}
111 | }
112 | Observation: "Japan has a population of 125 million and an area of 377,975 square kilometers."
113 |
114 | Action:
115 | {
116 | "name": "web_search",
117 | "arguments": {"query": "population and area of India"}
118 | }
119 | Observation: "India has a population of 1.38 billion and an area of 3,287,263 square kilometers."
120 |
121 | Action:
122 | {
123 | "name": "calculate",
124 | "arguments": {"expression": "125 million / 377,975 and 1.38 billion / 3,287,263"}
125 | }
126 | Observation: "Japan: 330.7 people/km²; India: 419.6 people/km²."
127 |
128 | Action:
129 | {
130 | "name": "final_answer",
131 | "arguments": {"answer": "India has a higher population density (419.6 people/km²) than Japan (330.7 people/km²)."}
132 | }
133 |
134 | ---
135 | Task: "Which country has won more total Olympic gold medals: the United States or China?"
136 |
137 | Action:
138 | {
139 | "name": "web_search",
140 | "arguments": {"query": "total Olympic gold medals won by the United States"}
141 | }
142 | Observation: "The United States has won 1,127 gold medals."
143 |
144 | Action:
145 | {
146 | "name": "web_search",
147 | "arguments": {"query": "total Olympic gold medals won by China"}
148 | }
149 | Observation: "China has won 283 gold medals."
150 |
151 | Action:
152 | {
153 | "name": "calculate",
154 | "arguments": {"expression": "1,127 - 283"}
155 | }
156 | Observation: "The United States has 844 more gold medals than China."
157 |
158 | Action:
159 | {
160 | "name": "final_answer",
161 | "arguments": {"answer": "The United States has won more Olympic gold medals (1,127) than China (283)."}
162 | }
163 |
164 | ---
165 | Task: "Who discovered the structure of DNA, and in which year was the discovery made?"
166 |
167 | Action:
168 | {
169 | "name": "web_search",
170 | "arguments": {"query": "scientists who discovered DNA structure"}
171 | }
172 | Observation: "James Watson and Francis Crick discovered the structure of DNA."
173 |
174 | Action:
175 | {
176 | "name": "web_search",
177 | "arguments": {"query": "year DNA structure discovered"}
178 | }
179 | Observation: "The structure of DNA was discovered in 1953."
180 |
181 | Action:
182 | {
183 | "name": "final_answer",
184 | "arguments": {"answer": "James Watson and Francis Crick discovered the structure of DNA in 1953."}
185 | }
186 |
187 | ---
188 | Task: "How many meters taller is the Burj Khalifa compared to the Empire State Building?"
189 |
190 | Action:
191 | {
192 | "name": "web_search",
193 | "arguments": {"query": "height of Burj Khalifa"}
194 | }
195 | Observation: "The Burj Khalifa is 828 meters tall."
196 |
197 | Action:
198 | {
199 | "name": "web_search",
200 | "arguments": {"query": "height of Empire State Building"}
201 | }
202 | Observation: "The Empire State Building is 381 meters tall."
203 |
204 | Action:
205 | {
206 | "name": "calculate",
207 | "arguments": {"expression": "828 - 381"}
208 | }
209 | Observation: "The difference is 447 meters."
210 |
211 | Action:
212 | {
213 | "name": "final_answer",
214 | "arguments": {"answer": "The Burj Khalifa is 447 meters taller than the Empire State Building."}
215 | }
216 |
217 | ---
218 | Task: "Which country launched the first satellite into space, and what was the name of the satellite?"
219 |
220 | Action:
221 | {
222 | "name": "web_search",
223 | "arguments": {"query": "first satellite launched into space"}
224 | }
225 | Observation: "The Soviet Union launched the first satellite."
226 |
227 | Action:
228 | {
229 | "name": "web_search",
230 | "arguments": {"query": "name of first satellite in space"}
231 | }
232 | Observation: "The first satellite was Sputnik 1."
233 |
234 | Action:
235 | {
236 | "name": "final_answer",
237 | "arguments": {"answer": "The Soviet Union launched the first satellite into space, named Sputnik 1."}
238 | }
239 |
240 | ---
241 | Task: "Which novel by George Orwell introduced the concept of 'Big Brother,' and in what year was it published?"
242 |
243 | Action:
244 | {
245 | "name": "web_search",
246 | "arguments": {"query": "novel by George Orwell Big Brother"}
247 | }
248 | Observation: "The novel is '1984.'"
249 |
250 | Action:
251 | {
252 | "name": "web_search",
253 | "arguments": {"query": "year '1984' by George Orwell published"}
254 | }
255 | Observation: "'1984' was published in 1949."
256 |
257 | Action:
258 | {
259 | "name": "final_answer",
260 | "arguments": {"answer": "George Orwell's novel '1984,' which introduced the concept of 'Big Brother,' was published in 1949."}
261 | }
262 |
263 | ---
264 | Task: "Which country hosted the first FIFA World Cup, and in what year?"
265 |
266 | Action:
267 | {
268 | "name": "web_search",
269 | "arguments": {"query": "country hosted first FIFA World Cup"}
270 | }
271 | Observation: "Uruguay hosted the first FIFA World Cup."
272 |
273 | Action:
274 | {
275 | "name": "web_search",
276 | "arguments": {"query": "year of first FIFA World Cup"}
277 | }
278 | Observation: "The first FIFA World Cup was held in 1930."
279 |
280 | Action:
281 | {
282 | "name": "final_answer",
283 | "arguments": {"answer": "Uruguay hosted the first FIFA World Cup in 1930."}
284 | }
285 |
286 | ---
287 | Task: "Who invented the light bulb, and what company did he later establish?"
288 |
289 | Action:
290 | {
291 | "name": "web_search",
292 | "arguments": {"query": "inventor of the light bulb"}
293 | }
294 | Observation: "Thomas Edison invented the light bulb."
295 |
296 | Action:
297 | {
298 | "name": "web_search",
299 | "arguments": {"query": "company founded by Thomas Edison"}
300 | }
301 | Observation: "Thomas Edison founded General Electric."
302 |
303 | Action:
304 | {
305 | "name": "final_answer",
306 | "arguments": {"answer": "Thomas Edison invented the light bulb and later established General Electric."}
307 | }
308 |
309 | ---
310 | Task: "In which city was the Declaration of Independence signed, and in what building?"
311 |
312 | Action:
313 | {
314 | "name": "web_search",
315 | "arguments": {"query": "city where Declaration of Independence was signed"}
316 | }
317 | Observation: "The Declaration of Independence was signed in Philadelphia."
318 |
319 | Action:
320 | {
321 | "name": "web_search",
322 | "arguments": {"query": "building where Declaration of Independence was signed"}
323 | }
324 | Observation: "It was signed in Independence Hall."
325 |
326 | Action:
327 | {
328 | "name": "final_answer",
329 | "arguments": {"answer": "The Declaration of Independence was signed in Philadelphia at Independence Hall."}
330 | }
331 |
332 | ---
333 | Task: "Who developed the theory of general relativity, and in what year was it published?"
334 |
335 | Action:
336 | {
337 | "name": "web_search",
338 | "arguments": {"query": "developer of general relativity"}
339 | }
340 | Observation: "Albert Einstein developed the theory of general relativity."
341 |
342 | Action:
343 | {
344 | "name": "web_search",
345 | "arguments": {"query": "year general relativity published"}
346 | }
347 | Observation: "The theory of general relativity was published in 1915."
348 |
349 | Action:
350 | {
351 | "name": "final_answer",
352 | "arguments": {"answer": "Albert Einstein developed the theory of general relativity, which was published in 1915."}
353 | }
354 |
355 | ---
356 | Task: "Which Shakespeare play features the phrase 'To be, or not to be,' and who speaks this line?"
357 |
358 | Action:
359 | {
360 | "name": "web_search",
361 | "arguments": {"query": "Shakespeare play To be, or not to be"}
362 | }
363 | Observation: "The play is 'Hamlet.'"
364 |
365 | Action:
366 | {
367 | "name": "web_search",
368 | "arguments": {"query": "character who says To be, or not to be in Hamlet"}
369 | }
370 | Observation: "The line is spoken by Hamlet."
371 |
372 | Action:
373 | {
374 | "name": "final_answer",
375 | "arguments": {"answer": "The phrase 'To be, or not to be' is from Shakespeare's 'Hamlet,' and it is spoken by the character Hamlet."}
376 | }
377 |
378 | ---
379 | Task: "What is the tallest mountain in Africa, and how high is it?"
380 |
381 | Action:
382 | {
383 | "name": "web_search",
384 | "arguments": {"query": "tallest mountain in Africa"}
385 | }
386 | Observation: "Mount Kilimanjaro is the tallest mountain in Africa."
387 |
388 | Action:
389 | {
390 | "name": "web_search",
391 | "arguments": {"query": "height of Mount Kilimanjaro"}
392 | }
393 | Observation: "Mount Kilimanjaro is 5,895 meters tall."
394 |
395 | Action:
396 | {
397 | "name": "final_answer",
398 | "arguments": {"answer": "Mount Kilimanjaro, the tallest mountain in Africa, is 5,895 meters high."}
399 | }
400 |
401 | ---
402 | Task: "Who was the first President of the United States to serve two non-consecutive terms?"
403 |
404 | Action:
405 | {
406 | "name": "web_search",
407 | "arguments": {"query": "President who served two non-consecutive terms"}
408 | }
409 | Observation: "Grover Cleveland was the first President to serve two non-consecutive terms."
410 |
411 | Action:
412 | {
413 | "name": "final_answer",
414 | "arguments": {"answer": "Grover Cleveland was the first President of the United States to serve two non-consecutive terms."}
415 | }
416 |
417 | ---
418 | Task: "What planet is the largest in our solar system, and what is its diameter?"
419 |
420 | Action:
421 | {
422 | "name": "web_search",
423 | "arguments": {"query": "largest planet in solar system"}
424 | }
425 | Observation: "Jupiter is the largest planet in the solar system."
426 |
427 | Action:
428 | {
429 | "name": "web_search",
430 | "arguments": {"query": "diameter of Jupiter"}
431 | }
432 | Observation: "Jupiter's diameter is approximately 139,820 kilometers."
433 |
434 | Action:
435 | {
436 | "name": "final_answer",
437 | "arguments": {"answer": "Jupiter is the largest planet in the solar system, with a diameter of approximately 139,820 kilometers."}
438 | }
439 |
440 | ---
441 | Task: "What was the first airplane to fly, and in what year did it achieve this feat?"
442 |
443 | Action:
444 | {
445 | "name": "web_search",
446 | "arguments": {"query": "first airplane to fly"}
447 | }
448 | Observation: "The first airplane to fly was the Wright Flyer."
449 |
450 | Action:
451 | {
452 | "name": "web_search",
453 | "arguments": {"query": "year Wright Flyer first flight"}
454 | }
455 | Observation: "The Wright Flyer flew for the first time in 1903."
456 |
457 | Action:
458 | {
459 | "name": "final_answer",
460 | "arguments": {"answer": "The Wright Flyer was the first airplane to fly, achieving this feat in 1903."}
461 | }
462 |
463 | ---
464 | Task: "Who painted the Mona Lisa, and where is it displayed?"
465 |
466 | Action:
467 | {
468 | "name": "web_search",
469 | "arguments": {"query": "artist who painted Mona Lisa"}
470 | }
471 | Observation: "Leonardo da Vinci painted the Mona Lisa."
472 |
473 | Action:
474 | {
475 | "name": "web_search",
476 | "arguments": {"query": "where is the Mona Lisa displayed"}
477 | }
478 | Observation: "The Mona Lisa is displayed in the Louvre Museum in Paris."
479 |
480 | Action:
481 | {
482 | "name": "final_answer",
483 | "arguments": {"answer": "Leonardo da Vinci painted the Mona Lisa, which is displayed in the Louvre Museum in Paris."}
484 | }
485 |
486 | ---
487 | Task: "Who has won the most Grand Slam tennis titles, and how many have they won?"
488 |
489 | Action:
490 | {
491 | "name": "web_search",
492 | "arguments": {"query": "player with most Grand Slam tennis titles"}
493 | }
494 | Observation: "Novak Djokovic has won the most Grand Slam titles."
495 |
496 | Action:
497 | {
498 | "name": "web_search",
499 | "arguments": {"query": "number of Grand Slam titles Novak Djokovic"}
500 | }
501 | Observation: "Novak Djokovic has won 24 Grand Slam titles."
502 |
503 | Action:
504 | {
505 | "name": "final_answer",
506 | "arguments": {"answer": "Novak Djokovic has won the most Grand Slam tennis titles, with 24 titles."}
507 | }
508 |
509 | ---
510 | Task: "Who was the longest-reigning monarch in British history, and how many years did they reign?"
511 |
512 | Action:
513 | {
514 | "name": "web_search",
515 | "arguments": {"query": "longest reigning monarch in British history"}
516 | }
517 | Observation: "Queen Elizabeth II was the longest-reigning monarch in British history."
518 |
519 | Action:
520 | {
521 | "name": "web_search",
522 | "arguments": {"query": "length of reign Queen Elizabeth II"}
523 | }
524 | Observation: "Queen Elizabeth II reigned for 70 years."
525 |
526 | Action:
527 | {
528 | "name": "final_answer",
529 | "arguments": {"answer": "Queen Elizabeth II was the longest-reigning monarch in British history, with a reign of 70 years."}
530 | }
531 |
532 | ---
533 | Task: "Which Shakespeare play contains the line \"All the world's a stage,\" and how many years ago was it first performed if today is 2024?"
534 |
535 | Action:
536 | {
537 | "name": "web_search",
538 | "arguments": {"query": "Shakespeare play All the world's a stage"}
539 | }
540 | Observation: "The line is from \"As You Like It.\""
541 |
542 | Action:
543 | {
544 | "name": "web_search",
545 | "arguments": {"query": "year As You Like It first performed"}
546 | }
547 | Observation: "\"As You Like It\" was first performed in 1603."
548 |
549 | Action:
550 | {
551 | "name": "calculate",
552 | "arguments": {"expression": "2024 - 1603"}
553 | }
554 | Observation: "421 years."
555 |
556 | Action:
557 | {
558 | "name": "final_answer",
559 | "arguments": {"answer": "\"As You Like It\" contains the line \"All the world's a stage\" and was first performed 421 years ago in 1603."}
560 | }
561 |
562 | Above examples were using notional tools that might not exist for you. You only have access to these tools:
563 | {%- for tool in tools.values() %}
564 | - {{ tool.name }}: {{ tool.description }}
565 | Takes inputs: {{tool.inputs}}
566 | Returns an output of type: {{tool.output_type}}
567 | {%- endfor %}
568 |
569 | {%- if managed_agents and managed_agents.values() | list %}
570 | You can also give tasks to team members.
571 | Calling a team member works the same as for calling a tool: simply, the only argument you can give in the call is 'task', a long string explaining your task.
572 | Given that this team member is a real human, you should be very verbose in your task.
573 | Here is a list of the team members that you can call:
574 | {%- for agent in managed_agents.values() %}
575 | - {{ agent.name }}: {{ agent.description }}
576 | {%- endfor %}
577 | {%- else %}
578 | {%- endif %}
579 |
580 | Here are the rules you should always follow to solve your task:
581 | 1. ALWAYS provide a tool call, else you will fail.
582 | 2. Always use the right arguments for the tools. Never use variable names as the action arguments, use the value instead.
583 | 3. Call a tool only when needed: do not call the search agent if you do not need information, try to solve the task yourself.
584 | If no tool call is needed, use final_answer tool to return your answer.
585 | 4. Never re-do a tool call that you previously did with the exact same parameters.
586 |
587 | Now Begin! If you solve the task correctly, you will receive a reward of $1,000,000.
588 | """)
--------------------------------------------------------------------------------
/src/opendeepsearch/ranking_models/README.md:
--------------------------------------------------------------------------------
1 | ## Semantic Search and Reranking
2 |
3 | The OpenDeepSearch library provides a flexible framework for semantic search and document reranking. At its core is the `BaseSemanticSearcher` class, which can be extended to implement various reranking strategies.
4 |
5 | ### Creating Your Own Reranker
6 |
7 | To implement your own reranker, simply inherit from `BaseSemanticSearcher` and implement the `_get_embeddings()` method:
8 |
9 | ```python
10 | from opendeepsearch.ranking_models.base_reranker import BaseSemanticSearcher
11 | import torch
12 | class MyCustomReranker(BaseSemanticSearcher):
13 | def init(self):
14 | # Initialize your embedding model here
15 | super().__init__()
16 | self.model = YourEmbeddingModel()
17 | def get_embeddings(self, texts: List[str]) -> torch.Tensor:
18 | # Implement your embedding logic here
19 | pass
20 | embeddings = self.model.encode(texts)
21 | return torch.tensor(embeddings)
22 | ```
23 |
24 | The base class automatically handles:
25 | - Similarity score calculation
26 | - Score normalization (softmax, scaling, or none)
27 | - Document reranking
28 | - Top-k selection
29 |
30 | ### Using Infinity Rerankers
31 |
32 | For high-performance reranking, we support [Infinity](https://github.com/michaelfeil/infinity) rerankers which offer state-of-the-art performance. To use an Infinity reranker, first start the Infinity server:
33 |
34 | ```bash
35 | # requires ~16-32GB VRAM NVIDIA Compute Capability >= 8.0
36 | docker run \
37 | -v $PWD/data:/app/.cache --gpus "0" -p "7997":"7997" \
38 | michaelf34/infinity:0.0.68-trt-onnx \
39 | v2 --model-id Alibaba-NLP/gte-Qwen2-7B-instruct --revision "refs/pr/38" \
40 | --dtype bfloat16 --batch-size 8 --device cuda --engine torch --port 7997 \
41 | --no-bettertransformer
42 | ```
43 |
44 | This will start an Infinity server using the Qwen2-7B-instruct model. The server will be available at `localhost:7997`.
45 |
46 | Key parameters:
47 | - `--model-id`: The Hugging Face model ID to use (see [supported models](https://github.com/michaelfeil/infinity#supported-tasks-and-models-by-infinity))
48 | - `--dtype`: Data type for inference (bfloat16 recommended for modern GPUs)
49 | - `--batch-size`: Batch size for inference
50 | - `--port`: Port to expose the server on
51 |
52 | For specialized deployments, Infinity provides several Docker images:
53 | - `latest-cpu` - For CPU-only inference
54 | - `latest-rocm` - For AMD ROCm GPUs
55 | - `latest-trt-onnx` - For NVIDIA GPUs with TensorRT/ONNX optimizations
56 |
57 | See the [Infinity documentation](https://michaelfeil.github.io/infinity/) for more details on deployment options and configuration.
58 |
59 | Note: Ensure you have sufficient VRAM (16-32GB) and a compatible NVIDIA GPU (Compute Capability ≥ 8.0) before running the Infinity server.
60 |
61 | ### Using Jina AI (or API based) Rerankers
62 |
63 | Jina AI provides powerful embedding models through their API service. The `JinaReranker` class offers a simple way to leverage these models:
64 |
65 | ```python
66 | from opendeepsearch.ranking_models.jina_reranker import JinaReranker
67 |
68 | # Initialize with your API key
69 | reranker = JinaReranker(api_key="your_api_key") # or set JINA_API_KEY env variable
70 |
71 | # Example usage
72 | query = "What is machine learning?"
73 | documents = [
74 | "Machine learning is a subset of artificial intelligence",
75 | "Deep learning is a type of machine learning",
76 | "Natural language processing uses machine learning"
77 | ]
78 |
79 | # Get top 2 most relevant documents
80 | results = reranker.search(query, documents, k=2)
81 | ```
82 |
83 | The JinaReranker uses Jina's v3 embeddings by default, which provides:
84 | - 1024-dimensional embeddings
85 | - Optimized for text matching tasks
86 | - State-of-the-art performance for semantic search
87 |
88 | To use JinaReranker:
89 | 1. Sign up for a Jina AI API key at https://jina.ai
90 | 2. Either pass the API key directly or set it as an environment variable `JINA_API_KEY`
91 | 3. Optionally specify a different model using the `model` parameter
92 |
93 | Note: Unlike Infinity rerankers which run locally, Jina rerankers require an internet connection and API credits.
--------------------------------------------------------------------------------
/src/opendeepsearch/ranking_models/base_reranker.py:
--------------------------------------------------------------------------------
1 | from abc import ABC, abstractmethod
2 | import torch
3 | from typing import List, Dict, Union
4 |
5 | class BaseSemanticSearcher(ABC):
6 | """
7 | Abstract base class for semantic search implementations.
8 |
9 | This class defines the interface that all semantic searchers must implement.
10 | Subclasses should implement the _get_embeddings method according to their
11 | specific embedding source.
12 | """
13 |
14 | @abstractmethod
15 | def _get_embeddings(self, texts: List[str]) -> torch.Tensor:
16 | """
17 | Get embeddings for a list of texts.
18 |
19 | Args:
20 | texts: List of text strings to embed
21 |
22 | Returns:
23 | torch.Tensor containing the embeddings shape: (num_texts, embedding_dim)
24 | """
25 | pass
26 |
27 | def calculate_scores(
28 | self,
29 | queries: List[str],
30 | documents: List[str],
31 | normalize: str = "softmax" # Options: "softmax", "scale", "none"
32 | ) -> torch.Tensor:
33 | """
34 | Calculate similarity scores between queries and documents.
35 |
36 | Args:
37 | queries: List of query strings
38 | documents: List of document strings
39 | normalize: Normalization method:
40 | - "softmax": Apply softmax normalization (default)
41 | - "scale": Scale to 0-100 range
42 | - "none": No normalization
43 |
44 | Returns:
45 | torch.Tensor of shape (num_queries, num_documents) containing similarity scores
46 | """
47 | # Get embeddings for queries and documents
48 | query_embeddings = self._get_embeddings(queries)
49 | doc_embeddings = self._get_embeddings(documents)
50 |
51 | # Calculate similarity scores
52 | scores = query_embeddings @ doc_embeddings.T
53 |
54 | # Apply normalization
55 | if normalize == "softmax":
56 | scores = torch.softmax(scores, dim=-1)
57 | elif normalize == "scale":
58 | scores = scores * 100
59 | elif normalize == "none":
60 | pass
61 | else:
62 | raise ValueError(f"Unknown normalization method: {normalize}")
63 |
64 | return scores
65 |
66 | def rerank(
67 | self,
68 | query: Union[str, List[str]],
69 | documents: List[str],
70 | top_k: int = 5,
71 | normalize: str = "softmax"
72 | ) -> List[Dict[str, Union[str, float]]]:
73 | """
74 | Rerank documents based on their semantic similarity to the query.
75 |
76 | Args:
77 | query: Query string or list of query strings
78 | documents: List of documents to rerank
79 | top_k: Number of top results to return per query
80 | normalize: Normalization method for scores
81 |
82 | Returns:
83 | List of dicts containing reranked documents and their scores.
84 | For single query: [{"document": str, "score": float}, ...]
85 | For multiple queries: [[{"document": str, "score": float}, ...], ...]
86 | """
87 | queries = [query] if isinstance(query, str) else query
88 | scores = self.calculate_scores(queries, documents, normalize=normalize)
89 |
90 | results = []
91 | for query_scores in scores:
92 | top_indices = torch.topk(query_scores, min(top_k, len(documents)), dim=0)
93 | query_results = [
94 | {
95 | "document": documents[idx.item()],
96 | "score": score.item()
97 | }
98 | for score, idx in zip(top_indices.values, top_indices.indices)
99 | ]
100 | results.append(query_results)
101 |
102 | return results[0] if isinstance(query, str) else results
103 |
104 | def get_reranked_documents(
105 | self,
106 | query: Union[str, List[str]],
107 | documents: List[str],
108 | top_k: int = 5,
109 | normalize: str = "softmax"
110 | ) -> Union[List[str], List[List[str]]]:
111 | """
112 | Returns only the reranked documents without scores.
113 |
114 | Args:
115 | query: Query string or list of query strings
116 | documents: List of documents to rerank
117 | top_k: Number of top results to return per query
118 | normalize: Normalization method for scores
119 |
120 | Returns:
121 | For single query: List of reranked document strings
122 | For multiple queries: List of lists of reranked document strings
123 | """
124 | results = self.rerank(query, documents, top_k, normalize)
125 | return "\n".join([x['document'].strip() for x in results])
126 |
--------------------------------------------------------------------------------
/src/opendeepsearch/ranking_models/chunker.py:
--------------------------------------------------------------------------------
1 | from typing import List, Optional
2 | from langchain_text_splitters import RecursiveCharacterTextSplitter
3 |
4 | class Chunker:
5 | """A modular text chunking class that splits text into smaller, overlapping segments.
6 |
7 | This class provides a flexible way to break down large texts into smaller chunks
8 | while maintaining context through configurable overlap. It uses RecursiveCharacterTextSplitter
9 | from langchain under the hood.
10 |
11 | Attributes:
12 | chunk_size (int): The target size for each text chunk.
13 | chunk_overlap (int): The number of characters to overlap between chunks.
14 | separators (List[str]): List of separators to use for splitting, in order of preference.
15 | length_function (callable): Function to measure text length (default: len).
16 | """
17 |
18 | def __init__(
19 | self,
20 | chunk_size: int = 150,
21 | chunk_overlap: int = 50,
22 | separators: Optional[List[str]] = None,
23 | length_function: callable = len
24 | ):
25 | """Initialize the Chunker with specified parameters.
26 |
27 | Args:
28 | chunk_size (int, optional): Target size for each chunk. Defaults to 250.
29 | chunk_overlap (int, optional): Number of characters to overlap. Defaults to 50.
30 | separators (List[str], optional): Custom separators for splitting.
31 | Defaults to ["\n\n", "\n", " "].
32 | length_function (callable, optional): Function to measure text length.
33 | Defaults to len.
34 | """
35 | self.chunk_size = chunk_size
36 | self.chunk_overlap = chunk_overlap
37 | self.separators = separators or ["\n\n", "\n"]
38 | self.length_function = length_function
39 |
40 | self.splitter = RecursiveCharacterTextSplitter(
41 | separators=self.separators,
42 | chunk_size=self.chunk_size,
43 | chunk_overlap=self.chunk_overlap,
44 | length_function=self.length_function
45 | )
46 |
47 | def split_text(self, text: str) -> List[str]:
48 | """Split a single text into chunks.
49 |
50 | Args:
51 | text (str): The input text to be split into chunks.
52 |
53 | Returns:
54 | List[str]: A list of text chunks.
55 | """
56 | return self.splitter.split_text(text)
57 |
58 | def split_texts(self, texts: List[str]) -> List[List[str]]:
59 | """Split multiple texts into chunks.
60 |
61 | Args:
62 | texts (List[str]): A list of input texts to be split into chunks.
63 |
64 | Returns:
65 | List[List[str]]: A list of lists, where each inner list contains
66 | the chunks for one input text.
67 | """
68 | return [self.split_text(text) for text in texts]
69 |
--------------------------------------------------------------------------------
/src/opendeepsearch/ranking_models/infinity_rerank.py:
--------------------------------------------------------------------------------
1 | import torch
2 | import requests
3 | import json
4 | from typing import List
5 | from opendeepsearch.ranking_models.base_reranker import BaseSemanticSearcher
6 |
7 | class InfinitySemanticSearcher(BaseSemanticSearcher):
8 | """
9 | A semantic reranking model that uses the Infinity Embedding API for text embeddings.
10 |
11 | This class provides methods to rerank documents based on their semantic similarity
12 | to queries using embeddings from the Infinity API. The API endpoint expects to receive
13 | text inputs and returns high-dimensional embeddings that capture semantic meaning.
14 |
15 | The default model used is 'Alibaba-NLP/gte-Qwen2-7B-instruct', but other models
16 | available through the Infinity API can be specified.
17 |
18 | Attributes:
19 | embedding_endpoint (str): URL of the Infinity Embedding API endpoint
20 | model_name (str): Name of the embedding model to use
21 |
22 | Example:
23 | ```python
24 | reranker = SemanticSearch(
25 | embedding_endpoint="http://localhost:7997/embeddings",
26 | model_name="Alibaba-NLP/gte-Qwen2-7B-instruct"
27 | )
28 |
29 | documents = [
30 | "Munich is in Germany.",
31 | "The sky is blue."
32 | ]
33 |
34 | results = reranker.rerank(
35 | query="What color is the sky?",
36 | documents=documents,
37 | top_k=1
38 | )
39 | ```
40 | """
41 |
42 | def __init__(
43 | self,
44 | embedding_endpoint: str = "http://localhost:7997/embeddings",
45 | model_name: str = "Alibaba-NLP/gte-Qwen2-7B-instruct",
46 | instruction_prefix: str = "Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery: "
47 | ):
48 | """
49 | Initialize the semantic search engine with Infinity Embedding API settings.
50 |
51 | Args:
52 | embedding_endpoint: URL of the Infinity Embedding API endpoint
53 | model_name: Name of the embedding model available in Infinity API
54 | instruction_prefix: Prefix to add to queries for better search relevance
55 | """
56 | self.embedding_endpoint = embedding_endpoint
57 | self.model_name = model_name
58 | self.instruction_prefix = instruction_prefix
59 |
60 | def _get_embeddings(self, texts: List[str], embedding_type: str = "query") -> torch.Tensor:
61 | """
62 | Get embeddings for a list of texts using the Infinity API.
63 | """
64 | MAX_TEXTS = 2048
65 | if len(texts) > MAX_TEXTS:
66 | import warnings
67 | warnings.warn(f"Number of texts ({len(texts)}) exceeds maximum of {MAX_TEXTS}. List will be truncated.")
68 | texts = texts[:MAX_TEXTS]
69 |
70 | # Format queries with instruction prefix
71 | formatted_texts = [
72 | self.instruction_prefix + text if embedding_type == "query" else text
73 | for text in texts
74 | ]
75 |
76 | response = requests.post(
77 | self.embedding_endpoint,
78 | json={
79 | "model": self.model_name,
80 | "input": formatted_texts
81 | }
82 | )
83 |
84 | content_str = response.content.decode('utf-8')
85 | content_json = json.loads(content_str)
86 | return torch.tensor([item['embedding'] for item in content_json['data']])
87 |
--------------------------------------------------------------------------------
/src/opendeepsearch/ranking_models/jina_reranker.py:
--------------------------------------------------------------------------------
1 | import requests
2 | import torch
3 | from typing import List, Optional
4 | from dotenv import load_dotenv
5 | import os
6 | from .base_reranker import BaseSemanticSearcher
7 |
8 | class JinaReranker(BaseSemanticSearcher):
9 | """
10 | Semantic searcher implementation using Jina AI's embedding API.
11 | """
12 |
13 | def __init__(self, api_key: Optional[str] = None, model: str = "jina-embeddings-v3"):
14 | """
15 | Initialize the Jina reranker.
16 |
17 | Args:
18 | api_key: Jina AI API key. If None, will load from environment variable JINA_API_KEY
19 | model: Model name to use (default: "jina-embeddings-v3")
20 | """
21 | if api_key is None:
22 | load_dotenv()
23 | api_key = os.getenv('JINA_API_KEY')
24 | if not api_key:
25 | raise ValueError("No API key provided and JINA_API_KEY not found in environment variables")
26 |
27 | self.api_url = 'https://api.jina.ai/v1/embeddings'
28 | self.headers = {
29 | 'Content-Type': 'application/json',
30 | 'Authorization': f'Bearer {api_key}'
31 | }
32 | self.model = model
33 |
34 | def _get_embeddings(self, texts: List[str]) -> torch.Tensor:
35 | """
36 | Get embeddings for a list of texts using Jina AI API.
37 |
38 | Args:
39 | texts: List of text strings to embed
40 |
41 | Returns:
42 | torch.Tensor containing the embeddings
43 | """
44 | data = {
45 | "model": self.model,
46 | "task": "text-matching",
47 | "late_chunking": False,
48 | "dimensions": 1024,
49 | "embedding_type": "float",
50 | "input": texts
51 | }
52 |
53 | try:
54 | response = requests.post(self.api_url, headers=self.headers, json=data)
55 | response.raise_for_status() # Raise exception for non-200 status codes
56 |
57 | # Extract embeddings from response
58 | embeddings_data = [item["embedding"] for item in response.json()["data"]]
59 |
60 | # Convert to torch tensor
61 | embeddings = torch.tensor(embeddings_data)
62 |
63 | return embeddings
64 |
65 | except requests.exceptions.RequestException as e:
66 | raise RuntimeError(f"Error calling Jina AI API: {str(e)}")
67 |
--------------------------------------------------------------------------------
/src/opendeepsearch/serp_search/serp_search.py:
--------------------------------------------------------------------------------
1 | import os
2 | from dataclasses import dataclass
3 | from typing import Dict, Any, Optional, List, TypeVar, Generic, Union
4 | from abc import ABC, abstractmethod
5 |
6 | import requests
7 |
8 | T = TypeVar('T')
9 |
10 | class SearchAPIException(Exception):
11 | """Custom exception for Search API related errors"""
12 | pass
13 |
14 | class SerperAPIException(SearchAPIException):
15 | """Custom exception for Serper API related errors"""
16 | pass
17 |
18 | class SearXNGException(SearchAPIException):
19 | """Custom exception for SearXNG related errors"""
20 | pass
21 |
22 | @dataclass
23 | class SerperConfig:
24 | """Configuration for Serper API"""
25 | api_key: str
26 | api_url: str = "https://google.serper.dev/search"
27 | default_location: str = 'us'
28 | timeout: int = 10
29 |
30 | @classmethod
31 | def from_env(cls) -> 'SerperConfig':
32 | """Create config from environment variables"""
33 | api_key = os.getenv("SERPER_API_KEY")
34 | if not api_key:
35 | raise SerperAPIException("SERPER_API_KEY environment variable not set")
36 | return cls(api_key=api_key)
37 |
38 | @dataclass
39 | class SearXNGConfig:
40 | """Configuration for SearXNG instance"""
41 | instance_url: str
42 | api_key: Optional[str] = None
43 | default_location: str = 'all'
44 | timeout: int = 10
45 |
46 | @classmethod
47 | def from_env(cls) -> 'SearXNGConfig':
48 | """Create config from environment variables"""
49 | instance_url = os.getenv("SEARXNG_INSTANCE_URL")
50 | if not instance_url:
51 | raise SearXNGException("SEARXNG_INSTANCE_URL environment variable not set")
52 | api_key = os.getenv("SEARXNG_API_KEY") # Optional
53 | return cls(instance_url=instance_url, api_key=api_key)
54 |
55 | class SearchResult(Generic[T]):
56 | """Container for search results with error handling"""
57 | def __init__(self, data: Optional[T] = None, error: Optional[str] = None):
58 | self.data = data
59 | self.error = error
60 | self.success = error is None
61 |
62 | @property
63 | def failed(self) -> bool:
64 | return not self.success
65 |
66 | class SearchAPI(ABC):
67 | """Abstract base class for search APIs"""
68 | @abstractmethod
69 | def get_sources(
70 | self,
71 | query: str,
72 | num_results: int = 8,
73 | stored_location: Optional[str] = None
74 | ) -> SearchResult[Dict[str, Any]]:
75 | """Get search results from the API"""
76 | pass
77 |
78 | class SerperAPI(SearchAPI):
79 | def __init__(self, api_key: Optional[str] = None, config: Optional[SerperConfig] = None):
80 | if api_key:
81 | self.config = SerperConfig(api_key=api_key)
82 | else:
83 | self.config = config or SerperConfig.from_env()
84 |
85 | self.headers = {
86 | 'X-API-KEY': self.config.api_key,
87 | 'Content-Type': 'application/json'
88 | }
89 |
90 | @staticmethod
91 | def extract_fields(items: List[Dict[str, Any]], fields: List[str]) -> List[Dict[str, Any]]:
92 | """Extract specified fields from a list of dictionaries"""
93 | return [{key: item.get(key, "") for key in fields if key in item} for item in items]
94 |
95 | def get_sources(
96 | self,
97 | query: str,
98 | num_results: int = 8,
99 | stored_location: Optional[str] = None
100 | ) -> SearchResult[Dict[str, Any]]:
101 | """
102 | Fetch search results from Serper API.
103 |
104 | Args:
105 | query: Search query string
106 | num_results: Number of results to return (default: 8, max: 10)
107 | stored_location: Optional location string
108 |
109 | Returns:
110 | SearchResult containing the search results or error information
111 | """
112 | if not query.strip():
113 | return SearchResult(error="Query cannot be empty")
114 |
115 | try:
116 | search_location = (stored_location or self.config.default_location).lower()
117 |
118 | payload = {
119 | "q": query,
120 | "num": min(max(1, num_results), 10),
121 | "gl": search_location
122 | }
123 |
124 | response = requests.post(
125 | self.config.api_url,
126 | headers=self.headers,
127 | json=payload,
128 | timeout=self.config.timeout
129 | )
130 | response.raise_for_status()
131 | data = response.json()
132 |
133 | results = {
134 | 'organic': self.extract_fields(
135 | data.get('organic', []),
136 | ['title', 'link', 'snippet', 'date']
137 | ),
138 | 'topStories': self.extract_fields(
139 | data.get('topStories', []),
140 | ['title', 'imageUrl']
141 | ),
142 | 'images': self.extract_fields(
143 | data.get('images', [])[:6],
144 | ['title', 'imageUrl']
145 | ),
146 | 'graph': data.get('knowledgeGraph'),
147 | 'answerBox': data.get('answerBox'),
148 | 'peopleAlsoAsk': data.get('peopleAlsoAsk'),
149 | 'relatedSearches': data.get('relatedSearches')
150 | }
151 |
152 | return SearchResult(data=results)
153 |
154 | except requests.RequestException as e:
155 | return SearchResult(error=f"API request failed: {str(e)}")
156 | except Exception as e:
157 | return SearchResult(error=f"Unexpected error: {str(e)}")
158 |
159 |
160 | class SearXNGAPI(SearchAPI):
161 | """API client for SearXNG search engine"""
162 |
163 | def __init__(self, instance_url: Optional[str] = None, api_key: Optional[str] = None, config: Optional[SearXNGConfig] = None):
164 | if instance_url:
165 | self.config = SearXNGConfig(instance_url=instance_url, api_key=api_key)
166 | else:
167 | self.config = config or SearXNGConfig.from_env()
168 |
169 | self.headers = {'Content-Type': 'application/json'}
170 | if self.config.api_key:
171 | self.headers['X-API-Key'] = self.config.api_key
172 |
173 | def get_sources(
174 | self,
175 | query: str,
176 | num_results: int = 8,
177 | stored_location: Optional[str] = None
178 | ) -> SearchResult[Dict[str, Any]]:
179 | """
180 | Fetch search results from SearXNG instance.
181 |
182 | Args:
183 | query: Search query string
184 | num_results: Number of results to return (default: 8)
185 | stored_location: Optional location string (may not be supported by all instances)
186 |
187 | Returns:
188 | SearchResult containing the search results or error information
189 | """
190 | if not query.strip():
191 | return SearchResult(error="Query cannot be empty")
192 |
193 | try:
194 | # Ensure the instance URL ends with /search
195 | search_url = self.config.instance_url
196 | if not search_url.endswith('/search'):
197 | search_url = search_url.rstrip('/') + '/search'
198 |
199 | # Prepare parameters for SearXNG
200 | params = {
201 | 'q': query,
202 | 'format': 'json',
203 | 'pageno': 1,
204 | 'categories': 'general',
205 | 'language': 'all',
206 | 'time_range': None,
207 | 'safesearch': 0,
208 | 'engines': 'google,bing,duckduckgo', # Default engines, can be customised
209 | 'max_results': min(max(1, num_results), 20) # Limit to reasonable range
210 | }
211 |
212 | # Add location if provided and supported
213 | if stored_location and stored_location != 'all':
214 | params['language'] = stored_location
215 |
216 | response = requests.get(
217 | search_url,
218 | headers=self.headers,
219 | params=params,
220 | timeout=self.config.timeout
221 | )
222 | response.raise_for_status()
223 | data = response.json()
224 |
225 | # Transform SearXNG results to match SerperAPI format
226 | organic_results = []
227 | for result in data.get('results', [])[:num_results]:
228 | organic_results.append({
229 | 'title': result.get('title', ''),
230 | 'link': result.get('url', ''),
231 | 'snippet': result.get('content', ''),
232 | 'date': result.get('publishedDate', '')
233 | })
234 |
235 | # Extract image results if available
236 | image_results = []
237 | for result in data.get('results', []):
238 | if result.get('img_src'):
239 | image_results.append({
240 | 'title': result.get('title', ''),
241 | 'imageUrl': result.get('img_src', '')
242 | })
243 | image_results = image_results[:6] # Limit to 6 images like SerperAPI
244 |
245 | # Format results to match SerperAPI structure
246 | results = {
247 | 'organic': organic_results,
248 | 'images': image_results,
249 | 'topStories': [], # SearXNG might not have direct equivalent
250 | 'graph': None, # SearXNG doesn't provide knowledge graph
251 | 'answerBox': None, # SearXNG doesn't provide answer box
252 | 'peopleAlsoAsk': None,
253 | 'relatedSearches': data.get('suggestions', [])
254 | }
255 |
256 | return SearchResult(data=results)
257 |
258 | except requests.RequestException as e:
259 | return SearchResult(error=f"SearXNG API request failed: {str(e)}")
260 | except Exception as e:
261 | return SearchResult(error=f"Unexpected error with SearXNG: {str(e)}")
262 |
263 |
264 | def create_search_api(
265 | search_provider: str = "serper",
266 | serper_api_key: Optional[str] = None,
267 | searxng_instance_url: Optional[str] = None,
268 | searxng_api_key: Optional[str] = None
269 | ) -> SearchAPI:
270 | """
271 | Factory function to create the appropriate search API client.
272 |
273 | Args:
274 | search_provider: The search provider to use ('serper' or 'searxng')
275 | serper_api_key: Optional API key for Serper
276 | searxng_instance_url: Optional SearXNG instance URL
277 | searxng_api_key: Optional API key for SearXNG instance
278 |
279 | Returns:
280 | An instance of a SearchAPI implementation
281 |
282 | Raises:
283 | ValueError: If an invalid search provider is specified
284 | """
285 | if search_provider.lower() == "serper":
286 | return SerperAPI(api_key=serper_api_key)
287 | elif search_provider.lower() == "searxng":
288 | return SearXNGAPI(instance_url=searxng_instance_url, api_key=searxng_api_key)
289 | else:
290 | raise ValueError(f"Invalid search provider: {search_provider}. Must be 'serper' or 'searxng'")
291 |
--------------------------------------------------------------------------------
/src/opendeepsearch/wolfram_tool.py:
--------------------------------------------------------------------------------
1 | from smolagents import Tool
2 | import wolframalpha
3 | import json
4 | import os
5 |
6 | class WolframAlphaTool(Tool):
7 | name = "calculate"
8 | description = """
9 | Performs computational, mathematical, and factual queries using Wolfram Alpha's computational knowledge engine.
10 | """
11 | inputs = {
12 | "query": {
13 | "type": "string",
14 | "description": "The query to send to Wolfram Alpha",
15 | },
16 | }
17 | output_type = "string"
18 |
19 | def __init__(self, app_id: str):
20 | super().__init__()
21 | self.app_id = app_id
22 |
23 | def setup(self):
24 | self.search_tool = WolframAlphaTool(
25 | self.app_id,
26 | )
27 |
28 | def forward(self, query: str):
29 |
30 | # Initialize the Wolfram Alpha client
31 | self.wolfram_client = wolframalpha.Client(self.app_id)
32 |
33 | try:
34 | # Send the query to Wolfram Alpha
35 | res = self.wolfram_client.query(query)
36 |
37 | # Process the results
38 | results = []
39 | for pod in res.pods:
40 | if pod.title:
41 | for subpod in pod.subpods:
42 | if subpod.plaintext:
43 | results.append({
44 | 'title': pod.title,
45 | 'result': subpod.plaintext
46 | })
47 |
48 | # Convert results to a JSON-serializable format
49 | formatted_result = {
50 | 'queryresult': {
51 | 'success': bool(results),
52 | 'inputstring': query,
53 | 'pods': [
54 | {
55 | 'title': result['title'],
56 | 'subpods': [{'title': '', 'plaintext': result['result']}]
57 | } for result in results
58 | ]
59 | }
60 | }
61 |
62 | # Initialize final_result with a default value
63 | final_result = "No result found."
64 |
65 | # Extract the pods from the query result
66 | pods = formatted_result.get("queryresult", {}).get("pods", [])
67 |
68 | # Loop through pods to find the "Result" title
69 | for pod in pods:
70 | if pod.get("title") == "Result":
71 | # Extract and return the plaintext from the subpods
72 | subpods = pod.get("subpods", [])
73 | if subpods:
74 | final_result = subpods[0].get("plaintext", "").strip()
75 | break
76 |
77 | # If no "Result" pod was found, use the first available result
78 | if final_result == "No result found." and results:
79 | final_result = results[0]['result']
80 |
81 |
82 | print(f"QUERY: {query}\n\nRESULT: {final_result}")
83 | return final_result
84 |
85 | except Exception as e:
86 | error_message = f"Error querying Wolfram Alpha: {str(e)}"
87 | print(error_message)
88 | return error_message
89 |
--------------------------------------------------------------------------------
/tests/__init__.py:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
15 | 
18 | 
21 | 
27 | 
30 |