Adds %ai list, %ai help magic commands

docs/source/users/index.md

@@ -238,6 +238,15 @@ providers, as defined in [`langchain.llms`](https://langchain.readthedocs.io/en/
 - `openai-chat`
 - `sagemaker-endpoint`
 
+You can find a list of supported providers and models by running `%ai list`. Some providers
+define a list of supported models. If a provider does not define a list of supported models,
+consult the vendor's documentation. The [Hugging Face web site](https://huggingface.co/)
+includes a list of models, for example.
+
+Optionally, you can pass a provider ID as a parameter to `%ai list` to get all
+models provided by one provider. For example, `%ai list openai` will display only models
+provided by the `openai` provider.
+
 If your model ID is associated with only one provider, you can omit the `provider-id` and
 the colon from the first line. For example, because `ai21` is the only provider of the
 `j2-jumbo-instruct` model, you can either give the full provider and model,

examples/commands.ipynb

@@ -0,0 +1,250 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "ca3ba02c-c965-4ffe-88b3-ca606a9cf288",
+   "metadata": {},
+   "source": [
+    "# AI commands\n",
+    "\n",
+    "You can use the `%ai` cell magic to run special commands. If a model has the same name as a command, you will need to refer to the model using the `provider:model` format only; the `model` shortcut will not work."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "6c9c4016-711c-4592-b543-24b854f5b160",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "%reload_ext jupyter_ai"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cd2a9967-8923-43bf-96b0-9567c09775e2",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "## Getting help\n",
+    "\n",
+    "`%ai help` will show you a list of all supported commands."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "edd6ddd5-54fb-4750-8ae9-4143a6b83e2e",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "| Command | Description |\n",
+       "| ------- | ----------- |\n",
+       "| `help` | Display a list of supported commands|\n",
+       "| `list` | Display a list of models that you can use (optionally, for a single provider)|\n"
+      ],
+      "text/plain": [
+       "help - Display a list of supported commands\n",
+       "list - Display a list of models that you can use (optionally, for a single provider)\n"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "%ai help"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "0f073caa-265d-40d6-b537-d025b8df9f41",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "Cannot determine model provider from model ID `foo`.\n",
+       "\n",
+       "To see a list of models you can use, run `%ai list`.\n",
+       "\n",
+       "If you were trying to run a command, run `%ai help` to see a list of commands."
+      ],
+      "text/plain": [
+       "Cannot determine model provider from model ID 'foo'.\n",
+       "\n",
+       "To see a list of models you can use, run '%ai list'.\n",
+       "\n",
+       "If you were trying to run a command, run '%ai help' to see a list of commands."
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "%ai foo"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "bad2d8a8-6141-4247-9af7-7583426c59a6",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "| Provider | Environment variable | Set? | Models |\n",
+       "|----------|----------------------|------|--------|\n",
+       "| `ai21` | `AI21_API_KEY` | <abbr title=\"You have set this environment variable, so you can use this provider's models.\">✅</abbr> | `ai21:j1-large`, `ai21:j1-grande`, `ai21:j1-jumbo`, `ai21:j1-grande-instruct`, `ai21:j2-large`, `ai21:j2-grande`, `ai21:j2-jumbo`, `ai21:j2-grande-instruct`, `ai21:j2-jumbo-instruct` |\n",
+       "| `anthropic` | `ANTHROPIC_API_KEY` | <abbr title=\"You have set this environment variable, so you can use this provider's models.\">✅</abbr> | `anthropic:claude-v1`, `anthropic:claude-v1.0`, `anthropic:claude-v1.2`, `anthropic:claude-instant-v1`, `anthropic:claude-instant-v1.0` |\n",
+       "| `cohere` | `COHERE_API_KEY` | <abbr title=\"You have set this environment variable, so you can use this provider's models.\">✅</abbr> | `cohere:medium`, `cohere:xlarge` |\n",
+       "| `huggingface_hub` | `HUGGINGFACEHUB_API_TOKEN` | <abbr title=\"You have set this environment variable, so you can use this provider's models.\">✅</abbr> | This provider does not define a list of models. |\n",
+       "| `openai` | `OPENAI_API_KEY` | <abbr title=\"You have set this environment variable, so you can use this provider's models.\">✅</abbr> | `openai:text-davinci-003`, `openai:text-davinci-002`, `openai:text-curie-001`, `openai:text-babbage-001`, `openai:text-ada-001`, `openai:davinci`, `openai:curie`, `openai:babbage`, `openai:ada` |\n",
+       "| `openai-chat` | `OPENAI_API_KEY` | <abbr title=\"You have set this environment variable, so you can use this provider's models.\">✅</abbr> | `openai-chat:gpt-4`, `openai-chat:gpt-4-0314`, `openai-chat:gpt-4-32k`, `openai-chat:gpt-4-32k-0314`, `openai-chat:gpt-3.5-turbo`, `openai-chat:gpt-3.5-turbo-0301` |\n",
+       "| `sagemaker-endpoint` | Not applicable. | <abbr title=\"Not applicable\">N/A</abbr>  | This provider does not define a list of models. |\n"
+      ],
+      "text/plain": [
+       "ai21\n",
+       "Requires environment variable AI21_API_KEY (set)\n",
+       "* ai21:j1-large\n",
+       "* ai21:j1-grande\n",
+       "* ai21:j1-jumbo\n",
+       "* ai21:j1-grande-instruct\n",
+       "* ai21:j2-large\n",
+       "* ai21:j2-grande\n",
+       "* ai21:j2-jumbo\n",
+       "* ai21:j2-grande-instruct\n",
+       "* ai21:j2-jumbo-instruct\n",
+       "\n",
+       "anthropic\n",
+       "Requires environment variable ANTHROPIC_API_KEY (set)\n",
+       "* anthropic:claude-v1\n",
+       "* anthropic:claude-v1.0\n",
+       "* anthropic:claude-v1.2\n",
+       "* anthropic:claude-instant-v1\n",
+       "* anthropic:claude-instant-v1.0\n",
+       "\n",
+       "cohere\n",
+       "Requires environment variable COHERE_API_KEY (set)\n",
+       "* cohere:medium\n",
+       "* cohere:xlarge\n",
+       "\n",
+       "huggingface_hub\n",
+       "Requires environment variable HUGGINGFACEHUB_API_TOKEN (set)\n",
+       "* This provider does not define a list of models.\n",
+       "\n",
+       "openai\n",
+       "Requires environment variable OPENAI_API_KEY (set)\n",
+       "* openai:text-davinci-003\n",
+       "* openai:text-davinci-002\n",
+       "* openai:text-curie-001\n",
+       "* openai:text-babbage-001\n",
+       "* openai:text-ada-001\n",
+       "* openai:davinci\n",
+       "* openai:curie\n",
+       "* openai:babbage\n",
+       "* openai:ada\n",
+       "\n",
+       "openai-chat\n",
+       "Requires environment variable OPENAI_API_KEY (set)\n",
+       "* openai-chat:gpt-4\n",
+       "* openai-chat:gpt-4-0314\n",
+       "* openai-chat:gpt-4-32k\n",
+       "* openai-chat:gpt-4-32k-0314\n",
+       "* openai-chat:gpt-3.5-turbo\n",
+       "* openai-chat:gpt-3.5-turbo-0301\n",
+       "\n",
+       "sagemaker-endpoint\n",
+       "* This provider does not define a list of models.\n",
+       "\n"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "%ai list"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "4d84fcac-7348-4c02-9ec3-34b300ec8459",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "| Provider | Environment variable | Set? | Models |\n",
+       "|----------|----------------------|------|--------|\n",
+       "| `openai` | `OPENAI_API_KEY` | <abbr title=\"You have set this environment variable, so you can use this provider's models.\">✅</abbr> | `openai:text-davinci-003`, `openai:text-davinci-002`, `openai:text-curie-001`, `openai:text-babbage-001`, `openai:text-ada-001`, `openai:davinci`, `openai:curie`, `openai:babbage`, `openai:ada` |\n"
+      ],
+      "text/plain": [
+       "openai\n",
+       "Requires environment variable OPENAI_API_KEY (set)\n",
+       "* openai:text-davinci-003\n",
+       "* openai:text-davinci-002\n",
+       "* openai:text-curie-001\n",
+       "* openai:text-babbage-001\n",
+       "* openai:text-ada-001\n",
+       "* openai:davinci\n",
+       "* openai:curie\n",
+       "* openai:babbage\n",
+       "* openai:ada\n",
+       "\n"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "%ai list openai"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b56ff0e3-42c2-4927-affd-be6a089dfa43",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.16"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}