tools.wolfram_alpha module

Query Wolfram|Alpha via the LLM API.

Uses https://www.wolframalpha.com/api/v1/llm-api which returns plain-text results optimised for consumption by large language models. Resolve the App ID via per-user key, WOLFRAM_ALPHA_APP_ID env var, or api_keys.wolfram_alpha in config.yaml.

Optional: set WOLFRAM_ALPHA_USE_BEARER_AUTH=1 to send the App ID in the Authorization: Bearer header instead of the appid query parameter.

async tools.wolfram_alpha.run(query, maxchars=None, units=None, timeout=None, assumptions=None, languagecode=None, location=None, timezone=None, latlong=None, countrycode=None, currency=None, ip=None, scantimeout=None, formattimeout=None, parsetimeout=None, width=None, maxwidth=None, plotwidth=None, mag=None, ctx=None)[source]

Execute a Wolfram|Alpha LLM-API query and return a JSON-encoded result.

Entry point for the wolfram_alpha_query tool. Validates the query, resolves the App ID, builds the request parameters, performs an async HTTP GET against the Wolfram|Alpha LLM API, and serialises either the plain-text answer or a structured error to a JSON string. HTTP error statuses are mapped to friendly messages (501 = uninterpretable input, 403 = bad App ID, 400 = missing input, other = generic), and network/unexpected failures are caught and returned as error payloads rather than raised.

Resolves credentials via _resolve_app_id() (which checks the per-user key in Redis, the WOLFRAM_ALPHA_APP_ID env var, then config), normalises the query with _normalize_query_input(), chooses the auth scheme with _use_bearer_auth(), and constructs the query pairs with _build_query_pairs(). It opens an aiohttp.ClientSession to call LLM_API_URL, logs request/response activity, and on any non-200 status fires a fire-and-forget observability event through _emit_error_event(). When no App ID can be resolved it returns missing_api_key_error("wolfram_alpha") from tools.manage_api_keys.

This is invoked by the generic tool dispatcher in tool_loader.py (which locates the module’s run attribute via getattr(module, "run")) and directly by the tool’s tests in tests/test_wolfram_alpha_tool.py.

Parameters:

  • query (str) – Natural-language Wolfram|Alpha input; required and must be non-blank.

  • maxchars (int | None) – Max characters in the response (clamped 500-32000).

  • units (str | None) – Unit system, metric or imperial.

  • timeout (int | None) – Maps to Wolfram’s totaltimeout; bounded to [5, 30] seconds, defaulting to DEFAULT_TIMEOUT.

  • assumptions (list[str] | None) – Disambiguation tokens for re-tries.

  • languagecode (str | None) – Response language code.

  • location (str | None) – Location hint for locale-aware results.

  • timezone (str | None) – Timezone hint.

  • latlong (str | None) – lat,long geo hint.

  • countrycode (str | None) – Country code for regional defaults.

  • currency (str | None) – Preferred currency for financial queries.

  • ip (str | None) – Client IP hint for geolocation.

  • scantimeout (int | None) – Scan-phase timeout in seconds (1-120).

  • formattimeout (int | None) – Format-phase timeout in seconds (1-120).

  • parsetimeout (int | None) – Parse-phase timeout in seconds (1-120).

  • width (int | None) – Plot/image width hint (1-2048).

  • maxwidth (int | None) – Max width hint (1-2048).

  • plotwidth (int | None) – Plot width hint (1-2048).

  • mag (str | None) – Magnification string.

  • ctx (ToolContext | None) – Tool context supplying redis, user_id, channel_id, and config for per-user App ID resolution; may be None (falls back to env/config credentials).

Returns:

A JSON string. On success it contains query and answer; on failure it contains an error field (plus http_status and optional detail/suggestions for HTTP errors).

Return type:

str