ovos-wikipedia-plugin 1.0.0a1__tar.gz

ovos_wikipedia_plugin-1.0.0a1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ovos-wikipedia-plugin
+Version: 1.0.0a1
+Summary: OVOS Wikipedia plugin
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ovos-utils<1.0.0,>=0.7.0
+Requires-Dist: ovos-plugin-manager<3.0.0,>=2.3.0a1
+Requires-Dist: ovos-bus-client>=1.0.1
+Requires-Dist: rapidfuzz
+Requires-Dist: pydantic
+Requires-Dist: requests
+
+# ovos-wikipedia-plugin
+
+[![PyPI](https://img.shields.io/pypi/v/ovos-wikipedia-plugin)](https://pypi.org/project/ovos-wikipedia-plugin/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://www.python.org/)
+
+Wikipedia integration for [OpenVoiceOS](https://openvoiceos.org). Provides a **retrieval engine** for RAG pipelines and
+an **agent toolbox** for tool-using agents, both as standard OPM plugins.
+
+---
+
+## Installation
+
+```bash
+pip install ovos-wikipedia-plugin
+```
+
+---
+
+## OPM Entry Points
+
+| Entry point                                      | Class                      | Use case                                                 |
+|--------------------------------------------------|----------------------------|----------------------------------------------------------|
+| `opm.agents.retrieval` — `ovos-wikipedia-plugin` | `WikipediaRetrievalEngine` | Retrieval — returns ranked `(passage, score)` tuples     |
+| `opm.agents.toolbox` — `ovos-wikipedia-tool`     | `WikipediaToolbox`         | Agent tool use — exposes `search_wikipedia`              |
+
+---
+
+## Retrieval Engine
+
+`WikipediaRetrievalEngine` implements the `RetrievalEngine` OPM interface. It searches Wikipedia, fetches article
+summaries in parallel, scores them for relevance, and optionally applies extractive QA and reranking sub-plugins.
+
+```python
+from ovos_wikipedia import WikipediaRetrievalEngine
+
+engine = WikipediaRetrievalEngine()
+
+# Returns List[WikipediaResult] sorted by relevance
+for result in engine.search("Ada Lovelace", lang="en"):
+    print(result.title, result.conf)
+    print(result.summary)
+    if result.image:
+        print(result.image)
+
+# RAG interface: List[Tuple[str, float]]  (passage, score)
+passages = engine.query("who was Ada Lovelace", lang="en", k=3)
+```
+
+### Optional sub-plugins
+
+| Config key          | OPM type                   | Effect                                                    |
+|---------------------|----------------------------|-----------------------------------------------------------|
+| `extractive_qa`     | `opm.agents.extractive_qa` | Extract the best passage from each article summary        |
+| `reranker`          | `opm.agents.reranker`      | Re-score results with a cross-encoder                     |
+| `keyword_extractor` | `opm.plugin.keywords`      | Rewrite the query when the initial search returns nothing |
+
+```python
+engine = WikipediaRetrievalEngine(config={
+    "extractive_qa": "ovos-bm25-solver",
+    "reranker": "ovos-bm25-reranker",
+    "keyword_extractor": "ovos-rake-keywords",
+})
+```
+
+---
+
+## Agent Toolbox
+
+`WikipediaToolbox` exposes a single `search_wikipedia` tool that any OPM-compatible agent loop (
+e.g. [ovos-agentic-loop](https://github.com/TigreGotico/ovos-agentic-loop)) can discover and call.
+
+### Loading via entry point (recommended)
+
+Any agent loop that supports `opm.agents.toolbox` entry points will auto-discover this toolbox by name:
+
+```json
+{
+  "name": "ResearchAgent",
+  "solvers": [
+    "ovos-react-loop"
+  ],
+  "ovos-react-loop": {
+    "brain": "ovos-chat-openai-plugin",
+    "ovos-chat-openai-plugin": {
+      "api_url": "http://localhost:11434/v1/chat/completions"
+    },
+    "toolboxes": [
+      "ovos-wikipedia-tool"
+    ]
+  }
+}
+```
+
+### Direct usage
+
+```python
+from ovos_wikipedia import WikipediaToolbox, SearchWikipediaArgs
+
+tb = WikipediaToolbox()
+
+# Discover the tool (used internally by agent loops)
+tools = tb.discover_tools()
+# [AgentTool(name="search_wikipedia", description="Search Wikipedia for information about a topic...")]
+
+# Call directly
+output = tb.search_wikipedia(SearchWikipediaArgs(query="Ada Lovelace", lang="en"))
+for title, summary in output.results:
+    print(title)
+    print(summary)
+```
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

ovos_wikipedia_plugin-1.0.0a1/README.md

@@ -0,0 +1,117 @@
+# ovos-wikipedia-plugin
+
+[![PyPI](https://img.shields.io/pypi/v/ovos-wikipedia-plugin)](https://pypi.org/project/ovos-wikipedia-plugin/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://www.python.org/)
+
+Wikipedia integration for [OpenVoiceOS](https://openvoiceos.org). Provides a **retrieval engine** for RAG pipelines and
+an **agent toolbox** for tool-using agents, both as standard OPM plugins.
+
+---
+
+## Installation
+
+```bash
+pip install ovos-wikipedia-plugin
+```
+
+---
+
+## OPM Entry Points
+
+| Entry point                                      | Class                      | Use case                                                 |
+|--------------------------------------------------|----------------------------|----------------------------------------------------------|
+| `opm.agents.retrieval` — `ovos-wikipedia-plugin` | `WikipediaRetrievalEngine` | Retrieval — returns ranked `(passage, score)` tuples     |
+| `opm.agents.toolbox` — `ovos-wikipedia-tool`     | `WikipediaToolbox`         | Agent tool use — exposes `search_wikipedia`              |
+
+---
+
+## Retrieval Engine
+
+`WikipediaRetrievalEngine` implements the `RetrievalEngine` OPM interface. It searches Wikipedia, fetches article
+summaries in parallel, scores them for relevance, and optionally applies extractive QA and reranking sub-plugins.
+
+```python
+from ovos_wikipedia import WikipediaRetrievalEngine
+
+engine = WikipediaRetrievalEngine()
+
+# Returns List[WikipediaResult] sorted by relevance
+for result in engine.search("Ada Lovelace", lang="en"):
+    print(result.title, result.conf)
+    print(result.summary)
+    if result.image:
+        print(result.image)
+
+# RAG interface: List[Tuple[str, float]]  (passage, score)
+passages = engine.query("who was Ada Lovelace", lang="en", k=3)
+```
+
+### Optional sub-plugins
+
+| Config key          | OPM type                   | Effect                                                    |
+|---------------------|----------------------------|-----------------------------------------------------------|
+| `extractive_qa`     | `opm.agents.extractive_qa` | Extract the best passage from each article summary        |
+| `reranker`          | `opm.agents.reranker`      | Re-score results with a cross-encoder                     |
+| `keyword_extractor` | `opm.plugin.keywords`      | Rewrite the query when the initial search returns nothing |
+
+```python
+engine = WikipediaRetrievalEngine(config={
+    "extractive_qa": "ovos-bm25-solver",
+    "reranker": "ovos-bm25-reranker",
+    "keyword_extractor": "ovos-rake-keywords",
+})
+```
+
+---
+
+## Agent Toolbox
+
+`WikipediaToolbox` exposes a single `search_wikipedia` tool that any OPM-compatible agent loop (
+e.g. [ovos-agentic-loop](https://github.com/TigreGotico/ovos-agentic-loop)) can discover and call.
+
+### Loading via entry point (recommended)
+
+Any agent loop that supports `opm.agents.toolbox` entry points will auto-discover this toolbox by name:
+
+```json
+{
+  "name": "ResearchAgent",
+  "solvers": [
+    "ovos-react-loop"
+  ],
+  "ovos-react-loop": {
+    "brain": "ovos-chat-openai-plugin",
+    "ovos-chat-openai-plugin": {
+      "api_url": "http://localhost:11434/v1/chat/completions"
+    },
+    "toolboxes": [
+      "ovos-wikipedia-tool"
+    ]
+  }
+}
+```
+
+### Direct usage
+
+```python
+from ovos_wikipedia import WikipediaToolbox, SearchWikipediaArgs
+
+tb = WikipediaToolbox()
+
+# Discover the tool (used internally by agent loops)
+tools = tb.discover_tools()
+# [AgentTool(name="search_wikipedia", description="Search Wikipedia for information about a topic...")]
+
+# Call directly
+output = tb.search_wikipedia(SearchWikipediaArgs(query="Ada Lovelace", lang="en"))
+for title, summary in output.results:
+    print(title)
+    print(summary)
+```
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

ovos_wikipedia_plugin-1.0.0a1/ovos_wikipedia/__init__.py

@@ -0,0 +1,390 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import concurrent.futures
+import dataclasses
+from functools import lru_cache
+from typing import Optional, Tuple, Dict, Any, List, Type
+from urllib.parse import urlencode
+
+import requests
+from ovos_plugin_manager.agents import (
+    load_extractive_qa_plugin,
+    load_reranker_plugin,
+)
+from ovos_plugin_manager.keywords import load_keyword_extract_plugin
+from ovos_plugin_manager.templates.agent_tools import AgentTool, ToolBox, ToolOutput, ToolArguments
+from ovos_plugin_manager.templates.agents import ExtractiveQAEngine, ReRankerEngine
+from ovos_plugin_manager.templates.agents import RetrievalEngine
+from ovos_plugin_manager.templates.keywords import KeywordExtractor
+from ovos_utils.log import LOG
+from ovos_utils.parse import fuzzy_match, MatchStrategy
+from ovos_utils.text_utils import rm_parentheses
+from ovos_wikipedia.version import VERSION_BUILD, VERSION_MAJOR, VERSION_MINOR
+from pydantic import Field
+
+
+@dataclasses.dataclass
+class WikipediaResult:
+    """
+    Data container for a Wikipedia search result.
+
+    Attributes:
+        page_id: The unique Wikipedia page identifier.
+        lang: BCP-47 language code of the page.
+        title: Title of the Wikipedia article.
+        summary: Plain-text introductory summary.
+        image: URL to the primary article image.
+        conf: Confidence score of the result (0.0 to 1.0).
+        query: The original search query that produced this result.
+        best_passage: The specific snippet extracted by a QA engine, if available.
+    """
+    page_id: str
+    lang: str
+    title: str
+    summary: str
+    image: Optional[str] = None
+    conf: float = 0.5
+    query: Optional[str] = None
+    best_passage: Optional[str] = None
+
+
+class WikipediaRetrievalEngine(RetrievalEngine):
+    """
+    A solver for answering questions using Wikipedia search and summaries.
+    Utilizes keyword extraction, extractive QA, and reranking plugins.
+    """
+    USER_AGENT: str = (
+        f"ovos-wikipedia-solver/{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD} "
+        f"(https://github.com/OpenVoiceOS/ovos-wikipedia-solver)"
+    )
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        """
+        Initializes the Wikipedia engine and loads sub-plugins.
+
+        Args:
+            config: Configuration mapping for the specific engine.
+        """
+        super().__init__(config)
+        self._kword_extractor: Optional[KeywordExtractor] = self._load_keyword_extractor()
+        self._extractive_qa: Optional[ExtractiveQAEngine] = self._load_extractive_qa()
+        self._reranker: Optional[ReRankerEngine] = self._load_reranker()
+        LOG.debug(f"KeywordExtractor: {self._kword_extractor}")
+        LOG.debug(f"Reranker: {self._reranker}")
+        LOG.debug(f"ExtractiveQA: {self._extractive_qa}")
+
+    def query(self, query: str, lang: Optional[str] = None, k: int = 3) -> List[Tuple[str, float]]:
+        """
+        Searches the knowledge base for relevant documents or data.
+
+        Args:
+            query: The search string.
+            lang: BCP-47 language code.
+            k: The maximum number of results to return.
+
+        Returns:
+            List of tuples containing (content, score) for the top k matches.
+        """
+        return [(page.best_passage or page.summary, page.conf)
+                for page in self.search(query, lang, k)]
+
+    ###########################
+    # plugin loading
+    ###########################
+    def _load_extractive_qa(self) -> Optional[ExtractiveQAEngine]:
+        """
+        Loads the Extractive QA plugin defined in the config.
+
+        Returns:
+            An instance of ExtractiveQAEngine or None if loading fails.
+        """
+        plugin_name: Optional[str] = self.config.get("extractive_qa")
+        if plugin_name:
+            cls: Optional[Type[ExtractiveQAEngine]] = load_extractive_qa_plugin(plugin_name)
+            if cls:
+                try:
+                    return cls()
+                except Exception as e:
+                    LOG.warning(f"Extractive QA plugin '{plugin_name}' failed to load ({e}), using BM25")
+        return None
+
+    def _load_reranker(self) -> Optional[ReRankerEngine]:
+        """
+        Loads the ReRanker plugin defined in the config.
+
+        Returns:
+            An instance of ReRankerEngine or None if loading fails.
+        """
+        plugin_name: Optional[str] = self.config.get("reranker")
+        if plugin_name:
+            cls: Optional[Type[ReRankerEngine]] = load_reranker_plugin(plugin_name)
+            if cls:
+                try:
+                    return cls()
+                except Exception as e:
+                    LOG.warning(f"Reranker plugin '{plugin_name}' failed to load ({e}), using BM25")
+        return None
+
+    def _load_keyword_extractor(self) -> Optional[KeywordExtractor]:
+        """
+        Loads the Keyword Extractor plugin defined in the config.
+
+        Returns:
+            An instance of KeywordExtractor or None if loading fails.
+        """
+        plugin_name: Optional[str] = self.config.get("keyword_extractor")
+        if plugin_name:
+            cls: Optional[Type[KeywordExtractor]] = load_keyword_extract_plugin(plugin_name)
+            if cls:
+                try:
+                    return cls()
+                except Exception as e:
+                    LOG.warning(f"KeywordExtractor plugin '{plugin_name}' failed to load ({e}), using RAKE")
+        return None
+
+    ###########################
+    # wikipedia integration
+    ###########################
+    def search(self, query: str, lang: Optional[str] = None, top_k: int = 3) -> List[WikipediaResult]:
+        """
+        Performs a Wikipedia search, fetches page content, and optionally reranks results.
+
+        Args:
+            query: The search string.
+            lang: BCP-47 language code (e.g., "en-US").
+            top_k: Number of search results to process.
+
+        Returns:
+            A list of WikipediaResult objects sorted by confidence.
+        """
+        LOG.debug(f"WikiSolver query: {query}")
+        lang = (lang or self.lang).split("-")[0]
+        search_params = urlencode({
+            "action": "query",
+            "list": "search",
+            "srsearch": query,
+            "format": "json",
+        })
+        search_url = f"https://{lang}.wikipedia.org/w/api.php?{search_params}"
+        try:
+            search_results: List[Dict[str, Any]] = requests.get(
+                search_url,
+                timeout=5,
+                headers={"User-Agent": self.USER_AGENT}
+            ).json().get("query", {}).get("search", [])
+        except Exception as e:
+            LOG.error(f"Error fetching search results: {e}")
+            search_results = []
+
+        if not search_results:
+            if self._kword_extractor:
+                keywords: List[str] = self._kword_extractor.extract(query, lang=lang)
+                if keywords:
+                    fallback_query = max(keywords, key=len)
+                    if fallback_query and fallback_query != query:
+                        LOG.debug(f"WikiSolver Fallback, new query: {fallback_query}")
+                        return self.search(fallback_query, lang=lang, top_k=top_k)
+            return []
+
+        LOG.debug(f"Matched {len(search_results)} Wikipedia pages, using top {top_k}")
+        search_results = search_results[:top_k]
+
+        # Prepare for parallel fetch and maintain original order
+        summaries: List[Optional[WikipediaResult]] = [None] * len(search_results)
+        with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
+            future_to_idx = {
+                executor.submit(self._get_page_data, str(r["pageid"]), lang, query, idx): idx
+                for idx, r in enumerate(search_results)
+                if "(disambiguation)" not in r["title"]
+            }
+
+            for future in concurrent.futures.as_completed(future_to_idx):
+                idx = future_to_idx[future]
+                summaries[idx] = future.result()
+
+        res: List[WikipediaResult] = [s for s in summaries if s is not None]
+
+        if self._extractive_qa:
+            for page in res:
+                page.best_passage = self._extractive_qa.get_best_passage(
+                    evidence=page.summary,
+                    question=query,
+                    lang=lang
+                ).strip()
+
+        return self._rerank_pages(query, res, lang)
+
+    @classmethod
+    def _get_page_data(cls, pid: str, lang: str, query: Optional[str] = None, idx: int = 0) -> Optional[
+        WikipediaResult]:
+        """
+        Fetch the title, plain-text intro summary, and an image URL for a Wikipedia page.
+
+        Args:
+            pid: Wikipedia pageid.
+            lang: Language code (e.g., "en", "pt").
+            query: The original query for scoring purposes.
+            idx: The original search index for scoring purposes.
+
+        Returns:
+            A WikipediaResult object if successful, else None.
+        """
+        url = (
+            f"https://{lang}.wikipedia.org/w/api.php?format=json&action=query&"
+            f"prop=extracts|pageimages&exintro&explaintext&redirects=1&pageids={pid}"
+        )
+        try:
+            disambiguation_indicators = ["may refer to:", "refers to:"]
+            response = requests.get(url, timeout=5, headers={"User-Agent": cls.USER_AGENT}).json()
+            page = response["query"]["pages"][pid]
+
+            summary = rm_parentheses(page.get("extract", ""))
+            if any(i in summary for i in disambiguation_indicators):
+                return None  # Disambiguation list page
+
+            img: Optional[str] = None
+            if "thumbnail" in page:
+                thumbnail = page["thumbnail"]["source"]
+                parts = thumbnail.split("/")[:-1]
+                img = "/".join(part for part in parts if part != "thumb")
+
+            result = WikipediaResult(
+                lang=lang,
+                title=page["title"],
+                summary=summary.strip(),
+                image=img,
+                page_id=pid,
+                conf=cls._score_page(query or "", page["title"], summary, idx),
+                query=query
+            )
+            return result
+        except Exception as e:
+            LOG.error(f"Error fetching page data for PID {pid}: {e}")
+            return None
+
+    ###########################
+    # helpers to score results
+    ###########################
+    @staticmethod
+    @lru_cache(maxsize=128)
+    def _score_page(query: str, title: str, summary: str, idx: int) -> float:
+        """
+        Compute a relevance score for a Wikipedia page given a search query.
+
+        Args:
+            query: The user's search query.
+            title: The page title.
+            summary: The page summary text.
+            idx: The page's index in the original search results.
+
+        Returns:
+            Relevance score where higher values indicate greater relevance.
+        """
+        page_mod = 1 - (idx * 0.05)  # Favor original order returned by Wikipedia
+        title_score = fuzzy_match(query, rm_parentheses(title), MatchStrategy.TOKEN_SET_RATIO)
+        summary_score = fuzzy_match(summary, query, MatchStrategy.TOKEN_SET_RATIO)
+        return title_score * summary_score * page_mod
+
+    def _rerank_pages(self, query: str, results: List[WikipediaResult], lang: str) -> List[WikipediaResult]:
+        """
+        Uses the loaded ReRanker plugin to re-score the list of results.
+
+        Args:
+            query: The user's search query.
+            results: List of fetched WikipediaResult objects.
+            lang: Language code.
+
+        Returns:
+            List of WikipediaResult objects sorted by updated confidence scores.
+        """
+        if self._reranker is not None:
+            ranked = self._reranker.rerank(query, [r.best_passage or r.summary for r in results], lang)
+            for idx, (score, summary) in enumerate(ranked):
+                LOG.debug(f"{results[idx].title}: {results[idx].conf} -> {score}")
+                results[idx].conf = score
+        return sorted(results, key=lambda k: k.conf, reverse=True)
+
+
+class SearchWikipediaArgs(ToolArguments):
+    """Input arguments for the search_wikipedia tool."""
+    query: str = Field(..., description="The search query to look up on Wikipedia.")
+    lang: str = Field(..., description="BCP-47 language code, e.g. 'en', 'pt', 'de'.")
+
+
+class SearchWikipediaOutput(ToolOutput):
+    """Output from the search_wikipedia tool."""
+    results: List[Tuple[str, str]] = Field(
+        ...,
+        description="List of (title, summary) pairs for the top matching Wikipedia articles."
+    )
+
+
+class WikipediaToolbox(ToolBox):
+    toolbox_id = "ovos-wikipedia-tools"
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Initialise the toolbox.
+
+        Args:
+            config: Plugin configuration dict (currently unused).
+        """
+        self.wiki = WikipediaRetrievalEngine(config)
+        super().__init__(toolbox_id=self.toolbox_id)
+
+    def search_wikipedia(self, args: SearchWikipediaArgs) -> SearchWikipediaOutput:
+        """
+        Search Wikipedia for articles matching the given query.
+
+        Args:
+            args: Validated ``SearchWikipediaArgs`` with ``query`` and ``lang`` fields.
+
+        Returns:
+            ``SearchWikipediaOutput`` with a list of (title, summary) pairs.
+        """
+        return SearchWikipediaOutput(
+            results=[(res.title, res.summary)
+                     for res in self.wiki.search(query=args.query, lang=args.lang)],
+        )
+
+    def discover_tools(self) -> List[AgentTool]:
+        """
+        Abstract method to be implemented by concrete ToolBox plugins.
+
+        This method must define and return the list of AgentTools provided by this plugin.
+        The implementation should be idempotent (safe to call multiple times).
+
+        Returns:
+            A list of instantiated AgentTool objects.
+        """
+        return [
+            AgentTool(
+                name="search_wikipedia",
+                description=(
+                    "Search Wikipedia for information about a topic. "
+                    "Returns a list of matching article titles and their introductory summaries."
+                ),
+                argument_schema=SearchWikipediaArgs,
+                output_schema=SearchWikipediaOutput,
+                tool_call=self.search_wikipedia,
+            )
+        ]
+
+
+if __name__ == "__main__":
+    LOG.set_level("ERROR")
+
+    s = WikipediaRetrievalEngine()
+
+    data = s.search("who is venus")
+    for r in data:
+        print(r)

ovos_wikipedia_plugin-1.0.0a1/ovos_wikipedia/version.py

@@ -0,0 +1,8 @@
+# START_VERSION_BLOCK
+VERSION_MAJOR = 1
+VERSION_MINOR = 0
+VERSION_BUILD = 0
+VERSION_ALPHA = 1
+# END_VERSION_BLOCK
+
+__version__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD}" + (f"a{VERSION_ALPHA}" if VERSION_ALPHA else "")

ovos_wikipedia_plugin-1.0.0a1/ovos_wikipedia_plugin.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ovos-wikipedia-plugin
+Version: 1.0.0a1
+Summary: OVOS Wikipedia plugin
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ovos-utils<1.0.0,>=0.7.0
+Requires-Dist: ovos-plugin-manager<3.0.0,>=2.3.0a1
+Requires-Dist: ovos-bus-client>=1.0.1
+Requires-Dist: rapidfuzz
+Requires-Dist: pydantic
+Requires-Dist: requests
+
+# ovos-wikipedia-plugin
+
+[![PyPI](https://img.shields.io/pypi/v/ovos-wikipedia-plugin)](https://pypi.org/project/ovos-wikipedia-plugin/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://www.python.org/)
+
+Wikipedia integration for [OpenVoiceOS](https://openvoiceos.org). Provides a **retrieval engine** for RAG pipelines and
+an **agent toolbox** for tool-using agents, both as standard OPM plugins.
+
+---
+
+## Installation
+
+```bash
+pip install ovos-wikipedia-plugin
+```
+
+---
+
+## OPM Entry Points
+
+| Entry point                                      | Class                      | Use case                                                 |
+|--------------------------------------------------|----------------------------|----------------------------------------------------------|
+| `opm.agents.retrieval` — `ovos-wikipedia-plugin` | `WikipediaRetrievalEngine` | Retrieval — returns ranked `(passage, score)` tuples     |
+| `opm.agents.toolbox` — `ovos-wikipedia-tool`     | `WikipediaToolbox`         | Agent tool use — exposes `search_wikipedia`              |
+
+---
+
+## Retrieval Engine
+
+`WikipediaRetrievalEngine` implements the `RetrievalEngine` OPM interface. It searches Wikipedia, fetches article
+summaries in parallel, scores them for relevance, and optionally applies extractive QA and reranking sub-plugins.
+
+```python
+from ovos_wikipedia import WikipediaRetrievalEngine
+
+engine = WikipediaRetrievalEngine()
+
+# Returns List[WikipediaResult] sorted by relevance
+for result in engine.search("Ada Lovelace", lang="en"):
+    print(result.title, result.conf)
+    print(result.summary)
+    if result.image:
+        print(result.image)
+
+# RAG interface: List[Tuple[str, float]]  (passage, score)
+passages = engine.query("who was Ada Lovelace", lang="en", k=3)
+```
+
+### Optional sub-plugins
+
+| Config key          | OPM type                   | Effect                                                    |
+|---------------------|----------------------------|-----------------------------------------------------------|
+| `extractive_qa`     | `opm.agents.extractive_qa` | Extract the best passage from each article summary        |
+| `reranker`          | `opm.agents.reranker`      | Re-score results with a cross-encoder                     |
+| `keyword_extractor` | `opm.plugin.keywords`      | Rewrite the query when the initial search returns nothing |
+
+```python
+engine = WikipediaRetrievalEngine(config={
+    "extractive_qa": "ovos-bm25-solver",
+    "reranker": "ovos-bm25-reranker",
+    "keyword_extractor": "ovos-rake-keywords",
+})
+```
+
+---
+
+## Agent Toolbox
+
+`WikipediaToolbox` exposes a single `search_wikipedia` tool that any OPM-compatible agent loop (
+e.g. [ovos-agentic-loop](https://github.com/TigreGotico/ovos-agentic-loop)) can discover and call.
+
+### Loading via entry point (recommended)
+
+Any agent loop that supports `opm.agents.toolbox` entry points will auto-discover this toolbox by name:
+
+```json
+{
+  "name": "ResearchAgent",
+  "solvers": [
+    "ovos-react-loop"
+  ],
+  "ovos-react-loop": {
+    "brain": "ovos-chat-openai-plugin",
+    "ovos-chat-openai-plugin": {
+      "api_url": "http://localhost:11434/v1/chat/completions"
+    },
+    "toolboxes": [
+      "ovos-wikipedia-tool"
+    ]
+  }
+}
+```
+
+### Direct usage
+
+```python
+from ovos_wikipedia import WikipediaToolbox, SearchWikipediaArgs
+
+tb = WikipediaToolbox()
+
+# Discover the tool (used internally by agent loops)
+tools = tb.discover_tools()
+# [AgentTool(name="search_wikipedia", description="Search Wikipedia for information about a topic...")]
+
+# Call directly
+output = tb.search_wikipedia(SearchWikipediaArgs(query="Ada Lovelace", lang="en"))
+for title, summary in output.results:
+    print(title)
+    print(summary)
+```
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

ovos_wikipedia_plugin-1.0.0a1/ovos_wikipedia_plugin.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+ovos_wikipedia/__init__.py
+ovos_wikipedia/version.py
+ovos_wikipedia_plugin.egg-info/PKG-INFO
+ovos_wikipedia_plugin.egg-info/SOURCES.txt
+ovos_wikipedia_plugin.egg-info/dependency_links.txt
+ovos_wikipedia_plugin.egg-info/entry_points.txt
+ovos_wikipedia_plugin.egg-info/requires.txt
+ovos_wikipedia_plugin.egg-info/top_level.txt
+tests/test_wikipedia_solver.py

ovos_wikipedia_plugin-1.0.0a1/ovos_wikipedia_plugin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ovos_wikipedia_plugin-1.0.0a1/ovos_wikipedia_plugin.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[opm.agents.retrieval]
+ovos-wikipedia-plugin = ovos_wikipedia:WikipediaRetrievalEngine
+
+[opm.agents.toolbox]
+ovos-wikipedia-tool = ovos_wikipedia:WikipediaToolbox

ovos_wikipedia_plugin-1.0.0a1/ovos_wikipedia_plugin.egg-info/requires.txt

@@ -0,0 +1,6 @@
+ovos-utils<1.0.0,>=0.7.0
+ovos-plugin-manager<3.0.0,>=2.3.0a1
+ovos-bus-client>=1.0.1
+rapidfuzz
+pydantic
+requests

ovos_wikipedia_plugin-1.0.0a1/ovos_wikipedia_plugin.egg-info/top_level.txt

@@ -0,0 +1 @@
+ovos_wikipedia

ovos_wikipedia_plugin-1.0.0a1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ovos-wikipedia-plugin"
+dynamic = ["version"]
+description = "OVOS Wikipedia plugin"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+dependencies = [
+    "ovos-utils>=0.7.0,<1.0.0",
+    "ovos-plugin-manager>=2.3.0a1,<3.0.0",
+    "ovos-bus-client>=1.0.1",
+    "rapidfuzz",
+    "pydantic",
+    "requests"
+]
+
+[project.entry-points."opm.agents.retrieval"]
+ovos-wikipedia-plugin = "ovos_wikipedia:WikipediaRetrievalEngine"
+
+[project.entry-points."opm.agents.toolbox"]
+ovos-wikipedia-tool = "ovos_wikipedia:WikipediaToolbox"
+
+[tool.setuptools.dynamic]
+version = {attr = "ovos_wikipedia.version.__version__"}

ovos_wikipedia_plugin-1.0.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ovos_wikipedia_plugin-1.0.0a1/tests/test_wikipedia_solver.py

@@ -0,0 +1,435 @@
+"""
+Unit tests for WikipediaRetrievalEngine and WikipediaToolbox.
+
+Uses mocked HTTP calls (no network required) unless marked as integration tests.
+"""
+import unittest
+from unittest.mock import patch, MagicMock
+
+from ovos_wikipedia import WikipediaRetrievalEngine, WikipediaResult, WikipediaToolbox
+
+
+def _make_engine(**cfg) -> WikipediaRetrievalEngine:
+    return WikipediaRetrievalEngine(config=cfg or {})
+
+
+def _fake_result(title="Test Page", summary="Test summary about the topic.", conf=0.8) -> WikipediaResult:
+    return WikipediaResult(
+        page_id="123",
+        lang="en",
+        title=title,
+        summary=summary,
+        conf=conf,
+        query="test query",
+    )
+
+
+# ---------------------------------------------------------------------------
+# WikipediaResult dataclass
+# ---------------------------------------------------------------------------
+
+class TestWikipediaResult(unittest.TestCase):
+
+    def test_required_fields(self):
+        r = WikipediaResult(page_id="1", lang="en", title="T", summary="S")
+        self.assertEqual(r.page_id, "1")
+        self.assertEqual(r.lang, "en")
+        self.assertIsNone(r.image)
+        self.assertIsNone(r.best_passage)
+        self.assertEqual(r.conf, 0.5)
+
+    def test_optional_fields(self):
+        r = WikipediaResult(page_id="1", lang="en", title="T", summary="S",
+                            image="http://img", conf=0.9, query="q", best_passage="p")
+        self.assertEqual(r.image, "http://img")
+        self.assertEqual(r.conf, 0.9)
+        self.assertEqual(r.best_passage, "p")
+
+
+# ---------------------------------------------------------------------------
+# Plugin loading
+# ---------------------------------------------------------------------------
+
+class TestPluginLoading(unittest.TestCase):
+
+    def test_no_plugins_when_config_empty(self):
+        s = _make_engine()
+        self.assertIsNone(s._extractive_qa)
+        self.assertIsNone(s._reranker)
+        self.assertIsNone(s._kword_extractor)
+
+    def test_extractive_qa_loads_when_plugin_available(self):
+        mock_cls = MagicMock(return_value=MagicMock())
+        with patch("ovos_wikipedia.load_extractive_qa_plugin", return_value=mock_cls):
+            s = WikipediaRetrievalEngine(config={"extractive_qa": "some-plugin"})
+        self.assertIsNotNone(s._extractive_qa)
+
+    def test_reranker_loads_when_plugin_available(self):
+        mock_cls = MagicMock(return_value=MagicMock())
+        with patch("ovos_wikipedia.load_reranker_plugin", return_value=mock_cls):
+            s = WikipediaRetrievalEngine(config={"reranker": "some-plugin"})
+        self.assertIsNotNone(s._reranker)
+
+    def test_keyword_extractor_loads_when_plugin_available(self):
+        mock_cls = MagicMock(return_value=MagicMock())
+        with patch("ovos_wikipedia.load_keyword_extract_plugin", return_value=mock_cls):
+            s = WikipediaRetrievalEngine(config={"keyword_extractor": "some-plugin"})
+        self.assertIsNotNone(s._kword_extractor)
+
+    def test_unknown_extractive_qa_plugin_returns_none(self):
+        with patch("ovos_wikipedia.load_extractive_qa_plugin", return_value=None):
+            s = WikipediaRetrievalEngine(config={"extractive_qa": "nonexistent-plugin"})
+        self.assertIsNone(s._extractive_qa)
+
+    def test_unknown_reranker_plugin_returns_none(self):
+        with patch("ovos_wikipedia.load_reranker_plugin", return_value=None):
+            s = WikipediaRetrievalEngine(config={"reranker": "nonexistent-plugin"})
+        self.assertIsNone(s._reranker)
+
+    def test_plugin_init_exception_returns_none(self):
+        mock_cls = MagicMock(side_effect=RuntimeError("init failed"))
+        with patch("ovos_wikipedia.load_extractive_qa_plugin", return_value=mock_cls):
+            s = WikipediaRetrievalEngine(config={"extractive_qa": "bad-plugin"})
+        self.assertIsNone(s._extractive_qa)
+
+
+# ---------------------------------------------------------------------------
+# _score_page (pure function)
+# ---------------------------------------------------------------------------
+
+class TestScorePage(unittest.TestCase):
+
+    def test_perfect_title_match_scores_high(self):
+        WikipediaRetrievalEngine._score_page.cache_clear()
+        score = WikipediaRetrievalEngine._score_page("python", "Python", "Python is a programming language.", 0)
+        self.assertGreater(score, 0.1)
+
+    def test_unrelated_title_scores_low(self):
+        WikipediaRetrievalEngine._score_page.cache_clear()
+        score = WikipediaRetrievalEngine._score_page("python language", "Banana", "Banana is a tropical fruit.", 0)
+        self.assertLess(score, 0.5)
+
+    def test_later_index_scores_lower(self):
+        WikipediaRetrievalEngine._score_page.cache_clear()
+        score_first = WikipediaRetrievalEngine._score_page("python", "Python", "Python language.", 0)
+        score_later = WikipediaRetrievalEngine._score_page("python", "Python", "Python language.", 3)
+        self.assertGreater(score_first, score_later)
+
+    def test_empty_query_does_not_crash(self):
+        WikipediaRetrievalEngine._score_page.cache_clear()
+        score = WikipediaRetrievalEngine._score_page("", "Python", "Python is a programming language.", 0)
+        self.assertIsInstance(score, float)
+
+
+# ---------------------------------------------------------------------------
+# _rerank_pages
+# ---------------------------------------------------------------------------
+
+class TestRerankPages(unittest.TestCase):
+
+    def setUp(self):
+        self.s = _make_engine()
+
+    def test_sorted_by_conf_descending_without_reranker(self):
+        pages = [
+            _fake_result(title="B", conf=0.3),
+            _fake_result(title="A", conf=0.9),
+            _fake_result(title="C", conf=0.6),
+        ]
+        result = self.s._rerank_pages("query", pages, "en")
+        confs = [r.conf for r in result]
+        self.assertEqual(confs, sorted(confs, reverse=True))
+
+    def test_reranker_updates_conf_scores(self):
+        mock_reranker = MagicMock()
+        mock_reranker.rerank.return_value = [(0.95, "summary A"), (0.1, "summary B")]
+        self.s._reranker = mock_reranker
+
+        pages = [
+            _fake_result(title="A", conf=0.3, summary="summary A"),
+            _fake_result(title="B", conf=0.8, summary="summary B"),
+        ]
+        result = self.s._rerank_pages("query", pages, "en")
+        self.assertEqual(result[0].conf, 0.95)
+        self.assertEqual(result[1].conf, 0.1)
+
+    def test_reranker_called_with_summaries(self):
+        mock_reranker = MagicMock()
+        mock_reranker.rerank.return_value = [(0.9, "s1"), (0.8, "s2")]
+        self.s._reranker = mock_reranker
+
+        p1 = _fake_result(summary="s1")
+        p2 = _fake_result(summary="s2")
+        self.s._rerank_pages("q", [p1, p2], "en")
+        mock_reranker.rerank.assert_called_once_with("q", ["s1", "s2"], "en")
+
+    def test_best_passage_used_over_summary_for_reranker(self):
+        mock_reranker = MagicMock()
+        mock_reranker.rerank.return_value = [(0.9, "passage1")]
+        self.s._reranker = mock_reranker
+
+        p = _fake_result(summary="full summary")
+        p.best_passage = "passage1"
+        self.s._rerank_pages("q", [p], "en")
+        mock_reranker.rerank.assert_called_once_with("q", ["passage1"], "en")
+
+
+# ---------------------------------------------------------------------------
+# _get_page_data (mocked HTTP)
+# ---------------------------------------------------------------------------
+
+class TestGetPageData(unittest.TestCase):
+
+    def _make_response(self, pid, title, extract, thumbnail=None):
+        page = {"title": title, "extract": extract}
+        if thumbnail:
+            page["thumbnail"] = {"source": thumbnail}
+        return {"query": {"pages": {pid: page}}}
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_returns_wikipedia_result(self, mock_get):
+        mock_get.return_value.json.return_value = self._make_response(
+            "42", "Python (programming language)", "Python is a high-level language."
+        )
+
+        result = WikipediaRetrievalEngine._get_page_data("42", "en", "python", 0)
+        self.assertIsInstance(result, WikipediaResult)
+        self.assertEqual(result.title, "Python (programming language)")
+        self.assertEqual(result.lang, "en")
+        self.assertEqual(result.page_id, "42")
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_disambiguation_page_returns_none(self, mock_get):
+        mock_get.return_value.json.return_value = self._make_response(
+            "99", "Mercury", "Mercury may refer to: the planet, the element, the god."
+        )
+
+        result = WikipediaRetrievalEngine._get_page_data("99", "en", "mercury", 0)
+        self.assertIsNone(result)
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_image_url_strips_thumb_path(self, mock_get):
+        thumbnail = "https://upload.wikimedia.org/thumb/img/320px-img.jpg"
+        mock_get.return_value.json.return_value = self._make_response(
+            "7", "Eiffel Tower", "The Eiffel Tower is in Paris.", thumbnail=thumbnail
+        )
+
+        result = WikipediaRetrievalEngine._get_page_data("7", "en", "eiffel tower", 0)
+        self.assertIsNotNone(result.image)
+        self.assertNotIn("thumb", result.image)
+        self.assertNotIn("320px-img.jpg", result.image)
+
+    @patch("ovos_wikipedia.requests.get", side_effect=Exception("network error"))
+    def test_network_error_returns_none(self, mock_get):
+
+        result = WikipediaRetrievalEngine._get_page_data("1", "en", "q", 0)
+        self.assertIsNone(result)
+
+
+# ---------------------------------------------------------------------------
+# search (mocked HTTP)
+# ---------------------------------------------------------------------------
+
+_SEARCH_RESULTS = {
+    "query": {
+        "search": [
+            {"pageid": 1001, "title": "Python (programming language)"},
+            {"pageid": 1002, "title": "Python (snake)"},
+        ]
+    }
+}
+
+_PAGE_DATA_1001 = {
+    "query": {"pages": {"1001": {"title": "Python (programming language)", "extract": "Python is a language."}}}
+}
+_PAGE_DATA_1002 = {
+    "query": {"pages": {"1002": {"title": "Python (snake)", "extract": "Python is a large snake."}}}
+}
+
+
+class TestSearch(unittest.TestCase):
+
+    def setUp(self):
+        self.s = _make_engine()
+
+
+    def _patch_requests(self, search_data, page_data_map):
+        def side_effect(url, **kwargs):
+            mock_resp = MagicMock()
+            if "list=search" in url:
+                mock_resp.json.return_value = search_data
+            else:
+                for pid, data in page_data_map.items():
+                    if f"pageids={pid}" in url:
+                        mock_resp.json.return_value = data
+                        break
+                else:
+                    mock_resp.json.return_value = {"query": {"pages": {}}}
+            return mock_resp
+        return side_effect
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_returns_list_of_results(self, mock_get):
+        mock_get.side_effect = self._patch_requests(
+            _SEARCH_RESULTS, {"1001": _PAGE_DATA_1001, "1002": _PAGE_DATA_1002}
+        )
+        results = self.s.search("python", "en", top_k=2)
+        self.assertIsInstance(results, list)
+        self.assertGreater(len(results), 0)
+        self.assertIsInstance(results[0], WikipediaResult)
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_results_sorted_by_conf_descending(self, mock_get):
+        mock_get.side_effect = self._patch_requests(
+            _SEARCH_RESULTS, {"1001": _PAGE_DATA_1001, "1002": _PAGE_DATA_1002}
+        )
+        results = self.s.search("python", "en", top_k=2)
+        confs = [r.conf for r in results]
+        self.assertEqual(confs, sorted(confs, reverse=True))
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_empty_search_returns_empty_list(self, mock_get):
+        mock_get.return_value.json.return_value = {"query": {"search": []}}
+        results = self.s.search("xyzzy_nonexistent_12345", "en")
+        self.assertEqual(results, [])
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_network_error_returns_empty_list(self, mock_get):
+        mock_get.side_effect = Exception("timeout")
+        results = self.s.search("python", "en")
+        self.assertEqual(results, [])
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_disambiguation_pages_are_skipped(self, mock_get):
+        search_data = {"query": {"search": [{"pageid": 555, "title": "Mercury (disambiguation)"}]}}
+        mock_get.side_effect = self._patch_requests(search_data, {})
+        results = self.s.search("mercury", "en")
+        self.assertEqual(results, [])
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_extractive_qa_called_when_loaded(self, mock_get):
+        mock_get.side_effect = self._patch_requests(
+            _SEARCH_RESULTS, {"1001": _PAGE_DATA_1001, "1002": _PAGE_DATA_1002}
+        )
+        mock_qa = MagicMock()
+        mock_qa.get_best_passage.return_value = "Python is a language."
+        self.s._extractive_qa = mock_qa
+
+        results = self.s.search("python programming", "en", top_k=2)
+        self.assertTrue(mock_qa.get_best_passage.called)
+        for r in results:
+            self.assertEqual(r.best_passage, "Python is a language.")
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_keyword_fallback_when_empty_results(self, mock_get):
+        call_count = [0]
+
+        def side_effect(url, **kwargs):
+            resp = MagicMock()
+            if "list=search" in url:
+                if call_count[0] == 0:
+                    resp.json.return_value = {"query": {"search": []}}
+                else:
+                    resp.json.return_value = _SEARCH_RESULTS
+                call_count[0] += 1
+            else:
+                resp.json.return_value = _PAGE_DATA_1001
+            return resp
+
+        mock_get.side_effect = side_effect
+
+        mock_kw = MagicMock()
+        mock_kw.extract.return_value = ["python programming language"]
+        self.s._kword_extractor = mock_kw
+
+        results = self.s.search("what is python used for programming", "en")
+        self.assertGreater(len(results), 0)
+        mock_kw.extract.assert_called_once()
+
+    @patch("ovos_wikipedia.requests.get")
+    def test_lang_code_stripped_to_two_chars(self, mock_get):
+        mock_get.return_value.json.return_value = {"query": {"search": []}}
+        self.s.search("python", "en-US")
+        search_url = mock_get.call_args_list[0][0][0]
+        self.assertIn("en.wikipedia.org", search_url)
+        self.assertNotIn("en-US", search_url)
+
+
+# ---------------------------------------------------------------------------
+# query() method
+# ---------------------------------------------------------------------------
+
+class TestQuery(unittest.TestCase):
+
+    def setUp(self):
+        self.s = _make_engine()
+
+    def test_returns_list_of_tuples(self):
+        fake_pages = [
+            _fake_result(summary="Summary one.", conf=0.9),
+            _fake_result(summary="Summary two.", conf=0.7),
+        ]
+        with patch.object(self.s, "search", return_value=fake_pages):
+            results = self.s.query("test query", "en", k=2)
+        self.assertEqual(len(results), 2)
+        for content, score in results:
+            self.assertIsInstance(content, str)
+            self.assertIsInstance(score, float)
+
+    def test_best_passage_preferred_over_summary(self):
+        page = _fake_result(summary="Full summary text.")
+        page.best_passage = "Extracted passage."
+        with patch.object(self.s, "search", return_value=[page]):
+            results = self.s.query("q", "en")
+        self.assertEqual(results[0][0], "Extracted passage.")
+
+    def test_summary_used_when_no_best_passage(self):
+        page = _fake_result(summary="Full summary text.")
+        page.best_passage = None
+        with patch.object(self.s, "search", return_value=[page]):
+            results = self.s.query("q", "en")
+        self.assertEqual(results[0][0], "Full summary text.")
+
+    def test_empty_search_returns_empty_list(self):
+        with patch.object(self.s, "search", return_value=[]):
+            results = self.s.query("q", "en")
+        self.assertEqual(results, [])
+
+    def test_k_forwarded_to_search(self):
+        with patch.object(self.s, "search", return_value=[]) as mock_search:
+            self.s.query("q", "en", k=5)
+        mock_search.assert_called_once_with("q", "en", 5)
+
+
+# ---------------------------------------------------------------------------
+# WikipediaToolbox
+# ---------------------------------------------------------------------------
+
+class TestWikipediaToolbox(unittest.TestCase):
+
+    def test_discover_tools_returns_search_tool(self):
+        tb = WikipediaToolbox()
+        tools = tb.discover_tools()
+        self.assertEqual(len(tools), 1)
+        self.assertEqual(tools[0].name, "search_wikipedia")
+
+    def test_search_wikipedia_returns_title_summary_pairs(self):
+        tb = WikipediaToolbox()
+        fake_pages = [
+            _fake_result(title="Python", summary="A programming language."),
+        ]
+        with patch.object(tb.wiki, "search", return_value=fake_pages):
+            from ovos_wikipedia import SearchWikipediaArgs
+            output = tb.search_wikipedia(SearchWikipediaArgs(query="python", lang="en"))
+        self.assertEqual(output.results, [("Python", "A programming language.")])
+
+    def test_search_wikipedia_empty_results(self):
+        tb = WikipediaToolbox()
+        with patch.object(tb.wiki, "search", return_value=[]):
+            from ovos_wikipedia import SearchWikipediaArgs
+            output = tb.search_wikipedia(SearchWikipediaArgs(query="xyzzy", lang="en"))
+        self.assertEqual(output.results, [])
+
+
+if __name__ == "__main__":
+    unittest.main()