ovos-wolfram-alpha-plugin

Wolfram Alpha integration for OpenVoiceOS. 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 is required. A demo key is bundled for development but is rate-limited and should not be used in production.

Installation

pip install ovos-wolfram-alpha-plugin

OPM Entry Points

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.

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:

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) 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:

{
  "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."
    }
  }
}

See the official LLM API docs for more tips on writing effective Wolfram system prompts.

Direct usage

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)

Related projects

• OpenVoiceOS/ovos-skill-wolfie — a voice skill that wires WolframAlphaRetrievalEngine into the OVOS intent, Common Query, and fallback pipelines.
• OpenVoiceOS/ovos-agentic-loop — an agent loop that can discover and call the WolframAlphaToolbox tool.

Docker

This repo publishes ghcr.io/openvoiceos/ovos-wolfram-alpha-plugin, a standalone ovos-persona-server that serves one persona, WolframBot, backed by the WolframAlphaRetrievalEngine in this plugin. Every query hits api.wolframalpha.com and needs an appid. If you do not set one, the container falls back to the demo appid bundled in this plugin, so it works with no configuration at all. That demo key is shared by every user of this plugin and is rate limited -- fine to try the image out, not fine for real traffic. Get your own free appid from the Wolfram developer portal and pass it as WOLFRAM_APPID:

docker run -p 8392:8337 -e WOLFRAM_APPID=your-appid-here \
    ghcr.io/openvoiceos/ovos-wolfram-alpha-plugin:dev

curl http://localhost:8392/v1/models
curl http://localhost:8392/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model": "WolframBot", "messages": [{"role": "user", "content": "distance from earth to the moon"}]}'

Known issue as of ovos-persona 0.9.0a9 through 0.9.0a16 (the latest published alpha): Persona.chat passes sess.lang and sess.system_unit into chat_completion in the wrong order, so the retrieval engine receives the unit string ("metric") where it expects a language code, and the request above answers 500 Internal Server Error with Persona chat failed: 'NoneType' object has no attribute 'split'. This is a bug in ovos-persona itself, not in this plugin or this image -- calling WolframAlphaRetrievalEngine().query(...) directly, with the bundled demo key, returns a correct answer. It will clear up once a fixed ovos-persona is published; there is nothing to configure around it from this image.

A compose snippet:

services:
  ovos-wolfram-persona:
    image: ghcr.io/openvoiceos/ovos-wolfram-alpha-plugin:dev
    ports:
      - "8392:8337"
    environment:
      - WOLFRAM_APPID=your-appid-here
    restart: unless-stopped

The image builds on every pull request touching Dockerfile, entrypoint.sh, .dockerignore, pyproject.toml, or the docker workflow itself (build only, no push), and publishes on pushes to master (latest), dev (dev), and version tags. See the docker workflow.

License

Apache 2.0. See LICENSE.