diff --git a/api-reference/lifecycle-hooks/audio-chunk.mdx b/api-reference/lifecycle-hooks/audio-chunk.mdx new file mode 100644 index 0000000..bb6e5d7 --- /dev/null +++ b/api-reference/lifecycle-hooks/audio-chunk.mdx @@ -0,0 +1,16 @@ +--- +title: "audio_chunk" +--- + +Hook to react to an incoming audio chunk from the user's microphone. + +## Usage + +```python +import chainlit + + +@chainlit.on_audio_chunk +async def on_audio_chunk(chunk: chainlit.InputAudioChunk): + pass +``` diff --git a/api-reference/lifecycle-hooks/on-audio-end.mdx b/api-reference/lifecycle-hooks/audio-end.mdx similarity index 90% rename from api-reference/lifecycle-hooks/on-audio-end.mdx rename to api-reference/lifecycle-hooks/audio-end.mdx index 82562a2..f44e857 100644 --- a/api-reference/lifecycle-hooks/on-audio-end.mdx +++ b/api-reference/lifecycle-hooks/audio-end.mdx @@ -1,5 +1,5 @@ --- -title: "on_audio_end" +title: "audio_end" --- Hook to react to the end of an audio recording coming from the user's microphone. diff --git a/api-reference/lifecycle-hooks/audio-start.mdx b/api-reference/lifecycle-hooks/audio-start.mdx new file mode 100644 index 0000000..7d37b87 --- /dev/null +++ b/api-reference/lifecycle-hooks/audio-start.mdx @@ -0,0 +1,17 @@ +--- +title: "audio_start" +--- + +Hook to react to the end of an audio recording coming from the user's microphone. + +## Usage + +```python +from io import BytesIO +import chainlit as cl + + +@cl.on_audio_end +async def on_audio_end(): + pass +``` \ No newline at end of file diff --git a/api-reference/lifecycle-hooks/header-auth-callback.mdx b/api-reference/lifecycle-hooks/header-auth-callback.mdx new file mode 100644 index 0000000..04304c4 --- /dev/null +++ b/api-reference/lifecycle-hooks/header-auth-callback.mdx @@ -0,0 +1,4 @@ +--- +title: "header_auth_callback" +url: "/authentication/header" +--- \ No newline at end of file diff --git a/api-reference/lifecycle-hooks/oauth-callback.mdx b/api-reference/lifecycle-hooks/oauth-callback.mdx new file mode 100644 index 0000000..a9bdd0c --- /dev/null +++ b/api-reference/lifecycle-hooks/oauth-callback.mdx @@ -0,0 +1,4 @@ +--- +title: "oauth_callback" +url: "/authentication/oauth" +--- \ No newline at end of file diff --git a/api-reference/lifecycle-hooks/on-app-shutdown.mdx b/api-reference/lifecycle-hooks/on-app-shutdown.mdx new file mode 100644 index 0000000..3bc0590 --- /dev/null +++ b/api-reference/lifecycle-hooks/on-app-shutdown.mdx @@ -0,0 +1,21 @@ +--- +title: "on_app_shutdown" +--- + +Hook to run code when the Chainlit application shuts down. + +Useful for cleaning up resources, closing connections, saving state, etc. + +The function can be synchronous or asynchronous. + +## Usage + +```python Code Example +import chainlit + + +@chainlit.on_app_shutdown +async def on_app_shutdown(): + print("Application is shutting down!") + # Clean up resources here +``` diff --git a/api-reference/lifecycle-hooks/on-app-startup.mdx b/api-reference/lifecycle-hooks/on-app-startup.mdx new file mode 100644 index 0000000..4c775a6 --- /dev/null +++ b/api-reference/lifecycle-hooks/on-app-startup.mdx @@ -0,0 +1,21 @@ +--- +title: "on_app_startup" +--- + +Hook to run code when the Chainlit application starts. + +Useful for initializing resources, loading models, setting up database connections, etc. + +The function can be synchronous or asynchronous. + +## Usage + +```python Code Example +import chainlit + + +@chainlit.on_app_startup +async def startup(): + print("Application is starting!") + # Initialize resources here +``` diff --git a/api-reference/lifecycle-hooks/on-audio-chunk.mdx b/api-reference/lifecycle-hooks/on-audio-chunk.mdx deleted file mode 100644 index 52e6675..0000000 --- a/api-reference/lifecycle-hooks/on-audio-chunk.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "on_audio_chunk" ---- - -Hook to react to an incoming audio chunk from the user's microphone. - -## Usage - -```python -from io import BytesIO -import chainlit as cl - - -@cl.on_audio_chunk -async def on_audio_chunk(chunk: cl.InputAudioChunk): - pass -``` diff --git a/api-reference/lifecycle-hooks/on-chat-resume.mdx b/api-reference/lifecycle-hooks/on-chat-resume.mdx index bd3cda5..4ba54cb 100644 --- a/api-reference/lifecycle-hooks/on-chat-resume.mdx +++ b/api-reference/lifecycle-hooks/on-chat-resume.mdx @@ -14,13 +14,22 @@ This decorator will automatically: Only JSON serializable fields of the user session will be saved and restored. +## Parameters + + + The persisted chat to resume. + + ## Usage -At minimum, you will need to use the `@cl.on_chat_resume` decorator to resume conversations. +At minimum, you will need to use the `@chainlit.on_chat_resume` decorator to resume conversations. ```python -@cl.on_chat_resume -async def on_chat_resume(thread): +import chainlit +from chainlit import ThreadDict + +@chainlit.on_chat_resume +async def on_chat_resume(thread: ThreadDict): pass ``` @@ -34,9 +43,3 @@ However, if you are using a Langchain agent for instance, you will need to reins > Practical example of how to resume a chat with context. - -## Parameters - - - The persisted chat to resume. - diff --git a/api-reference/lifecycle-hooks/on-chat-start.mdx b/api-reference/lifecycle-hooks/on-chat-start.mdx index 1c27598..fc295f4 100644 --- a/api-reference/lifecycle-hooks/on-chat-start.mdx +++ b/api-reference/lifecycle-hooks/on-chat-start.mdx @@ -7,11 +7,12 @@ Hook to react to the user websocket connection event. ## Usage ```python Code Example -from chainlit import AskUserMessage, Message, on_chat_start +import chainlit +from chainlit import AskUserMessage, Message -@on_chat_start -async def main(): +@chainlit.on_chat_start +async def on_chat_start(): res = await AskUserMessage(content="What is your name?", timeout=30).send() if res: await Message( diff --git a/api-reference/lifecycle-hooks/on-logout.mdx b/api-reference/lifecycle-hooks/on-logout.mdx index 9e63317..74e7671 100644 --- a/api-reference/lifecycle-hooks/on-logout.mdx +++ b/api-reference/lifecycle-hooks/on-logout.mdx @@ -18,10 +18,10 @@ Decorator to react to a user logging out. Useful to clear cookies or other user ```python from fastapi import Request, Response -import chainlit as cl +import chainlit -@cl.on_logout +@chainlit.on_logout def main(request: Request, response: Response): response.delete_cookie("my_cookie") ``` diff --git a/api-reference/lifecycle-hooks/on-message.mdx b/api-reference/lifecycle-hooks/on-message.mdx index f5e113c..7eaf907 100644 --- a/api-reference/lifecycle-hooks/on-message.mdx +++ b/api-reference/lifecycle-hooks/on-message.mdx @@ -7,17 +7,17 @@ The decorated function is called every time a new message is received. ## Parameters - + The message coming from the UI. ## Usage ```python -import chainlit as cl +import chainlit -@cl.on_message -def main(message: cl.Message): +@chainlit.on_message +def on_message(message: chainlit.Message): content = message.content # do something ``` diff --git a/api-reference/lifecycle-hooks/on-window-message.mdx b/api-reference/lifecycle-hooks/on-window-message.mdx new file mode 100644 index 0000000..56dcf19 --- /dev/null +++ b/api-reference/lifecycle-hooks/on-window-message.mdx @@ -0,0 +1,4 @@ +--- +title: "on_window_message" +url: "/api-reference/window-message#on-window-message" +--- \ No newline at end of file diff --git a/api-reference/lifecycle-hooks/password-auth-callback.mdx b/api-reference/lifecycle-hooks/password-auth-callback.mdx new file mode 100644 index 0000000..5f3003c --- /dev/null +++ b/api-reference/lifecycle-hooks/password-auth-callback.mdx @@ -0,0 +1,4 @@ +--- +title: "password_auth_callback" +url: "/authentication/password" +--- \ No newline at end of file diff --git a/api-reference/lifecycle-hooks/send-window-message.mdx b/api-reference/lifecycle-hooks/send-window-message.mdx new file mode 100644 index 0000000..b342a4d --- /dev/null +++ b/api-reference/lifecycle-hooks/send-window-message.mdx @@ -0,0 +1,4 @@ +--- +title: "send_window_message" +url: "/api-reference/window-message#send-window-message" +--- \ No newline at end of file diff --git a/api-reference/window-message.mdx b/api-reference/window-message.mdx index 36347c1..4f9af92 100644 --- a/api-reference/window-message.mdx +++ b/api-reference/window-message.mdx @@ -4,39 +4,44 @@ title: "Window Messaging" # on_window_message -Decorator to react to messages coming from the Web App's parent window. +Decorator to react to JavaScript [window message events](https://developer.mozilla.org/en-US/docs/Web/API/Window/message_event) coming from the Web App's parent window. The decorated function is called every time a new window message is received. ## Parameters - - The message coming from the Web App's parent window. + + Window message event data coming from the Web App's parent window. ## Usage -```python -import chainlit as cl +```python Code Example +from typing import Any -@cl.on_window_message -def main(message: str): - # do something +import chainlit + + +@chainlit.on_window_message +async def on_window_message(message: Any): + print(message) # can be a string, dict, TypedDict, etc. ``` # send_window_message -Function to send messages to the Web App's parent window. +Function to send messages to the Web App's parent window via a [window.postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) method. ## Parameters - - The message to send to the Web App's parent window. + + The data to send with the event to the Web App's parent window. ## Usage -```python -@cl.on_message -async def message(): - await cl.send_window_message("Server: Hello from Chainlit") +```python Code Example +import chainlit + + +# can be a string, dict, TypedDict, etc +chainlit.send_window_message({ "greeting": "Hello World!" }) ``` \ No newline at end of file diff --git a/authentication/oauth.mdx b/authentication/oauth.mdx index 61a57d6..a94106b 100644 --- a/authentication/oauth.mdx +++ b/authentication/oauth.mdx @@ -211,7 +211,8 @@ def oauth_callback( provider_id: str, token: str, raw_user_data: Dict[str, str], - default_user: cl.User, + default_app_user: cl.User, + id_token: Optional[str] ) -> Optional[cl.User]: return default_user ``` @@ -228,7 +229,8 @@ def oauth_callback( provider_id: str, token: str, raw_user_data: Dict[str, str], - default_user: cl.User, + default_app_user: cl.User, + id_token: Optional[str] ) -> Optional[cl.User]: if provider_id == "google": if raw_user_data["hd"] == "example.org": diff --git a/authentication/password.mdx b/authentication/password.mdx index 04d3f40..31da710 100644 --- a/authentication/password.mdx +++ b/authentication/password.mdx @@ -18,7 +18,7 @@ from typing import Optional import chainlit as cl @cl.password_auth_callback -def auth_callback(username: str, password: str): +def auth_callback(username: str, password: str) -> Optional[cl.User]: # Fetch the user matching username from your database # and compare the hashed password with the value stored in the database if (username, password) == ("admin", "admin"): diff --git a/concepts/chat-lifecycle.mdx b/concepts/app-lifecycle.mdx similarity index 98% rename from concepts/chat-lifecycle.mdx rename to concepts/app-lifecycle.mdx index b1a2801..7022fcc 100644 --- a/concepts/chat-lifecycle.mdx +++ b/concepts/app-lifecycle.mdx @@ -1,5 +1,5 @@ --- -title: Chat Life Cycle +title: App Lifecycle --- Whenever a user connects to your Chainlit app, a new chat session is created. A chat session goes through a life cycle of events, which you can respond to by defining hooks. diff --git a/concepts/user-session.mdx b/concepts/user-session.mdx index 47ae4c0..b764cef 100644 --- a/concepts/user-session.mdx +++ b/concepts/user-session.mdx @@ -2,7 +2,7 @@ title: User Session --- -The user session is designed to persist data in memory through the [life cycle](/concepts/chat-lifecycle) of a chat session. Each user session is unique to a user and a given chat session. +The user session is designed to persist data in memory through the [life cycle](/concepts/app-lifecycle) of a chat session. Each user session is unique to a user and a given chat session. ## Why use the user session? @@ -60,21 +60,25 @@ The following keys are reserved for chat session related data: The session id. + Only set if you are enabled [Authentication](/authentication). Contains the user object of the user that started this chat session. + Only relevant if you are using the [Chat Profiles](/advanced-features/chat-profiles) feature. Contains the chat profile selected by this user. + Only relevant if you are using the [Chat Settings](/advanced-features/chat-settings) feature. Contains the chat settings given by this user. + - Only relevant if you are using the [user_env](/backend/config/project) config. + Only relevant if you are using the [user\_env](/backend/config/project) config. Contains the environment variables given by this user. diff --git a/docs.json b/docs.json index 83fb5f2..500511f 100644 --- a/docs.json +++ b/docs.json @@ -63,7 +63,7 @@ { "group": "Basic Concepts", "pages": [ - "concepts/chat-lifecycle", + "concepts/app-lifecycle", "concepts/starters", "concepts/message", "concepts/step", @@ -170,13 +170,41 @@ { "group": "Life Cycle Hooks", "pages": [ - "api-reference/lifecycle-hooks/on-chat-start", - "api-reference/lifecycle-hooks/on-chat-end", - "api-reference/lifecycle-hooks/on-chat-resume", - "api-reference/lifecycle-hooks/on-message", - "api-reference/lifecycle-hooks/on-logout", - "api-reference/lifecycle-hooks/on-audio-chunk", - "api-reference/lifecycle-hooks/on-audio-end" + { + "group": "Application", + "pages": [ + "api-reference/lifecycle-hooks/on-app-startup", + "api-reference/lifecycle-hooks/on-app-shutdown" + ] + }, + { + "group": "Authentication", + "pages": [ + "api-reference/lifecycle-hooks/on-logout", + "api-reference/lifecycle-hooks/password-auth-callback", + "api-reference/lifecycle-hooks/header-auth-callback", + "api-reference/lifecycle-hooks/oauth-callback" + ] + }, + { + "group": "Chat", + "pages": [ + "api-reference/lifecycle-hooks/on-chat-start", + "api-reference/lifecycle-hooks/on-chat-resume", + "api-reference/lifecycle-hooks/on-message", + "api-reference/lifecycle-hooks/on-chat-end" + ] + }, + { + "group": "Audio", + "pages": [ + "api-reference/lifecycle-hooks/audio-start", + "api-reference/lifecycle-hooks/audio-chunk", + "api-reference/lifecycle-hooks/audio-end" + ] + }, + "api-reference/lifecycle-hooks/send-window-message", + "api-reference/lifecycle-hooks/on-window-message" ] }, { @@ -260,6 +288,24 @@ ] } }, + "redirects": [ + { + "source": "/concepts/chat-lifecycle", + "destination": "/concepts/app-lifecycle" + }, + { + "source": "/api-reference/lifecycle-hooks/on-audio-start", + "destination": "/api-reference/lifecycle-hooks/audio-start" + }, + { + "source": "/api-reference/lifecycle-hooks/on-audio-chunk", + "destination": "/api-reference/lifecycle-hooks/audio-chunk" + }, + { + "source": "/api-reference/lifecycle-hooks/on-audio-end", + "destination": "/api-reference/lifecycle-hooks/audio-end" + } + ], "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg",