update for 0.3.0 (#5)

* update for 0.3.0

* add callbacks to doc

* update to make_async

* rework migration guide

Author: willydouhard

api-reference/action.mdx

@@ -31,17 +31,17 @@ The `Action` class is designed to create and manage actions to be sent and displ
 import chainlit as cl
 
 @cl.action_callback("action_button")
-def on_action(action):
-    cl.Message(content=f"Executed {action.name}").send()
+async def on_action(action):
+    await cl.Message(content=f"Executed {action.name}").send()
     # Optionally remove the action button from the chatbot user interface
-    action.remove()
+    await action.remove()
 
 @cl.on_chat_start
-def start():
+async def start():
     # Sending an action button within a chatbot message
     actions = [
         cl.Action(name="action_button", value="example_value", description="Click me!")
     ]
 
-    cl.Message(content="Interact with this action button:", actions=actions).send()
+    await cl.Message(content="Interact with this action button:", actions=actions).send()
 ```

api-reference/ask/ask-for-file.mdx

@@ -18,6 +18,9 @@ If a project ID is configured, the messages will be uploaded to the cloud storag
 <ParamField path="max_size_mb" type="int" optional>
   Maximum file size in MB. Defaults to 2. Max 100.
 </ParamField>
+<ParamField path="max_files" type="int" optional>
+  Maximum number of files to upload. Defaults to 1. Maximum value is 10.
+</ParamField>
 <ParamField path="timeout" type="int" optional>
   The number of seconds to wait for an answer before raising a TimeoutError.
 </ParamField>
@@ -27,8 +30,8 @@ If a project ID is configured, the messages will be uploaded to the cloud storag
 
 ### Returns
 
-<ResponseField name="response" type="AskFileResponse" required>
-  The file uploaded by the user.
+<ResponseField name="response" type="List[AskFileResponse]" required>
+  The files uploaded by the user.
 </ResponseField>
 
 ### Usage
@@ -38,20 +41,21 @@ import chainlit as cl
 
 
 @cl.on_chat_start
-def start():
+async def start():
     file = None
 
     # Wait for the user to upload a file
-    while file == None:
-        file = cl.AskFileMessage(
+    while files == None:
+        files = await cl.AskFileMessage(
             content="Please upload a text file to begin!", accept=["text/plain"]
         ).send()
     # Decode the file
-    text = file.content.decode("utf-8")
+    text_file = files[0]
+    text = text_file.content.decode("utf-8")
 
     # Let the user know that the system is ready
-    cl.Message(
-        content=f"`{file.name}` uploaded, it contains {len(text)} characters!"
+    await cl.Message(
+        content=f"`{text_file.name}` uploaded, it contains {len(text)} characters!"
     ).send()
 ```
 
@@ -60,7 +64,7 @@ You can also pass a dict to the `accept` parameter to precise the file extension
 ```python Code Example
 import chainlit as cl
 
-file = cl.AskFileMessage(
+file = await cl.AskFileMessage(
         content="Please upload a python file to begin!", accept={"text/plain": [".py"]}
       ).send()
 ```

api-reference/ask/ask-for-input.mdx

@@ -24,7 +24,7 @@ If a project ID is configured, the messages will be uploaded to the cloud storag
 
 ### Returns
 
-<ResponseField name="response" type="str" required>
+<ResponseField name="response" type="AskResponse" required>
   The response of the user.
 </ResponseField>
 
@@ -35,10 +35,10 @@ import chainlit as cl
 
 
 @cl.on_chat_start
-def main():
-    res = cl.AskUserMessage(content="What is your name?", timeout=10).send()
+async def main():
+    res = await cl.AskUserMessage(content="What is your name?", timeout=10).send()
     if res:
-        cl.Message(
+        await cl.Message(
             content=f"Your name is: {res['content']}",
         ).send()
 ```

api-reference/elements/avatar.mdx

@@ -0,0 +1,54 @@
+---
+title: "Avatar"
+---
+
+The `Avatar` class allows you to display an avatar image next to a message instead of the author name.
+
+You need to send the element once. Next if the name of an avatar matches the name of an author, the avatar will be automatically displayed.
+
+You must provide either an url or a path or content bytes.
+
+### Attributes
+
+<ParamField path="name" type="str">
+  The name of the avatar. This will be used to replace author names.
+</ParamField>
+
+<ParamField path="url" type="str" optional>
+  The remote URL of the avatar image source.
+</ParamField>
+
+<ParamField path="path" type="str" optional>
+  The local file path of the avatar image.
+</ParamField>
+
+<ParamField path="content" type="bytes" optional>
+  The file content of the avatar image in bytes format.
+</ParamField>
+
+### Usage
+
+```python Code Example
+import chainlit as cl
+
+
+@cl.on_chat_start
+async def start():
+    await cl.Avatar(
+        name="Tool 1",
+        url="https://avatars.githubusercontent.com/u/128686189?s=400&u=a1d1553023f8ea0921fba0debbe92a8c5f840dd9&v=4",
+    ).send()
+
+    await cl.Message(
+        content="This message should not have an avatar!", author="Tool 0"
+    ).send()
+
+    await cl.Message(
+        content="This message should have an avatar!", author="Tool 1"
+    ).send()
+
+    await cl.Message(
+        content="This message should not have an avatar!", author="Tool 2"
+    ).send()
+
+```

api-reference/elements/local-image.mdx api-reference/elements/image.mdxapi-reference/elements/local-image.mdx renamed to api-reference/elements/image.mdx

@@ -1,8 +1,10 @@
 ---
-title: "Local Image"
+title: "Image"
 ---
 
-The `LocalImage` class is designed to create and handle local image elements to be sent and displayed in the chatbot user interface.
+The `Image` class is designed to create and handle image elements to be sent and displayed in the chatbot user interface.
+
+You must provide either an url or a path or content bytes.
 
 ### Attributes
 
@@ -20,13 +22,16 @@ The `LocalImage` class is designed to create and handle local image elements to
   are "small", "medium" (default), or "large".
 </ParamField>
 
+<ParamField path="url" type="str" optional>
+  The remote URL of the image source.
+</ParamField>
+
 <ParamField path="path" type="str" optional>
-  The local file path of the image. Must provide either path or content.
+  The local file path of the image.
 </ParamField>
 
 <ParamField path="content" type="bytes" optional>
-  The file content of the image in bytes format. Must provide either path or
-  content.
+  The file content of the image in bytes format.
 </ParamField>
 
 ### Usage with message scope
@@ -36,24 +41,25 @@ import chainlit as cl
 
 # Sending an image with the local file path
 elements = [
-  cl.LocalImage(name="image1", display="inline", path="./image1.jpg")
+  cl.Image(name="image1", display="inline", path="./image1.jpg")
 ]
 
-cl.Message(content="Look at this local image!", elements=elements).send()
+await cl.Message(content="Look at this local image!", elements=elements).send()
 ```
 
 ### Usage without scope
 
 ```python Code Example
 import chainlit as cl
+import aiofiles
 
 # Sending an image with the local file path
-image1 = cl.LocalImage(name="image1", display="inline", path="./image1.jpg")
-image1.send()
+image1 = cl.Image(name="image1", display="inline", path="./image1.jpg")
+await image1.send()
 
 # Sending an image with file content as bytes
-with open("./image2.jpg", "rb") as f:
-    image_content = f.read()
-    image2 = cl.LocalImage(name="image2", display="inline", content=image_content)
-    image2.send()
+async with aiofiles.open("./image2.jpg", "rb") as f:
+    image_content = await f.read()
+    image2 = cl.Image(name="image2", display="inline", content=image_content)
+    await image2.send()
 ```

api-reference/elements/remote-image.mdx

@@ -3,15 +3,27 @@ title: "Text"
 ---
 
 The `Text` class allows you to display a text element in the chatbot UI. This class takes a string and creates a text element that can be sent to the UI.
+It supports the markdown syntax for formatting text.
+
+You must provide either an url or a path or content bytes.
 
 ### Attributes
 
 <ParamField path="name" type="str">
   The name of the text element to be displayed in the UI.
 </ParamField>
 
-<ParamField path="text" type="str">
-  The text string that should be displayed as the content of the text element.
+<ParamField path="content" type="Union[str, bytes]" optional>
+  The text string or bytes that should be displayed as the content of the text
+  element.
+</ParamField>
+
+<ParamField path="url" type="str" optional>
+  The remote URL of the text source.
+</ParamField>
+
+<ParamField path="path" type="str" optional>
+  The local file path of the text file.
 </ParamField>
 
 <ParamField path="display" type="ElementDisplay" optional>
@@ -32,10 +44,10 @@ import chainlit as cl
 
 text_content = "Hello, this is a text element."
 elements = [
-    cl.Text(name="simple_text", text=text_content, display="inline")
+    cl.Text(name="simple_text", content=text_content, display="inline")
 ]
 
-cl.Message(content="Check out this text element!", elements=elements).send()
+await cl.Message(content="Check out this text element!", elements=elements).send()
 ```
 
 ### Usage without scope
@@ -44,5 +56,5 @@ cl.Message(content="Check out this text element!", elements=elements).send()
 import chainlit as cl
 
 text_content = "Hello, this is a text element."
-cl.Text(name="simple_text", text=text_content, display="inline").send()
+await cl.Text(name="simple_text", content=text_content, display="inline").send()
 ```

api-reference/elements/text.mdx

@@ -0,0 +1,39 @@
+---
+title: "Callback Handlers"
+---
+
+When running your own LangChain agent, typically using [langchain_run](/api-reference/langchain/langchain-run), it is essential to provide the appropriate callback handler. This ensures seamless communication between the Chainlit UI and your agent.
+
+There are two ways to pass the callback handler:
+
+1. Pass the callback handler during runtime. This will apply the handler to all calls made by your agent.
+2. Pass the callback handler to individual components, such as an `llm`, allowing you to control what information is returned to the UI.
+
+### Asynchronous Callback Handler
+
+The following code example demonstrates how to pass an asynchronous callback handler.
+
+```python
+@cl.langchain_run
+async def run(agent, input_str):
+    res = await agent.acall(input_str, callbacks=[cl.AsyncChainlitCallbackHandler()])
+    await cl.Message(content=res["text"]).send()
+```
+
+Notice the `acall` here, that could also be `arun` or any other async function. Since we are calling the asynchronous implementation of the agent, we need to use the asynchronous callback handler.
+
+### Synchronous Callback Handler
+
+Alternatively, you can pass a synchronous callback handler, as shown in the example below:
+
+```python
+@cl.langchain_run
+async def run(agent, input_str):
+    res = await cl.make_async(agent)(input_str, callbacks=[cl.ChainlitCallbackHandler()])
+    await cl.Message(content=res["text"]).send()
+```
+
+Since we are calling a long running synchronous function, we need to wrap it in `cl.make_async` to make it asynchronous and not block the event loop.
+The function will still run synchronously in its own thread, hence we use the synchronous callback handler.
+
+Choose the appropriate callback handler based on your specific requirements, ensuring seamless interaction between your LangChain agent and the Chainlit UI.

api-reference/langchain/callbacks.mdx

@@ -1,20 +1,27 @@
 ---
 title: "langchain_factory"
 ---
-Plug and play decorator for the LangChain library.  
+
+Plug and play decorator for the LangChain library.
 
 The decorated function should instantiate a new LangChain instance (Chain, Agent...). One instance per user session is created and cached. The per user instance is called every time a new message is received.
 
-<RequestExample>
+### Parameters
+
+<ParamField path="use_async" type="bool">
+  Whether to use the async implementation of the agent or not.
+</ParamField>
+
+### Usage
+
 ```python Code Example
 from langchain import OpenAI, LLMMathChain
 from chainlit import langchain_factory
 
-@langchain_factory
+@langchain_factory(use_async=True)
 def load():
     llm = OpenAI(temperature=0)
     llm_math = LLMMathChain.from_llm(llm=llm)
 
     return llm_math
 ```
-</RequestExample>