Block raw calls for helper-covered endpoint families

_monty_codegen_shared.md

@@ -6,6 +6,7 @@
 - Use helper functions first. Use raw `call_api('/api/...')` only if no helper fits.
 - `call_api` must receive a raw path starting with `/api/...`; never call helper names through `call_api`.
 - `call_api(...)` returns `{ok, status, url, data, error}`. Always check `resp["ok"]` before reading `resp["data"]`. Do not read `resp["items"]` or `resp["meta"]` directly from `call_api(...)`.
+- Use `call_api(...)` only for endpoint families that do not already have a helper, such as `/api/daily_papers` or tag metadata endpoints.
 - Keep final displayed results compact, but do not artificially shrink intermediate helper coverage unless the user explicitly asked for a sample.
 - Prefer canonical snake_case keys in generated code and in JSON output.
 - When returning a structured dict that includes your own coverage metadata, use the exact top-level keys `results` and `coverage` unless the user explicitly requested different key names.

monty_api_tool_v2.py

@@ -295,6 +295,27 @@ HELPER_EXTERNALS = (
     "hf_collection_items",
 )
 
+HELPER_COVERED_ENDPOINT_PATTERNS: list[tuple[str, str]] = [
+    (r"^/api/whoami-v2$", "hf_whoami"),
+    (r"^/api/trending$", "hf_trending"),
+    (r"^/api/recent-activity$", "hf_recent_activity"),
+    (r"^/api/models$", "hf_repo_search"),
+    (r"^/api/datasets$", "hf_repo_search"),
+    (r"^/api/spaces$", "hf_repo_search"),
+    (r"^/api/(models|datasets|spaces)/[^/]+/[^/]+$", "hf_repo_details"),
+    (r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions$", "hf_repo_discussions"),
+    (r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+$", "hf_repo_discussion_details"),
+    (r"^/api/(models|datasets|spaces)/(?:[^/]+|[^/]+/[^/]+)/likers$", "hf_repo_likers"),
+    (r"^/api/users/[^/]+/likes$", "hf_user_likes"),
+    (r"^/api/users/[^/]+/(followers|following)$", "hf_user_graph"),
+    (r"^/api/organizations/[^/]+/members$", "hf_org_members"),
+    (r"^/api/organizations/[^/]+/overview$", "hf_org_overview"),
+    (r"^/api/organizations/[^/]+/followers$", "hf_user_graph"),
+    (r"^/api/collections$", "hf_collections_search"),
+    (r"^/api/collections/[^/]+$", "hf_collection_items"),
+    (r"^/api/collections/[^/]+/[^/]+$", "hf_collection_items"),
+]
+
 
 def _resolve_helper_functions(namespace: dict[str, Any]) -> dict[str, Callable[..., Any]]:
     resolved: dict[str, Callable[..., Any]] = {}
@@ -943,6 +964,12 @@ def _validate_generated_code(code: str) -> None:
     if not valid_final_await:
         raise ValueError("Generated code must end with `await solve(query, max_calls)`.")
 
+    def _preferred_helper_for_endpoint(endpoint: str) -> str | None:
+        for pattern, helper_name in HELPER_COVERED_ENDPOINT_PATTERNS:
+            if re.match(pattern, endpoint):
+                return helper_name
+        return None
+
     def _call_api_endpoint_hint(expr: ast.AST | None) -> str | None:
         if isinstance(expr, ast.Constant) and isinstance(expr.value, str):
             return expr.value
@@ -971,6 +998,10 @@ def _validate_generated_code(code: str) -> None:
         endpoint_hint = _call_api_endpoint_hint(endpoint_expr)
         if endpoint_hint and "/api/collections/" in endpoint_hint and "/items" in endpoint_hint:
             raise ValueError("Use `hf_collection_items(...)` for collection contents instead of guessing `/api/collections/.../items`.")
+        if endpoint_hint:
+            preferred_helper = _preferred_helper_for_endpoint(endpoint_hint)
+            if preferred_helper is not None:
+                raise ValueError(f"Use `{preferred_helper}(...)` instead of `call_api({endpoint_hint!r}, ...)` for this endpoint family.")
 
     allowed_external_calls = ["call_api(", *[f"{name}(" for name in HELPER_EXTERNALS]]
     if not any(token in code for token in allowed_external_calls):
@@ -990,6 +1021,9 @@ def _validate_generated_code(code: str) -> None:
             raise ValueError("Do not call helper names through call_api; call hf_* helpers directly.")
         if re.match(r"^/api/collections/(?:[^/]+/)?[^/]+/items$", endpoint_literal):
             raise ValueError("Use `hf_collection_items(...)` for collection contents instead of guessing `/api/collections/.../items`.")
+        preferred_helper = _preferred_helper_for_endpoint(endpoint_literal)
+        if preferred_helper is not None:
+            raise ValueError(f"Use `{preferred_helper}(...)` instead of `call_api({endpoint_literal!r}, ...)` for this endpoint family.")
         if not endpoint_literal.startswith("/api/"):
             raise ValueError("call_api endpoint must be a raw path starting with '/api/...'.")