feat: Google drive impersonator

.github/workflows/shared-packages.yml

@@ -184,6 +184,7 @@ jobs:
         env:
           GOOGLE_DRIVE_CLIENTID_JSON: ${{ secrets.GOOGLE_DRIVE_CLIENTID_JSON }}
           GOOGLE_SOURCE_UNIT_TEST_FOLDER: ${{ secrets.GOOGLE_SOURCE_UNIT_TEST_FOLDER }}
+          GOOGLE_DRIVE_TARGET_EMAIL: ${{ secrets.GOOGLE_DRIVE_TARGET_EMAIL }}
 
       - name: Test Report
         uses: mikepenz/action-junit-report@v4

docs/how-to/agents/define_and_use_agents.md

@@ -49,6 +49,14 @@ The result is an [AgentResult][ragbits.agents.AgentResult], which includes the m
 
 You can find the complete code example in the Ragbits repository [here](https://github.com/deepsense-ai/ragbits/blob/main/examples/agents/tool_use.py).
 
+## Tool choice
+To control what tool is used at first call you could use `tool_choice` parameter. There are the following options:
+- "auto": let model decide if tool call is needed
+- "none": do not call tool
+- "required: enforce tool usage (model decides which one)
+- Callable: one of provided tools
+
+
 ## Conversation history
 [`Agent`][ragbits.agents.Agent]s can retain conversation context across multiple interactions by enabling the `keep_history` flag when initializing the agent. This is useful when you want the agent to understand follow-up questions without needing the user to repeat earlier details.
 

docs/how-to/sources/google-drive.md

@@ -187,6 +187,50 @@ async def process_drive_documents():
 asyncio.run(process_drive_documents())
 ```
 
+## Impersonating Google Accounts
+
+You can configure your Google service account to impersonate other users in your Google Workspace domain. This is useful when you need to access files or perform actions on behalf of specific users.
+
+### Step 1: Enable Domain-Wide Delegation
+
+1. **Sign in to the [Google Admin Console](https://admin.google.com/) as a Super Admin.**
+2. Navigate to:
+    **Security > Access and data control > API controls > MANAGE DOMAIN WIDE DELEGATION**
+3. Add a new API client or edit an existing one, and include the following OAuth scopes:
+     - `https://www.googleapis.com/auth/cloud-platform`
+     - `https://www.googleapis.com/auth/drive`
+4. Click **Authorize** or **Save** to apply the changes.
+
+### Step 2: Impersonate a User in Your Code
+
+After configuring domain-wide delegation, you can specify a target user to impersonate when using the `GoogleDriveSource` in your code.
+
+```python
+from ragbits.core.sources.google_drive import GoogleDriveSource
+
+target_email = "[email protected]"
+credentials_file = "service-account-key.json"
+
+# Set the path to your service account key file
+GoogleDriveSource.set_credentials_file_path(credentials_file)
+
+# Option 1: Set default impersonation for all instances (class-level)
+GoogleDriveSource.set_default_impersonation_target(target_email)
+
+# Option 2: Set impersonation for specific instances
+sources = await GoogleDriveSource.from_uri("folder_id/**", impersonate_target_email=target_email)
+
+# Option 3: Set impersonation on individual instances
+source = GoogleDriveSource(file_id="...", file_name="...", mime_type="...")
+source.set_impersonation_target(target_email)
+```
+
+**Note:**
+- The `target_email` must be a valid user in your Google Workspace domain.
+- Ensure your service account has been granted domain-wide delegation as described above.
+
+This setup allows your service account to act on behalf of the specified user, enabling access to their Google Drive files and resources as permitted by the assigned scopes.
+
 ## Troubleshooting
 
 ### Common Issues

examples/agents/tool_use.py

@@ -82,7 +82,7 @@ async def main() -> None:
         tools=[get_weather],
         default_options=AgentOptions(max_total_tokens=500, max_turns=5),
     )
-    response = await agent.run(WeatherPromptInput(location="Paris"))
+    response = await agent.run(WeatherPromptInput(location="Paris"), tool_choice=get_weather)
     print(response)
 
 

examples/chat/README_authenticated.md

@@ -0,0 +1,215 @@
+# Authenticated Chat Example
+
+This example demonstrates how to create a chat interface with user authentication using Ragbits Chat.
+
+## Features
+
+- 🔐 **User Authentication**: Login/logout with username/password
+- 👤 **Role-based Access**: Different user roles (admin, moderator, user) with specific capabilities
+- 🛡️ **Secure Sessions**: Session-based authentication with Bearer tokens
+- 📊 **Personalized Responses**: User-specific chat responses based on profile and roles
+- 🔄 **Live Updates**: Role-specific live updates during processing
+- 📚 **User Context**: Reference documents with user profile information
+- 🎨 **UI Customization**: Custom welcome messages, headers, and branding
+- 📝 **Feedback System**: Like/dislike forms with custom Pydantic models
+- ⚙️ **User Settings**: Configurable user preferences (e.g., language selection)
+
+## Files
+
+- `authenticated_chat.py` - Main authenticated chat implementation
+- `README_authenticated.md` - This documentation
+
+## Quick Start
+
+### 1. Start the Server
+
+#### Full Authentication Support (Recommended)
+```bash
+# From the examples/chat directory - includes login/logout endpoints
+uv run python authenticated_chat.py
+```
+
+#### Alternative Methods
+```bash
+# From project root
+python examples/chat/authenticated_chat.py
+
+# Via CLI with authentication support
+uv run ragbits api run examples.chat.authenticated_chat:MyAuthenticatedChat --auth examples.chat.authenticated_chat:get_auth_backend
+```
+
+The server will start at `http://127.0.0.1:8000` with a web interface.
+
+**Note**: When using the CLI, include the `--auth` flag with the authentication backend factory function to enable full authentication features including login/logout endpoints.
+
+### 2. Test Users
+
+The example includes these test users:
+
+| Username  | Password  | Roles                    | Description         |
+|-----------|-----------|--------------------------|---------------------|
+| `admin`   | `admin123` | admin, moderator, user  | System administrator |
+| `moderator` | `mod123` | moderator, user        | Community moderator |
+| `alice`   | `alice123` | user                   | Regular user        |
+| `bob`     | `bob123`   | user                   | Regular user        |
+
+### 3. Authentication Workflow
+
+#### Web Interface
+1. Open `http://127.0.0.1:8000` in your browser
+2. Use the login form with any test user credentials
+3. Start chatting after successful authentication
+
+#### API Endpoints
+1. **Login**: `POST /api/auth/login`
+   ```json
+   {
+     "username": "admin",
+     "password": "admin123"
+   }
+   ```
+
+2. **Chat**: `POST /api/chat` (with Bearer token)
+   ```bash
+   Authorization: Bearer <session_id>
+   ```
+
+3. **Logout**: `POST /api/auth/logout`
+   ```json
+   {
+     "session_id": "<session_id>"
+   }
+   ```
+
+## Testing
+
+You can test the authentication functionality using:
+
+### Web Interface Testing
+1. Start the server: `python examples/chat/authenticated_chat.py`
+2. Open `http://127.0.0.1:8000` in your browser
+3. Use the login form with any of the test user credentials
+4. Test different roles and their specific features
+
+### API Testing with curl
+```bash
+# Login
+curl -X POST http://127.0.0.1:8000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "admin", "password": "admin123"}'
+
+# Chat (replace <session_id> with the session_id from login response)
+curl -X POST http://127.0.0.1:8000/api/chat \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <session_id>" \
+  -d '{"message": "Hello!"}'
+
+# Logout
+curl -X POST http://127.0.0.1:8000/api/auth/logout \
+  -H "Content-Type: application/json" \
+  -d '{"session_id": "<session_id>"}'
+```
+
+## Example Chat Interactions
+
+### As Admin User
+```
+💬 You: What admin features are available?
+🤖 Bot: As an administrator, you have full system access including:
+- User management and permissions
+- System configuration and monitoring
+- Content moderation capabilities
+- Administrative dashboards and reports
+```
+
+### As Regular User
+```
+💬 You: Tell me about my profile
+🤖 Bot: Hello Alice Johnson! You're logged in as 'alice' with user role.
+Your profile shows you're part of the Marketing department.
+```
+
+## Architecture
+### ListAuthBackend
+- In-memory user storage with hashed passwords
+- Session management with expiration
+- User roles and metadata support
+- Suitable for development and small deployments
+
+### Role-based Features
+- **Admin**: Full system access, admin-specific live updates, special admin profile images
+- **Moderator**: Content moderation features with policy checks and content guidelines
+- **User**: Standard chat features with personalized responses and user-specific context
+
+## Customization
+
+### Adding New Users
+Edit the `get_auth_backend()` factory function in `authenticated_chat.py`:
+
+```python
+users = [
+    {
+        "username": "newuser",
+        "password": "newpass123",
+        "email": "[email protected]",
+        "full_name": "New User",
+        "roles": ["user"],
+        "metadata": {"department": "Engineering"}
+    }
+]
+```
+
+
+### Role-specific Responses
+Modify the `chat()` method to customize responses based on user roles:
+
+```python
+# Get user info from context
+user_info = context.state.get("authenticated_user") if context else None
+user_roles = user_info.roles if user_info else []
+
+if "admin" in user_roles:
+    yield self.create_text_response("🔧 Admin-specific content...")
+elif "moderator" in user_roles:
+    yield self.create_text_response("🛡️ Moderator-specific content...")
+```
+
+### UI Customization
+
+The example demonstrates UI customization features:
+
+```python
+from ragbits.chat.interface.ui_customization import HeaderCustomization, UICustomization
+
+ui_customization = UICustomization(
+    header=HeaderCustomization(
+        title="🔐 Authenticated Ragbits Chat",
+        subtitle="by deepsense.ai - Secure Chat Experience",
+        logo="🛡️"
+    ),
+    welcome_message="🔐 **Welcome to Authenticated Ragbits Chat!**\n\n..."
+)
+```
+
+### Feedback Configuration
+
+Custom feedback forms using Pydantic models:
+
+```python
+from ragbits.chat.interface.forms import FeedbackConfig
+
+feedback_config = FeedbackConfig(
+    like_enabled=True,
+    like_form=LikeFormExample,  # Custom Pydantic model
+    dislike_enabled=True,
+    dislike_form=DislikeFormExample,  # Custom Pydantic model
+)
+```
+
+## Security Notes
+
+- Passwords are hashed using bcrypt in `ListAuthBackend`
+- Sessions have configurable expiration times
+- Bearer tokens are used for API authentication
+- CORS is configured for web interface access
+- State signatures prevent tampering with conversation state