# `vllm_mlx.gradio_app`

Gradio Chatbot Interface for vllm-mlx.

[View the complete module source at #L1-L411](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L1-L411).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: vllm_mlx.gradio_app
    options:
      members:
        - encode_file_to_base64
        - build_message_content
        - create_chat_function
        - main
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-vllm_mlx.gradio_app.encode_file_to_base64" markdown="1">
<summary><code>vllm_mlx.gradio_app.encode_file_to_base64</code> · function</summary>

```python
vllm_mlx.gradio_app.encode_file_to_base64(file_path: str) -> tuple[str, str]
```

Encode a file to base64 data URL.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `file_path` | `str` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `tuple[str, str]`
- Direct return expressions: `(f'data:{mime_type};base64,{data}', media_type)`

**Exceptions and behavior**

Function `encode_file_to_base64` calls `Path`, `path.suffix.lower`, `open`, `base64.b64encode(f.read()).decode`; returns `(f'data:{mime_type};base64,{data}', media_type)`.
No direct `raise` statement appears in this definition.

[View source #L33-L76](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L33-L76).

</details>

<details class="api-contract" id="contract-vllm_mlx.gradio_app.build_message_content" markdown="1">
<summary><code>vllm_mlx.gradio_app.build_message_content</code> · function</summary>

```python
vllm_mlx.gradio_app.build_message_content(text: str, files: list[str] | None = None) -> list | str
```

Build OpenAI-compatible message content with text and optional files.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `str` | `yes` | `none` | The text message |
| `files` | `list[str] \| None` | `no` | `None` | Optional list of file paths (images or videos) |

**Returns**

- Type: `list | str`
- Direct return expressions: `text`; `content if content else text`

**Exceptions and behavior**

Function `build_message_content` calls `content.append`, `encode_file_to_base64`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L79-L108](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L79-L108).

</details>

<details class="api-contract" id="contract-vllm_mlx.gradio_app.create_chat_function" markdown="1">
<summary><code>vllm_mlx.gradio_app.create_chat_function</code> · function</summary>

```python
vllm_mlx.gradio_app.create_chat_function(server_url: str, max_tokens: int, temperature: float, served_model_name: str = 'default') -> not annotated
```

Create the chat function for Gradio ChatInterface.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `server_url` | `str` | `yes` | `none` | URL of the vllm-mlx server |
| `max_tokens` | `int` | `yes` | `none` | Maximum tokens to generate |
| `temperature` | `float` | `yes` | `none` | Sampling temperature |
| `served_model_name` | `str` | `no` | `'default'` | Model name to send in OpenAI-compatible requests |

**Returns**

- Type: `not annotated`
- Direct return expressions: `chat`

**Exceptions and behavior**

Function `create_chat_function` returns `chat`.
No direct `raise` statement appears in this definition.

[View source #L111-L257](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L111-L257).

</details>

<details class="api-contract" id="contract-vllm_mlx.gradio_app.create_chat_function.chat" markdown="1">
<summary><code>vllm_mlx.gradio_app.create_chat_function.chat</code> · nested function</summary>

```python
vllm_mlx.gradio_app.create_chat_function.chat(message: dict, history: list) -> str
```

Process a multimodal message and return response.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `message` | `dict` | `yes` | `none` | Dict with 'text' and optional 'files' keys |
| `history` | `list` | `yes` | `none` | List of previous messages |

**Returns**

- Type: `str`
- Direct return expressions: `result['choices'][0]['message']['content']`; `'Error: Cannot connect to server. Make sure vllm-mlx is running.'`; `'Error: Timeout - server took too long to respond.'`; `f'Error: {str(e)}'`

**Exceptions and behavior**

Nested Function `create_chat_function.chat` calls `isinstance`, `message.get`, `print`, `len`; has 4 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L132-L255](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L132-L255).

</details>

<details class="api-contract" id="contract-vllm_mlx.gradio_app.main" markdown="1">
<summary><code>vllm_mlx.gradio_app.main</code> · function</summary>

```python
vllm_mlx.gradio_app.main() -> not annotated
```

Run the Gradio app.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Function `main` calls `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_args`, `print`.
No direct `raise` statement appears in this definition.

[View source #L260-L407](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L260-L407).

</details>

<details class="api-contract" id="contract-vllm_mlx.gradio_app.main.text_chat" markdown="1">
<summary><code>vllm_mlx.gradio_app.main.text_chat</code> · nested function</summary>

```python
vllm_mlx.gradio_app.main.text_chat(message: str, history: list) -> str
```

Process a text-only message.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `message` | `str` | `yes` | `none` | Required positional or keyword input. |
| `history` | `list` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `str`
- Direct return expressions: `result['choices'][0]['message']['content']`; `'Error: Cannot connect to server. Make sure vllm-mlx is running.'`; `'Error: Timeout - server took too long to respond.'`; `f'Error: {str(e)}'`

**Exceptions and behavior**

Nested Function `main.text_chat` calls `isinstance`, `msg.get`, `p.get`, `' '.join`; has 4 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L331-L368](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L331-L368).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`encode_file_to_base64`](#contract-vllm_mlx.gradio_app.encode_file_to_base64) | function | `encode_file_to_base64(file_path: str) -> tuple[str, str]` | Encode a file to base64 data URL. | [#L33-L76](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L33-L76) |
| [`build_message_content`](#contract-vllm_mlx.gradio_app.build_message_content) | function | `build_message_content(text: str, files: list[str] \| None = None) -> list \| str` | Build OpenAI-compatible message content with text and optional files. | [#L79-L108](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L79-L108) |
| [`create_chat_function`](#contract-vllm_mlx.gradio_app.create_chat_function) | function | `create_chat_function(server_url: str, max_tokens: int, temperature: float, served_model_name: str = 'default') -> not annotated` | Create the chat function for Gradio ChatInterface. | [#L111-L257](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L111-L257) |
| [`create_chat_function.chat`](#contract-vllm_mlx.gradio_app.create_chat_function.chat) | nested function | `create_chat_function.chat(message: dict, history: list) -> str` | Process a multimodal message and return response. | [#L132-L255](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L132-L255) |
| [`main`](#contract-vllm_mlx.gradio_app.main) | function | `main() -> not annotated` | Run the Gradio app. | [#L260-L407](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L260-L407) |
| [`main.text_chat`](#contract-vllm_mlx.gradio_app.main.text_chat) | nested function | `main.text_chat(message: str, history: list) -> str` | Process a text-only message. | [#L331-L368](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/gradio_app.py#L331-L368) |