ovos-wolfram-alpha-plugin 1.0.0a1__tar.gz

ovos_wolfram_alpha_plugin-1.0.0a1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: ovos-wolfram-alpha-plugin
+Version: 1.0.0a1
+Summary: ovos wolfram-alpha plugin
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-wolfram-alpha-plugin
+Keywords: ovos,plugin,wolfram
+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-config<2.0.0,>=0.0.12
+Requires-Dist: requests>=2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+
+# ovos-wolfram-alpha-plugin
+
+[![PyPI](https://img.shields.io/pypi/v/ovos-wolfram-alpha-plugin)](https://pypi.org/project/ovos-wolfram-alpha-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/)
+
+[Wolfram Alpha](https://www.wolframalpha.com/) 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.
+
+Wolfram Alpha excels at questions with a single definitive answer: maths, unit conversions, scientific constants, chemical properties, astronomy, nutrition, geography, and historical dates. It is not a search engine — it computes answers from curated data.
+
+An [API key](https://products.wolframalpha.com/api/) is required. A demo key is bundled for development but is rate-limited and should not be used in production.
+
+---
+
+## Installation
+
+```bash
+pip install ovos-wolfram-alpha-plugin
+```
+
+---
+
+## OPM Entry Points
+
+| Entry point | Class | Use case |
+|---|---|---|
+| `opm.agents.retrieval` — `ovos-wolfram-alpha-solver` | `WolframAlphaRetrievalEngine` | RAG — returns `(answer, score)` tuples |
+| `opm.agents.toolbox` — `ovos-wolfram-alpha-tools` | `WolframAlphaToolbox` | Agent tool use — exposes `search_wolfram_alpha` |
+
+---
+
+## Retrieval Engine
+
+`WolframAlphaRetrievalEngine` implements the `RetrievalEngine` OPM interface. It calls the Wolfram Alpha spoken-answer endpoint and handles non-English queries by translating them to English before the request and back after.
+
+```python
+from ovos_wolfram_alpha_plugin import WolframAlphaRetrievalEngine
+
+engine = WolframAlphaRetrievalEngine(config={"appid": "YOUR-KEY"})
+
+# Maths & conversions
+engine.get_spoken_answer("integral of x^2 sin(x)", lang="en")
+# "x^2 (-cos(x)) + 2 x sin(x) + 2 cos(x) + constant"
+
+engine.get_spoken_answer("100 miles in kilometers", lang="en")
+# "160.934 kilometers"
+
+engine.get_spoken_answer("1000 USD in EUR", lang="en")
+# "approximately 923 euros"  (live rate)
+
+# Science & constants
+engine.get_spoken_answer("speed of light", lang="en")
+# "about 2.998 × 10^8 meters per second"
+
+engine.get_spoken_answer("boiling point of ethanol", lang="en")
+# "78.37 degrees Celsius"
+
+engine.get_spoken_answer("distance from Earth to Mars", lang="en")
+# "currently about 1.69 AU"  (live ephemeris)
+
+# Factual lookups
+engine.get_spoken_answer("population of Brazil", lang="en")
+# "approximately 215.3 million people"
+
+engine.get_spoken_answer("calories in 100g of almonds", lang="en")
+# "579 kilocalories"
+
+engine.get_spoken_answer("when was the Eiffel Tower built", lang="en")
+# "construction was from January 28, 1887 to March 31, 1889"
+
+# Non-English — translated automatically
+engine.get_spoken_answer("massa do Sol", lang="pt")
+# "aproximadamente 1,989 × 10^30 kg"
+
+# Image result — returns a local file path to a Wolfram visual
+engine.get_image("benzene molecular structure", lang="en")
+
+# Full structured pod results — list of {"title", "summary"} dicts
+for pod in engine.get_expanded_answer("Neptune", lang="en"):
+    print(pod["title"], "—", pod.get("summary", pod.get("img")))
+# "Orbital period — 164.8 years"
+# "Surface gravity — 11.15 m/s²"
+# ...
+
+# RAG interface: List[Tuple[str, float]]  (answer, score)
+results = engine.query("half-life of carbon-14", lang="en")
+# [("5730 years", 0.9)]
+```
+
+### Translation
+
+Non-English queries require a translation plugin. Configure it by passing `translate_plugin` in the config:
+
+```python
+engine = WolframAlphaRetrievalEngine(config={
+    "appid": "YOUR-KEY",
+    "translate_plugin": "ovos-translate-plugin-server",
+})
+```
+
+If no translation plugin is available, only English queries are answered.
+
+---
+
+## Agent Toolbox
+
+`WolframAlphaToolbox` exposes a single `search_wolfram_alpha` tool that any OPM-compatible agent loop (e.g. [ovos-agentic-loop](https://github.com/OpenVoiceOS/ovos-agentic-loop)) can discover and call. The tool uses the LLM-optimised Wolfram endpoint, which returns a more structured answer than the spoken endpoint.
+
+### Persona JSON
+
+Reference the toolbox by its entry point name inside any agentic persona. Pass a `system_prompt` to the brain plugin so the LLM knows how to query Wolfram correctly:
+
+```json
+{
+  "name": "Wolfram Alpha",
+  "solvers": ["ovos-react-loop"],
+  "ovos-react-loop": {
+    "brain": "ovos-chat-openai-plugin",
+    "toolboxes": ["ovos-wolfram-alpha-tools"],
+    "ovos-chat-openai-plugin": {
+      "api_url": "http://localhost:11434/v1/chat/completions",
+      "system_prompt": "You have access to Wolfram Alpha. Use it for maths, science, unit conversions, and factual questions with a definite answer. Always send queries in English as concise keywords (e.g. 'France population', not 'how many people live in France'). Use the exponent notation 6*10^14, never 6e14. If the result is not relevant, retry with a more specific query rather than rephrasing."
+    }
+  }
+}
+```
+
+> 💡 The [official LLM API docs](https://products.wolframalpha.com/llm-api/documentation) have more tips on writing effective Wolfram system prompts.
+
+### Direct usage
+
+```python
+from ovos_wolfram_alpha_plugin import WolframAlphaToolbox, SearchWolframAlphaArgs
+
+tb = WolframAlphaToolbox(config={"appid": "YOUR-KEY"})
+
+tools = tb.discover_tools()
+# [AgentTool(name="search_wolfram_alpha", ...)]
+
+output = tb.search_wolfram(SearchWolframAlphaArgs(query="France population", units="metric"))
+print(output.result)
+```
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

ovos_wolfram_alpha_plugin-1.0.0a1/README.md

@@ -0,0 +1,148 @@
+# ovos-wolfram-alpha-plugin
+
+[![PyPI](https://img.shields.io/pypi/v/ovos-wolfram-alpha-plugin)](https://pypi.org/project/ovos-wolfram-alpha-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/)
+
+[Wolfram Alpha](https://www.wolframalpha.com/) 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.
+
+Wolfram Alpha excels at questions with a single definitive answer: maths, unit conversions, scientific constants, chemical properties, astronomy, nutrition, geography, and historical dates. It is not a search engine — it computes answers from curated data.
+
+An [API key](https://products.wolframalpha.com/api/) is required. A demo key is bundled for development but is rate-limited and should not be used in production.
+
+---
+
+## Installation
+
+```bash
+pip install ovos-wolfram-alpha-plugin
+```
+
+---
+
+## OPM Entry Points
+
+| Entry point | Class | Use case |
+|---|---|---|
+| `opm.agents.retrieval` — `ovos-wolfram-alpha-solver` | `WolframAlphaRetrievalEngine` | RAG — returns `(answer, score)` tuples |
+| `opm.agents.toolbox` — `ovos-wolfram-alpha-tools` | `WolframAlphaToolbox` | Agent tool use — exposes `search_wolfram_alpha` |
+
+---
+
+## Retrieval Engine
+
+`WolframAlphaRetrievalEngine` implements the `RetrievalEngine` OPM interface. It calls the Wolfram Alpha spoken-answer endpoint and handles non-English queries by translating them to English before the request and back after.
+
+```python
+from ovos_wolfram_alpha_plugin import WolframAlphaRetrievalEngine
+
+engine = WolframAlphaRetrievalEngine(config={"appid": "YOUR-KEY"})
+
+# Maths & conversions
+engine.get_spoken_answer("integral of x^2 sin(x)", lang="en")
+# "x^2 (-cos(x)) + 2 x sin(x) + 2 cos(x) + constant"
+
+engine.get_spoken_answer("100 miles in kilometers", lang="en")
+# "160.934 kilometers"
+
+engine.get_spoken_answer("1000 USD in EUR", lang="en")
+# "approximately 923 euros"  (live rate)
+
+# Science & constants
+engine.get_spoken_answer("speed of light", lang="en")
+# "about 2.998 × 10^8 meters per second"
+
+engine.get_spoken_answer("boiling point of ethanol", lang="en")
+# "78.37 degrees Celsius"
+
+engine.get_spoken_answer("distance from Earth to Mars", lang="en")
+# "currently about 1.69 AU"  (live ephemeris)
+
+# Factual lookups
+engine.get_spoken_answer("population of Brazil", lang="en")
+# "approximately 215.3 million people"
+
+engine.get_spoken_answer("calories in 100g of almonds", lang="en")
+# "579 kilocalories"
+
+engine.get_spoken_answer("when was the Eiffel Tower built", lang="en")
+# "construction was from January 28, 1887 to March 31, 1889"
+
+# Non-English — translated automatically
+engine.get_spoken_answer("massa do Sol", lang="pt")
+# "aproximadamente 1,989 × 10^30 kg"
+
+# Image result — returns a local file path to a Wolfram visual
+engine.get_image("benzene molecular structure", lang="en")
+
+# Full structured pod results — list of {"title", "summary"} dicts
+for pod in engine.get_expanded_answer("Neptune", lang="en"):
+    print(pod["title"], "—", pod.get("summary", pod.get("img")))
+# "Orbital period — 164.8 years"
+# "Surface gravity — 11.15 m/s²"
+# ...
+
+# RAG interface: List[Tuple[str, float]]  (answer, score)
+results = engine.query("half-life of carbon-14", lang="en")
+# [("5730 years", 0.9)]
+```
+
+### Translation
+
+Non-English queries require a translation plugin. Configure it by passing `translate_plugin` in the config:
+
+```python
+engine = WolframAlphaRetrievalEngine(config={
+    "appid": "YOUR-KEY",
+    "translate_plugin": "ovos-translate-plugin-server",
+})
+```
+
+If no translation plugin is available, only English queries are answered.
+
+---
+
+## Agent Toolbox
+
+`WolframAlphaToolbox` exposes a single `search_wolfram_alpha` tool that any OPM-compatible agent loop (e.g. [ovos-agentic-loop](https://github.com/OpenVoiceOS/ovos-agentic-loop)) can discover and call. The tool uses the LLM-optimised Wolfram endpoint, which returns a more structured answer than the spoken endpoint.
+
+### Persona JSON
+
+Reference the toolbox by its entry point name inside any agentic persona. Pass a `system_prompt` to the brain plugin so the LLM knows how to query Wolfram correctly:
+
+```json
+{
+  "name": "Wolfram Alpha",
+  "solvers": ["ovos-react-loop"],
+  "ovos-react-loop": {
+    "brain": "ovos-chat-openai-plugin",
+    "toolboxes": ["ovos-wolfram-alpha-tools"],
+    "ovos-chat-openai-plugin": {
+      "api_url": "http://localhost:11434/v1/chat/completions",
+      "system_prompt": "You have access to Wolfram Alpha. Use it for maths, science, unit conversions, and factual questions with a definite answer. Always send queries in English as concise keywords (e.g. 'France population', not 'how many people live in France'). Use the exponent notation 6*10^14, never 6e14. If the result is not relevant, retry with a more specific query rather than rephrasing."
+    }
+  }
+}
+```
+
+> 💡 The [official LLM API docs](https://products.wolframalpha.com/llm-api/documentation) have more tips on writing effective Wolfram system prompts.
+
+### Direct usage
+
+```python
+from ovos_wolfram_alpha_plugin import WolframAlphaToolbox, SearchWolframAlphaArgs
+
+tb = WolframAlphaToolbox(config={"appid": "YOUR-KEY"})
+
+tools = tb.discover_tools()
+# [AgentTool(name="search_wolfram_alpha", ...)]
+
+output = tb.search_wolfram(SearchWolframAlphaArgs(query="France population", units="metric"))
+print(output.result)
+```
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

ovos_wolfram_alpha_plugin-1.0.0a1/ovos_wolfram_alpha_plugin/__init__.py

@@ -0,0 +1,362 @@
+# 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 tempfile
+from os.path import join, isfile
+from typing import Optional, Tuple, Dict, Any, List
+
+import requests
+from ovos_config import Configuration
+from ovos_plugin_manager.templates.language import LanguageTranslator
+from ovos_plugin_manager.templates.agent_tools import AgentTool, ToolBox, ToolOutput, ToolArguments
+from ovos_plugin_manager.templates.agents import RetrievalEngine
+from ovos_utils.text_utils import rm_parentheses
+from pydantic import Field
+from ovos_utils.log import LOG
+from ovos_plugin_manager.language import load_tx_plugin
+
+
+class WolframAlphaApi:
+    def __init__(self, key: str):
+        self.key = key or "Y7R353-9HQAAL8KKA"
+
+    @staticmethod
+    def _get_lat_lon(**kwargs):
+        lat = kwargs.get("latitude") or kwargs.get("lat")
+        lon = kwargs.get("longitude") or kwargs.get("lon") or kwargs.get("lng")
+        if not lat or not lon:
+            cfg = Configuration().get("location", {}).get("coordinate", {})
+            lat = cfg.get("latitude")
+            lon = cfg.get("longitude")
+        return lat, lon
+
+    def spoken(self, query, units="metric", lat_lon=None, optional_params=None):
+        optional_params = optional_params or {}
+        if not lat_lon:
+            lat_lon = self._get_lat_lon(**optional_params)
+        params = {'i': query,
+                  "geolocation": "{},{}".format(*lat_lon),
+                  'units': units,
+                  "appid": self.key,
+                  **optional_params}
+        url = 'https://api.wolframalpha.com/v1/spoken'
+        return requests.get(url, params=params).text
+
+    def simple(self, query, units="metric", lat_lon=None, optional_params=None):
+        optional_params = optional_params or {}
+        if not lat_lon:
+            lat_lon = self._get_lat_lon(**optional_params)
+        params = {'i': query,
+                  "geolocation": "{},{}".format(*lat_lon),
+                  'units': units,
+                  "appid": self.key,
+                  **optional_params}
+        url = 'https://api.wolframalpha.com/v1/simple'
+        return requests.get(url, params=params).text
+
+    def query_recognizer(self, query, units="metric", lat_lon=None, optional_params=None):
+        optional_params = optional_params or {}
+        params = {'i': query,
+                  "appid": self.key,
+                  "output": "json",
+                  "mode": "Voice",
+                  **optional_params}
+        url = 'https://www.wolframalpha.com/queryrecognizer/query.jsp'
+        # TODO - {"status":401,"message":"Not permitted"}
+        # what am i doin wrong? https://products.wolframalpha.com/query-recognizer/documentation
+        return requests.get(url, params=params).json()
+
+    def llm(self, query, units="metric", lat_lon=None, optional_params=None):
+        optional_params = optional_params or {}
+        if not lat_lon:
+            lat_lon = self._get_lat_lon(**optional_params)
+        params = {'input': query,
+                  "geolocation": "{},{}".format(*lat_lon),
+                  'units': units,
+                  "appid": self.key,
+                  **optional_params}
+        url = 'https://api.wolframalpha.com/v1/llm-api'
+        return requests.get(url, params=params).text
+
+    def full_results(self, query, units="metric", lat_lon=None, optional_params=None):
+        """Wrapper for the WolframAlpha Full Results v2 API.
+        https://products.wolframalpha.com/api/documentation/
+        Pods of interest
+        - Input interpretation - Wolfram's determination of what is being asked about.
+        - Name - primary name of
+        """
+        optional_params = optional_params or {}
+        if not lat_lon:
+            lat_lon = self._get_lat_lon(**optional_params)
+        params = {'input': query,
+                  "units": units,
+                  "mode": "Default",
+                  "format": "image,plaintext",
+                  "geolocation": "{},{}".format(*lat_lon),
+                  "output": "json",
+                  "appid": self.key,
+                  **optional_params}
+        url = 'https://api.wolframalpha.com/v2/query'
+        data = requests.get(url, params=params)
+        return data.json()
+
+    def get_image(self, query: str, units: Optional[str] = None):
+        """Return path to a image result for the query."""
+        units = units or Configuration().get("system_unit", "metric")
+        url = 'http://api.wolframalpha.com/v1/simple'
+        params = {"appid": self.key,
+                  "i": query,
+                  # "background": "F5F5F5",
+                  "layout": "labelbar",
+                  "units": units}
+        path = join(tempfile.gettempdir(), query.replace(" ", "_") + ".gif")
+        if not isfile(path):
+            image = requests.get(url, params=params).content
+            with open(path, "wb") as f:
+                f.write(image)
+        return path
+
+
+class WolframAlphaRetrievalEngine(RetrievalEngine):
+    def __init__(self, config=None, translator: Optional[LanguageTranslator] = None):
+        super().__init__(config=config)
+        self.api = WolframAlphaApi(key=self.config.get("appid") or "Y7R353-9HQAAL8KKA")
+        self.translator: Optional[LanguageTranslator] = translator
+        if not translator:
+            self._load_translator()
+
+    def _load_translator(self):
+        lang_cfg = Configuration().get("language", {})
+        plug_id = self.config.get("translate_plugin") or lang_cfg.get("translation_module", "ovos-translate-plugin-server")
+        clazz = load_tx_plugin(plug_id)
+        if clazz is None:
+            LOG.error(f"Translation plugin not loaded '{plug_id}': only english queries will be answered")
+        else:
+            self.translator = clazz(config=lang_cfg.get(plug_id, {}))
+            LOG.debug(f"Loaded translation plugin: '{plug_id}'")
+
+    def query(self, query: str, lang: Optional[str] = None, k: int = 3) -> List[Tuple[str, float]]:
+        """
+        Searches Wolfram Alpha for a spoken answer.
+
+        Args:
+            query: The search string.
+            lang: BCP-47 language code.
+            k: Maximum number of results (unused; Wolfram returns one answer).
+
+        Returns:
+            List of (content, score) tuples, or empty list if no answer.
+        """
+        units = self.config.get("units") or Configuration().get("system_unit", "metric")
+        answer = self.get_spoken_answer(query, lang, units)
+        if answer:
+            # TODO - use query recognizer to get a confidence level
+            return [(answer, 0.9)]
+        return []
+
+    ################################
+    # helpers to parse api results
+    ################################
+    def get_image(self, query: str,
+                  lang: Optional[str] = None,
+                  units: Optional[str] = None):
+        """Return path to a cached image result for the query."""
+        if lang != "en":
+            query = self.translator.translate(query, target="en", source=lang)
+        units = units or Configuration().get("system_unit", "metric")
+        return self.api.get_image(query, units=units)
+
+    def get_spoken_answer(self, query: str,
+                          lang: Optional[str] = None,
+                          units: Optional[str] = None):
+        """Return a single natural-language sentence answering the query."""
+        lang = lang.split("-")[0].lower()
+        if lang != "en":
+            query = self.translator.translate(query, target="en", source=lang)
+        units = units or Configuration().get("system_unit", "metric")
+        answer = self.api.spoken(query, units=units)
+        bad_answers = ["no spoken result available",
+                       "wolfram alpha did not understand your input"]
+        if answer.lower().strip() in bad_answers:
+            return None
+        if lang != "en":
+            answer = self.translator.translate(answer, target=lang, source="en")
+        return answer
+
+    def get_expanded_answer(self, query,
+                            lang: Optional[str] = None,
+                            units: Optional[str] = None):
+        """Return a list of structured result pods from the Full Results API."""
+        if lang != "en":
+            query = self.translator.translate(query, target="en", source=lang)
+        data = self.api.full_results(query, units=units)
+        skip = ['Input interpretation', 'Interpretation',
+                'Result', 'Value', 'Image']
+        steps = []
+
+        for pod in data['queryresult'].get('pods', []):
+            title = pod["title"]
+            if title in skip:
+                continue
+
+            for sub in pod["subpods"]:
+                subpod = {"title": title}
+                summary = sub["img"]["alt"]
+                subtitle = sub.get("title") or sub["img"]["title"]
+                if subtitle and subtitle != summary:
+                    subpod["title"] = subtitle
+
+                if summary == title:
+                    # it's an image result
+                    subpod["img"] = sub["img"]["src"]
+                elif summary.startswith("(") and summary.endswith(")"):
+                    continue
+                else:
+                    subpod["summary"] = summary
+                steps.append(subpod)
+
+        # do any extra processing here
+        prev = ""
+        for idx, step in enumerate(steps):
+            # merge steps
+            if step["title"] == prev:
+                summary = steps[idx - 1]["summary"] + "\n" + step["summary"]
+                steps[idx]["summary"] = summary
+                steps[idx]["img"] = step.get("img") or steps[idx - 1].get("img")
+                steps[idx - 1] = None
+            elif step.get("summary") and step["title"]:
+                # inject title in speech, eg we do not want wolfram to just read family names without context
+                steps[idx]["summary"] = step["title"] + ".\n" + step["summary"]
+
+            # normalize summary
+            if step.get("summary"):
+                steps[idx]["summary"] = self.make_speakable(steps[idx]["summary"])
+
+            if lang != "en":
+                steps[idx]["title"] = self.translator.translate(steps[idx]["title"], target=lang, source="en")
+                if step.get("summary"):
+                    steps[idx]["summary"] = self.translator.translate(steps[idx]["summary"], target=lang, source="en")
+
+            prev = step["title"]
+        return [s for s in steps if s]
+
+    @staticmethod
+    def make_speakable(summary: str):
+        """Normalise a Wolfram result string for text-to-speech."""
+        # let's remove unwanted data from parantheses
+        #  - many results have (human: XX unit) ref values, remove them
+        if "(human: " in summary:
+            splits = summary.split("(human: ")
+            for idx, s in enumerate(splits):
+                splits[idx] = ")".join(s.split(")")[1:])
+            summary = " ".join(splits)
+
+        # remove duplicated units in text
+        # TODO probably there's a lot more to add here....
+        replaces = {
+            "cm (centimeters)": "centimeters",
+            "cm³ (cubic centimeters)": "cubic centimeters",
+            "cm² (square centimeters)": "square centimeters",
+            "mm (millimeters)": "millimeters",
+            "mm² (square millimeters)": "square millimeters",
+            "mm³ (cubic millimeters)": "cubic millimeters",
+            "kg (kilograms)": "kilograms",
+            "kHz (kilohertz)": "kilohertz",
+            "ns (nanoseconds)": "nanoseconds",
+            "µs (microseconds)": "microseconds",
+            "m/s (meters per second)": "meters per second",
+            "km/s (kilometers per second)": "kilometers per second",
+            "mi/s (miles per second)": "miles per second",
+            "mph (miles per hour)": "miles per hour",
+            "ª (degrees)": " degrees"
+        }
+        for k, v in replaces.items():
+            summary = summary.replace(k, v)
+
+        # replace units, only if they are individual words
+        units = {
+            "cm": "centimeters",
+            "cm³": "cubic centimeters",
+            "cm²": "square centimeters",
+            "mm": "millimeters",
+            "mm²": "square millimeters",
+            "mm³": "cubic millimeters",
+            "kg": "kilograms",
+            "kHz": "kilohertz",
+            "ns": "nanoseconds",
+            "µs": "microseconds",
+            "m/s": "meters per second",
+            "km/s": "kilometers per second",
+            "mi/s": "miles per second",
+            "mph": "miles per hour"
+        }
+        words = [w if w not in units else units[w]
+                 for w in summary.split(" ")]
+        summary = " ".join(words)
+        return rm_parentheses(summary)
+
+
+class SearchWolframAlphaArgs(ToolArguments):
+    query: str = Field(..., description="The natural language or mathematical query to look up on Wolfram Alpha. Convert conversational phrasing to concise keywords (e.g. 'France population' not 'how many people live in France'). Always send in English.")
+    units: str = Field("metric", description="Unit system for the answer: 'metric' or 'imperial'.")
+
+
+class SearchWolframAlphaOutput(ToolOutput):
+    result: str = Field(..., description="The LLM-optimised Wolfram Alpha answer for the query.")
+
+
+class WolframAlphaToolbox(ToolBox):
+    toolbox_id = "ovos-wolfram-alpha-tools"
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Initialise the toolbox.
+
+        Args:
+            config: Plugin configuration dict.
+        """
+        self.config = config or {}
+        self.api = WolframAlphaApi(key=self.config.get("appid") or "Y7R353-9HQAAL8KKA")
+        super().__init__(toolbox_id=self.toolbox_id)
+
+    def search_wolfram(self, args: SearchWolframAlphaArgs) -> SearchWolframAlphaOutput:
+        """Query Wolfram Alpha and return the LLM-optimised answer."""
+        return SearchWolframAlphaOutput(
+            result=self.api.llm(query=args.query, units=args.units)
+        )
+
+    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_wolfram_alpha",
+                description=(
+                    "Query Wolfram Alpha for factual answers: maths, science, unit conversions, "
+                    "geography, history, and more. Always send queries in English as concise keywords."
+                ),
+                argument_schema=SearchWolframAlphaArgs,
+                output_schema=SearchWolframAlphaOutput,
+                tool_call=self.search_wolfram,
+            )
+        ]
+
+
+if __name__ == "__main__":
+    s = WolframAlphaRetrievalEngine()
+    print(s.api.spoken("Who is the author of The Fault in our Stars"))

ovos_wolfram_alpha_plugin-1.0.0a1/ovos_wolfram_alpha_plugin/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_wolfram_alpha_plugin-1.0.0a1/ovos_wolfram_alpha_plugin.egg-info/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: ovos-wolfram-alpha-plugin
+Version: 1.0.0a1
+Summary: ovos wolfram-alpha plugin
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-wolfram-alpha-plugin
+Keywords: ovos,plugin,wolfram
+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-config<2.0.0,>=0.0.12
+Requires-Dist: requests>=2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+
+# ovos-wolfram-alpha-plugin
+
+[![PyPI](https://img.shields.io/pypi/v/ovos-wolfram-alpha-plugin)](https://pypi.org/project/ovos-wolfram-alpha-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/)
+
+[Wolfram Alpha](https://www.wolframalpha.com/) 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.
+
+Wolfram Alpha excels at questions with a single definitive answer: maths, unit conversions, scientific constants, chemical properties, astronomy, nutrition, geography, and historical dates. It is not a search engine — it computes answers from curated data.
+
+An [API key](https://products.wolframalpha.com/api/) is required. A demo key is bundled for development but is rate-limited and should not be used in production.
+
+---
+
+## Installation
+
+```bash
+pip install ovos-wolfram-alpha-plugin
+```
+
+---
+
+## OPM Entry Points
+
+| Entry point | Class | Use case |
+|---|---|---|
+| `opm.agents.retrieval` — `ovos-wolfram-alpha-solver` | `WolframAlphaRetrievalEngine` | RAG — returns `(answer, score)` tuples |
+| `opm.agents.toolbox` — `ovos-wolfram-alpha-tools` | `WolframAlphaToolbox` | Agent tool use — exposes `search_wolfram_alpha` |
+
+---
+
+## Retrieval Engine
+
+`WolframAlphaRetrievalEngine` implements the `RetrievalEngine` OPM interface. It calls the Wolfram Alpha spoken-answer endpoint and handles non-English queries by translating them to English before the request and back after.
+
+```python
+from ovos_wolfram_alpha_plugin import WolframAlphaRetrievalEngine
+
+engine = WolframAlphaRetrievalEngine(config={"appid": "YOUR-KEY"})
+
+# Maths & conversions
+engine.get_spoken_answer("integral of x^2 sin(x)", lang="en")
+# "x^2 (-cos(x)) + 2 x sin(x) + 2 cos(x) + constant"
+
+engine.get_spoken_answer("100 miles in kilometers", lang="en")
+# "160.934 kilometers"
+
+engine.get_spoken_answer("1000 USD in EUR", lang="en")
+# "approximately 923 euros"  (live rate)
+
+# Science & constants
+engine.get_spoken_answer("speed of light", lang="en")
+# "about 2.998 × 10^8 meters per second"
+
+engine.get_spoken_answer("boiling point of ethanol", lang="en")
+# "78.37 degrees Celsius"
+
+engine.get_spoken_answer("distance from Earth to Mars", lang="en")
+# "currently about 1.69 AU"  (live ephemeris)
+
+# Factual lookups
+engine.get_spoken_answer("population of Brazil", lang="en")
+# "approximately 215.3 million people"
+
+engine.get_spoken_answer("calories in 100g of almonds", lang="en")
+# "579 kilocalories"
+
+engine.get_spoken_answer("when was the Eiffel Tower built", lang="en")
+# "construction was from January 28, 1887 to March 31, 1889"
+
+# Non-English — translated automatically
+engine.get_spoken_answer("massa do Sol", lang="pt")
+# "aproximadamente 1,989 × 10^30 kg"
+
+# Image result — returns a local file path to a Wolfram visual
+engine.get_image("benzene molecular structure", lang="en")
+
+# Full structured pod results — list of {"title", "summary"} dicts
+for pod in engine.get_expanded_answer("Neptune", lang="en"):
+    print(pod["title"], "—", pod.get("summary", pod.get("img")))
+# "Orbital period — 164.8 years"
+# "Surface gravity — 11.15 m/s²"
+# ...
+
+# RAG interface: List[Tuple[str, float]]  (answer, score)
+results = engine.query("half-life of carbon-14", lang="en")
+# [("5730 years", 0.9)]
+```
+
+### Translation
+
+Non-English queries require a translation plugin. Configure it by passing `translate_plugin` in the config:
+
+```python
+engine = WolframAlphaRetrievalEngine(config={
+    "appid": "YOUR-KEY",
+    "translate_plugin": "ovos-translate-plugin-server",
+})
+```
+
+If no translation plugin is available, only English queries are answered.
+
+---
+
+## Agent Toolbox
+
+`WolframAlphaToolbox` exposes a single `search_wolfram_alpha` tool that any OPM-compatible agent loop (e.g. [ovos-agentic-loop](https://github.com/OpenVoiceOS/ovos-agentic-loop)) can discover and call. The tool uses the LLM-optimised Wolfram endpoint, which returns a more structured answer than the spoken endpoint.
+
+### Persona JSON
+
+Reference the toolbox by its entry point name inside any agentic persona. Pass a `system_prompt` to the brain plugin so the LLM knows how to query Wolfram correctly:
+
+```json
+{
+  "name": "Wolfram Alpha",
+  "solvers": ["ovos-react-loop"],
+  "ovos-react-loop": {
+    "brain": "ovos-chat-openai-plugin",
+    "toolboxes": ["ovos-wolfram-alpha-tools"],
+    "ovos-chat-openai-plugin": {
+      "api_url": "http://localhost:11434/v1/chat/completions",
+      "system_prompt": "You have access to Wolfram Alpha. Use it for maths, science, unit conversions, and factual questions with a definite answer. Always send queries in English as concise keywords (e.g. 'France population', not 'how many people live in France'). Use the exponent notation 6*10^14, never 6e14. If the result is not relevant, retry with a more specific query rather than rephrasing."
+    }
+  }
+}
+```
+
+> 💡 The [official LLM API docs](https://products.wolframalpha.com/llm-api/documentation) have more tips on writing effective Wolfram system prompts.
+
+### Direct usage
+
+```python
+from ovos_wolfram_alpha_plugin import WolframAlphaToolbox, SearchWolframAlphaArgs
+
+tb = WolframAlphaToolbox(config={"appid": "YOUR-KEY"})
+
+tools = tb.discover_tools()
+# [AgentTool(name="search_wolfram_alpha", ...)]
+
+output = tb.search_wolfram(SearchWolframAlphaArgs(query="France population", units="metric"))
+print(output.result)
+```
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

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

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

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,5 @@
+[opm.agents.retrieval]
+ovos-wolfram-alpha-plugin = ovos_wolfram_alpha_plugin:WolframAlphaRetrievalEngine
+
+[opm.agents.toolbox]
+ovos-wolfram-alpha-tools = ovos_wolfram_alpha_plugin:WolframAlphaToolbox

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

@@ -0,0 +1,5 @@
+ovos-utils<1.0.0,>=0.7.0
+ovos-plugin-manager<3.0.0,>=2.3.0a1
+ovos-config<2.0.0,>=0.0.12
+requests>=2.0.0
+pydantic<3.0.0,>=2.0.0

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

@@ -0,0 +1 @@
+ovos_wolfram_alpha_plugin

ovos_wolfram_alpha_plugin-1.0.0a1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ovos-wolfram-alpha-plugin"
+dynamic = ["version"]
+description = "ovos wolfram-alpha plugin"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "JarbasAi", email = "jarbasai@mailfence.com"}
+]
+keywords = ["ovos", "plugin", "wolfram"]
+dependencies = [
+    "ovos-utils>=0.7.0,<1.0.0",
+    "ovos-plugin-manager>=2.3.0a1,<3.0.0",
+    "ovos-config>=0.0.12,<2.0.0",
+    "requests>=2.0.0",
+    "pydantic>=2.0.0,<3.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/OpenVoiceOS/ovos-wolfram-alpha-plugin"
+
+[project.entry-points."opm.agents.retrieval"]
+"ovos-wolfram-alpha-plugin" = "ovos_wolfram_alpha_plugin:WolframAlphaRetrievalEngine"
+
+[project.entry-points."opm.agents.toolbox"]
+"ovos-wolfram-alpha-tools" = "ovos_wolfram_alpha_plugin:WolframAlphaToolbox"
+
+[tool.setuptools.dynamic]
+version = {attr = "ovos_wolfram_alpha_plugin.version.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["ovos_wolfram_alpha_plugin*"]

ovos_wolfram_alpha_plugin-1.0.0a1/setup.cfg

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

ovos_wolfram_alpha_plugin-1.0.0a1/tests/test_wolfram_alpha.py

@@ -0,0 +1,196 @@
+"""
+Unit tests for ovos-wolfram-alpha-plugin.
+
+All network calls and OVOS config are mocked — no API key or daemon required.
+"""
+import unittest
+from unittest.mock import MagicMock, patch, mock_open
+
+from ovos_wolfram_alpha_plugin import (
+    WolframAlphaApi,
+    WolframAlphaRetrievalEngine,
+    WolframAlphaToolbox,
+    SearchWolframAlphaArgs,
+    SearchWolframAlphaOutput,
+)
+
+
+# ---------------------------------------------------------------------------
+# WolframAlphaApi
+# ---------------------------------------------------------------------------
+
+class TestWolframAlphaApi(unittest.TestCase):
+
+    def setUp(self):
+        self.api = WolframAlphaApi(key="TEST-KEY")
+
+    def test_key_stored(self):
+        self.assertEqual(self.api.key, "TEST-KEY")
+
+    def test_default_key_used_when_falsy(self):
+        api = WolframAlphaApi(key=None)
+        self.assertEqual(api.key, "Y7R353-9HQAAL8KKA")
+
+    def _mock_get(self, text="answer"):
+        m = MagicMock()
+        m.text = text
+        m.content = b"imagedata"
+        return m
+
+    def test_spoken_returns_text(self):
+        with patch("ovos_wolfram_alpha_plugin.requests.get") as mock_get:
+            mock_get.return_value = self._mock_get("The speed of light is 3×10^8 m/s.")
+            result = self.api.spoken("speed of light", lat_lon=(0, 0))
+        self.assertEqual(result, "The speed of light is 3×10^8 m/s.")
+
+    def test_llm_returns_text(self):
+        with patch("ovos_wolfram_alpha_plugin.requests.get") as mock_get:
+            mock_get.return_value = self._mock_get("42")
+            result = self.api.llm("meaning of life", lat_lon=(0, 0))
+        self.assertEqual(result, "42")
+
+    def test_full_results_returns_json(self):
+        payload = {"queryresult": {"pods": []}}
+        with patch("ovos_wolfram_alpha_plugin.requests.get") as mock_get:
+            mock_get.return_value.json.return_value = payload
+            result = self.api.full_results("mercury", lat_lon=(0, 0))
+        self.assertEqual(result, payload)
+
+    def test_get_image_writes_file_on_miss(self):
+        with patch("ovos_wolfram_alpha_plugin.isfile", return_value=False), \
+             patch("ovos_wolfram_alpha_plugin.requests.get") as mock_get, \
+             patch("builtins.open", mock_open()) as mocked_open:
+            mock_get.return_value.content = b"gif"
+            path = self.api.get_image("mercury")
+        self.assertTrue(path.endswith(".gif"))
+        mocked_open.assert_called_once()
+
+    def test_get_image_skips_download_on_hit(self):
+        with patch("ovos_wolfram_alpha_plugin.isfile", return_value=True), \
+             patch("ovos_wolfram_alpha_plugin.requests.get") as mock_get:
+            self.api.get_image("mercury")
+        mock_get.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# WolframAlphaRetrievalEngine
+# ---------------------------------------------------------------------------
+
+class TestWolframAlphaRetrievalEngine(unittest.TestCase):
+
+    def _make_engine(self):
+        with patch("ovos_wolfram_alpha_plugin.load_tx_plugin", return_value=None), \
+             patch("ovos_wolfram_alpha_plugin.Configuration", return_value={}):
+            return WolframAlphaRetrievalEngine(config={"appid": "TEST"})
+
+    def test_query_returns_answer_and_score(self):
+        engine = self._make_engine()
+        engine.get_spoken_answer = MagicMock(return_value="Venus is the second planet.")
+        with patch("ovos_wolfram_alpha_plugin.Configuration", return_value={}):
+            result = engine.query("venus", lang="en")
+        self.assertEqual(result, [("Venus is the second planet.", 0.9)])
+
+    def test_query_returns_empty_when_no_answer(self):
+        engine = self._make_engine()
+        engine.get_spoken_answer = MagicMock(return_value=None)
+        with patch("ovos_wolfram_alpha_plugin.Configuration", return_value={}):
+            result = engine.query("xyzzy", lang="en")
+        self.assertEqual(result, [])
+
+    def test_get_spoken_answer_filters_bad_responses(self):
+        engine = self._make_engine()
+        engine.api = MagicMock()
+        engine.api.spoken.return_value = "Wolfram Alpha did not understand your input"
+        with patch("ovos_wolfram_alpha_plugin.Configuration", return_value={}):
+            result = engine.get_spoken_answer("gibberish", lang="en")
+        self.assertIsNone(result)
+
+    def test_get_spoken_answer_returns_answer_for_english(self):
+        engine = self._make_engine()
+        engine.api = MagicMock()
+        engine.api.spoken.return_value = "Mercury is the smallest planet."
+        with patch("ovos_wolfram_alpha_plugin.Configuration", return_value={}):
+            result = engine.get_spoken_answer("mercury", lang="en")
+        self.assertEqual(result, "Mercury is the smallest planet.")
+
+    def test_get_spoken_answer_translates_non_english(self):
+        engine = self._make_engine()
+        engine.translator = MagicMock()
+        engine.translator.translate.side_effect = lambda q, target, source: f"[{target}]{q}"
+        engine.api = MagicMock()
+        engine.api.spoken.return_value = "Mercury is a planet."
+        with patch("ovos_wolfram_alpha_plugin.Configuration", return_value={}):
+            result = engine.get_spoken_answer("mercúrio", lang="pt")
+        self.assertIn("pt", result)
+
+
+# ---------------------------------------------------------------------------
+# make_speakable
+# ---------------------------------------------------------------------------
+
+class TestMakeSpeakable(unittest.TestCase):
+
+    def test_removes_human_parenthetical(self):
+        text = "The height is 1.8 m (human: 5 ft 11 in)"
+        result = WolframAlphaRetrievalEngine.make_speakable(text)
+        self.assertNotIn("human:", result)
+
+    def test_expands_unit_abbreviation(self):
+        result = WolframAlphaRetrievalEngine.make_speakable("mass is 5 kg")
+        self.assertIn("kilograms", result)
+
+    def test_expands_cm_unit(self):
+        result = WolframAlphaRetrievalEngine.make_speakable("height 180 cm")
+        self.assertIn("centimeters", result)
+
+    def test_noop_on_plain_text(self):
+        text = "The answer is forty-two."
+        result = WolframAlphaRetrievalEngine.make_speakable(text)
+        self.assertEqual(result, text)
+
+
+# ---------------------------------------------------------------------------
+# WolframAlphaToolbox
+# ---------------------------------------------------------------------------
+
+class TestWolframAlphaToolbox(unittest.TestCase):
+
+    def _make_toolbox(self):
+        with patch("ovos_wolfram_alpha_plugin.WolframAlphaApi"):
+            return WolframAlphaToolbox(config={"appid": "TEST"})
+
+    def test_discover_tools_returns_one_tool(self):
+        tb = self._make_toolbox()
+        tools = tb.discover_tools()
+        self.assertEqual(len(tools), 1)
+        self.assertEqual(tools[0].name, "search_wolfram_alpha")
+
+    def test_search_wolfram_returns_output(self):
+        tb = self._make_toolbox()
+        tb.api = MagicMock()
+        tb.api.llm.return_value = "42"
+        args = SearchWolframAlphaArgs(query="meaning of life", units="metric")
+        result = tb.search_wolfram(args)
+        self.assertIsInstance(result, SearchWolframAlphaOutput)
+        self.assertEqual(result.result, "42")
+
+    def test_toolbox_id(self):
+        self.assertEqual(WolframAlphaToolbox.toolbox_id, "ovos-wolfram-alpha-tools")
+
+
+# ---------------------------------------------------------------------------
+# Plugin loading
+# ---------------------------------------------------------------------------
+
+class TestPluginLoading(unittest.TestCase):
+
+    def test_imports(self):
+        from ovos_wolfram_alpha_plugin import (
+            WolframAlphaApi,
+            WolframAlphaRetrievalEngine,
+            WolframAlphaToolbox,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()