From dec499c96913aa982eaf7725d944ca19d2acfb8c Mon Sep 17 00:00:00 2001
From: Alan Meeson <alanmeeson@users.noreply.github.com>
Date: Thu, 31 Oct 2024 01:10:50 +0000
Subject: [PATCH] Backport PR #1056: Add examples of using Fields and
 EnvAuthStrategy to developer documentation

---
 docs/source/developers/index.md | 55 +++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/docs/source/developers/index.md b/docs/source/developers/index.md
index c9874e77c..af4cfcea0 100644
--- a/docs/source/developers/index.md
+++ b/docs/source/developers/index.md
@@ -121,6 +121,61 @@ your new provider's `id`:
 [LLM]: https://api.python.langchain.com/en/v0.0.339/llms/langchain.llms.base.LLM.html#langchain.llms.base.LLM
 [BaseChatModel]: https://api.python.langchain.com/en/v0.0.339/chat_models/langchain.chat_models.base.BaseChatModel.html
 
+### API keys and fields for custom providers
+
+You can add handle authentication via API keys, and configuration with
+custom parameters using an auth strategy and fields as shown in the example
+below.
+
+```python
+from typing import ClassVar, List
+from jupyter_ai_magics import BaseProvider
+from jupyter_ai_magics.providers import EnvAuthStrategy, Field, TextField, MultilineTextField
+from langchain_community.llms import FakeListLLM
+
+
+class MyProvider(BaseProvider, FakeListLLM):
+    id = "my_provider"
+    name = "My Provider"
+    model_id_key = "model"
+    models = [
+        "model_a",
+        "model_b"
+    ]
+
+    auth_strategy = EnvAuthStrategy(
+        name="MY_API_KEY", keyword_param="my_api_key_param"
+    )
+
+    fields: ClassVar[List[Field]] = [
+        TextField(key="my_llm_parameter", label="The name for my_llm_parameter to show in the UI"),
+        MultilineTextField(key="custom_config", label="Custom Json Config", format="json"),
+    ]
+
+    def __init__(self, **kwargs):
+        model = kwargs.get("model_id")
+        kwargs["responses"] = (
+            ["This is a response from model 'a'"]
+            if model == "model_a" else
+            ["This is a response from model 'b'"]
+        )
+        super().__init__(**kwargs)
+```
+
+The `auth_strategy` handles specifying API keys for providers and models.
+The example shows the `EnvAuthStrategy` which takes the API key from the
+environment variable with the name specified in `name` and be provided to the
+model's `__init__` as a kwarg with the name specified in `keyword_param`.
+This will also cause a field to be present in the configuration UI with the
+`name` of the environment variable as the label.
+
+Further configuration can be handled adding `fields` into the settings
+dialogue for your custom model by specifying a list of fields as shown in
+the example.  These will be passed into the `__init__` as kwargs, with the
+key specified by the key in the field object. The label specified in the field
+object determines the text shown in the configuration section of the user
+interface.
+
 ### Custom embeddings providers
 
 To provide a custom embeddings model an embeddings providers should be defined implementing the API of `jupyter-ai`'s `BaseEmbeddingsProvider` and of `langchain`'s [`Embeddings`][Embeddings] abstract class.