doctor: per-toolset hint for unavailable multi-provider toolsets (#40)#41
Merged
Conversation
Surveying image_gen + video_gen plugins for diagnostic-loudness
gaps. Found a real one in the Tool Availability section.
video_generation_tool.py + image_generation_tool register with
requires_env=[] because the toolset is multi-provider (any of
FAL, xAI, OpenAI works). When no provider is configured, doctor's
unavailable loop falls through to `(system dependency not met)`
— accurate but unhelpful: operators have to grep the plugin docs
to learn which env var would unblock them.
Add `_doctor_tool_unavailable_detail(toolset) -> str`, parallel to
the existing `_doctor_tool_availability_detail`. Returns per-toolset
hints:
image_gen → "no image-gen provider configured — set
OPENAI_API_KEY, XAI_API_KEY, or use OpenAI Codex
OAuth (see `hermes tools`)"
video_gen → "no video-gen provider configured — set FAL_KEY,
XAI_API_KEY, or use xAI OAuth (see `hermes tools`)"
The unavailable loop prefers this when no explicit `requires_env`
to surface. Falls back to "(system dependency not met)" for any
toolset without an entry.
Tests:
- image_gen hint mentions OPENAI_API_KEY + XAI_API_KEY + OAuth.
- video_gen hint mentions FAL_KEY + XAI_API_KEY.
- Unknown toolsets return ""; the doctor loop falls back to the
generic line.
68 doctor-tests pass — no regression.
Closes #40.
2 tasks
PowerCreek
added a commit
that referenced
this pull request
May 23, 2026
After shipping the image_gen / video_gen hint in #41 / #40, the parallel gap exists for the web toolset — same shape: multi-provider, registered with requires_env=[]. Without any provider configured + ddgs not installed, doctor previously said "(system dependency not met)" — accurate but unhelpful. Add a "web" entry to _doctor_tool_unavailable_detail listing the alternative env vars: TAVILY_API_KEY, BRAVE_SEARCH_API_KEY, EXA_API_KEY, FIRECRAWL_API_KEY, SEARXNG_URL — or `pip install ddgs` for the keyless DuckDuckGo backend. Calling out ddgs explicitly matters: it's the simplest unblock for operators on a lightweight install who don't want to deal with API keys at all. Everyone else picks their preferred paid / self-hosted provider from the list. Test mirrors the image_gen + video_gen pattern — asserts each env var appears in the hint plus the keyless ddgs callout.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #40. Surveying image_gen + video_gen plugins for diagnostic-loudness gaps. Found a real one in the Tool Availability section.
tools/video_generation_tool.py+tools/image_generation_tool.py(and similar) register withrequires_env=[]because the toolset is multi-provider (any of FAL, xAI, OpenAI works). When no provider is configured, doctor's unavailable loop falls through to(system dependency not met)— accurate but unhelpful. Operators have to grep the plugin docs to learn which env var would unblock them.Fix
Add
_doctor_tool_unavailable_detail(toolset) -> str, parallel to the existing_doctor_tool_availability_detail. Returns per-toolset hints:image_genno image-gen provider configured — set OPENAI_API_KEY, XAI_API_KEY, or use OpenAI Codex OAuth (see hermes tools)video_genno video-gen provider configured — set FAL_KEY, XAI_API_KEY, or use xAI OAuth (see hermes tools)The unavailable loop prefers this string when no explicit
requires_envto surface. Falls back to(system dependency not met)for any toolset without an entry — no regression for non-listed toolsets.Why not generalize at registry-level
A general "alternative env-var sets" declaration in the tool registry would let every multi-provider toolset describe its own fallback. That's a bigger registry-API change and not yet justified — only two such toolsets ship today (image_gen, video_gen). When a third lands, the generalization becomes worth the cost. Until then, two per-toolset rows in doctor are the minimum viable diagnostic.
Test plan
tests/hermes_cli/test_doctor.py::TestDoctorToolUnavailableDetail:image_genmentionsOPENAI_API_KEY,XAI_API_KEY, and OAuth fallbackvideo_genmentionsFAL_KEY,XAI_API_KEY""so doctor falls back to its generic linepytest tests/hermes_cli/test_doctor.py→ 68 passed (65 existing + 3 new).Filed by hermes-maintainer (PowerCreek).