Resolve capability-table path through Galaxy's config system

The original loader walked CWD-relative paths and an `__file__`-derived
sample path -- both fragile under Galaxy's various install shapes (per
John's review on #22609: package installs flatten the tree, CWD isn't
always the Galaxy root, and the existing config-resolution machinery is
the standard tool for this).

Introduce ``agent_model_capabilities_file`` as a first-class config
option with ``path_resolves_to: config_dir`` and add it to
``add_sample_file_to_defaults`` so Galaxy's own config loader resolves
it the same way it does ``tool_data_table_config_path`` and friends:
admin override in ``config_dir`` if present, otherwise the shipped
sample under ``sample_config_dir``. The agents code just reads
``config.agent_model_capabilities_file`` and feeds the result into
``_load_model_capabilities()``, which is now per-path-keyed in its
cache and falls back to the built-in defaults when the path is
missing, unset, or unparseable.

The schema description for ``inference_services`` no longer duplicates
the capability-table prose -- it points at the new option instead.
``galaxy.yml.sample`` was regenerated via ``make config-rebuild``.

Author: dannon

lib/galaxy/agents/base.py

@@ -108,57 +108,45 @@
     "default": {"structured_output": True},
 }
 
-# Search order for the capability table. First hit wins.
-_MODEL_CAPABILITIES_BASENAME = "agent_model_capabilities.yml"
-_MODEL_CAPABILITIES_SEARCH_PATHS = (
-    # Admin-edited copy in the runtime config directory.
-    os.path.join("config", _MODEL_CAPABILITIES_BASENAME),
-    # The shipped sample (what most installs will end up reading).
-    os.path.join(
-        os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
-        "config",
-        "sample",
-        _MODEL_CAPABILITIES_BASENAME + ".sample",
-    ),
-    os.path.join("config", _MODEL_CAPABILITIES_BASENAME + ".sample"),
-)
-
-_model_capabilities_cache: Optional[dict[str, Any]] = None
+_model_capabilities_cache: dict[str, dict[str, Any]] = {}
 
 
-def _load_model_capabilities(force_reload: bool = False) -> dict[str, Any]:
-    """Return the parsed model-capabilities table, loading it on first use.
+def _load_model_capabilities(path: Optional[str], force_reload: bool = False) -> dict[str, Any]:
+    """Return the parsed model-capabilities table for ``path``.
 
-    Looks at a small set of standard locations and parses the first one that
-    exists. Falls back to a sane hardcoded default if nothing is found or the
-    file fails to parse -- we'd rather keep agents working than block on a
-    missing config file.
+    ``path`` should come from ``config.agent_model_capabilities_file``, which
+    Galaxy resolves at startup (admin override in ``config_dir`` if present,
+    otherwise the shipped sample under ``sample_config_dir``). Falls back to a
+    sane hardcoded default when the input is missing, not a string, or points
+    at a file we can't parse -- we'd rather keep agents working than block on
+    a misconfigured deployment.
     """
-    global _model_capabilities_cache
-    if _model_capabilities_cache is not None and not force_reload:
-        return _model_capabilities_cache
+    if not isinstance(path, str) or not path:
+        return _DEFAULT_MODEL_CAPABILITIES
 
-    for path in _MODEL_CAPABILITIES_SEARCH_PATHS:
-        if not os.path.exists(path):
-            continue
-        try:
-            with open(path) as fh:
-                parsed = yaml.safe_load(fh) or {}
-        except (OSError, yaml.YAMLError) as exc:
-            log.warning("Could not parse model capabilities at %s: %s", path, exc)
-            continue
-        if not isinstance(parsed, dict):
-            log.warning("Ignoring model capabilities at %s: not a mapping", path)
-            continue
-        _model_capabilities_cache = parsed
-        return _model_capabilities_cache
+    if not force_reload and path in _model_capabilities_cache:
+        return _model_capabilities_cache[path]
 
-    log.warning(
-        "Model capabilities file not found (looked in %s); falling back to built-in defaults.",
-        ", ".join(_MODEL_CAPABILITIES_SEARCH_PATHS),
-    )
-    _model_capabilities_cache = _DEFAULT_MODEL_CAPABILITIES
-    return _model_capabilities_cache
+    if not os.path.exists(path):
+        log.warning("Model capabilities file not found at %s; using built-in defaults.", path)
+        _model_capabilities_cache[path] = _DEFAULT_MODEL_CAPABILITIES
+        return _DEFAULT_MODEL_CAPABILITIES
+
+    try:
+        with open(path) as fh:
+            parsed = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError) as exc:
+        log.warning("Could not parse model capabilities at %s: %s; using built-in defaults.", path, exc)
+        _model_capabilities_cache[path] = _DEFAULT_MODEL_CAPABILITIES
+        return _DEFAULT_MODEL_CAPABILITIES
+
+    if not isinstance(parsed, dict):
+        log.warning("Ignoring model capabilities at %s: not a mapping; using built-in defaults.", path)
+        _model_capabilities_cache[path] = _DEFAULT_MODEL_CAPABILITIES
+        return _DEFAULT_MODEL_CAPABILITIES
+
+    _model_capabilities_cache[path] = parsed
+    return parsed
 
 
 def _capability_for_model(model_name: str, capability: str, table: dict[str, Any]) -> Optional[bool]:
@@ -693,15 +681,18 @@ def _supports_structured_output(self) -> bool:
         Resolution order:
           1. Agent-specific ``structured_output_override`` in inference_services
           2. Global ``default.structured_output_override`` in inference_services
-          3. Glob match against the admin capability table, or shipped sample
-          4. The selected table's ``default`` block (true if absent)
+          3. Glob match in the capability table at ``config.agent_model_capabilities_file``
+             (Galaxy resolves this to the admin override in ``config_dir`` if present,
+             otherwise the shipped sample under ``sample_config_dir``)
+          4. The capability table's ``default`` block (true if absent)
         """
         override = self._get_agent_config("structured_output_override")
         if override is not None:
             return bool(override)
 
         model_name = self._get_agent_config("model", "")
-        capability = _capability_for_model(model_name, "structured_output", _load_model_capabilities())
+        capabilities_path = getattr(self.deps.config, "agent_model_capabilities_file", None)
+        capability = _capability_for_model(model_name, "structured_output", _load_model_capabilities(capabilities_path))
         if capability is None:
             return True
         return capability

lib/galaxy/config/__init__.py

@@ -725,6 +725,7 @@ class GalaxyAppConfiguration(BaseAppConfiguration, CommonConfigurationMixin):
     }
 
     add_sample_file_to_defaults = {
+        "agent_model_capabilities_file",
         "build_sites_config_file",
         "datatypes_config_file",
         "tool_data_table_config_path",

lib/galaxy/config/sample/galaxy.yml.sample

@@ -3040,14 +3040,23 @@ galaxy:
   # path to replace all LLM calls with deterministic responses for
   # testing: inference_services: { static_responses:
   # test/integration/static_agents.yml } Per-agent or default-block
-  # ``structured_output_override: true|false`` beats the model capability
-  # table. Admins can place overrides in config/agent_model_capabilities.yml;
-  # otherwise Galaxy reads the shipped sample from
-  # lib/galaxy/config/sample/agent_model_capabilities.yml.sample. The table is
-  # consulted to decide whether the configured model can produce tool-calling /
-  # JSON-mode output.
+  # ``structured_output_override: true|false`` beats the model
+  # capability table -- see ``agent_model_capabilities_file`` for the
+  # table's location and contents.
   #inference_services: null
 
+  # YAML file with capability hints for agent inference models. Maps
+  # fnmatch-style globs against model names to features such as
+  # structured-output (tool-calling / JSON-mode) support. Galaxy ships a
+  # sample populated with common model families; admins can drop a file
+  # named ``agent_model_capabilities.yml`` in ``config_dir`` to override
+  # the shipped table for private models. ``inference_services``
+  # ``structured_output_override`` overrides this table for a specific
+  # agent or default block.
+  # The value of this option will be resolved with respect to
+  # <config_dir>.
+  #agent_model_capabilities_file: agent_model_capabilities.yml
+
   # Allow the display of tool recommendations in workflow editor and
   # after tool execution. If it is enabled and set to true, please
   # enable 'tool_recommendation_model_path' as well

lib/galaxy/config/schemas/config_schema.yml

@@ -4148,11 +4148,23 @@ mapping:
           deterministic responses for testing:
           inference_services: { static_responses: test/integration/static_agents.yml }
           Per-agent or default-block ``structured_output_override: true|false``
-          beats the model capability table. Admins can place overrides in
-          config/agent_model_capabilities.yml; otherwise Galaxy reads the
-          shipped sample from lib/galaxy/config/sample/agent_model_capabilities.yml.sample.
-          The table is consulted to decide whether the configured model can
-          produce tool-calling / JSON-mode output.
+          beats the model capability table -- see ``agent_model_capabilities_file``
+          for the table's location and contents.
+
+      agent_model_capabilities_file:
+        type: str
+        default: agent_model_capabilities.yml
+        path_resolves_to: config_dir
+        required: false
+        desc: |
+          YAML file with capability hints for agent inference models. Maps
+          fnmatch-style globs against model names to features such as
+          structured-output (tool-calling / JSON-mode) support. Galaxy ships a
+          sample populated with common model families; admins can drop a file
+          named ``agent_model_capabilities.yml`` in ``config_dir`` to override
+          the shipped table for private models. ``inference_services``
+          ``structured_output_override`` overrides this table for a specific
+          agent or default block.
 
       enable_tool_recommendations:
         type: bool

test/unit/app/test_agents.py

@@ -76,6 +76,15 @@ def setup_method(self):
         self.mock_config.ai_api_key = "test-key"
         self.mock_config.ai_model = "llama-4-scout"
         self.mock_config.ai_api_base_url = "http://localhost:4000/v1/"
+        # Point at the shipped capability sample so _supports_structured_output
+        # exercises the real table rather than the built-in fallback.
+        self.mock_config.agent_model_capabilities_file = os.path.join(
+            os.path.dirname(agents_base.__file__),
+            "..",
+            "config",
+            "sample",
+            "agent_model_capabilities.yml.sample",
+        )
 
         self.mock_user = mock.Mock()
         self.mock_user.id = 1
@@ -870,7 +879,7 @@ def test_supports_structured_output_falls_back_to_default(self):
 
     def test_capability_table_glob_matching(self):
         """Globs should match wildcard suffixes (e.g. gpt-4-turbo)."""
-        table = _load_model_capabilities()
+        table = _load_model_capabilities(self.mock_config.agent_model_capabilities_file)
         assert _capability_for_model("gpt-4-turbo", "structured_output", table) is True
         assert _capability_for_model("gpt-4o-mini", "structured_output", table) is True
         assert _capability_for_model("claude-3-5-sonnet", "structured_output", table) is True
@@ -881,20 +890,17 @@ def test_capability_table_glob_matching(self):
         assert _capability_for_model("deepseek-r1", "structured_output", table) is False
         assert _capability_for_model("deepseek-v3", "structured_output", table) is False
 
-    def test_capability_table_loads_with_missing_file(self, monkeypatch):
-        """Force every search path to miss; loader should warn and use defaults."""
-        monkeypatch.setattr(agents_base, "_MODEL_CAPABILITIES_SEARCH_PATHS", ())
-        monkeypatch.setattr(agents_base, "_model_capabilities_cache", None)
-
-        table = agents_base._load_model_capabilities(force_reload=True)
-
-        # Should be the hardcoded fallback.
+    def test_capability_table_falls_back_when_file_is_missing(self):
+        """Pointing at a non-existent path should fall back to the built-in defaults."""
+        table = _load_model_capabilities("/nonexistent/path/agent_model_capabilities.yml", force_reload=True)
         assert table is agents_base._DEFAULT_MODEL_CAPABILITIES
         assert _capability_for_model("deepseek-r1", "structured_output", table) is False
         assert _capability_for_model("gpt-4o", "structured_output", table) is True
 
-        # Reset cache so subsequent tests pick up the real file again.
-        monkeypatch.setattr(agents_base, "_model_capabilities_cache", None)
+    def test_capability_table_falls_back_when_path_is_unset(self):
+        """A None or non-string path (e.g. unset config option) yields the built-in defaults."""
+        assert _load_model_capabilities(None) is agents_base._DEFAULT_MODEL_CAPABILITIES
+        assert _load_model_capabilities("") is agents_base._DEFAULT_MODEL_CAPABILITIES
 
 
 @pytestmark_live_llm