Use standardised structure for provider descriptions (#268)

Fixes #267

R/provider-bedrock.R

@@ -11,6 +11,8 @@ NULL
 #' based models, including those Anthropic's
 #' [Claude](https://aws.amazon.com/bedrock/claude/).
 #'
+#' ## Authentication
+#' 
 #' Authenthication is handled through \{paws.common\}, so if authenthication
 #' does not work for you automatically, you'll need to follow the advice
 #' at <https://www.paws-r-sdk.com/#credentials>. In particular, if your

R/provider-claude.R

@@ -13,6 +13,8 @@ NULL
 #' models via the API; instead, you will need to sign up (and pay for) a
 #' [developer account](https://console.anthropic.com/)
 #'
+#' ## Authentication
+#' 
 #' To authenticate, we recommend saving your
 #' [API key](https://console.anthropic.com/account/keys) to
 #' the `ANTHROPIC_API_KEY` env var in your `.Renviron`

R/provider-cortex.R

@@ -10,6 +10,20 @@ NULL
 #' Chat with the LLM-powered [Snowflake Cortex
 #' Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst).
 #'
+#' ## Authentication
+#'
+#' `chat_cortex()` picks up the following ambient Snowflake credentials:
+#'
+#' - A static OAuth token defined via the `SNOWFLAKE_TOKEN` environment
+#'   variable.
+#' - Key-pair authentication credentials defined via the `SNOWFLAKE_USER` and
+#'   `SNOWFLAKE_PRIVATE_KEY` (which can be a PEM-encoded private key or a path
+#'   to one) environment variables.
+#' - Posit Workbench-managed Snowflake credentials for the corresponding
+#'   `account`.
+#'
+#' ## Known limitations
+#'
 #' Unlike most comparable model APIs, Cortex does not take a system prompt.
 #' Instead, the caller must provide a "semantic model" describing available
 #' tables, their meaning, and verified queries that can be run against them as a
@@ -23,18 +37,6 @@ NULL
 #' See [chat_snowflake()] to chat with more general-purpose models hosted on
 #' Snowflake.
 #'
-#' ## Authentication
-#'
-#' `chat_cortex()` picks up the following ambient Snowflake credentials:
-#'
-#' - A static OAuth token defined via the `SNOWFLAKE_TOKEN` environment
-#'   variable.
-#' - Key-pair authentication credentials defined via the `SNOWFLAKE_USER` and
-#'   `SNOWFLAKE_PRIVATE_KEY` (which can be a PEM-encoded private key or a path
-#'   to one) environment variables.
-#' - Posit Workbench-managed Snowflake credentials for the corresponding
-#'   `account`.
-#'
 #' @param account A Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier),
 #'   e.g. `"testorg-test_account"`. Defaults to the value of the
 #'   `SNOWFLAKE_ACCOUNT` environment variable.

R/provider-databricks.R

@@ -5,10 +5,6 @@
 #' models](https://docs.databricks.com/en/machine-learning/model-serving/score-foundation-models.html)
 #' and can also serve as a gateway for external models hosted by a third party.
 #'
-#' Databricks models do not support images, but they do support structured
-#' outputs. Tool calling support is also very limited at present; too limited
-#' for `ellmer`'s tool calling features to work properly at all.
-#'
 #' ## Authentication
 #'
 #' `chat_databricks()` picks up on ambient Databricks credentials for a subset
@@ -22,6 +18,12 @@
 #' - Authentication via the Databricks CLI
 #' - Posit Workbench-managed credentials
 #'
+#' ## Known limitations
+#'
+#' Databricks models do not support images, but they do support structured
+#' outputs. Tool calling support is also very limited at present and is
+#' currently not supported by ellmer.
+#'
 #' @family chatbots
 #' @param workspace The URL of a Databricks workspace, e.g.
 #'   `"https://example.cloud.databricks.com"`. Will use the value of the

R/provider-gemini.R

@@ -6,6 +6,7 @@ NULL
 
 #' Chat with a Google Gemini model
 #'
+#' ## Authentication
 #' To authenticate, we recommend saving your
 #' [API key](https://aistudio.google.com/app/apikey) to
 #' the `GOOGLE_API_KEY` env var in your `.Renviron`

R/provider-groq.R

@@ -9,7 +9,9 @@ NULL
 #' This function is a lightweight wrapper around [chat_openai()] with
 #' the defaults tweaked for groq.
 #'
-#' It does not currently support structured data extraction.
+#' ## Known limitations
+#'
+#' groq does not currently support structured data extraction.
 #'
 #' @export
 #' @family chatbots

R/provider-snowflake.R

@@ -8,12 +8,6 @@ NULL
 #' The Snowflake provider allows you to interact with LLM models available
 #' through the [Cortex LLM REST API](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-llm-rest-api).
 #'
-#' Note that Snowflake-hosted models do not support images, tool calling, or
-#' structured outputs.
-#'
-#' See [chat_cortex()] to chat with the Snowflake Cortex Analyst rather than a
-#' general-purpose model.
-#'
 #' ## Authentication
 #'
 #' `chat_snowflake()` picks up the following ambient Snowflake credentials:
@@ -26,6 +20,13 @@ NULL
 #' - Posit Workbench-managed Snowflake credentials for the corresponding
 #'   `account`.
 #'
+#' ## Known limitations
+#' Note that Snowflake-hosted models do not support images, tool calling, or
+#' structured outputs.
+#'
+#' See [chat_cortex()] to chat with the Snowflake Cortex Analyst rather than a
+#' general-purpose model.
+#'
 #' @inheritParams chat_openai
 #' @inheritParams chat_cortex
 #' @inherit chat_openai return