Revamp docs

holoviz-topics · Mar 16, 2024 · 98a97d3 · 98a97d3
1 parent 718b029
commit 98a97d3
Show file tree

Hide file tree

Showing 70 changed files with 985 additions and 4,010 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -6,7 +6,7 @@
         "codespaces": {
           "openFiles": [
             "README.md",
-            "docs/examples/basics/basic_chat.py",
+            "docs/examples/features/feature_chat.py",
             "docs/examples/openai/openai_chat.py"
           ]
         },

diff --git a/.gitignore b/.gitignore
@@ -166,7 +166,6 @@ test-results/
 cache/
 
 .DS_STORE
-docs/basics.md
 docs/components.md
 docs/features.md
 docs/langchain.md

diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
@@ -37,7 +37,6 @@ On contribution:
 
 ```bash
 hatch run pytest -s -m ui --screenshot on --video on --headed -k <NAME_OF_YOUR_EXAMPLE>
-hatch run python scripts/postprocess_videos.py
 hatch run docs-build
 git checkout -b <YOUR_BRANCH_NAME>
 git add commit
@@ -63,21 +62,21 @@ Please ensure it's installed on your system with
 pip install hatch
 ```
 
-Please ensure [Playwright](https://playwright.dev/python/) browsers are installed
+Please ensure [Playwright](https://playwright.dev/python/) browsers are installed.
 
 ```bash
 hatch run playwright install chromium
 ```
 
 The first time `hatch run ...` is run, it will install the required dependencies.
 
-Please ensure `pre-commit` is installed by running
+Please ensure `pre-commit` is installed by running:
 
 ```bash
 hatch run pre-commit install
 ```
 
-You will also need to set the below environment variables
+You will also need to set the below environment variables if it's not already in your environment.
 
 ```bash
 export OPENAI_API_KEY=...
@@ -103,7 +102,7 @@ hatch run test
 
 ## Run UI tests
 
-To run the Playwright tests in *headed* mode (i.e. show the browser) you can run
+To run the Playwright tests in *headed* mode (i.e. show the browser) you can run:
 
 ```bash
 hatch run pytest -s -m ui --headed

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ Examples using [Panel](https://panel.holoviz.org/) and its [Chat Components](htt
 
 https://github.com/holoviz-topics/panel-chat-examples/assets/42288570/cdb78a39-b98c-44e3-886e-29de6a079bde
 
-Panels Chat Components are available from Panel v1.3.0.
+Panels Chat Components are available with `pip install "panel>=1.3.0"`; some examples require `pip install "panel>=1.4.0"`.
 
 ## Exploration
 
@@ -21,8 +21,6 @@ To install and serve all examples:
 ```bash
 git clone https://github.com/holoviz-topics/panel-chat-examples
 cd panel-chat-examples
-# Optionally create a new virtual environment with conda, venv, etc.
-pip install .
 # Optionally set the OPENAI_API_KEY environment variable
 panel serve docs/examples/**/*.py --static-dirs thumbnails=docs/assets/thumbnails --autoreload
 ```
@@ -31,23 +29,6 @@ Then open [http://localhost:5006](http://localhost:5006) in your browser.
 
 ![Panel Index Page](https://raw.githubusercontent.com/holoviz-topics/panel-chat-examples/main/assets/images/panel-chat-examples-index-page.png)
 
-### GPU Usage
-
-Note the default installation is not optimized for GPU usage. To enable GPU support for local
-models (i.e. not OpenAI), install `ctransformers` with the [proper backend](https://github.com/marella/ctransformers#gpu) and modify the scripts configs' accordingly, e.g. `n_gpu_layers=1` for a single GPU.
-
-CUDA:
-
-```bash
-pip install ctransformers[cuda] --no-binary ctransformers --no-cache --no-binary ctransformers --force
-```
-
-Mac M1/2:
-
-```bash
-CT_METAL=1 hatch run pip install ctransformers --no-binary ctransformers --no-cache --no-binary ctransformers --force # for m1
-```
-
 ## Contributing
 
 We would ❤️ to collaborate with you. Check out the [DEVELOPER GUIDE](https://github.com/holoviz-topics/panel-chat-examples/blob/main/DEVELOPER_GUIDE.md) for to get started.

diff --git a/docs/assets/thumbnails/feature_chained_response.png b/docs/assets/thumbnails/feature_chained_response.png
diff --git a/docs/assets/thumbnails/feature_control_callback_response.png b/docs/assets/thumbnails/feature_control_callback_response.png
diff --git a/docs/assets/thumbnails/feature_custom_input_widgets.png b/docs/assets/thumbnails/feature_custom_input_widgets.png
diff --git a/docs/assets/thumbnails/feature_delayed_placeholder.png b/docs/assets/thumbnails/feature_delayed_placeholder.png
diff --git a/docs/assets/thumbnails/feature_echo_chat.png b/docs/assets/thumbnails/feature_echo_chat.png
diff --git a/docs/assets/thumbnails/feature_slim_interface.png b/docs/assets/thumbnails/feature_slim_interface.png
diff --git a/docs/assets/thumbnails/feature_stream_echo_chat.png b/docs/assets/thumbnails/feature_stream_echo_chat.png
diff --git a/docs/assets/videos/feature_chained_response.mp4 b/docs/assets/videos/feature_chained_response.mp4
diff --git a/docs/assets/videos/feature_control_callback_response.mp4 b/docs/assets/videos/feature_control_callback_response.mp4
diff --git a/docs/assets/videos/feature_custom_input_widgets.mp4 b/docs/assets/videos/feature_custom_input_widgets.mp4
diff --git a/docs/assets/videos/feature_delayed_placeholder.mp4 b/docs/assets/videos/feature_delayed_placeholder.mp4
diff --git a/docs/assets/videos/feature_echo_chat.mp4 b/docs/assets/videos/feature_echo_chat.mp4
diff --git a/docs/assets/videos/feature_slim_interface.mp4 b/docs/assets/videos/feature_slim_interface.mp4
diff --git a/docs/assets/videos/feature_stream_echo_chat.mp4 b/docs/assets/videos/feature_stream_echo_chat.mp4
diff --git a/docs/examples/basics/basic_chat.py b/docs/examples/basics/basic_chat.py
diff --git a/docs/examples/basics/basic_custom_widgets.py b/docs/examples/basics/basic_custom_widgets.py
diff --git a/docs/examples/components/component_chat_input.py b/docs/examples/components/component_chat_input.py
diff --git a/docs/examples/components/component_environment_widget.py b/docs/examples/components/component_environment_widget.py
diff --git a/docs/examples/components/component_status.py b/docs/examples/components/component_status.py
diff --git a/docs/examples/feature/feature_chained_response.py b/docs/examples/feature/feature_chained_response.py
@@ -0,0 +1,51 @@
+"""
+Demonstrates how to chain responses from a single message in the callback.
+
+Highlight:
+
+- The `respond` parameter in the `send` method is used to chain responses.
+- It's also possible to use `respond` as a method to chain responses.
+"""
+
+from asyncio import sleep
+
+import panel as pn
+
+pn.extension()
+
+PERSON_1 = "Happy User"
+PERSON_2 = "Excited User"
+PERSON_3 = "Passionate User"
+
+
+async def callback(contents: str, user: str, instance: pn.chat.ChatInterface):
+    await sleep(2)
+    if user == "User":
+        instance.send(
+            f"Hey, {PERSON_2}! Did you hear the user?",
+            user=PERSON_1,
+            avatar="😊",
+            respond=True,  # This is the default, but it's here for clarity
+        )
+    elif user == PERSON_1:
+        user_message = instance.objects[-2]
+        user_contents = user_message.object
+        yield pn.chat.ChatMessage(
+            f'Yeah, they said "{user_contents}"! Did you also hear {PERSON_3}?',
+            user=PERSON_2,
+            avatar="😄",
+        )
+        instance.respond()
+    elif user == PERSON_2:
+        instance.send(
+            f"Yup, I heard!",
+            user=PERSON_3,
+            avatar="😆",
+            respond=False,
+        )
+
+
+chat_interface = pn.chat.ChatInterface(
+    help_text="Send a message to start the conversation!", callback=callback
+)
+chat_interface.servable()
diff --git a/docs/examples/feature/feature_control_callback_response.py b/docs/examples/feature/feature_control_callback_response.py
@@ -0,0 +1,58 @@
+"""
+Demonstrates how to precisely control the callback response.
+
+Highlights:
+
+- Use a placeholder text to display a message while waiting for the response.
+- Use a placeholder threshold to control when the placeholder text is displayed.
+- Use send instead of stream/yield/return to keep the placeholder text while still sending a message, ensuring respond=False to avoid a recursive loop.
+- Use yield to continuously update the response message.
+- Use pn.chat.ChatMessage or dict to send a message with a custom user and avatar.
+"""
+
+from asyncio import sleep
+from random import choice
+
+import panel as pn
+
+pn.extension()
+
+
+async def callback(contents: str, user: str, instance: pn.chat.ChatInterface):
+    await sleep(0.5)
+    # use send instead of stream/yield/return to keep the placeholder text
+    # while still sending a message; ensure respond=False to avoid a recursive loop
+    instance.send(
+        "Let me flip the coin for you...", user="Game Master", avatar="🎲", respond=False
+    )
+    await sleep(1)
+
+    characters = "/|\\_"
+    index = 0
+    for _ in range(0, 28):
+        index = (index + 1) % len(characters)
+        # use yield to continuously update the response message
+        # use pn.chat.ChatMessage to send a message with a custom user and avatar
+        yield pn.chat.ChatMessage("\r" + characters[index], user="Coin", avatar="🪙")
+        await sleep(0.005)
+
+    result = choice(["heads", "tails"])
+    if result in contents.lower():
+        # equivalently, use a dict instead of a pn.chat.ChatMessage
+        yield {"object": f"Woohoo, {result}! You win!", "user": "Coin", "avatar": "🎲"}
+    else:
+        yield {"object": f"Aw, got {result}. Try again!", "user": "Coin", "avatar": "🎲"}
+
+
+chat_interface = pn.chat.ChatInterface(
+    widgets=[
+        pn.widgets.RadioButtonGroup(
+            options=["Heads!", "Tails!"], button_type="primary", button_style="outline"
+        )
+    ],
+    callback=callback,
+    help_text="Select heads or tails, then click send!",
+    placeholder_text="Waiting for the result...",
+    placeholder_threshold=0.1,
+)
+chat_interface.servable()