Merge pull request #674 from open-webui/dev

merge dev to main

Author: Classic298

docs/features/code-execution/index.md

@@ -7,10 +7,10 @@ Open WebUI offers powerful code execution capabilities directly within your chat
 
 ## Key Features
 
-- **Python Code Execution**: Run Python scripts directly in your browser using Pyodide, with support for popular libraries like pandas and matplotlib no setup required.
+- **Python Code Execution**: Run Python scripts directly in your browser using Pyodide, with support for popular libraries like pandas and matplotlib with no setup required.
 
 - **MermaidJS Rendering**: Create and visualize flowcharts, diagrams, and other visual representations with MermaidJS syntax that automatically renders in your chat.
 
 - **Interactive Artifacts**: Generate and interact with rich content like HTML websites, SVG graphics, and JavaScript visualizations directly within your conversations.
 
-These execution capabilities bridge the gap between conversation and implementation, allowing you to explore ideas, analyze data, and create visual content seamlessly while chatting with AI models.
+These execution capabilities bridge the gap between conversation and implementation, allowing you to explore ideas, analyze data, and create visual content seamlessly while chatting with AI models.

docs/features/plugin/functions/action.mdx

@@ -3,12 +3,11 @@ sidebar_position: 3
 title: "🎬 Action Function"
 ---
 
-Action functions allow you to write custom buttons to the message toolbar for end users to interact
-with. This feature enables more interactive messaging, enabling users to grant permission before a
-task is performed, generate visualizations of structured data, download an audio snippet of chats,
-and many other use cases.
+Action functions allow you to write custom buttons that appear in the message toolbar for end users to interact with. This feature enables more interactive messaging, allowing users to grant permission before a task is performed, generate visualizations of structured data, download an audio snippet of chats, and many other use cases.
 
-A scaffold of Action code can be found [in the community section](https://openwebui.com/f/hub/custom_action/).
+Actions are admin-managed functions that extend the chat interface with custom interactive capabilities. When a message is generated by a model that has actions configured, these actions appear as clickable buttons beneath the message.
+
+A scaffold of Action code can be found [in the community section](https://openwebui.com/f/hub/custom_action/). For more Action Function examples built by the community, visit [https://openwebui.com/functions](https://openwebui.com/functions).
 
 An example of a graph visualization Action can be seen in the video below.
 
@@ -21,46 +20,195 @@ An example of a graph visualization Action can be seen in the video below.
 	</a>
 </p>
 
-### Action
+## Action Function Architecture
 
-Actions are used to create a button in the Message UI (the small buttons found directly underneath individual chat messages).
+Actions are Python-based functions that integrate directly into the chat message toolbar. They execute server-side and can interact with users through real-time events, modify message content, and access the full Open WebUI context.
 
-Actions have a single main component called an action function. This component takes an object defining the type of action and the data being processed.
+### Function Structure
 
-<details>
-<summary>Example</summary>
+Actions follow a specific class structure with an `action` method as the main entry point:
 
 ```python
-async def action(
-        self,
-        body: dict,
-        __user__=None,
-        __event_emitter__=None,
-        __event_call__=None,
-    ) -> Optional[dict]:
-        print(f"action:{__name__}")
+class Action:
+    def __init__(self):
+        self.valves = self.Valves()
+    
+    class Valves(BaseModel):
+        # Configuration parameters
+        parameter_name: str = "default_value"
+    
+    async def action(self, body: dict, __user__=None, __event_emitter__=None, __event_call__=None):
+        # Action implementation
+        return {"content": "Modified message content"}
+```
+
+### Action Method Parameters
+
+The `action` method receives several parameters that provide access to the execution context:
+
+- **`body`** - Dictionary containing the message data and context
+- **`__user__`** - Current user object with permissions and settings
+- **`__event_emitter__`** - Function to send real-time updates to the frontend
+- **`__event_call__`** - Function for bidirectional communication (confirmations, inputs)
+- **`__model__`** - Model information that triggered the action
+- **`__request__`** - FastAPI request object for accessing headers, etc.
+- **`__id__`** - Action ID (useful for multi-action functions)
+
+## Event System Integration
+
+Actions can utilize Open WebUI's real-time event system for interactive experiences:
+
+### Event Emitter (`__event_emitter__`)
+
+**For more information about Events and Event emitters, [see here](https://docs.openwebui.com/features/plugin/events/).**
+
+Send real-time updates to the frontend during action execution:
+
+```python
+async def action(self, body: dict, __event_emitter__=None):
+    # Send status updates
+    await __event_emitter__({
+        "type": "status", 
+        "data": {"description": "Processing request..."}
+    })
+    
+    # Send notifications
+    await __event_emitter__({
+        "type": "notification",
+        "data": {"type": "info", "content": "Action completed successfully"}
+    })
+```
+
+### Event Call (`__event_call__`)
+Request user input or confirmation during execution:
+
+```python
+async def action(self, body: dict, __event_call__=None):
+    # Request user confirmation
+    response = await __event_call__({
+        "type": "confirmation",
+        "data": {
+            "title": "Confirm Action",
+            "message": "Are you sure you want to proceed?"
+        }
+    })
+    
+    # Request user input
+    user_input = await __event_call__({
+        "type": "input",
+        "data": {
+            "title": "Enter Value",
+            "message": "Please provide additional information:",
+            "placeholder": "Type your input here..."
+        }
+    })
+```
+
+## Action Types and Configurations
+
+### Single Actions
+Standard actions with one `action` method:
+
+```python
+async def action(self, body: dict, **kwargs):
+    # Single action implementation
+    return {"content": "Action result"}
+```
+
+### Multi-Actions
+Functions can define multiple sub-actions through an `actions` array:
+
+```python
+actions = [
+    {
+        "id": "summarize",
+        "name": "Summarize",
+        "icon_url": "data:image/svg+xml;base64,..."
+    },
+    {
+        "id": "translate",
+        "name": "Translate", 
+        "icon_url": "data:image/svg+xml;base64,..."
+    }
+]
+
+async def action(self, body: dict, __id__=None, **kwargs):
+    if __id__ == "summarize":
+        # Summarization logic
+        return {"content": "Summary: ..."}
+    elif __id__ == "translate":
+        # Translation logic  
+        return {"content": "Translation: ..."}
+```
+
+### Global vs Model-Specific Actions
+- **Global Actions** - Turn on the toggle in the Action's settings, to globally enable it for all users and all models.
+- **Model-Specific Actions** - Configure enabled actions for specific models in the model settings.
+
+## Advanced Capabilities
 
-        response = await __event_call__(
+### Background Task Execution
+For long-running operations, actions can integrate with the task system:
+
+```python
+async def action(self, body: dict, __event_emitter__=None):
+    # Start long-running process
+    await __event_emitter__({
+        "type": "status",
+        "data": {"description": "Starting background processing..."}
+    })
+    
+    # Perform time-consuming operation
+    result = await some_long_running_function()
+    
+    return {"content": f"Processing completed: {result}"}
+```
+
+### File and Media Handling
+Actions can work with uploaded files and generate new media:
+
+```python
+async def action(self, body: dict):
+    message = body
+    
+    # Access uploaded files
+    if message.get("files"):
+        for file in message["files"]:
+            # Process file based on type
+            if file["type"] == "image":
+                # Image processing logic
+                pass
+    
+    # Return new files
+    return {
+        "content": "Analysis complete",
+        "files": [
             {
-                "type": "input",
-                "data": {
-                    "title": "write a message",
-                    "message": "here write a message to append",
-                    "placeholder": "enter your message",
-                },
+                "type": "image",
+                "url": "generated_chart.png",
+                "name": "Analysis Chart"
             }
-        )
-        print(response)
+        ]
+    }
 ```
 
-</details>
+### User Context and Permissions
+Actions can access user information and respect permissions:
+
+```python
+async def action(self, body: dict, __user__=None):
+    if __user__["role"] != "admin":
+        return {"content": "This action requires admin privileges"}
+    
+    user_name = __user__["name"]
+    return {"content": f"Hello {user_name}, admin action completed"}
+```
 
-### Example - Specifying Action Frontmatter
+## Example - Specifying Action Frontmatter
 
 Each Action function can include a docstring at the top to define metadata for the button. This helps customize the display and behavior of your Action in Open WebUI.
 
 Example of supported frontmatter fields:
-
 - `title`: Display name of the Action.
 - `author`: Name of the creator.
 - `version`: Version number of the Action.
@@ -69,13 +217,100 @@ Example of supported frontmatter fields:
 
 **Base64-Encoded Example:**
 
+<details>
+<summary>Example</summary>
+
 ```python
 """
-title: Summarize Text
-author: @you
-version: 1.0.0
+title: Enhanced Message Processor
+author: @admin
+version: 1.2.0
 required_open_webui_version: 0.5.0
-icon_url: data:image/svg+xml;base64,<IMAGE STRING>...
+icon_url: data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTEyIDJMMTMuMDkgOC4yNkwyMCA5TDEzLjA5IDE1Ljc0TDEyIDIyTDEwLjkxIDE1Ljc0TDQgOUwxMC45MSA4LjI2TDEyIDJaIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz4KPHN2Zz4K
+requirements: requests,beautifulsoup4
 """
 
+from pydantic import BaseModel
+
+class Action:
+    def __init__(self):
+        self.valves = self.Valves()
+
+    class Valves(BaseModel):
+        api_key: str = ""
+        processing_mode: str = "standard"
+
+    async def action(
+        self,
+        body: dict,
+        __user__=None,
+        __event_emitter__=None,
+        __event_call__=None,
+    ):
+        # Send initial status
+        await __event_emitter__({
+            "type": "status",
+            "data": {"description": "Processing message..."}
+        })
+        
+        # Get user confirmation
+        response = await __event_call__({
+            "type": "confirmation",
+            "data": {
+                "title": "Process Message",
+                "message": "Do you want to enhance this message?"
+            }
+        })
+        
+        if not response:
+            return {"content": "Action cancelled by user"}
+        
+        # Process the message
+        original_content = body.get("content", "")
+        enhanced_content = f"Enhanced: {original_content}"
+        
+        return {"content": enhanced_content}
 ```
+
+</details>
+
+## Best Practices
+
+### Error Handling
+Always implement proper error handling in your actions:
+
+```python
+async def action(self, body: dict, __event_emitter__=None):
+    try:
+        # Action logic here
+        result = perform_operation()
+        return {"content": f"Success: {result}"}
+    except Exception as e:
+        await __event_emitter__({
+            "type": "notification",
+            "data": {"type": "error", "content": f"Action failed: {str(e)}"}
+        })
+        return {"content": "Action encountered an error"}
+```
+
+### Performance Considerations
+- Use async/await for I/O operations
+- Implement timeouts for external API calls
+- Provide progress updates for long-running operations
+- Consider using background tasks for heavy processing
+
+### User Experience
+- Always provide clear feedback through event emitters
+- Use confirmation dialogs for destructive actions
+- Include helpful error messages
+
+## Integration with Open WebUI Features
+
+Actions integrate seamlessly with other Open WebUI features:
+- **Models** - Actions can be model-specific or global
+- **Tools** - Actions can invoke external tools and APIs
+- **Files** - Actions can process uploaded files and generate new ones
+- **Memory** - Actions can access conversation history and context
+- **Permissions** - Actions respect user roles and access controls
+
+For more examples and community-contributed actions, visit [https://openwebui.com/functions](https://openwebui.com/functions) where you can discover, download, and explore custom functions built by the Open WebUI community.

docs/getting-started/advanced-topics/development.md

@@ -14,7 +14,7 @@ Before you begin, ensure your system meets these minimum requirements:
 - **Operating System:** Linux (or WSL on Windows), Windows 11, or macOS. *(Recommended for best compatibility)*
 - **Python:** Version **3.11 or higher**. *(Required for backend services)*
 - **Node.js:** Version **22.10 or higher**. *(Required for frontend development)*
-- **IDE (Recommended):** We recommend using an IDE like [VSCode](https://code.visualstudio.com/) for code editing, debugging, and integrated terminal access. Feel free to use your favorite IDE if you have one!
+- **IDE (Recommended):** We recommend using an IDE like [VS Code](https://code.visualstudio.com/) for code editing, debugging, and integrated terminal access. Feel free to use your favorite IDE if you have one!
 - **[Optional] GitHub Desktop:** For easier management of the Git repository, especially if you are less familiar with command-line Git, consider installing [GitHub Desktop](https://desktop.github.com/).
 
 ## Setting Up Your Local Environment
@@ -49,7 +49,7 @@ Let's get the user interface (what you see in your browser) up and running first
 
      This command copies the `.env.example` file to a new file named `.env`. The `.env` file is where you'll configure environment variables for the frontend.
 
-   - **Customize `.env`**: Open the `.env` file in your code editor (like VSCode). This file contains configuration variables for the frontend, such as API endpoints and other settings. For local development, the default settings in `.env.example` are usually sufficient to start with. However, you can customize them if needed.
+   - **Customize `.env`**: Open the `.env` file in your code editor (like VS Code). This file contains configuration variables for the frontend, such as API endpoints and other settings. For local development, the default settings in `.env.example` are usually sufficient to start with. However, you can customize them if needed.
 
   **Important:** Do not commit sensitive information to `.env` if you are contributing back to the repository.
 
@@ -107,17 +107,17 @@ npm run build
 
 We **require** you to use separate terminal instances for your frontend and backend processes. This keeps your workflows organized and makes it easier to manage each part of the application independently.
 
-**Using VSCode Integrated Terminals:**
+**Using VS Code Integrated Terminals:**
 
-VSCode's integrated terminal feature makes managing multiple terminals incredibly easy. Here's how to leverage it for frontend and backend separation:
+VS Code's integrated terminal feature makes managing multiple terminals incredibly easy. Here's how to leverage it for frontend and backend separation:
 
-1. **Frontend Terminal (You likely already have this):** If you followed the Frontend Setup steps, you probably already have a terminal open in VSCode at the project root (`open-webui` directory). This is where you'll run your frontend commands (`npm run dev`, etc.). Ensure you are in the `open-webui` directory for the next steps if you are not already.
+1. **Frontend Terminal (You likely already have this):** If you followed the Frontend Setup steps, you probably already have a terminal open in VS Code at the project root (`open-webui` directory). This is where you'll run your frontend commands (`npm run dev`, etc.). Ensure you are in the `open-webui` directory for the next steps if you are not already.
 
 2. **Backend Terminal (Open a New One):**
-   - In VSCode, go to **Terminal > New Terminal** (or use the shortcut `Ctrl+Shift+` on Windows/Linux or `Cmd+Shift+` on macOS). This will open a new integrated terminal panel.
+   - In VS Code, go to **Terminal > New Terminal** (or use the shortcut `Ctrl+Shift+` on Windows/Linux or `Cmd+Shift+` on macOS). This will open a new integrated terminal panel.
    - **Navigate to the `backend` directory:** In this *new* terminal, use the `cd backend` command to change the directory to the `backend` folder within your project. This ensures all backend-related commands are executed in the correct context.
 
-   Now you have **two separate terminal instances within VSCode**: one for the frontend (likely in the `open-webui` directory) and one specifically for the backend (inside the `backend` directory). You can easily switch between these terminals within VSCode to manage your frontend and backend processes independently. This setup is highly recommended for a cleaner and more efficient development workflow.
+   Now you have **two separate terminal instances within VS Code**: one for the frontend (likely in the `open-webui` directory) and one specifically for the backend (inside the `backend` directory). You can easily switch between these terminals within VS Code to manage your frontend and backend processes independently. This setup is highly recommended for a cleaner and more efficient development workflow.
 
 **Backend Setup Steps (in your *backend* terminal):**