Adjust changelog entry date

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [ "main" ]
+  push:
+    branches:
+      - "**"
+    tags: [ "v*" ]
+permissions:
+  contents: read
+  pull-requests: read
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+jobs:
+  prek:
+    name: Lint, format & test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # Toolchain version + components come from rust-toolchain.toml. rustflags is
+      # cleared so plain builds don't fail on warnings; the clippy hook still does.
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          rustflags: ''
+
+      - name: Install SQLite3
+        run: sudo apt-get update && sudo apt-get install -y libsqlite3-dev
+
+      # just drives the prek recipes; mise provides the pinned prek (mise.toml).
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: just
+      - uses: jdx/mise-action@v4
+
+      # Run the same prek hooks devs run locally; .pre-commit-config.yaml is the
+      # source of truth. Tests are a separate step for visible timing.
+      - name: Lint & format (prek hooks, excluding tests)
+        run: just prek-run-on-all --skip test-unit
+
+      - name: Unit tests
+        run: just test

.github/workflows/publish.yml

@@ -0,0 +1,124 @@
+name: Publish
+on:
+  workflow_run:
+    workflows: [ "CI" ]
+    types: [ "completed" ]
+permissions:
+  contents: read
+concurrency:
+  group: publish-${{ github.event.workflow_run.id || github.ref }}
+  cancel-in-progress: false
+jobs:
+  docker-clean-metadata:
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      (
+        github.event.workflow_run.head_branch == 'main' ||
+        startsWith(github.event.workflow_run.head_branch || '', 'v')
+      )
+    runs-on: ubuntu-latest
+    outputs:
+      json: ${{ steps.meta.outputs.json }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable=${{ github.event.workflow_run.head_branch == 'main' }}
+            type=semver,pattern={{raw}},value=${{ github.event.workflow_run.head_branch }},enable=${{ startsWith(github.event.workflow_run.head_branch || '', 'v') }}
+
+  docker-build:
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      (
+        github.event.workflow_run.head_branch == 'main' ||
+        startsWith(github.event.workflow_run.head_branch || '', 'v')
+      )
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    strategy:
+      matrix:
+        include:
+          - os: self-hosted
+            arch: amd64
+          - os: ubuntu-24.04-arm
+            arch: arm64
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+      - name: Log in to the GitHub Container registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          tags: |
+            type=raw,value=latest,enable=${{ github.event.workflow_run.head_branch == 'main' }}
+            type=semver,pattern={{raw}},value=${{ github.event.workflow_run.head_branch }},enable=${{ startsWith(github.event.workflow_run.head_branch || '', 'v') }}
+          flavor: |
+            latest=auto
+            suffix=-${{ matrix.arch }},onlatest=true
+          images: |
+            ghcr.io/${{ github.repository }}
+
+      - name: Build and push Docker images
+        uses: docker/build-push-action@v7
+        with:
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  docker-manifest:
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      (
+        github.event.workflow_run.head_branch == 'main' ||
+        startsWith(github.event.workflow_run.head_branch || '', 'v')
+      )
+    permissions:
+      contents: read
+      packages: write
+    needs:
+      - docker-build
+      - docker-clean-metadata
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        image: ${{ fromJson(needs.docker-clean-metadata.outputs.json).tags }}
+
+    steps:
+      - name: Log in to the GitHub Container registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push manifest
+        run: |
+          docker buildx imagetools create -t ${{ matrix.image }} ${{ matrix.image }}-amd64 ${{ matrix.image }}-arm64

.github/workflows/workflow.yml

@@ -1,51 +0,0 @@
-name: CI (main and tags)
-on:
-  push:
-    branches: [ "main" ]
-    tags: [ "v*" ]
-  schedule:
-    - cron: '0 0 * * 1'
-permissions:
-  checks: write
-  contents: write
-  packages: write
-  pull-requests: read
-jobs:
-  test-and-clippy:
-    name: Unit testing and linting
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - run: cargo test --all-features
-      - run: cargo clippy
-
-  build-publish:
-    name: Build and Publish
-    runs-on: self-hosted
-    steps:
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v1
-      - name: Login to ghcr.io
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: |
-            ghcr.io/${{ github.repository }}
-            registry.etke.cc/${{ github.repository }}
-          tags: |
-            type=raw,value=latest,enable=${{ github.ref_name == 'main' }}
-            type=semver,pattern={{raw}}
-      - name: Build and push
-        uses: docker/build-push-action@v6
-        with:
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}

.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+repos:
+  # Fast built-in hooks (Rust-native, no dependencies)
+  - repo: builtin
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=1024']
+
+  # Local hooks that run project-specific tools
+  - repo: local
+    hooks:
+      - id: cargo-fmt-check
+        name: Cargo Format Check
+        entry: cargo fmt --all -- --check
+        language: system
+        files: '\.rs$'
+        pass_filenames: false
+
+      - id: cargo-clippy
+        name: Cargo Clippy
+        entry: cargo clippy -- -D warnings
+        language: system
+        files: '\.rs$'
+        pass_filenames: false
+        priority: 100
+
+      - id: test-unit
+        name: Unit Tests
+        entry: just test
+        language: system
+        files: '\.rs$'
+        pass_filenames: false
+        priority: 100

CHANGELOG.md

@@ -1,3 +1,377 @@
+# (2026-06-29) Version 1.25.0
+
+- (**Feature**) [♻️ Context management](./docs/configuration/text-generation.md#️-context-management) now works with every provider, not only [OpenAI](./docs/providers.md#openai). Token counting previously went through [tiktoken-rs](https://github.com/zurawiki/tiktoken-rs), which is accurate only for OpenAI models and silently mis-counted everything else (worst of all for non-English text). OpenAI agents keep using tiktoken-rs; every other provider, including the recommended [Venice](./docs/providers.md#venice), now uses a provider-neutral approximation that needs no per-model tokenizer (ASCII counted at about four characters per token, other scripts such as Cyrillic and CJK at about two), landing within roughly 10-20% of the real count. See the [context management docs](./docs/configuration/text-generation.md#️-context-management).
+
+- (**Improvement**) Context management now trims a conversation on whole-turn boundaries for every provider, so an assistant reply is never kept without the user message it answered. This also adjusts how the OpenAI provider trims: a dangling assistant reply at the oldest edge of the kept history is now dropped along with its missing prompt, rather than left in place.
+
+
+# (2026-06-26) Version 1.24.0
+
+- (**Feature**) Add an opt-in 💭 **thinking notice** for text generation. When enabled, a slow response (for example, from a reasoning model that runs for minutes) posts a "thinking…" placeholder after a short delay, refreshes it periodically with varying flavor text, and then edits that same message into the final answer, so a long wait no longer looks like a stuck bot. The notice is **disabled by default** and configurable per-room or globally via `text-generation set-thinking-notice-enabled true`. Fast responses (under the delay threshold) never show a placeholder. See the [text-generation configuration docs](./docs/configuration/text-generation.md#-thinking-notice).
+
+- (**Bugfix**) The [Venice](https://venice.ai) unsupported-field auto-recovery (added in 1.23.1) now actually remembers rejections across messages. The cache lived on the provider's controller, which is rebuilt on every message for room-local and global agents, so each turn started with an empty cache, re-sent the unsupported field, and logged the same `400 Bad Request` warning again. The cache is now process-global (keyed per Venice deployment), so a field a model rejects is dropped proactively on every later request instead of being re-discovered each turn.
+
+
+# (2026-06-24) Version 1.23.1
+
+- (**Bugfix**) The [Venice](https://venice.ai) provider now auto-recovers when a model rejects an optional knob it does not support. Venice's request body is strict (`additionalProperties: false`), so a model that lacks `prompt_cache_retention`, `reasoning_effort`, or `prompt_cache_key` rejected the whole request with a `400 Bad Request` — breaking agent creation and every reply. baibot now drops the unsupported field and retries, remembering the rejection per model so later requests skip it without a wasted round-trip. Only these meaning-preserving fields are dropped; sampling knobs that change the output (`temperature`, `top_p`, the penalties) are never silently removed and still surface as an error.
+
+- (**Improvement**) When Venice rejects a request with a `400 Bad Request`, baibot now surfaces Venice's actual error message (e.g. `Extra inputs are not permitted, field: 'prompt_cache_retention'`) instead of a generic "configuration does not result in a working agent". This makes agent-creation failures self-explanatory. Other error statuses keep their bodies redacted, since those can carry account or rate-limit details.
+
+
+# (2026-06-23) Version 1.23.0
+
+- (**Feature**) The [Venice](https://venice.ai) provider now accepts file inputs (PDF, DOCX, and other documents, up to 25MB), the same way it already handled images. This makes Venice the second provider after OpenAI to accept files; the others (Anthropic and the OpenAI-compatible providers) skip them. See the [text-generation feature docs](./docs/features.md#-text-generation).
+
+- (**Feature**) Add prompt caching to the Venice provider, on by default (`prompt_cache_retention: 24h`). baibot derives the cache key from the system prompt and the conversation start time (both fixed for the life of a conversation), so a long, stable system prompt stays cached across the day instead of being reprocessed and re-billed on every turn. See [Text Generation / Prompt Override](./docs/configuration/text-generation.md#️-prompt-override).
+
+- (**Feature**) Wire up the rest of Venice's sampling and reasoning controls: top-level `top_p`, `frequency_penalty`, `presence_penalty`, `repetition_penalty`, and `reasoning_effort`; `verbosity` in the `venice_parameters` bag; and a `show_reasoning` toggle that appends the model's reasoning to the reply as a collapsible, folded-by-default `💭 Reasoning` block (off by default). See the [Venice configuration reference](./docs/providers.md#venice).
+
+- (**Feature**) Render Venice web-search citations as readable `[n]` references with a `Sources:` list of links, instead of leaving Venice's raw `^n^` superscripts in the reply.
+
+- (**Security**) Escape citation titles and validate citation URLs before rendering them, and drop user-supplied filenames from error messages, so a hostile web page or a crafted filename cannot inject a spoofed link into the bot's reply.
+
+- (**Bugfix**) The [OpenAI-compatible](./docs/providers.md#openai-compatible) provider now trusts the system CA store (honoring `SSL_CERT_FILE`), so endpoints served behind a private/internal CA (FreeIPA, organization PKI) no longer fail the TLS handshake with `invalid peer certificate: UnknownIssuer`. Fixed upstream in `etke_openai_api_rust` 0.1.10. Thanks to [@shaba](https://github.com/shaba) for the report in [#188](https://github.com/etkecc/baibot/pull/188).
+
+
+# (2026-06-21) Version 1.22.0
+
+- (**Feature**) Add a native [Venice](https://venice.ai) provider with [🖌️ image-generation](./docs/features.md#️-image-creation) (incl. editing), [💬 text-generation](./docs/features.md#-text-generation) (incl. vision), [🗣️ text-to-speech](./docs/features.md#️-text-to-speech), [🦻 speech-to-text](./docs/features.md#-speech-to-text), and Venice's native web search via the full `venice_parameters` knob set. Unlike the [OpenAI-compatible](./docs/providers.md#openai-compatible) path (which drops images and can't reach Venice's audio or native image endpoints), it talks to Venice's API directly, using the knob-rich native `/image/generate` and `/image/edit` endpoints. See the [Venice provider docs](./docs/providers.md#venice).
+
+
+# (2026-06-05) Version 1.21.1
+
+- (**Security**) Update the [anthropic](https://github.com/etkecc/anthropic-rs) dependency to use [reqwest](https://crates.io/crates/reqwest) 0.12 / [rustls](https://crates.io/crates/rustls) 0.23, replacing the vulnerable `rustls-webpki` 0.101 line with 0.103.13. This resolves [`GHSA-82j2-j2ch-gfr8`](https://github.com/advisories/GHSA-82j2-j2ch-gfr8) (high — denial of service via panic on a malformed CRL), [`GHSA-xgp8-3hg3-c2mh`](https://github.com/advisories/GHSA-xgp8-3hg3-c2mh) and [`GHSA-965h-392x-2mh5`](https://github.com/advisories/GHSA-965h-392x-2mh5) (name-constraint validation issues).
+
+
+# (2026-06-05) Version 1.21.0
+
+- (**Improvement**) Default to OpenAI's `gpt-image-2` model for image generation (in newly-created OpenAI agents and the sample provider configs).
+
+- (**Internal Improvement**) Update [async-openai](https://crates.io/crates/async-openai) from 0.40 to 0.41, which [resynchronizes with the upstream OpenAI API spec](https://github.com/64bit/async-openai/issues/557) after it had drifted out of sync — a mismatch that was already causing some breakage (hopefully now resolved). Adapts to the newly-added `gpt-image-2` image model and an `ImageSize` type change.
+
+- (**Internal Improvement**) Dependency updates.
+
+
+# (2026-06-02) Version 1.20.0
+
+- (**Internal Improvement**) Update [matrix-sdk](https://crates.io/crates/matrix-sdk) from 0.17 to 0.18 and [mxlink](https://crates.io/crates/mxlink) to 1.15.0.
+
+- (**Internal Improvement**) Update [tiktoken-rs](https://crates.io/crates/tiktoken-rs) to 0.12, backporting OpenAI [tiktoken](https://github.com/openai/tiktoken) 0.13.0 for better alignment with upstream tokenization behavior.
+
+- (**Internal Improvement**) Bump the pinned Rust toolchain from 1.95.0 to 1.96.0 (in `rust-toolchain.toml` and the Docker build images).
+
+- (**Internal Improvement**) Dependency updates.
+
+
+# (2026-05-27) Version 1.19.3
+
+- (**Internal Improvement**) Update [async-openai](https://crates.io/crates/async-openai) to 0.40.2, pulling in several upstream fixes (streaming HTTP error surfacing, default `ResponseTextParam.format` deserialization, etc.).
+
+- (**Internal Improvement**) Dependency updates.
+
+
+# (2026-05-21) Version 1.19.2
+
+- (**Internal Improvement**) Update [async-openai](https://crates.io/crates/async-openai) to 0.40.0.
+
+- (**Internal Improvement**) Dependency updates.
+
+
+# (2026-05-09) Version 1.19.1
+
+- (**Internal Improvement**) Update [async-openai](https://crates.io/crates/async-openai) to 0.38.0.
+
+- (**Internal Improvement**) Dependency updates.
+
+
+# (2026-05-09) Version 1.19.0
+
+- (**Internal Improvement**) Update [matrix-sdk](https://crates.io/crates/matrix-sdk) from 0.16 to 0.17 and [mxlink](https://crates.io/crates/mxlink) to 1.14.0. matrix-sdk 0.17 dropped its `native-tls` feature and now uses [rustls](https://github.com/rustls/rustls) exclusively as its TLS backend.
+
+- (**Internal Improvement**) Bump the pinned Rust toolchain from 1.93.0 to 1.95.0 (in `rust-toolchain.toml` and the Docker build images).
+
+- (**Internal Improvement**) Dependency updates.
+
+
+# (2026-04-11) Version 1.18.0
+
+- (**Bugfix**) Fix the bot not sending a welcome message when joining a room on homeservers (like [Continuwuity](https://continuwuity.org/)) that place the join membership event in the sync response's `state` block rather than the `timeline` block, via [mxlink](https://crates.io/crates/mxlink) 1.13.1
+
+- (**Improvement**) Update [tiktoken-rs](https://crates.io/crates/tiktoken-rs) to 0.11, adding tokenization support for newer GPT models (gpt-5.x, codex, etc.) and fixing context sizes for o1-mini/chatgpt-4o/gpt-4.5
+
+- (**Internal Improvement**) Dependency updates
+
+
+# (2026-03-25) Version 1.17.0
+
+- (**Feature**) Add `text-generation sender-context-mode` for attaching sender metadata to conversation messages. See the [💬 Text Generation](./docs/configuration/text-generation.md#-sender-context-mode) documentation for details. Thanks to [kschwank](https://github.com/kschwank) for the contribution in [#104](https://github.com/etkecc/baibot/pull/104)!
+
+
+# (2026-03-24) Version 1.16.1
+
+- (**Bugfix**) Fix compatibility with [async-openai](https://crates.io/crates/async-openai) 0.34.0 by populating the new `phase` field required for OpenAI Responses API message inputs. baibot does not currently distinguish between assistant `commentary` and `final_answer` turns, so using `None` preserves the previous behavior while remaining compatible with the updated crate.
+
+- (**Internal Improvement**) Dependency updates.
+
+
+# (2026-03-20) Version 1.16.0
+
+- (**Feature**) Add support for file attachments (`m.file` Matrix messages) in conversations. Files like PDFs, text documents, spreadsheets, code files, etc. are now downloaded and forwarded to the LLM alongside the conversation context, similar to how images (`m.image`) are already handled. See the [💬 Text Generation](./docs/features.md#-text-generation) documentation for details and known limitations.
+
+- (**Improvement**) Use the [mime_guess](https://crates.io/crates/mime_guess) crate for MIME type detection from file extensions, replacing a hand-maintained mapping. This covers hundreds of file extensions out of the box.
+
+
+
+# (2026-03-07) Version 1.15.0
+
+- (**Feature**) Add support for authentication via access tokens (for [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service)/OIDC-enabled homeservers) as an alternative to password authentication. See [🔐 Authentication](./docs/configuration/authentication.md) for setup details. Thanks to [Taylor Southwick](https://github.com/twsouthwick) for the contribution in [#83](https://github.com/etkecc/baibot/pull/83)!
+
+- (**Internal Improvement**) Pin the Rust toolchain to `1.93.0` in both CI and local development to avoid `matrix-sdk` build failures on newer stable toolchains.
+
+- (**Internal Improvement**) Documentation updates.
+
+- (**Internal Improvement**) Dependency updates.
+
+
+# (2026-02-18) Version 1.14.3
+
+- (**Internal Improvement**) Add [Renovate](https://docs.renovatebot.com/) configuration for automated dependency updates
+
+- (**Internal Improvement**) Dependency updates
+
+
+# (2026-02-18) Version 1.14.2
+
+- (**Internal Improvement**) Dependency updates
+
+- (**Internal Improvement**) Reorganize the development environment to support [Continuwuity](https://continuwuity.org/) as a homeserver choice (in addition to [Synapse](https://github.com/element-hq/synapse)). Continuwuity is now the default for its lighter footprint (no external database required). See [development docs](./docs/development.md) for details.
+
+
+# (2026-02-10) Version 1.14.1
+
+- (**Security**) Dependency updates to fix security vulnerabilities ([time](https://crates.io/crates/time) stack exhaustion DoS, [bytes](https://crates.io/crates/bytes) integer overflow), via [mxlink](https://crates.io/crates/mxlink) 1.12.0
+
+- (**Internal Improvement**) Switch from deprecated [serde_yaml](https://crates.io/crates/serde_yaml) to its maintained fork [serde_yaml_ng](https://crates.io/crates/serde_yaml_ng)
+
+- (**Internal Improvement**) Add [prek](https://github.com/nicholasgasior/prek) pre-commit hooks via [mise](https://mise.jdx.dev/) for automated code quality checks (formatting, clippy, tests)
+
+- (**Internal Improvement**) Fix clippy warnings and formatting issues
+
+
+# (2026-02-04) Version 1.14.0
+
+- (**Feature**) The `openai` provider now uses OpenAI's [Responses API](https://platform.openai.com/docs/api-reference/responses) (instead of the older Chat Completions API), adding support for [🛠️ built-in tools](./docs/features.md#️-built-in-tools-openai-only) (`web_search` and `code_interpreter`). These tools are **disabled by default** and can be enabled via the `text_generation.tools` configuration (see the [sample configuration](https://github.com/etkecc/baibot/blob/c70387b0c38d8d0f30bba2179a2a21a3710dbeaf/docs/sample-provider-configs/openai.yml#L12-L15)). To enable tools on an existing agent, you need to [update the agent](./docs/agents.md#updating-agents) to re-create it with the `text_generation.tools` section added and enable the tools you need. Thanks to [Layla Manley](https://github.com/yeslayla) for the contribution in [#62](https://github.com/etkecc/baibot/pull/62)!
+
+- (**Bugfix**) Fix sticker generation for newer GPT image models (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`) which don't support the previously hardcoded `256x256` size (minimum is `1024x1024`)
+
+- (**Internal Improvement**) Dependency updates
+
+
+# (2026-01-23) Version 1.13.0
+
+- (**Improvement**) Extend auto-switching to support cheaper models (`gpt-image-1-mini`) for `gpt-image-1` and `gpt-image-1.5` when generating stickers ([e0b4a40](https://github.com/etkecc/baibot/commit/e0b4a40))
+
+- (**Internal Improvement**) Upgrade Rust compiler (1.92.0 -> 1.93.0) ([691aeeb](https://github.com/etkecc/baibot/commit/691aeeb))
+
+- (**Internal Improvement**) Dependency updates
+
+
+# (2025-12-21) Version 1.12.0
+
+- (**Improvement**) Upgrade [async-openai](https://crates.io/crates/async-openai) (0.31.1 -> 0.32.2) and add support for OpenAI's `gpt-image-1.5` model ([08c689a](https://github.com/etkecc/baibot/commit/08c689a), [f7bf3d7](https://github.com/etkecc/baibot/commit/f7bf3d7))
+
+- (**Internal Improvement**) Dependency updates
+
+
+# (2025-12-15) Version 1.11.0
+
+- (**Feature**) Add support for custom avatars via file path and for keeping the already-set avatar (for those who wish to manage it by themselves via other means). See the [sample config](./etc/app/config.yml.dist) for details. ([062fbbb](https://github.com/etkecc/baibot/commit/062fbbb8ef9ad600db483a431c5c782402191023))
+
+- (**Internal Improvement**) Dependency updates ([99bde53](https://github.com/etkecc/baibot/commit/99bde53ef648a5a9086a96778fde4a9dbc1ede58))
+
+- (**Internal Improvement**) Documentation updates ([b3fd8e5](https://github.com/etkecc/baibot/commit/b3fd8e548f83fe46398ced4760d7e2bb7588c24d))
+
+- (**Internal Improvement**) Upgrade Rust compiler (1.91.1 -> 1.92.0) ([22906aa](https://github.com/etkecc/baibot/commit/22906aa2d3cae51815fad2560a545eaa69c247b6))
+
+
+# (2025-12-06) Version 1.10.0
+
+- (**Internal Improvement**) Dependency updates. This version is based on [mxlink](https://crates.io/crates/mxlink)@1.11.0 (which is based on the newly released [matrix-sdk](https://crates.io/crates/matrix-sdk)@[0.16.0](https://github.com/matrix-org/matrix-rust-sdk/releases/tag/matrix-sdk-0.16.0).
+
+# (2025-11-30) Version 1.9.0
+
+- (**Internal Improvement**) Upgrade [async-openai](https://crates.io/crates/async-openai) from our own etkecc fork (0.28.1-patched) to the official upstream version 0.31.1. This upgrade required some code adaptations to the new module structure, etc. While tested, regressions are possible.
+
+# (2025-11-28) Version 1.8.3
+
+- (**Improvement**) Add support for the `BAIBOT_PERSISTENCE_SESSION_ENCRYPTION_KEY` environment variable for configuring `persistence.session_encryption_key`
+
+- (**Improvement**) Add support for the `BAIBOT_USER_ENCRYPTION_RECOVERY_RESET_ALLOWED` environment variable for configuring `user.encryption.recovery_reset_allowed`
+
+- (**Internal Improvement**) Dependency updates.
+
+# (2025-11-20) Version 1.8.2
+
+- (**Internal Improvement**) Dependency and compiler updates (Rust 1.89.0 -> 1.91.1).
+
+# (2025-09-12) Version 1.8.1
+
+- (**Internal Improvement**) Dependency updates.
+
+# (2025-09-08) Version 1.8.0
+
+- (**Internal Improvement**) Upgrade [mxlink](https://crates.io/crates/mxlink) (1.9.0 -> 1.10.0) and [matrix-sdk](https://crates.io/crates/matrix-sdk) (0.13.0 -> 0.14.0)
+
+- (**Internal Improvement**) Upgrade [Rust](https://www.rust-lang.org/) (1.88.0 -> 1.89.0)
+
+- (**Internal Improvement**) Upgrade Debian base for container images (12/bookworm -> 13/trixie)
+
+# (2025-07-11) Version 1.7.6
+
+- (**Internal Improvement**) Dependency updates. This version is based on [mxlink](https://crates.io/crates/mxlink)@1.9.0 (which is based on the newly released [matrix-sdk](https://crates.io/crates/matrix-sdk)@[0.13.0](https://github.com/matrix-org/matrix-rust-sdk/releases/tag/matrix-sdk-0.13.0), which contains fixes for some security vulnerabilities)
+
+# (2025-06-10) Version 1.7.5
+
+- (**Internal Improvement**) Dependency and compiler updates (Rust 1.86 -> 1.86).
+
+# (2025-06-10) Version 1.7.4
+
+- (**Internal Improvement**) Dependency updates.
+
+# (2025-06-10) Version 1.7.3
+
+- (**Internal Improvement**) Dependency updates. This version is based on [mxlink](https://crates.io/crates/mxlink)@1.8.0 (which is based on the newly released [matrix-sdk](https://crates.io/crates/matrix-sdk)@[0.12.0](https://github.com/matrix-org/matrix-rust-sdk/releases/tag/matrix-sdk-0.12.0), which contains fixes for important security vulnerabilities)
+
+# (2025-05-11) Version 1.7.2
+
+- (**Bugfix**) Allow `image_generation.size` configuration value for OpenAI to be `null` to allow the model to choose the size automatically and default to that
+
+# (2025-05-11) Version 1.7.1
+
+- (**Bugfix**) Fix lack of documentation for the new [image-editing](./docs/features.md#-image-editing) feature in the `!bai usage` command's output
+
+# (2025-05-10) Version 1.7.0
+
+- (**Feature**) Add vision support to the OpenAI and Anthropic providers. You can now mix text and images in your conversations - fixes [issue #5](https://github.com/etkecc/baibot/issues/5)
+
+- (**Feature**) Add [image-editing](./docs/features.md#-image-editing) support to the OpenAI provider
+
+- (**Improvement**) Add compatibility with OpenAI's `gpt-image-1` model - fixes [issue #40](https://github.com/etkecc/baibot/issues/40)
+
+- (**Change**) Rework [image-creation](./docs/features.md#-image-creation) to avoid command conflicts with [image-editing](./docs/features.md#-image-editing). The image-creation command syntax is now `!bai image create <prompt>` (previously: `!bai image <prompt>`).
+
+- (**Internal Improvement**) Dependency and compiler updates
+
+> [!WARNING]
+> Unlike other releases, this release is not published to [crates.io](https://crates.io), because it relies on multiple library forks (`async-openai` and `anthropic-rs`) sourced from Github.
+
+
+# (2025-04-12) Version 1.6.0
+
+- (**Internal Improvement**) Dependency updates. This version is based on [mxlink](https://crates.io/crates/mxlink)@1.7.0 (which is based on the newly released [matrix-sdk](https://crates.io/crates/matrix-sdk)@[0.11.0](https://github.com/matrix-org/matrix-rust-sdk/releases/tag/matrix-sdk-0.11.0))
+
+
+# (2025-03-31) Version 1.5.1
+
+- (**Internal Improvement**) Dependency updates
+
+# (2025-02-27) Version 1.5.0
+
+- (**Feature**) Add support for sending Speech-to-Text replies for [Transcribe-only mode](./docs/features.md#transcribe-only-mode) as regular text messages instead of notices and doing it so by default ([a1bd292752](https://github.com/etkecc/baibot/commit/a1bd292752bdd37a196788c73d00b5619e843a78)) - improvement for [issue #14](https://github.com/etkecc/baibot/issues/14). See [🦻 Speech-to-Text / 🪄 Message Type for non-threaded only-transcribed messages](./docs/configuration/speech-to-text.md#-message-type-for-non-threaded-only-transcribed-messages) for details.
+
+- (**Feature**) Add config setting controlling if a self-introduction message is posted after joining a room ([c051da2f4a](https://github.com/etkecc/baibot/commit/c051da2f4a161de0974ebb917f7a52d01f5a001f)) - fixes [issue #32](https://github.com/etkecc/baibot/issues/32). You may wish to add a `room.post_join_self_introduction_enabled` property to your configuration. See the [sample config](./etc/app/config.yml.dist) for details. If unspecified, it defaults to `true` anyway which preserves the old behavior.
+
+- (**Feature**) Add support for configuring `max_completion_tokens` for OpenAI ([47d8edea70](https://github.com/etkecc/baibot/commit/47d8edea705a44aa25a9bfaec4888c0f9ea8700e))
+
+- (**Improvement**) Dependency updates. This version is based on [mxlink](https://crates.io/crates/mxlink)@1.6.1 (which is based on the newly released [matrix-sdk](https://crates.io/crates/matrix-sdk)@[0.10.0](https://github.com/matrix-org/matrix-rust-sdk/releases/tag/matrix-sdk-0.10.0))
+
+- (**Improvement**) Populate image/audio attachment `body` with a filename, not with text to avoid incorrect rendering in Element Web, etc. ([ec1879d212](https://github.com/etkecc/baibot/commit/ec1879d212fa8d6e5f8590486e94c72abfcb75a5))
+
+- (**Improvement**) Replace Anthropic library ([anthropic-rs](https://crates.io/crates/anthropic-rs) -> [anthropic](https://crates.io/crates/anthropic)) and switch default recommended model (`claude-3-5-sonnet-20240620` -> `claude-3-7-sonnet-20250219`) ([692d61b239](https://github.com/etkecc/baibot/commit/692d61b2398f073b81d32d4cbe8145ab3929e48c)) - fixes [issue #22](https://github.com/etkecc/baibot/issues/22)
+
+- (**Internal Improvement**) Switch to native building of `arm64` container images to decrease total build times from ~40 minutes to ~8 minutes ([6719538530b](https://github.com/etkecc/baibot/commit/6719538530bf76b3ff2d24077b2a7fa868276b79))
+
+- (**Internal Improvement**) Various other internal changes, including upgrading [Rust from 1.82 to 1.85 and switching to Rust edition 2024](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0.html)
+
+
+# (2024-12-12) Version 1.4.1
+
+- (**Bugfix**) Fix detection for whether the bot is the last member in a room, to avoid incorrectly leaving multi-user rooms that have had at least one person `leave` ([3c47d40781](https://github.com/etkecc/baibot/commit/3c47d407819aa9c0121117a411858238724f06da))
+
+
+# (2024-11-19) Version 1.4.0
+
+- (**Improvement**) Dependency updates. This version is based on [mxlink](https://crates.io/crates/mxlink)@1.4.0 (which is based on the newly released [matrix-sdk](https://crates.io/crates/matrix-sdk)@[0.8.0](https://github.com/matrix-org/matrix-rust-sdk/releases/tag/matrix-sdk-0.8.0)). Once you run this version at least once and your matrix-sdk datastore gets upgraded to the new schema, **you will not be able to downgrade to older baibot versions** (based on the older matrix-sdk), unless you start with an empty datastore.
+
+- (**Bugfix**) Add missing typing notices sending functionality while generating images ([9d166e35ba](https://github.com/etkecc/baibot/commit/9d166e35ba6fc0daaf69318870e92436f3302056))
+
+- (**Feature**) Support for [Matrix authenticated media](https://matrix.org/docs/spec-guides/authed-media-servers/), thanks to upgrading [mxlink](https://crates.io/crates/mxlink) / [matrix-sdk](https://crates.io/crates/matrix-sdk) - fixes [issue #12](https://github.com/etkecc/baibot/issues/12)
+
+
+# (2024-11-12) Version 1.3.2
+
+Dependency updates.
+
+
+# (2024-10-03) Version 1.3.1
+
+- (**Improvement**) Improves fallback user mentions support for old clients (like Element iOS) which use the bot's display name (not its full Matrix User ID). ([d9a045a5e4](https://github.com/etkecc/baibot/commit/d9a045a5e41d2b99694f92ec9e90f47529546d89))
+
+
+# (2024-10-03) Version 1.3.0
+
+**TLDR**: you can now use OpenAI's [o1](https://platform.openai.com/docs/models/o1) models, benefit from [prompt caching](https://platform.openai.com/docs/guides/prompt-caching) and mention the bot again from old clients lacking proper [user mentions support](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions) (like Element iOS).
+
+- (**Feature**) Introduces a new `baibot_conversation_start_time_utc` [prompt variable](./docs/configuration/text-generation.md#️-prompt-override) which is not a moving target (like the `baibot_now_utc` variable) and allows [prompt caching](https://platform.openai.com/docs/guides/prompt-caching) to work. All default/sample configs have been adjusted to make use of this new variable, but users need to adjust your existing dynamically-created agents to start using it. ([85e66406dc](https://github.com/etkecc/baibot/commit/85e66406dc6f430741c7819f420e2df4ae6e8d3b))
+
+- (**Improvement**) Allows for the `max_response_tokens` configuration value for the [OpenAI provider](./docs/providers.md#openai) to be set to `null` to allow [o1](https://platform.openai.com/docs/models/o1) models (which do not support `max_response_tokens`) to be used. See the new o1 sample config [here](./docs/sample-provider-configs/openai-o1.yml). ([db9422740c](https://github.com/etkecc/baibot/commit/db9422740ceca32956d9628b6326b8be206344e2))
+
+- (**Improvement**) Switches the sample configs for the [OpenAI provider](./docs/providers.md#openai) to point to the `gpt-4o` model, which since 2024-10-02 is the same as the `gpt-4o-2024-08-06` model. We previously explicitly pointed the bot to the `gpt-4o-2024-08-06` model, because it was much better (longer context window). Now that `gpt-4o` points to the same powerful model, we don't need to pin its version anymore. Existing users may wish to adjust their configuration to match. ([90fbad5b64](https://github.com/etkecc/baibot/commit/90fbad5b643cd06c23179f055a309ec6a7cba161))
+
+- (**Bugfix**) Restores fallback user mentions support (via regular text, not via the [user mentions spec](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions)) to allow certain old clients (like Element iOS) to be able to mention the bot again. Support for this was intentionally removed recently (in [v1.2.0](#2024-10-01-version-120)), but it turned out to be too early to do this. ([b40226826f](https://github.com/etkecc/baibot/commit/b40226826fe914d0d5d265230ebc5bac8058b6f7))
+
+
+# (2024-10-01) Version 1.2.0
+
+- (**Feature**) Adds support for [on-demand involvement](./docs/features.md#on-demand-involvement) of the bot (via mention) in arbitrary threads and reply chains ([9908512968](https://github.com/etkecc/baibot/commit/990851296828168c2106eb3f4668833e9e5a7463)) - fixes [issue #15](https://github.com/etkecc/baibot/issues/15)
+
+- (**Improvement**) Simplifies [Transcribe-only mode](./docs/features.md#transcribe-only-mode) reply format (removing `> 🦻` prefixing) to allow easier forwarding, etc. ([e6aa956423](https://github.com/etkecc/baibot/commit/e6aa95642376ee7d87932d0e66dcfedf261b188b)) - fixes [issue #14](https://github.com/etkecc/baibot/issues/14)
+
+- (**Bugfix**) Fixes speech-to-text replies rendering incorrectly in certain clients, due to them confusing our old reply format with [fallback for rich replies](https://spec.matrix.org/v1.11/client-server-api/#fallbacks-for-rich-replies) ([e6aa956423](https://github.com/etkecc/baibot/commit/e6aa95642376ee7d87932d0e66dcfedf261b188b)) - fixes [issue #17](https://github.com/etkecc/baibot/issues/17)
+
+
+# (2024-09-22) Version 1.1.1
+
+- (**Bugfix**) Fix thread messages being lost due to lack of pagination support ([d4ddd29660](https://github.com/etkecc/baibot/commit/d4ddd29660d9f51d248119dd6032e68ab29e7d35)) - fixes [issue #13](https://github.com/etkecc/baibot/issues/13)
+
+- (**Bugfix**) Fix Anthropic conversations getting stuck when being impatient and sending multiple consecutive messages ([8b12bdf2b3](https://github.com/etkecc/baibot/commit/8b12bdf2b3196abea0e8db33d7c50fff48341cb9)) - fixes [issue #13](https://github.com/etkecc/baibot/issues/13)
+
+
+# (2024-09-21) Version 1.1.0
+
+- (**Feature**) Adds support for [prompt variables](./docs/configuration/text-generation.md#️-prompt-override) (date/time, bot name, model id) ([2a5a2d6a4d](https://github.com/etkecc/baibot/commit/2a5a2d6a4dbf5fd7cb504ac07d4187fdc32ae395)) - fixes [issue #10](https://github.com/etkecc/baibot/issues/10)
+
+- (**Improvement**) [Dockerfile](./Dockerfile) changes to produce ~20MB smaller container images ([354063abb7](https://github.com/etkecc/baibot/commit/354063abb79035069bd3b26c53214874e9cdd95d))
+
+- (**Improvement**) [Dockerfile](./Dockerfile) changes to optimize local (debug) runs in a container ([c8c5e0e540](https://github.com/etkecc/baibot/commit/c8c5e0e540ab981e849452eb3ddb0378105e1fc6))
+
+- (**Improvement**) CI changes to try and work around multi-arch image issues like [this one](https://github.com/etkecc/baibot/issues/2) ([5de7559ed6](https://github.com/etkecc/baibot/commit/5de7559ed685a41c22dfc12283681f02f4c2ee00))
+
+
+# (2024-09-19) Version 1.0.6
+
+Improvements to:
+
+- messages sent by the bot - better onboarding flow, especially when no agents have been created yet
+- documentation pages
+
+
+# (2024-09-14) Version 1.0.5
+
+Further [improves](https://github.com/etkecc/baibot/commit/3b25b92a81a05ebaf1c6dbabf675fbfbe6c9f418) the typing notification logic, so that it tolerates edge cases better.
+
+
 # (2024-09-14) Version 1.0.4
 
 [Improves](https://github.com/etkecc/baibot/commit/dd1dd78312e3db7f92b37fb3b4750fbe35de7115) the typing notification logic.

Cargo.toml

@@ -7,31 +7,36 @@ license = "AGPL-3.0-or-later"
 readme = "README.md"
 keywords = ["matrix", "chat", "bot", "AI", "LLM"]
 include = ["/etc/assets/baibot-torso-768.png", "/src", "/README.md", "/CHANGELOG.md", "/LICENSE"]
-version = "1.0.4"
-edition = "2021"
+version = "1.25.0"
+edition = "2024"
 
 [lib]
 name = "baibot"
 path = "src/lib.rs"
 
 [dependencies]
-anthropic-rs = "0.1.*"
+anthropic = { git = "https://github.com/etkecc/anthropic-rs.git", branch = "fix-content-block-image" }
 anyhow = "1.0.*"
-async-openai = "0.24.*"
+async-openai = { version = "0.41.0", features = ["audio", "chat-completion", "image", "responses"] }
 base64 = "0.22.*"
+chrono = { version = "0.4.*", default-features = false, features = ["std", "now"] }
 # We'd rather not depend on this, but we cannot use the ruma-events EventContent macro without it.
-matrix-sdk = { version = "0.7.1", default-features = false }
+matrix-sdk = { version = "0.18.0", default-features = false }
+mime_guess = "2.0.*"
 mxidwc = "1.0.*"
-mxlink = "1.2.*"
+mxlink = ">=1.15.0"
 etke_openai_api_rust = "0.1.*"
-quick_cache = "0.6.*"
-regex = "1.10.*"
+quick_cache = "0.7.*"
+regex = "1.12.*"
+# HTTP client for the native `venice` provider. rustls only (no extra TLS stack), matching the
+# reqwest copy async-openai/matrix-sdk/mxlink already use.
+reqwest = { version = "0.13.*", default-features = false, features = ["json", "multipart", "rustls"] }
 serde = { version = "1.0.*", features = ["derive"], default-features = false }
 serde_json = "1.0.*"
-serde_yaml = "0.9.*"
-tempfile = "3.12.*"
-tiktoken-rs = { version = "0.5.*", features = ["async-openai"] }
-tokio = { version = "1.40.*", features = ["rt", "rt-multi-thread", "macros"] }
+serde_yaml_ng = "0.10.*"
+tempfile = "3.27.*"
+tiktoken-rs = { version = "0.12.*", default-features = false }
+tokio = { version = "1.52.*", features = ["rt", "rt-multi-thread", "macros"] }
 tracing = "0.1.*"
 tracing-subscriber = { version = "0.3.*", features = ["env-filter"] }
 url = "2.5.*"

Dockerfile

@@ -4,7 +4,7 @@
 #                                     #
 #######################################
 
-FROM docker.io/rust:1.80.1-slim-bookworm AS build
+FROM docker.io/rust:1.96.0-slim-trixie AS build
 
 RUN apt-get update && apt-get install -y build-essential pkg-config libssl-dev libsqlite3-dev
 
@@ -15,14 +15,23 @@ WORKDIR /app
 
 COPY . /app
 
+ARG RELEASE_BUILD=true
+
 RUN --mount=type=cache,target=/cargo,sharing=locked \
 	--mount=type=cache,target=/target,sharing=locked \
-	cargo build --release
+	if [ "$RELEASE_BUILD" = "true" ]; then \
+		cargo build --release; \
+	else \
+		cargo build; \
+	fi
 
 # Move it out of the mounted cache, so we can copy it in the next stage.
 RUN --mount=type=cache,target=/target,sharing=locked \
-	cp /target/release/baibot /baibot
-
+	if [ "$RELEASE_BUILD" = "true" ]; then \
+		cp /target/release/baibot /baibot; \
+	else \
+		cp /target/debug/baibot /baibot; \
+	fi
 
 #######################################
 #                                     #
@@ -30,9 +39,11 @@ RUN --mount=type=cache,target=/target,sharing=locked \
 #                                     #
 #######################################
 
-FROM docker.io/debian:bookworm-slim
+FROM docker.io/debian:trixie-slim
 
-RUN apt-get update && apt-get install -y ca-certificates sqlite3
+RUN apt-get update && apt-get install -y ca-certificates sqlite3 && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
 

Dockerfile.ci

@@ -0,0 +1,35 @@
+#######################################
+#                                     #
+# Stage 1: building                   #
+#                                     #
+#######################################
+
+FROM docker.io/rust:1.96.0-slim-trixie AS build
+
+RUN apt-get update && apt-get install -y build-essential pkg-config libssl-dev libsqlite3-dev
+
+WORKDIR /app
+
+COPY . /app
+
+RUN cargo build --release
+
+#######################################
+#                                     #
+# Stage 2: packaging                  #
+#                                     #
+#######################################
+
+FROM docker.io/debian:trixie-slim
+
+RUN apt-get update && apt-get install -y ca-certificates sqlite3 && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=build /app/target/release/baibot .
+
+ENTRYPOINT ["/bin/sh", "-c"]
+
+CMD ["/app/baibot"]

README.md

@@ -13,14 +13,14 @@ It's influenced by [chaz](https://github.com/arcuru/chaz), but does **not** use
 
 ## 🌟 Features
 
-- 🎨 Encourages **[provider](./docs/providers.md) choice** ([Anthropic](./docs/providers.md#anthropic), [Groq](./docs/providers.md#groq), [LocalAI](./docs/providers.md#localai), [OpenAI](./docs/providers.md#openai) and [☁️ many more](./docs/providers.md#️-providers)) as well as **[mixing & matching models](./docs/features.md#-mixing--matching-models)**:
+- 🎨 Encourages **[provider](./docs/providers.md) choice** ([Anthropic](./docs/providers.md#anthropic), [Groq](./docs/providers.md#groq), [LocalAI](./docs/providers.md#localai), [OpenAI](./docs/providers.md#openai), [Venice](./docs/providers.md#venice) and [☁️ many more](./docs/providers.md#️-providers)) as well as **[mixing & matching models](./docs/features.md#-mixing--matching-models)**:
 
 - Supports **different use purposes** (depending on the [☁️ provider](./docs/providers.md) & model):
 
-  - [💬 text-generation](./docs/features.md#-text-generation): communicating with you via text
+  - [💬 text-generation](./docs/features.md#-text-generation): communicating with you via text (though certain models may "see" images as well). The [OpenAI provider](./docs/providers.md#openai) also supports [🛠️ built-in tools](./docs/features.md#️-built-in-tools-openai-only) (web search, code interpreter)
   - [🦻 speech-to-text](./docs/features.md#-speech-to-text): turning your voice messages into text
   - [🗣️ text-to-speech](./docs/features.md#%EF%B8%8F-text-to-speech): turning bot or users text messages into voice messages
-  - [🖌️ image-generation](./docs/features.md#%EF%B8%8F-image-generation): generating images based on instructions
+  - [🖌️ image-generation](./docs/features.md#image-generation): creating and editing images based on instructions
 
 - 🪄 Supports [seamless voice interaction](./docs/features.md#seamless-voice-interaction) (turning user voice messages into text, answering in text, then turning that text back into voice)
 
@@ -30,7 +30,7 @@ It's influenced by [chaz](https://github.com/arcuru/chaz), but does **not** use
 
 - 🔒 Supports [encryption](./docs/features.md#-encryption) for Matrix communication and Account-Data-stored configuration
 
-- ♻️ Supports [context-management](./docs/configuration/text-generation.md#️-context-management) handling on some models (automatically adjusting the message history length, etc.)
+- ♻️ Supports [context-management](./docs/configuration/text-generation.md#️-context-management) for every [provider](./docs/providers.md) (automatically trimming older messages on whole-turn boundaries once a conversation outgrows the context window)
 
 - 🛠️ Allows **customizing much of the bot's [configuration](./docs/configuration/README.md)** at runtime (using commands sent via chat)
 
@@ -41,7 +41,7 @@ It's influenced by [chaz](https://github.com/arcuru/chaz), but does **not** use
 
 ![Introduction and general usage](./docs/screenshots/introduction-and-general-usage.webp)
 
-You can find more screenshots on the the [🌟 Features](./docs/features.md) and other [📚 Documentation](./docs/README.md) pages, as well as in the [docs/screenshots](./docs/screenshots) directory.
+You can find more screenshots on the [🌟 Features](./docs/features.md) and other [📚 Documentation](./docs/README.md) pages, as well as in the [docs/screenshots](./docs/screenshots) directory.
 
 
 ## 🚀 Getting Started

docs/access.md

@@ -5,17 +5,22 @@ This bot employs access control to decide who can use its services and manage it
 
 ### 👋 Joining rooms
 
-The bot automatically joins rooms when invited by someone considered a bot [user](#-users).
+The bot automatically joins rooms only when invited by someone considered a bot [👥 user](#-users).
 
 
 ### 👥 Users
 
-The bot will ignore messages (and room invitations) from unallowed users.
-
-Users can **use all the bot's [features](./features.md)** ([💬 Text Generation](./features.md#-text-generation), [🦻 Speech-to-Text](./features.md#-speech-to-text), etc.), but **cannot manage the bot's configuration**.
-
 The bot can be used by users that match some [dynamically](./configuration/README.md#dynamic-configuration) configured [Matrix user id](https://spec.matrix.org/v1.11/#users) patterns.
 
+Users:
+
+- ✅ can **invite the bot to rooms**
+- ✅ can **use all the bot's [features](./features.md)** ([💬 Text Generation](./features.md#-text-generation), [🦻 Speech-to-Text](./features.md#-speech-to-text), etc.) by sending room messages
+- ✅ can **mention the bot** in threads and reply chains to provoke it to respond to non-user messages (see [🌟 Features / 💬 Text Generation / On-demand involvement](./features.md#on-demand-involvement))
+- ✅ can **change the bot's configuration in a room** (e.g. `!bai config room ...` commands)
+- ❌ cannot **change the bot's global configuration** (e.g. `!bai config global ...` commands)
+- ❌ cannot **create new [🤖 Agents](./agents.md)** (neither in rooms, nor globally). See [💼 Room-local agent managers](#-room-local-agent-managers) for controlling which users can create agents.
+
 The following commands are available:
 - **Show** the currently allowed users: `!bai access users`
 - **Set** the list of allowed users: `!bai access set-users SPACE_SEPARATED_PATTERNS`
@@ -27,6 +32,8 @@ Example patterns: `@*:example.com @*:another.com @someone:company.org`
 
 Administrators can **manage the bot's configuration and access control**.
 
+Administrators are [👥 Users](#-users) and [💼 Room-local agent managers](#-room-local-agent-managers) implicitly, so they inherit all their permissions.
+
 The bot can be administrated by users that match some [statically](./configuration/README.md#static-configuration) configured [Matrix user id](https://spec.matrix.org/v1.11/#users) patterns.
 
 Administrators cannot be changed without adjusting the bot's configuration on the server.
@@ -35,12 +42,12 @@ Administrators cannot be changed without adjusting the bot's configuration on th
 ### 💼 Room-local agent managers
 
 Room-local agent managers are users privileged to **create their own [agents](./agents.md)** (see `!bai agent`) in rooms.
-Letting regular users create agents which contact arbitrary network services **may be a security issue**.
 
-No room-local agent manager patterns are configured, so new agents can only be created by administrators.
+> [!WARNING]
+> Letting regular users create agents which contact arbitrary network services **may be a security issue**.
 
 The following commands are available:
 - **Show** the currently allowed users: `!bai access room-local-agent-managers`
 - **Set** the list of allowed users: `!bai access set-room-local-agent-managers SPACE_SEPARATED_PATTERNS`
 
-Example patterns: `@*:synapse.127.0.0.1.nip.io @*:another.com @someone:company.org`
+Example patterns: `@*:example.com @*:another.com @someone:company.org`

docs/agents.md

@@ -35,7 +35,7 @@ Depending on where the agent is defined (within a room, globally, or [statically
 
 When creating an agent, you will be given some sample [YAML](https://en.wikipedia.org/wiki/YAML) configuration which you can use to customize the agent's behavior.
 
-This configuration varies depending on the [☁️ provider](./providers.md) used and the capabilities of the agent. Based on the configuration keys you pass, certain features will be enabled or disabled. For example, if you skip the `image_generation` key for an [OpenAI](./providers.md#openai) agent, it won't be able to generate images (see [🖌️ Image Generation](./features.md#-image-generation)).
+This configuration varies depending on the [☁️ provider](./providers.md) used and the capabilities of the agent. Based on the configuration keys you pass, certain features will be enabled or disabled. For example, if you skip the `image_generation` key for an [OpenAI](./providers.md#openai) agent, it won't be able to generate images (see [🖌️ Image Creation](./features.md#-image-creation), [🎨 Image Editing](./features.md#-image-editing), [🫵 Sticker Creation](./features.md#-sticker-creation)).
 
 After making your modifications to the sample YAML, you submit it back to the bot and the new agent will be created.
 

docs/configuration/README.md

@@ -12,12 +12,17 @@ This file is created from the template found in [etc/app/config.yml.dist](../../
 
 Certain keys can be left unset, in which case [📝 hardcoded defaults](../../src/entity/cfg/defaults.rs) would be used.
 
-Each configuration key found in the YAML configuration can be overridden by setting an environment variable (dots should be replaced with `_`). Example:
+Some configuration keys found in the YAML configuration can be overridden by setting an environment variable (dots should be replaced with `_`). Example:
 
 - to override `command_prefix`, set an environment variable `BAIBOT_COMMAND_PREFIX`
 - to override `homeserver.server_name`, set an environment variable `BAIBOT_HOMESERVER_SERVER_NAME`
 
-The static configuration contains an `initial_global_config` key, which is used to populate the bot's global configuration (stored as [dynamic configuration](#dynamic-configuration)) the first time the bot starts. Modifying this subsequently will not have any effect. After initial global configuration creation, it's expected to be managed dynamically via chat commands.
+You can see the list of supported environment variables in the [🦀 src/entity/cfg/env.rs](../../src/entity/cfg/env.rs) file.
+
+> [!WARNING]
+> The static configuration contains an `initial_global_config` key, which is used to populate the bot's global configuration (stored as [dynamic configuration](#dynamic-configuration)) the first time the bot starts. Modifying this subsequently will not have any effect. After initial global configuration creation, it's expected to be managed dynamically via chat commands.
+
+For Matrix-account authentication setup, see [🔐 Authentication](./authentication.md).
 
 
 ### Dynamic configuration
@@ -40,7 +45,7 @@ You can adjust the following settings per room and/or globally:
 - [💬 Text Generation](text-generation.md)
 - [🦻 Speech-to-Text](speech-to-text.md)
 - [🗣️ Text-to-Speech](text-to-speech.md)
-- [🖌️ Image Generation](image-generation.md)
+- [🖌️ Image Creation](image-generation.md)
 - [🤝 Handlers](handlers.md)
 
 Refer to the bot's help messages (as a response to a `!bai config` help command) for the most up-to-date information on what Room Settings can be configured.

docs/configuration/authentication.md

@@ -0,0 +1,23 @@
+## 🔐 Authentication
+
+baibot supports 2 authentication modes for the Matrix account (`user.*` keys in config).
+
+Set **exactly one** mode. If both are set (or neither is set), startup validation fails.
+
+### Password authentication
+
+- Config key: `user.password`
+- Environment variable: `BAIBOT_USER_PASSWORD`
+
+### Access token authentication
+
+- Config keys: `user.access_token` + `user.device_id`
+- Environment variables: `BAIBOT_USER_ACCESS_TOKEN` + `BAIBOT_USER_DEVICE_ID`
+
+Access-token authentication is useful for OIDC-enabled homeservers (e.g. those using [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service)).
+
+Example token-generation command:
+
+```sh
+mas-cli manage issue-compatibility-token <username> [device_id]
+```

docs/configuration/handlers.md

@@ -8,10 +8,10 @@ You can also use **different models within the same room** (e.g. [💬 text-gene
 
 The bot supports the following use-purposes:
 
-- [💬 text-generation](../features.md#-text-generation): communicating with you via text
+- [💬 text-generation](../features.md#-text-generation): communicating with you via text (though certain models may also process images and files)
 - [🦻 speech-to-text](../features.md#-speech-to-text): turning your voice messages into text
 - [🗣️ text-to-speech](../features.md#️-text-to-speech): turning bot or users text messages into voice messages
-- [🖌️ image-generation](../features.md#-image-generation): generating images based on instructions
+- [🖌️ image-generation](../features.md#image-generation): generating images based on instructions
 
 In a given room, each different purpose can be served by a different [provider](../providers.md) and model. This combination of provider and model configuration is called an [🤖 agent](../agents.md). Each purpose can be served by a different **handler** agent.
 

docs/configuration/image-generation.md

@@ -1,9 +1,11 @@
 
-## 🖌️ Image Generation
+## Image Generation
 
-The Image Generation feature is not configurable at this moment.
+The Image Creation and Image Editing features are not configurable at this moment.
 
 You may also wish to see:
 
-- [🌟 Features / 🖌️ Image Generation](../features.md#-image-generation) for a higher-level introduction to the Image Generation features
-- [📖 Usage / 🖌️ Image Generation](../usage.md#-image-generation) section for more details on how to use the bot for Image Generation in a room
+- [🌟 Features / Image Generation / 🖌️ Image Creation](../features.md#-image-creation) for a higher-level introduction to the Image Creation features
+- [🌟 Features / Image Generation / 🎨 Image Editing](../features.md#-image-editing) for a higher-level introduction to the Image Editing features
+- [📖 Usage / Image Generation / 🖌️ Creating Images](../usage.md#-creating-images) section for more details on how to use the bot for Image Creation in a room
+- [📖 Usage / Image Generation / 🎨 Editing images](../usage.md#-editing-images) section for more details on how to use the bot for Image Editing in a room

docs/configuration/speech-to-text.md

@@ -23,6 +23,19 @@ The following configuration values are recognized:
 Example: `!bai config room speech-to-text set-flow-type ignore` (this can also be set globally, see [🛠️ Room Settings](./README.md#room-settings))
 
 
+### 🪄 Message Type for non-threaded only-transcribed messages
+
+Controls how the transcribed text of voice messages is sent to the chat when Flow Type = `only_transcribe`.
+
+The following configuration values are recognized:
+
+- (default) `text`: the transcribed text is sent as a regular message. This is more convenient if you'd like to forward the transcribed message to other rooms.
+
+- `notice`: the transcribed text is sent as a notice message. This provides better compatibility with other bots in the room, as they are less likely to interact with messages of type notice.
+
+Example: `!bai config room speech-to-text set-msg-type-for-non-threaded-only-transcribed-messages notice` (this can also be set globally, see [🛠️ Room Settings](./README.md#room-settings))
+
+
 ### 🔤 Language
 
 Lets you specify the language of the input voice messages, to avoid using auto-detection.

docs/configuration/text-generation.md

@@ -13,7 +13,7 @@ You may also wish to see:
 
 In Direct Message rooms with the bot (1:1 rooms), it most usually makes sense for the bot to respond to **all** of your messages, as shown on this [🖼️ screenshot](../screenshots/text-generation.webp).
 
-In group rooms (with multiple users), it may be more appropriate for the bot to only respond to messages that are **prefixed** with the command prefix (e.g. `!bai`), so that other chat exchange in the room will not trigger it. Such a setup is shown on this [🖼️ screenshot](../screenshots/text-generation-prefix-requirement.webp).
+In group rooms (with multiple users), it may be more appropriate for the bot to only respond to messages that are **prefixed** with the command prefix (e.g. `!bai`) or which are [mentioning](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions) the bot (e.g. `@baibot`), so that other chat exchange in the room will not trigger it. Such a setup is shown on the [🖼️ On-demand involvement in the room](../screenshots/text-generation-prefix-requirement.webp) screenshot.
 
 There are exceptions to these rules, and you can configure the bot to respond only to prefixed messages in a 1:1 room, or to respond to all messages even in a multi-user group room.
 
@@ -27,7 +27,10 @@ By default, the bot is **auto-configured (upon joining a new room)** to use the
 
 Example: `!bai config room text-generation set-prefix-requirement-type command_prefix` (this can also be set globally, see [🛠️ Room Settings](./README.md#room-settings))
 
-Regardless of this configuration, **the bot will also respond to messages which directly [mention](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions) the bot** (e.g. `@baibot`), even if they are not prefixed. An example of this can be seen on this [🖼️ screenshot](../screenshots/text-generation-prefix-requirement.webp).
+Regardless of this configuration, **the bot will also respond to messages by allowed [👥 Users](../access.md#-users) which directly [mention](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions) the bot** (e.g. `@baibot`), even if they are not prefixed. An example of this can be seen on these screenshots:
+
+- [🖼️ On-demand involvement in a thread](../screenshots/text-generation-on-demand-thread-involvement.webp)
+- [🖼️ On-demand involvement in a reply chain](../screenshots/text-generation-on-demand-reply-involvement.webp)
 
 
 ### 🪄 Auto Usage
@@ -47,13 +50,41 @@ Example: `!bai config room text-generation set-auto-usage only_for_voice` (this
 
 ### ♻️ Context Management
 
-The bot also supports ♻️ **context management**, which automatically adjusts the message history length, etc.
+The bot also supports ♻️ **context management**, which automatically trims the oldest messages once a conversation grows past the context window. It drops whole turns at a time, so a reply is never separated from the message it answered.
 
-This feature relies on [tokenization](https://en.wikipedia.org/wiki/Large_language_model#Tokenization) performed by the [tiktoken-rs](https://github.com/zurawiki/tiktoken-rs) library which is [poorly well-maintained](https://github.com/zurawiki/tiktoken-rs/issues/50) and only works well for [OpenAI](../providers.md#openai) models.
+Counting tokens precisely needs the model's own tokenizer. For [OpenAI](../providers.md#openai) models, the bot counts them with the [tiktoken-rs](https://github.com/zurawiki/tiktoken-rs) library. For every other provider, including the recommended [Venice](../providers.md#venice), the bot falls back to a provider-neutral **approximation** that needs no per-model tokenizer: it counts ASCII text at about four characters per token and other scripts (Cyrillic, CJK, and so on) at about two. Treat it as rough, within roughly 10-20% of the real count for typical text, which is plenty for keeping a long conversation inside the context window.
 
 This setting is **disabled by default**, but can be enabled via `!bai config room text-generation set-context-management-enabled true` (this can also be set globally, see [🛠️ Room Settings](./README.md#room-settings)).
 
 
+### 💭 Thinking Notice
+
+The bot can post a 💭 **"thinking…" notice** while text generation is running, useful for slow models (for example, reasoning models that may run for minutes) where the response would otherwise look stuck.
+
+When enabled, a placeholder message appears only after a short delay (so fast responses get no notice), updates periodically with varying status text, and is then edited in place to become the final answer.
+
+This setting is **disabled by default**, but can be enabled via `!bai config room text-generation set-thinking-notice-enabled true` (this can also be set globally, see [🛠️ Room Settings](./README.md#room-settings)).
+
+
+### 👤 Sender Context Mode
+
+In multi-user rooms, it may be useful for the model to know which participant sent each message in the conversation context.
+
+To support this, the bot has a `text-generation sender-context-mode` setting, which can be set to:
+
+- (default) `disabled`: do not attach sender metadata to messages before sending them to the model
+
+- `matrix_user_id`: prefix text messages with the sender's Matrix user ID, for example: `[sender=@alice:example.com] Hello bot`
+
+- `matrix_user_id_and_timestamp`: prefix text messages with the sender's Matrix user ID and the message timestamp, for example: `[sender=@alice:example.com sent_at=2026-03-23T14:30:00Z] Hello bot`
+
+This sender metadata is attached to conversation messages before they are sent to the model provider. It applies to user and assistant text messages, but not to system prompts or non-text content.
+
+⚠️ Enabling this sends Matrix user IDs, and optionally timestamps, to the model provider.
+
+Example: `!bai config room text-generation set-sender-context-mode matrix_user_id` (this can also be set globally, see [🛠️ Room Settings](./README.md#room-settings))
+
+
 ### ⌨️ Prompt Override
 
 You can override the [system prompt](https://huggingface.co/docs/transformers/en/tasks/prompting) configured at the [🤖 agent](../agents.md) level.
@@ -68,6 +99,24 @@ Where appropriate, you'll mention best practices and common pitfalls.
 
 A prompt override can also be set globally, see [🛠️ Room Settings](./README.md#room-settings).
 
+Prompts may contain the following **placeholder variables** which will be replaced *every time* the bot is interacted with:
+
+| Placeholder               | Description | Example |
+|---------------------------|-------------|---------|
+| `{{ baibot_name }}`       | Name of the bot as configured in the `user.name` field in the [Static configuration](./README.md#static-configuration) | `Baibot` |
+| `{{ baibot_model_id }}`   | Text-Generation model ID as configured in the [🤖 agent](../agents.md)'s configuration | `gpt-4o` |
+| `{{ baibot_now_utc }}`    | Current date and time in UTC (⚠️ usage may break prompt caching - see below) | `2024-09-20 (Friday), 14:26:42 UTC` |
+| `{{ baibot_conversation_start_time_utc }}` | The date and time in UTC that the conversation started | `2024-09-20 (Friday), 14:26:42 UTC` |
+
+💡 `{{ baibot_now_utc }}` changes as time goes on, which prevents [prompt caching](https://platform.openai.com/docs/guides/prompt-caching) from working. It's better to use `{{ baibot_conversation_start_time_utc }}` in prompts, as its value doesn't change yet still orients the bot to the current date/time.
+
+💡 On the [Venice provider](../providers.md#venice), baibot derives the prompt-cache key from the system prompt and the conversation start time, both stable for the life of a conversation, and ships `prompt_cache_retention: 24h` by default. A stable system prompt then stays cached across the whole conversation instead of being reprocessed (and re-billed) on every turn.
+
+Here's a prompt that combines some of the above variables:
+
+> You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
+
+
 ### 🌡️ Temperature Override
 
 You can override the [temperature](https://blogs.novita.ai/what-are-large-language-model-settings-temperature-top-p-and-max-tokens/#what-is-llm-temperature) (randomness / creativity) parameter configured at the [🤖 agent](../agents.md) level.

docs/configuration/text-to-speech.md

@@ -56,7 +56,7 @@ Example: `!bai config room text-to-speech set-speed-override 1.5` (this can also
 
 ### 👫 Voice override
 
-The voice override setting lets you change the voice being used by the text-to-speech model configured at the [🤖 agent](../agents.md) level (usually `onyx` when using [OpenAI](../providers.md#openai)).
+The voice override setting lets you change the voice being used by the text-to-speech model configured at the [🤖 agent](../agents.md) level (e.g. `onyx` when using [OpenAI](../providers.md#openai), or `af_sky` when using [Venice](../providers.md#venice)).
 
 Possible values (e.g. `onyx`) depend on the model you're using. For example, for [OpenAI](../providers.md#openai)'s Whisper model, [these voices](https://platform.openai.com/docs/guides/text-to-speech/voice-options) are available.
 

docs/development.md

@@ -18,6 +18,27 @@ For local development, we run all dependency services in [🐋 Docker](https://w
 - (Optional) an API key for some Large Language Model [☁️ provider](./providers.md) (e.g. [OpenAI](./providers.md#openai)), though we recommend using [LocalAI](#localai) or [Ollama](#ollama) for local development
 
 
+### Choosing a homeserver
+
+The development environment supports two homeserver implementations:
+
+- **[Continuwuity](https://continuwuity.org/)** (default) — lightweight, no external database required. Good for most development needs.
+- **[Synapse](https://github.com/element-hq/synapse)** — the reference implementation, bundled with Postgres. Use this if you need Synapse-specific behavior.
+
+To choose a homeserver (optional — defaults to Continuwuity if skipped):
+
+```sh
+just homeserver-init continuwuity  # or: just homeserver-init synapse
+```
+
+The choice is stored in `var/homeserver` and affects all subsequent commands.
+
+> **Note:** If you switch homeservers after initial setup, you will need to:
+> - Delete `var/app/local/` and/or `var/app/container/` (app config and data)
+> - Delete `var/services/element-web/` (to regenerate its config)
+> - Re-run the prepare and user registration steps
+
+
 ### Getting started guide
 
 Developing [locally](#running-locally) is possible, but requires a [Rust](https://www.rust-lang.org/) toolchain.
@@ -28,11 +49,12 @@ In any case, you will need [🐋 Docker](https://www.docker.com/) as [dependency
 
 #### Running locally
 
-1. Start the core dependency services (Postgres, Synapse, Element Web): `just services-start`
-2. (Only the first time around) Prepare initial app configuration in `var/app/local/config.yml`: `just app-local-prepare`
-3. (Only the first time around) [Prepare your configuration file](#prepare-your-configuration-file)
-4. (Only the first time around) Prepare initial default Matrix user accounts (`admin` and `baibot`): `just users-prepare`
-5. (Optional) Start additional services depending on which [agent provider you've chosen](#choosing-an-agent-provider):
+1. (Optional) Choose a homeserver: `just homeserver-init continuwuity` (or `synapse`). Default is `continuwuity`.
+2. Start the homeserver and Element Web: `just services-start`
+3. (Only the first time around) Prepare initial app configuration in `var/app/local/config.yml`: `just app-local-prepare`
+4. (Only the first time around) [Prepare your configuration file](#prepare-your-configuration-file)
+5. (Only the first time around) Prepare initial default Matrix user accounts (`admin` and `baibot`): `just users-prepare`
+6. (Optional) Start additional services depending on which [agent provider you've chosen](#choosing-an-agent-provider):
   - for [LocalAI](#localai):
     - Start services: `just localai-start`
 	- Wait a while for LocalAI to start up. It has a lot of models to download. Monitor progress using `just localai-tail-logs`
@@ -40,12 +62,12 @@ In any case, you will need [🐋 Docker](https://www.docker.com/) as [dependency
   - for [Ollama](#ollama):
     - Start services: `just ollama-start`
     - (Only the first time around) Pull the model configured in `agents.static_definitions` in the configuration file: `just ollama-pull-model gemma2:2b`
-6. Start the bot: `just run-locally`
-7. Go to http://element.127.0.0.1.nip.io:42025/ and login with `admin` / `admin`
-8. Create a new room and invite `@baibot:synapse.127.0.0.1.nip.io`
-9. When done, stop the bot (`Ctrl` + `C`)
-10. Stop the core dependency services: `just services-stop`
-11. (Optional) Stop additional services:
+7. Start the bot: `just run-locally`
+8. Go to http://element.127.0.0.1.nip.io:42025/ and login with `admin` / `admin`
+9. Create a new room and invite `@baibot:continuwuity.127.0.0.1.nip.io` (or `@baibot:synapse.127.0.0.1.nip.io` if using Synapse)
+10. When done, stop the bot (`Ctrl` + `C`)
+11. Stop the services: `just services-stop`
+12. (Optional) Stop additional services:
   - for [LocalAI](#localai): `just localai-stop`
   - for [Ollama](#ollama): `just ollama-stop`
 
@@ -54,11 +76,12 @@ In any case, you will need [🐋 Docker](https://www.docker.com/) as [dependency
 
 You can avoid having a [Rust](https://www.rust-lang.org/) toolchain installed locally and build/run this in a container.
 
-1. Start the core dependency services (Postgres, Synapse, Element Web): `just services-start`
-2. (Only the first time around) Prepare initial app configuration in `var/app/container/config.yml`: `just app-container-prepare`
-3. (Only the first time around) [Prepare your configuration file](#prepare-your-configuration-file)
-4. (Only the first time around) Prepare initial default Matrix user accounts (`admin` and `baibot`): `just users-prepare`
-5. (Optional) Start additional services depending on which [agent provider you've chosen](#choosing-an-agent-provider):
+1. (Optional) Choose a homeserver: `just homeserver-init continuwuity` (or `synapse`). Default is `continuwuity`.
+2. Start the homeserver and Element Web: `just services-start`
+3. (Only the first time around) Prepare initial app configuration in `var/app/container/config.yml`: `just app-container-prepare`
+4. (Only the first time around) [Prepare your configuration file](#prepare-your-configuration-file)
+5. (Only the first time around) Prepare initial default Matrix user accounts (`admin` and `baibot`): `just users-prepare`
+6. (Optional) Start additional services depending on which [agent provider you've chosen](#choosing-an-agent-provider):
   - for [LocalAI](#localai):
     - Start services: `just localai-start`
 	- Wait a while for LocalAI to start up. It has a lot of models to download. Monitor progress using `just localai-tail-logs`
@@ -66,12 +89,12 @@ You can avoid having a [Rust](https://www.rust-lang.org/) toolchain installed lo
   - for [Ollama](#ollama):
     - Start services: `just ollama-start`
     - (Only the first time around) Pull the model configured in `agents.static_definitions` in the configuration file: `just ollama-pull-model gemma2:2b`
-6. Start the bot: `just run-in-container`
-7. Go to http://element.127.0.0.1.nip.io:42025/ and login with `admin` / `admin`
-8. Create a new room and invite `@baibot:synapse.127.0.0.1.nip.io`
-9. When done, stop the bot (`Ctrl` + `C`)
-10. Stop the dependency services: `just services-stop`
-11. (Optional) Stop additional services:
+7. Start the bot: `just run-in-container`
+8. Go to http://element.127.0.0.1.nip.io:42025/ and login with `admin` / `admin`
+9. Create a new room and invite `@baibot:continuwuity.127.0.0.1.nip.io` (or `@baibot:synapse.127.0.0.1.nip.io` if using Synapse)
+10. When done, stop the bot (`Ctrl` + `C`)
+11. Stop the services: `just services-stop`
+12. (Optional) Stop additional services:
   - for [LocalAI](#localai): `just localai-stop`
   - for [Ollama](#ollama): `just ollama-stop`
 
@@ -93,7 +116,7 @@ For getting started most quickly (and locally), we recommend using [LocalAI](#lo
 
 **Ollama is most lightweight** (~2GB for the container image + ~1.6GB for the model), but supports only [💬 text-generation](./features.md#-text-generation).
 
-**LocalAI requires 4x more disk space** (~6GB for the container image + ~12GB for the models), but supports [💬 text-generation](./features.md#-text-generation), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text) and [🖼️ image-generation](./features.md#️-image-generation).
+**LocalAI requires 4x more disk space** (~6GB for the container image + ~12GB for the models), but supports [💬 text-generation](./features.md#-text-generation), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text) and [🖼️ image-generation](./features.md#️-image-creation).
 
 **OpenAI supports all of these capabilities** as well and does not require powerful hardware or lots of disk space. However, it requires signup and an API key.
 

docs/features.md

@@ -8,7 +8,7 @@ You can also use **different models within the same room** (e.g. [💬 text-gene
 
 The bot supports the following use-purposes:
 
-- [💬 text-generation](#-text-generation): communicating with you via text
+- [💬 text-generation](#-text-generation): communicating with you via text (though certain models may also process images and files)
 - [🦻 speech-to-text](#-speech-to-text): turning your voice messages into text
 - [🗣️ text-to-speech](#%EF%B8%8F-text-to-speech): turning bot or users text messages into voice messages
 - [🖌️ image-generation](#%EF%B8%8F-image-generation): generating images based on instructions
@@ -22,12 +22,18 @@ For more information about configuring handlers, see the [🤝 Handlers / Config
 
 ### 💬 Text Generation
 
-Text Generation is the bot's ability to **respond to users' text messages with text**.
+Text Generation is the bot's ability to **respond to users' messages with text**.
 
 ![Screenshot of Text Generation - a user sends a message and the bot replies in a new conversation thread](./screenshots/text-generation.webp)
 
+Some models also support vision and document understanding, so you may be able to mix text, images, and files (PDFs, text documents, etc.) in the same conversation. File inputs (documents such as PDFs) are currently accepted only by the OpenAI and Venice providers; the others skip them. Note that certain providers may not support all file types or may have issues with specific files (e.g. scanned/image-based PDFs). If a file is rejected by the provider, the conversation thread may become unusable — start a new thread to work around this.
+
 In multi-user (group) rooms, to avoid disturbing the normal conversation between people, the bot is auto-configured to only respond to messages starting with the command prefix (`!bai`) or direct mentions via the [💬 Text Generation / 🗟 Prefix Requirement Type](./configuration/text-generation.md#-prefix-requirement-type) setting.
 
+Normally, the bot only responds to allowed [👥 Users](./access.md#-users). In certain cases, it's useful for an allowed user to provoke the bot to respond even in foreign threads or reply chains. You can learn more about this feature in the [On-demand involvement](./features.md#on-demand-involvement) section below.
+
+If needed, the bot can also attach sender metadata to conversation messages before sending them to the model, which can help the model distinguish between participants in multi-user rooms. See [🛠️ Configuration / 💬 Text Generation / 👤 Sender Context Mode](./configuration/text-generation.md#-sender-context-mode).
+
 A few other features (like [🗣️ Text-to-Speech](#️-text-to-speech) and [🦻 Speech-to-Text](#-speech-to-text)) combine well with Text Generation, so you **don't necessarily need to communicate with the bot via text** (with [Seamless voice interaction](#seamless-voice-interaction), you can communicate only with voice).
 
 You may also wish to see:
@@ -36,6 +42,39 @@ You may also wish to see:
 - [📖 Usage / 💬 Text Generation](./usage.md#-text-generation) section for more details on how to use the bot for Text Generation in a room
 
 
+#### 🛠️ Built-in Tools (OpenAI only)
+
+
+
+The [OpenAI provider](./providers.md#openai) supports built-in tools that extend the model's capabilities:
+
+- [🔍 Web Search](https://platform.openai.com/docs/guides/tools-web-search) (`web_search`): allows the model to search the web for up-to-date information. [🖼️ Screenshot](./screenshots/text-generation-tools-web-search.webp)
+
+- [💻 Code Interpreter](https://platform.openai.com/docs/guides/tools-code-interpreter) (`code_interpreter`): allows the model to write and execute Python code in a sandbox
+
+These tools are **disabled by default** and need to be explicitly enabled in the agent's `text_generation.tools` configuration. See the [OpenAI sample configuration](https://github.com/etkecc/baibot/blob/c70387b0c38d8d0f30bba2179a2a21a3710dbeaf/docs/sample-provider-configs/openai.yml#L12-L15) for reference.
+
+To enable tools on an existing dynamically-created agent, you need to [update the agent](./agents.md#updating-agents) to re-create it with the `text_generation.tools` section added and enable the tools you need
+
+💡 **Note**: These tools run on OpenAI's infrastructure and may incur additional costs. Web search results include citations that are incorporated into the response.
+
+
+#### On-demand involvement
+
+In the following 2 cases, it's useful to involve the bot in conversations on-demand:
+
+1. In multi-user rooms (with the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting set to "required")
+2. In rooms with foreign users (users that are not authorized bot [👥 users](./access.md#-users))
+
+In these instances, an allowed [👥 user](./access.md#-users) can also provoke the bot to respond to **any** thread or reply chain by [mentioning](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions) the bot (e.g. `@baibot Hello!`). The following screenshots demonstrate this behavior:
+
+- [🖼️ On-demand involvement in the room](./screenshots/text-generation-prefix-requirement.webp)
+- [🖼️ On-demand involvement in a thread](./screenshots/text-generation-on-demand-thread-involvement.webp) (the Alice user in this example is not an allowed user, yet her messages are still considered as part of the conversation context)
+- [🖼️ On-demand involvement in a reply chain](./screenshots/text-generation-on-demand-reply-involvement.webp) (the Alice user in this example is not an allowed user, yet her messages are still considered as part of the conversation context)
+
+💡 **NOTE**: Normally, the bot **only considers messages from allowed [👥 Users](./access.md#-users)** and ignores all other messages when responding. However, **when the bot is explicitly invoked (via mention)** in a thread or reply chain, **it will consider all messages** in the thread and reply chain (even those from foreign users) as part of the conversation context.
+
+
 ### 🗣️ Text-to-Speech
 
 Text-to-Speech is the bot's ability to **turn text messages into voice messages**.
@@ -118,27 +157,45 @@ To operate in this mode, you can:
 
 - adjust the [🦻 Speech-to-Text / 🪄 Flow Type](./configuration/speech-to-text.md#-flow-type) setting to make the bot only transcribe (without doing [💬 Text Generation](#-text-generation)): `!bai config room speech-to-text set-flow-type only_transcribe`
 
+- optionally adjust [🦻 Speech-to-Text / 🪄 Message Type for non-threaded only-transcribed messages](./configuration/speech-to-text.md#-message-type-for-non-threaded-only-transcribed-messages), if you'd like to bot to send messages of type `notice` (for better compatibility with other bots in the room) instead of sending regular `text` messages (default)
 
-### 🖌️ Image Generation
 
-Image generation is the bot's ability to **generate images** based on text prompts.
+### Image Generation
 
-See a [🖼️ Screenshot of the Image Generation feature](./screenshots/image-generation.webp).
+#### 🖌️ Image Creation
+
+Image creation is the bot's ability to **create images** based on text prompts.
+
+See a [🖼️ Screenshot of the Image Creation feature](./screenshots/image-creation.webp).
 
 You may also wish to see:
 
 - [🛠️ Configuration / 🖌️ Image Generation](./configuration/image-generation.md) for configuration options related to Image Generation
-- [📖 Usage / 🖌️ Image Generation](./usage.md#-image-generation) section for more details on how to use the bot for Image Generation in a room
-- [🫵 Sticker Generation](#-sticker-generation) - a special case of Image Generation
+- [📖 Usage / Image Generation / 🖌️ Creating Images](./usage.md#-creating-images) section for more details on how to use the bot for Image Creation in a room
+- [🖌️ Image Editing](#️-image-editing) - another image generation feature
+- [🫵 Sticker Creation](#-sticker-creation) - a special case of Image Creation
 
 
-### 🫵 Sticker Generation
+#### 🎨 Image Editing
 
-Sticker generation is the bot's ability to **generate sticker** images based on text prompts. It's a special case of [🖌️ Image Generation](#️-image-generation).
+Image editing is the bot's ability to **edit images** based on a prompt and one or more existing images.
 
-See a [🖼️ Screenshot of the Sticker Generation feature](./screenshots/sticker-generation.webp).
+See a [🖼️ Screenshot of the Image Editing feature (manipulating a single image)](./screenshots/image-editing-single-image.webp) and a [🖼️ Screenshot of the Image Editing feature (manipulating multiple images)](./screenshots/image-editing-multiple-images.webp).
 
-See [📖 Usage / 🖌️ Image Generation / Generating Stickers](./usage.md#generating-stickers) for details.
+You may also wish to see:
+
+- [🛠️ Configuration / 🖌️ Image Generation](./configuration/image-generation.md) for configuration options related to Image Generation
+- [📖 Usage / Image Generation / 🎨 Editing images](./usage.md#-editing-images) section for more details on how to use the bot for Image Editing in a room
+- [🖌️ Image Creation](#️-image-creation) - another image generation feature
+
+
+#### 🫵 Sticker Creation
+
+Sticker generation is the bot's ability to **generate sticker** images based on text prompts. It's a special case of [🖌️ Image Creation](#️-image-creation).
+
+See a [🖼️ Screenshot of the Sticker Creation feature](./screenshots/sticker-generation.webp).
+
+See [📖 Usage / Image Generation / 🫵 Creating Stickers](./usage.md#-creating-stickers) for details.
 
 
 ### 🔒 Encryption

docs/installation.md

@@ -15,8 +15,16 @@
 
 We provide prebuilt container images for the `amd64` and `arm64` architectures, so **you don't necessarily need to build images yourself** and can jump to [Running in a container](#-running-in-a-container).
 
-If you nevertheless wish to build a container image yourself, you can do so by running `just build-container-image`.
-This will build and tag your container image as `localhost/baibot:latest`.
+If you nevertheless wish to build a container image yourself, you can do so by running:
+
+- (recommended) `just build-container-image-release` to build a release version of the container image
+
+- or `just build-container-image-debug` to build a debug version of the container image
+
+Debug images are faster to build but are larger in size.
+Release images are ~5x smaller in size, but are slower to build.
+
+Both of these commands will build and tag your container image as `localhost/baibot:latest`.
 
 
 ### 🐋 Running in a container
@@ -45,6 +53,7 @@ CONTAINER_IMAGE_NAME=ghcr.io/etkecc/baibot:v1.0.0
   --env BAIBOT_PERSISTENCE_DATA_DIR_PATH=/data \
   --mount type=bind,src=/path/to/config.yml,dst=/app/config.yml,ro \
   --mount type=bind,src=/path/to/data,dst=/data \
+  --tmpfs=/tmp:rw,noexec,nosuid,size=1024m \
   $CONTAINER_IMAGE_NAME
 ```
 

docs/providers.md

@@ -19,21 +19,25 @@ The list of supported providers is below.
   - [OpenAI Compatible](#openai-compatible)
   - [OpenRouter](#openrouter)
   - [Together AI](#together-ai)
+  - [Venice](#venice)
 
 
 ### How to choose a provider
 
-If you're not sure which provider to start with, we **recommend [OpenAI](#openai)** as it's the most popular and has the **widest range of capabilities**: [💬 text-generation](./features.md#-text-generation), [🖌️ image-generation](./features.md#️-image-generation), [🦻 speech-to-text](./features.md#-speech-to-text), [🗣️ text-to-speech](./features.md#️-text-to-speech).
+If you're not sure which provider to start with, **we recommend [Venice](#venice)**: it's the most capable provider baibot supports (covering [💬 text-generation](./features.md#-text-generation) with vision, file inputs, prompt caching, and native web search, plus [🖌️ image-generation](./features.md#️-image-creation) incl. editing, [🦻 speech-to-text](./features.md#-speech-to-text), and [🗣️ text-to-speech](./features.md#️-text-to-speech)) and the only one that runs inference with no logging and no training on your data. If you'd rather start with the most widely-used option, [OpenAI](#openai) is a solid, well-supported choice too.
 
 You don't need to choose just one though. The bot supports [mixing & matching models](./features.md#-mixing--matching-models), so you can use multiple providers at the same time.
 
 
 ### How to use a provider
 
-- sign up for it
-- obtain an API key
-- [create a new agent](./agents.md#creating-agents)
-- set it as a handler for some types of messages (see [Mixing & matching models](./features.md#-mixing--matching-models)) for a specific room or globally
+1. 📝 **Sign up for it**
+
+2. 🔑 **Obtain an API key**
+
+3. 🤖 **Create one or more agents** in a given room or globally. Next to each provider in the [list below](#supported-providers) you'll see **🗲 Quick start** commands, but you may also refer to the [agent creation guide](./agents.md#creating-agents).
+
+4. 🤝 **Set the new agent as a handler** for a given use-purpose like text-generation, image-generation, etc. The agent creation wizard will tell you how, but you may also refer to the [🤝 Handlers](./configuration/handlers.md) guide.
 
 
 ### Supported providers
@@ -44,7 +48,7 @@ You don't need to choose just one though. The bot supports [mixing & matching mo
 
 - 🆔 Identifier: `anthropic`
 - 🔗 Links: [🏠 Home page](https://www.anthropic.com/), [🌐 Wiki](https://en.wikipedia.org/wiki/Anthropic), [👤 Sign up](https://console.anthropic.com/), [📋 Models list](https://docs.anthropic.com/en/docs/about-claude/models)
-- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation)
+- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation) (incl. vision, no tools)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local anthropic my-anthropic-agent`
   - create a global agent: `!bai agent create-global anthropic my-anthropic-agent`
@@ -58,7 +62,7 @@ You don't need to choose just one though. The bot supports [mixing & matching mo
 
 - 🆔 Identifier: `groq`
 - 🔗 Links: [🏠 Home page](https://groq.com/), [🌐 Wiki](https://en.wikipedia.org/wiki/Groq), [👤 Sign up](https://console.groq.com/login), [📋 Models list](https://console.groq.com/docs/models)
-- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation), [🦻 speech-to-text](./features.md#-speech-to-text)
+- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation) (no vision, no tools), [🦻 speech-to-text](./features.md#-speech-to-text)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local groq my-groq-agent`
   - create a global agent: `!bai agent create-global groq my-groq-agent`
@@ -72,7 +76,7 @@ You don't need to choose just one though. The bot supports [mixing & matching mo
 
 - 🆔 Identifier: `localai`
 - 🔗 Links: [🏠 Home page](https://localai.io/), [📋 Models list](https://localai.io/gallery.html)
-- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text)
+- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation) (no vision, no tools), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local localai my-localai-agent`
   - create a global agent: `!bai agent create-global localai my-localai-agent`
@@ -86,7 +90,7 @@ You don't need to choose just one though. The bot supports [mixing & matching mo
 
 - 🆔 Identifier: `mistral`
 - 🔗 Links: [🏠 Home page](https://mistral.ai/), [🌐 Wiki](https://en.wikipedia.org/wiki/Mistral_AI), [👤 Sign up](https://auth.mistral.ai/ui/registration), [📋 Models list](https://docs.mistral.ai/getting-started/models/)
-- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation)
+- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation) (no vision, no tools)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local mistral my-mistral-agent`
   - create a global agent: `!bai agent create-global mistral my-mistral-agent`
@@ -100,7 +104,7 @@ You don't need to choose just one though. The bot supports [mixing & matching mo
 
 - 🆔 Identifier: `ollama`
 - 🔗 Links: [🏠 Home page](https://ollama.com/), [📋 Models list](https://ollama.com/library)
-- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation)
+- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation) (no vision, no tools)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local ollama my-ollama-agent`
   - create a global agent: `!bai agent create-global ollama my-ollama-agent`
@@ -117,7 +121,7 @@ For services which are not fully compatible with the OpenAI API, consider using
 
 - 🆔 Identifier: `openai`
 - 🔗 Links: [🏠 Home page](https://openai.com/), [🌐 Wiki](https://en.wikipedia.org/wiki/OpenAI), [👤 Sign up](https://platform.openai.com/signup), [📋 Models list](https://platform.openai.com/docs/models)
-- 🌟 Capabilities: [🖌️ image-generation](./features.md#️-image-generation), [💬 text-generation](./features.md#-text-generation), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text)
+- 🌟 Capabilities: [🖌️ image-generation](./features.md#️-image-creation), [💬 text-generation](./features.md#-text-generation) (incl. vision, incl. [🛠️ tools](./features.md#️-built-in-tools-openai-only)), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local openai my-openai-agent`
   - create a global agent: `!bai agent create-global openai my-openai-agent`
@@ -134,7 +138,7 @@ Some of these popular services already have **shortcut** providers (leading to t
 This provider is just as featureful as the [OpenAI](#openai) provider, but is more compatible with services which do not fully adhere to the [OpenAI API spec](https://github.com/openai/openai-openapi/).
 
 - 🆔 Identifier: `openai-compatible`
-- 🌟 Capabilities: [🖌️ image-generation](./features.md#️-image-generation), [💬 text-generation](./features.md#-text-generation), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text)
+- 🌟 Capabilities: [🖌️ image-generation](./features.md#️-image-creation), [💬 text-generation](./features.md#-text-generation) (no vision, no tools), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local openai-compatible my-openai-compatible-agent`
   - create a global agent: `!bai agent create-global openai-compatible my-openai-compatible-agent`
@@ -148,7 +152,7 @@ This provider is just as featureful as the [OpenAI](#openai) provider, but is mo
 
 - 🆔 Identifier: `openrouter`
 - 🔗 Links: [🏠 Home page](https://openrouter.ai/), [👤 Sign up](https://openrouter.ai/), [📋 Models list](https://openrouter.ai/models)
-- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation)
+- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation) (no vision, no tools)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local openrouter my-openrouter-agent`
   - create a global agent: `!bai agent create-global openrouter my-openrouter-agent`
@@ -162,9 +166,101 @@ This provider is just as featureful as the [OpenAI](#openai) provider, but is mo
 
 - 🆔 Identifier: `together-ai`
 - 🔗 Links: [🏠 Home page](https://www.together.ai/), [👤 Sign up](https://api.together.ai/signup), [📋 Models list](https://api.together.xyz/models)
-- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation)
+- 🌟 Capabilities: [💬 text-generation](./features.md#-text-generation) (no vision, no tools)
 - 🗲 Quick start:
   - create a room-local agent: `!bai agent create-room-local together-ai my-together-ai-agent`
   - create a global agent: `!bai agent create-global together-ai my-together-ai-agent`
 
 💡 When creating an agent, the bot will show you an up-to-date sample configuration for this provider which looks [like this](./sample-provider-configs/together-ai.yml).
+
+
+### Venice
+
+[Venice AI](https://venice.ai/chat?ref=kpXDe6) _(ref link with a $10 bonus for you)_ runs inference on Venice-controlled GPUs or zero-data-retention partner infrastructure and stores no prompts or responses, so your conversations don't linger anywhere. It serves both frontier proprietary models and the latest open-source ones.
+
+- 🆔 Identifier: `venice`
+- 🔗 Links: [🏠 Home page](https://venice.ai/chat?ref=kpXDe6), [👤 Sign up](https://venice.ai/chat?ref=kpXDe6), [📋 Models list](https://docs.venice.ai/models/overview)
+- 🌟 Capabilities: [🖌️ image-generation](./features.md#️-image-creation) (incl. editing, via the native knob-rich `/image/generate` and `/image/edit` endpoints), [💬 text-generation](./features.md#-text-generation) (incl. vision, file inputs like PDF and DOCX, and prompt caching; native web search via the `venice_parameters` config), [🗣️ text-to-speech](./features.md#️-text-to-speech), [🦻 speech-to-text](./features.md#-speech-to-text)
+- 🗲 Quick start:
+  - create a room-local agent: `!bai agent create-room-local venice my-venice-agent`
+  - create a global agent: `!bai agent create-global venice my-venice-agent`
+
+💡 When creating an agent, the bot will show you an up-to-date sample configuration for this provider which looks [like this](./sample-provider-configs/venice.yml).
+
+Unlike the [OpenAI Compatible](#openai-compatible) provider (which can talk to Venice but drops images and can't reach its audio or native image endpoints), this is a first-class Venice integration that exposes Venice's full parameter set. Image generation uses the native `/image/generate` endpoint rather than the OpenAI-compatible `/images/generations` shim, so every Venice-specific knob below is available.
+
+#### Configuration reference
+
+Every parameter below is optional unless marked otherwise. Omitting a knob lets Venice apply its own server-side default; this is **not** the same as setting it to `false`, which actively sends `false`.
+
+**`text_generation`** (top-level knobs) — sampling, caching, and reasoning controls that sit directly on `text_generation`, next to `model_id`, `prompt`, `temperature`, `max_response_tokens`, and `max_context_tokens`. They map to top-level fields on Venice's request, separate from the `venice_parameters` bag below.
+
+| Knob | What it does | Default |
+|------|--------------|---------|
+| `top_p` | Nucleus sampling, `0.0`–`1.0`. An alternative to `temperature`. | — |
+| `frequency_penalty` | Penalize tokens by how often they have already appeared, `-2.0`–`2.0`. | — |
+| `presence_penalty` | Penalize tokens that have appeared at all, `-2.0`–`2.0`. | — |
+| `repetition_penalty` | Penalize repetition. Values above `1.0` discourage repeats. | — |
+| `reasoning_effort` | Reasoning budget for models that support it: `low`, `medium`, `high`. | — |
+| `prompt_cache_retention` | How long Venice keeps the prompt prefix cached: `default`, `extended`, or `24h`. `24h` is the lever that makes a long, stable system prompt cheap across a day of conversations. | `24h` |
+| `show_reasoning` | Append the model's reasoning (its `reasoning_content`) below the answer, as a collapsible `💭 Reasoning` block that stays folded until clicked. Reads a field separate from the answer text, so it works regardless of `strip_thinking_response`. | `false` |
+
+**`text_generation.venice_parameters`** — Venice-specific request knobs sent in the `venice_parameters` bag. Set any of them to override Venice's behavior. The `Default` column shows the value baibot's sample config ships; a `—` means the knob is left unset, so Venice's own default applies.
+
+| Knob | What it does | Default |
+|------|--------------|---------|
+| `enable_web_search` | Web search mode: `auto` (model decides), `on` (always), or `off`. | `auto` |
+| `enable_web_citations` | Append source citations to web-search answers. | — |
+| `enable_web_scraping` | Allow the model to scrape page contents during web search. | — |
+| `enable_x_search` | Include X (Twitter) in web search. | — |
+| `include_search_results_in_stream` | Stream search results back as they arrive. | — |
+| `return_search_results_as_documents` | Return search results as structured documents. | — |
+| `include_venice_system_prompt` | Prepend Venice's own system prompt alongside yours. | — |
+| `character_slug` | Use a public Venice character by its slug. | — |
+| `strip_thinking_response` | Strip `<think></think>` blocks from reasoning models so the user sees only the answer. | `true` |
+| `disable_thinking` | Disable the model's reasoning step entirely. | — |
+| `enable_e2ee` | Run in end-to-end-encrypted mode rather than the default TEE-only mode. | `false` |
+| `verbosity` | Response verbosity for models that support it: `low`, `medium`, `high`. | — |
+
+**`text_to_speech`**:
+
+| Knob | What it does | Default |
+|------|--------------|---------|
+| `model_id` | The Venice TTS model (e.g. `tts-kokoro`, `tts-qwen3-1-7b`, `tts-xai-v1`). | `tts-kokoro` |
+| `voice` | The voice to synthesize with. Model-specific (Kokoro: `af_*`/`am_*`/`bf_*`/`bm_*`); a cloned-voice handle (`vv_<id>`) also works. | `af_sky` |
+| `response_format` | Audio format: `mp3`, `opus`, `aac`, `flac`, `wav`, or `pcm`. | `mp3` |
+| `speed` | Playback speed, `0.25`–`4.0`. | `1.0` |
+| `prompt` | A style prompt steering emotion/delivery. Only Qwen 3 TTS honors it. | — |
+| `temperature` | Sampling temperature, `0.0`–`2.0`. Only Qwen 3 / Orpheus / Chatterbox HD honor it. | — |
+| `top_p` | Nucleus sampling, `0.0`–`1.0`. Only Qwen 3 TTS honors it. | — |
+
+**`image_generation`**:
+
+| Knob | What it does | Default |
+|------|--------------|---------|
+| `model_id` | The image-generation model. | `chroma` |
+| `negative_prompt` | A description of what should **not** appear in the image. | — |
+| `cfg_scale` | CFG scale, `0`–`20`. Higher values adhere more closely to the prompt. | — |
+| `steps` | Number of inference steps. Model-specific; some models ignore it. | — |
+| `style_preset` | A named style to apply (e.g. `3D Model`). | — |
+| `seed` | Random seed, `-999999999`–`999999999`. Fix it for reproducible results. | random |
+| `safe_mode` | Blur images classified as adult content. | `true` |
+| `hide_watermark` | Hide the Venice watermark (may be ignored for some content). | `false` |
+| `format` | Output format: `jpeg`, `png`, or `webp`. | `webp` |
+| `width` / `height` | Image dimensions in pixels, each `1`–`1280`. | `1024` |
+| `aspect_ratio` | Aspect ratio for models that support it (e.g. `1:1`, `16:9`). Alternative to `width`/`height`. | — |
+| `resolution` | Resolution tier for models that support it (`1K`, `2K`, `4K`). | — |
+| `quality` | Output quality for supported models: `low`, `medium`, `high`. Higher can cost more. | — |
+| `lora_strength` | Lora strength, `0`–`100`. Only applies if the model uses additional Loras. | — |
+| `embed_exif_metadata` | Embed the generation prompt into the image's EXIF metadata. | `false` |
+| `enable_web_search` | Let the model pull the latest info from the web. Model-specific; costs extra credits. | — |
+
+**`image_generation.edit`** — image editing reuses the `image_generation` block; only the model and a few output knobs differ:
+
+| Knob | What it does | Default |
+|------|--------------|---------|
+| `model_id` | The image-edit model. | `firered-image-edit` |
+| `output_format` | Output format: `jpeg`, `png`, or `webp`. When omitted, Venice infers it (PNG at 1K, JPEG at 2K/4K). | inferred |
+| `aspect_ratio` | Aspect ratio of the result: `auto`, `1:1`, `3:2`, `16:9`, `21:9`, `9:16`, `2:3`, `3:4`, `4:5` (model-specific). | — |
+| `resolution` | Resolution tier: `1K`, `2K`, `4K` (model-specific). | `1K` |
+| `safe_mode` | Blur images classified as adult content. | `true` |

docs/sample-provider-configs/anthropic.yml

@@ -1,8 +1,8 @@
 base_url: https://api.anthropic.com/v1
 api_key: YOUR_API_KEY_HERE
 text_generation:
-  model_id: claude-3-5-sonnet-20240620
-  prompt: You are a brief, but helpful bot.
+  model_id: claude-3-7-sonnet-20250219
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
   max_response_tokens: 8192
   max_context_tokens: 204800

docs/sample-provider-configs/groq.yml

@@ -2,7 +2,7 @@ base_url: https://api.groq.com/openai/v1
 api_key: YOUR_API_KEY_HERE
 text_generation:
   model_id: llama3-70b-8192
-  prompt: You are a brief, but helpful bot.
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
   max_response_tokens: 4096
   max_context_tokens: 131072

docs/sample-provider-configs/localai.yml

@@ -2,7 +2,7 @@ base_url: http://my-localai-self-hosted-service:8080/v1
 api_key: YOUR_API_KEY_HERE
 text_generation:
   model_id: gpt-4
-  prompt: You are a brief, but helpful bot.
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
   max_response_tokens: 4096
   max_context_tokens: 128000

docs/sample-provider-configs/mistral.yml

@@ -2,7 +2,7 @@ base_url: https://api.mistral.ai/v1
 api_key: YOUR_API_KEY_HERE
 text_generation:
   model_id: mistral-large-latest
-  prompt: You are a brief, but helpful bot.
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
   max_response_tokens: 4096
   max_context_tokens: 128000

docs/sample-provider-configs/ollama.yml

@@ -2,7 +2,7 @@ base_url: http://my-ollama-self-hosted-service:11434/v1
 api_key: YOUR_API_KEY_HERE
 text_generation:
   model_id: gemma2:2b
-  prompt: You are a brief, but helpful bot.
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
   max_response_tokens: 4096
   max_context_tokens: 128000

docs/sample-provider-configs/openai-compatible.yml

@@ -2,7 +2,7 @@ base_url: ''
 api_key: YOUR_API_KEY_HERE
 text_generation:
   model_id: some-model
-  prompt: You are a brief, but helpful bot.
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
   max_response_tokens: 4096
   max_context_tokens: 128000

docs/sample-provider-configs/openai.yml

@@ -1,11 +1,18 @@
 base_url: https://api.openai.com/v1
 api_key: YOUR_API_KEY_HERE
 text_generation:
-  model_id: gpt-4o-2024-08-06
-  prompt: You are a brief, but helpful bot.
+  model_id: gpt-5.4
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
-  max_response_tokens: 16384
-  max_context_tokens: 128000
+  # Reasoning models need to use `max_completion_tokens` instead of `max_response_tokens`.
+  # If you're dealing with a non-reasoning model, specify `max_response_tokens` and unset `max_completion_tokens`.
+  max_response_tokens: null
+  max_completion_tokens: 128000
+  max_context_tokens: 400000
+  # Built-in tools
+  tools:
+    web_search: false
+    code_interpreter: false
 speech_to_text:
   model_id: whisper-1
 text_to_speech:
@@ -14,7 +21,7 @@ text_to_speech:
   speed: 1.0
   response_format: opus
 image_generation:
-  model_id: dall-e-3
-  style: vivid
-  size: 1024x1024
-  quality: standard
+  model_id: gpt-image-2
+  style: null
+  size: null
+  quality: null

docs/sample-provider-configs/openrouter.yml

@@ -2,7 +2,7 @@ base_url: https://openrouter.ai/api/v1
 api_key: YOUR_API_KEY_HERE
 text_generation:
   model_id: mattshumer/reflection-70b:free
-  prompt: You are a brief, but helpful bot.
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
   max_response_tokens: 2048
   max_context_tokens: 8192

docs/sample-provider-configs/together-ai.yml

@@ -2,7 +2,7 @@ base_url: https://api.together.xyz/v1
 api_key: YOUR_API_KEY_HERE
 text_generation:
   model_id: meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo
-  prompt: You are a brief, but helpful bot.
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
   temperature: 1.0
   max_response_tokens: 2048
   max_context_tokens: 8192

docs/sample-provider-configs/venice.yml

@@ -0,0 +1,117 @@
+base_url: https://api.venice.ai/api/v1
+api_key: YOUR_API_KEY_HERE
+text_generation:
+  model_id: kimi-k2-5
+  prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
+  temperature: 1.0
+  max_response_tokens: 4096
+  max_context_tokens: 128000
+  # Prompt caching: how long Venice keeps the prompt prefix cached. "default", "extended", or "24h".
+  # "24h" (shipped by default) makes a long, stable system prompt cheap across a day of conversations.
+  prompt_cache_retention: 24h
+  # Top-level sampling and reasoning knobs (uncomment to override Venice's default):
+  # Nucleus sampling, 0.0-1.0 (an alternative to temperature).
+  # top_p: 0.9
+  # Penalize tokens by how often they have already appeared, -2.0-2.0.
+  # frequency_penalty: 0.0
+  # Penalize tokens that have appeared at all, -2.0-2.0.
+  # presence_penalty: 0.0
+  # Penalize repetition; values above 1.0 discourage repeats.
+  # repetition_penalty: 1.0
+  # Reasoning budget for models that support it: low, medium, high.
+  # reasoning_effort: medium
+  # Append the model's reasoning below the answer as a collapsible "💭 Reasoning" block (folded by
+  # default). Reads a field separate from the answer text, so it works alongside
+  # strip_thinking_response (which only strips <think> blocks from the answer).
+  # show_reasoning: true
+  # Venice-specific request parameters. Only the keys present below are sent to Venice; omit a
+  # key to fall back to Venice's own default. Omitting a knob is NOT the same as setting it to
+  # `false` — `false` actively sends `false`.
+  venice_parameters:
+    # Web search: "auto" (model decides), "on" (always), or "off".
+    enable_web_search: "auto"
+    # Strip <think></think> blocks from reasoning models so the user sees only the answer.
+    strip_thinking_response: true
+    # Run in TEE-only mode instead of end-to-end encryption (works across all models).
+    enable_e2ee: false
+    # Other available knobs — uncomment to override Venice's default:
+    # enable_web_citations: true
+    # enable_web_scraping: true
+    # include_venice_system_prompt: false
+    # include_search_results_in_stream: true
+    # return_search_results_as_documents: true
+    # enable_x_search: true
+    # disable_thinking: true
+    # Response verbosity for models that support it: low, medium, high.
+    # verbosity: medium
+    # character_slug: public-character-id
+speech_to_text:
+  model_id: nvidia/parakeet-tdt-0.6b-v3
+text_to_speech:
+  # The Venice TTS model. Others include tts-qwen3-1-7b, tts-xai-v1,
+  # tts-elevenlabs-turbo-v2-5, tts-minimax-speech-02-hd. See the models list endpoint.
+  model_id: tts-kokoro
+  # The voice to synthesize with. Voices are model-specific: Kokoro uses af_*/am_*/bf_*/bm_*
+  # (e.g. af_sky, am_adam), other models have their own sets. You can also pass a cloned-voice
+  # handle (vv_<id>) created via Venice's voice-cloning API. An incompatible voice returns an error.
+  voice: af_sky
+  # Output audio format: mp3, opus, aac, flac, wav, or pcm. mp3 is the broadest Matrix-client fit.
+  response_format: mp3
+  # Other available knobs — uncomment to override Venice's default:
+  # Playback speed, 0.25–4.0 (1.0 is normal).
+  # speed: 1.0
+  # A style prompt steering emotion/delivery (e.g. "Excited and energetic."). Only Qwen 3 TTS uses it.
+  # prompt: "Calm and warm."
+  # Sampling temperature, 0.0–2.0 (higher = more varied). Only Qwen 3 / Orpheus / Chatterbox HD use it.
+  # temperature: 0.9
+  # Nucleus sampling, 0.0–1.0. Only Qwen 3 TTS uses it.
+  # top_p: 1.0
+image_generation:
+  # The image-generation model. See the models list endpoint for the full set.
+  model_id: chroma
+  # The image-edit model, used when editing an existing image rather than generating a new one.
+  # Editing shares this same image_generation config block; only the model differs.
+  edit:
+    model_id: firered-image-edit
+    # Other edit knobs — uncomment to override Venice's default:
+    # Output format: jpeg, png, or webp. When omitted, Venice infers it (PNG at 1K, JPEG at 2K/4K).
+    # output_format: png
+    # Aspect ratio of the result: auto, 1:1, 3:2, 16:9, 21:9, 9:16, 2:3, 3:4, 4:5 (model-specific).
+    # aspect_ratio: auto
+    # Resolution tier: 1K, 2K, 4K (model-specific). Defaults to 1K.
+    # resolution: 1K
+    # Blur images classified as adult content. Defaults to true.
+    # safe_mode: true
+  # Other generation knobs — uncomment to override Venice's default. Omitting a knob is NOT the same
+  # as setting it: an omitted knob lets Venice apply its own default, a set value is sent verbatim.
+  # A description of what should NOT appear in the image.
+  # negative_prompt: "blurry, watermark, text"
+  # CFG scale, 0–20. Higher values make the image adhere more closely to the prompt.
+  # cfg_scale: 7.5
+  # Number of inference steps. Model-specific; some models ignore it.
+  # steps: 8
+  # A named style to apply (e.g. "3D Model"). See Venice's image-styles reference.
+  # style_preset: "3D Model"
+  # Random seed, -999999999–999999999. Fix it for reproducible results; omit for a random seed.
+  # seed: 123456789
+  # Blur images classified as adult content. Defaults to true.
+  # safe_mode: true
+  # Hide the Venice watermark. Venice may ignore this for certain generated content. Defaults to false.
+  # hide_watermark: false
+  # Output format: jpeg, png, or webp. webp is smallest; png is highest-quality. Defaults to webp.
+  # format: webp
+  # Image dimensions in pixels, each 1–1280. Default 1024×1024.
+  # width: 1024
+  # height: 1024
+  # Aspect ratio (used by certain models, e.g. Nano Banana): "1:1", "16:9". An alternative to width/height.
+  # aspect_ratio: "1:1"
+  # Resolution tier (used by certain models): "1K", "2K", "4K".
+  # resolution: "1K"
+  # Output quality for supported models (e.g. GPT Image 2): low, medium, high. Higher can cost more.
+  # quality: high
+  # Lora strength, 0–100. Only applies if the model uses additional Loras.
+  # lora_strength: 50
+  # Embed the generation prompt into the image's EXIF metadata. Defaults to false.
+  # embed_exif_metadata: false
+  # Let the model pull the latest info from the web for the image. Model-specific; costs extra credits.
+  # enable_web_search: false

docs/usage.md

@@ -11,10 +11,13 @@ This is related to the [💬 Text Generation](./features.md#-text-generation) fe
 
 If there's a text-generation handler agent configured, the bot **may** respond to messages sent in the room.
 
-🖼️ See screenshots of:
+Some models also support vision and document understanding, so you may be able to mix text, images, and files (PDFs, text documents, etc.) in the same conversation.
 
-- the [default Text Generation flow](./screenshots/text-generation.webp) for 1:1 rooms
-- the [Text Generation flow in multi-user rooms](./screenshots/text-generation-prefix-requirement.webp) (where the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting is auto-configured to "required")
+See screenshots of:
+
+- 🖼️ [the default Text Generation flow](./screenshots/text-generation.webp) in 1:1 rooms
+- 🖼️ [the Text Generation flow in multi-user rooms](./screenshots/text-generation-prefix-requirement.webp) (where the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting is auto-configured to "required")
+- the [on-demand involvement](./features.md#on-demand-involvement) feature
 
 Whether the bot responds depends on:
 
@@ -24,9 +27,9 @@ Whether the bot responds depends on:
 
 - (🎨 agent capabilities) whether the configured `text-generation` (or `catch-all`) handler agent actually supports text-generation. The provider may lack support for this feature or it may be disabled in the [🤖 agents](./agents.md) configuration
 
-- (the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting) whether a prefix (e.g. `!bai`) is required in front of messages sent to the room. For multi-user rooms, this setting defaults to "required"
+- (the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting) whether a prefix (e.g. `!bai`) or user mention (e.g. `@baibot`) is required for messages sent to the room. For multi-user rooms, this setting defaults to "required". See [🌟 Features / 💬 Text Generation / On-demand involvement](./features.md#on-demand-involvement) for details.
 
-Room messages start a threaded conversation where you can continue back-and-forth communication with the bot.
+Room messages start a threaded conversation where you can continue back-and-forth communication with the bot. Using [on-demand involvement](./features.md#on-demand-involvement), you can can also mention the bot to provoke it to get involved in any conversation thread or reply chain.
 
 Unless you've enabled the [♻️ Context Management](./features.md#️-context-management) feature, all messages will be sent to the agent's API each time. If the context management feature is enabled, older messages may be dropped.
 
@@ -63,34 +66,48 @@ The speech-to-text feature triggers automatically by default, but can be adjuste
 If all your messages are in the same language, you can improve accuracy & latency by configuring the language (see [🦻 Speech-to-Text / 🔤 Language](./configuration/speech-to-text.md#-language)).
 
 
-### 🖌️ Image Generation
-
-This is related to the [🖌️ Image Generation](./features.md#️-image-generation) feature.
+### Image Generation
 
 This feature is not configurable at the moment. The configuration (size, quality, style) specified at the [🤖 agent](./agents.md) level will be used.
 
+Capabilities depend on the [☁️ provider](./providers.md) and model used.
 
-#### Generating images
 
-Simply send a command like `!bai image A beautiful sunset over the ocean` and the bot will start a threaded conversation and post an image based on your prompt.
+#### 🖌️ Creating images
 
-See a [🖼️ Screenshot of the Image Generation feature](./screenshots/image-generation.webp).
+Simply send a command like `!bai image create A beautiful sunset over the ocean` and the bot will start a threaded conversation and post an image based on your prompt.
 
-You can then, respond in the same message thread with:
+See a [🖼️ Screenshot of the Image Creation feature](./screenshots/image-creation.webp).
+
+You can then respond in the same message thread with:
 
 - more messages, to add more criteria to your prompt.
 - a message saying `again`, to generate one more image with the current prompt.
 
 
-#### Generating stickers
+#### 🎨 Editing images
 
-A variation of [generating images](#generating-images) is to generate "sticker images".
+Simply send a command like `!bai image edit Turn the following image into an anime-style drawing` and the bot will start a threaded conversation asking for more details.
 
-See a [🖼️ Screenshot of the Sticker Generation feature](./screenshots/sticker-generation.webp).
+See a [🖼️ Screenshot of the Image Editing feature (manipulating a single image)](./screenshots/image-editing-single-image.webp) and a [🖼️ Screenshot of the Image Editing feature (manipulating multiple images)](./screenshots/image-editing-multiple-images.webp).
 
-To generate a sticker, send a command like `!bai sticker A huge ramen bowl with lots of chashu and a mountain of beansprouts on top`.
+You can then respond in the same message thread with:
 
-The difference from [generating images](#generating-images) is that the bot will:
+- more messages, to add more criteria to your prompt.
+- one or more images, to provide the images that the bot will operate on.
+- a message saying `go`, to start the image generation process.
+- a message saying `again`, to prompt the bot to generate one more image edit with the current prompt.
+
+
+#### 🫵 Creating stickers
+
+A variation of [creating images](#creating-images) is creating "sticker images".
+
+See a [🖼️ Screenshot of the Sticker Creation feature](./screenshots/sticker-generation.webp).
+
+To create a sticker, send a command like `!bai sticker A huge ramen bowl with lots of chashu and a mountain of beansprouts on top`.
+
+The difference from [creating images](#creating-images) is that the bot will:
 
 - generate a smaller-resolution image (currently hardcoded to `256x256`) - smaller/quicker, but still good enough for a sticker
 - potentially switch to a different (cheaper or otherwise more suitable) model, if available

etc/app/config.yml.dist

@@ -1,16 +1,31 @@
 homeserver:
   # The canonical homeserver domain name
-  server_name: synapse.127.0.0.1.nip.io
-  url: http://synapse.127.0.0.1.nip.io:42020
+  server_name: __HOMESERVER_SERVER_NAME__
+  url: __HOMESERVER_URL__
 
 user:
   mxid_localpart: baibot
+
+  # Authentication: set EITHER password OR access_token + device_id.
+  #
+  # Password-based login (traditional homeservers):
   password: baibot
 
+  # Access token login (for Matrix Authentication Service/OIDC-enabled homeservers):
+  # Generate a token via: mas-cli manage issue-compatibility-token <username> [device_id]
+  # access_token: null
+  # device_id: null
+
   # The name the bot uses as a display name and when it refers to itself.
   # Leave empty to use the default (baibot).
   name: baibot
 
+  # An optional path to an image file to be used as a custom avatar image.
+  # - null or empty string: use the default avatar
+  # - "keep": don't touch the avatar, keep whatever is already set
+  # - any other value: path to a custom avatar image file
+  avatar: null
+
   encryption:
     # An optional passphrase to use for backing up and recovering the bot's encryption keys.
     # You can use any string here.
@@ -32,10 +47,14 @@ user:
 # Command prefix. Leave empty to use the default (!bai).
 command_prefix: "!bai"
 
+room:
+  # Whether the bot should send an introduction message after joining a room.
+  post_join_self_introduction_enabled: true
+
 access:
   # Space-separated list of MXID patterns which specify who is an admin.
   admin_patterns:
-    - "@admin:synapse.127.0.0.1.nip.io"
+    - "@admin:__HOMESERVER_SERVER_NAME__"
 
 persistence:
   # This is unset here, because we expect the configuration to come from an environment variable (BAIBOT_PERSISTENCE_DATA_DIR_PATH).
@@ -72,11 +91,18 @@ agents:
     #     base_url: https://api.openai.com/v1
     #     api_key: ""
     #     text_generation:
-    #       model_id: gpt-4o-2024-08-06
-    #       prompt: You are a brief, but helpful bot.
+    #       model_id: gpt-5.4
+    #       prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
     #       temperature: 1.0
-    #       max_response_tokens: 16384
-    #       max_context_tokens: 128000
+    #       # Reasoning models need to use `max_completion_tokens` instead of `max_response_tokens`.
+    #       # If you're dealing with a non-reasoning model, specify `max_response_tokens` and unset `max_completion_tokens`.
+    #       max_response_tokens: null
+    #       max_completion_tokens: 128000
+    #       max_context_tokens: 400000
+    #       # Built-in tools
+    #       tools:
+    #         web_search: false
+    #         code_interpreter: false
     #     speech_to_text:
     #       model_id: whisper-1
     #     text_to_speech:
@@ -85,10 +111,10 @@ agents:
     #       speed: 1.0
     #       response_format: opus
     #     image_generation:
-    #       model_id: dall-e-3
-    #       style: vivid
-    #       size: 1024x1024
-    #       quality: standard
+    #       model_id: gpt-image-2
+    #       style: null
+    #       size: null
+    #       quality: null
     #
     # - id: localai
     #   provider: localai
@@ -97,7 +123,7 @@ agents:
     #     api_key: null
     #     text_generation:
     #       model_id: gpt-4
-    #       prompt: You are a brief, but helpful bot.
+    #       prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
     #       temperature: 1.0
     #       max_response_tokens: 16384
     #       max_context_tokens: 128000
@@ -122,7 +148,7 @@ agents:
     #     api_key: null
     #     text_generation:
     #       model_id: "gemma2:2b"
-    #       prompt: "You are an assistant based on the gemma2:2b model. Be brief in your responses."
+    #       prompt: "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
     #       temperature: 1.0
     #       max_response_tokens: 4096
     #       max_context_tokens: 128000
@@ -140,7 +166,7 @@ initial_global_config:
   # Space-separated list of MXID patterns which specify who can use the bot.
   # By default, we let anyone on the homeserver use the bot.
   user_patterns:
-    - "@*:synapse.127.0.0.1.nip.io"
+    - "@*:__HOMESERVER_SERVER_NAME__"
 
 # Controls logging.
 #

etc/services/continuwuity/compose.yml

@@ -0,0 +1,23 @@
+services:
+  continuwuity:
+    image: forgejo.ellis.link/continuwuation/continuwuity:v0.5.10
+    user: "${UID}:${GID}"
+    restart: unless-stopped
+    cap_drop:
+      - ALL
+    read_only: true
+    environment:
+      CONDUWUIT_CONFIG: /etc/continuwuity/continuwuity.toml
+      CONDUWUIT_DATABASE_PATH: /var/lib/continuwuity
+    ports:
+      - "${SERVICE_CONTINUWUITY_BIND_PORT_CLIENT_API}:6167"
+    volumes:
+      - ../../etc/services/continuwuity/config:/etc/continuwuity:ro
+      - ./continuwuity/data:/var/lib/continuwuity
+    tmpfs:
+      - /tmp:rw,noexec,nosuid,size=500m
+
+networks:
+  default:
+    name: ${NETWORK_NAME}
+    external: true

etc/services/continuwuity/config/continuwuity.toml

@@ -0,0 +1,19 @@
+[global]
+server_name = "continuwuity.127.0.0.1.nip.io"
+
+address = "0.0.0.0"
+port = 6167
+
+database_path = "/var/lib/continuwuity"
+
+allow_registration = true
+yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse = true
+
+new_user_displayname_suffix = ""
+
+max_request_size = 20_000_000
+
+allow_federation = false
+trusted_servers = ["matrix.org"]
+
+log = "info,state_res=warn,rocket=off,_=off,sled=off"

etc/services/continuwuity/register-user.sh

@@ -0,0 +1,48 @@
+#!/bin/sh
+set -eu
+
+if [ $# -ne 3 ]; then
+	echo "Usage: $0 <env-file> <username> <password>"
+	exit 1
+fi
+
+ENV_FILE="$1"
+USERNAME="$2"
+PASSWORD="$3"
+
+SERVER="http://$(grep '^SERVICE_CONTINUWUITY_BIND_PORT_CLIENT_API=' "${ENV_FILE}" | cut -d= -f2)"
+REGISTER_URL="${SERVER}/_matrix/client/v3/register"
+
+echo "Registering user '${USERNAME}' on ${SERVER}..."
+
+SESSION_RESPONSE=$(curl -s -X POST "${REGISTER_URL}" \
+	-H 'Content-Type: application/json' \
+	-d "{\"username\": \"${USERNAME}\", \"password\": \"${PASSWORD}\"}")
+
+SESSION_ID=$(echo "${SESSION_RESPONSE}" | grep -o '"session":"[^"]*"' | head -1 | cut -d'"' -f4)
+if [ -z "${SESSION_ID}" ]; then
+	echo "Error: Could not get session ID. Response: ${SESSION_RESPONSE}"
+	exit 1
+fi
+
+# Determine the required auth flow from the server response.
+# The first user requires m.login.registration_token (bootstrap token from logs).
+# Subsequent users use m.login.dummy (open registration).
+if echo "${SESSION_RESPONSE}" | grep -q 'm.login.registration_token'; then
+	CONTAINER_ID=$(docker ps -q --filter name=baibot-continuwuity-continuwuity)
+	REG_TOKEN=$(docker logs "${CONTAINER_ID}" 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep 'using the registration token' | grep -oP 'registration token \K[A-Za-z0-9]+' | head -1)
+	AUTH_BODY="{\"type\": \"m.login.registration_token\", \"token\": \"${REG_TOKEN}\", \"session\": \"${SESSION_ID}\"}"
+else
+	AUTH_BODY="{\"type\": \"m.login.dummy\", \"session\": \"${SESSION_ID}\"}"
+fi
+
+RESULT=$(curl -s -X POST "${REGISTER_URL}" \
+	-H 'Content-Type: application/json' \
+	-d "{\"username\": \"${USERNAME}\", \"password\": \"${PASSWORD}\", \"auth\": ${AUTH_BODY}}")
+
+if echo "${RESULT}" | grep -q '"user_id"'; then
+	echo "Successfully registered user: $(echo "${RESULT}" | grep -o '"user_id":"[^"]*"' | cut -d'"' -f4)"
+else
+	echo "Registration failed. Response: ${RESULT}"
+	exit 1
+fi

etc/services/core/element-web/nginx.conf

@@ -1,60 +0,0 @@
-# This is a custom nginx configuration file that we use in the container (instead of the default one),
-# because it allows us to run nginx with a non-root user.
-#
-# For this to work, the default vhost file (`/etc/nginx/conf.d/default.conf`) also needs to be removed.
-# (mounting `/dev/null` over `/etc/nginx/conf.d/default.conf` works well)
-#
-# The following changes have been done compared to a default nginx configuration file:
-# - default server port is changed (80 -> 8080), so that a non-root user can bind it
-# - various temp paths are changed to `/tmp`, so that a non-root user can write to them
-# - the `user` directive was removed, as we don't want nginx to switch users
-
-worker_processes  1;
-
-error_log /var/log/nginx/error.log warn;
-pid /tmp/nginx.pid;
-
-
-events {
-	worker_connections  1024;
-}
-
-
-http {
-	client_body_temp_path /tmp/client_body_temp;
-	proxy_temp_path /tmp/proxy_temp;
-	fastcgi_temp_path /tmp/fastcgi_temp;
-	uwsgi_temp_path /tmp/uwsgi_temp;
-	scgi_temp_path /tmp/scgi_temp;
-
-	include       /etc/nginx/mime.types;
-	default_type  application/octet-stream;
-
-	log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
-					  '$status $body_bytes_sent "$http_referer" '
-					  '"$http_user_agent" "$http_x_forwarded_for"';
-
-	access_log  /var/log/nginx/access.log  main;
-
-	sendfile        on;
-	#tcp_nopush     on;
-
-	keepalive_timeout  65;
-
-	#gzip  on;
-
-	server {
-		listen       8080;
-		server_name  localhost;
-
-		location / {
-			root   /usr/share/nginx/html;
-			index  index.html index.htm;
-		}
-
-		error_page   500 502 503 504  /50x.html;
-		location = /50x.html {
-			root   /usr/share/nginx/html;
-		}
-	}
-}

etc/services/element-web/compose.yml

@@ -0,0 +1,21 @@
+services:
+  element-web:
+    image: ghcr.io/element-hq/element-web:v1.12.22
+    user: "${UID}:${GID}"
+    restart: unless-stopped
+    environment:
+      ELEMENT_WEB_PORT: 8080
+    ports:
+      - "${SERVICE_ELEMENT_WEB_BIND_PORT_HTTP}:8080"
+    volumes:
+    - ./element-web/config.json:/app/config.json:ro
+    tmpfs:
+      - /var/cache/nginx:rw,mode=777
+      - /var/run:rw,mode=777
+      - /tmp/element-web-config:rw,mode=777
+      - /etc/nginx/conf.d:rw,mode=777
+
+networks:
+  default:
+    name: ${NETWORK_NAME}
+    external: true

etc/services/element-web/config.json.dist

@@ -1,9 +1,9 @@
 {
-    "default_hs_url": "http://synapse.127.0.0.1.nip.io:42020",
+    "default_hs_url": "__HOMESERVER_CLIENT_URL__",
     "default_is_url": "https://vector.im",
     "integrations_ui_url": "https://scalar.vector.im/",
     "integrations_rest_url": "https://scalar.vector.im/api",
-    "bug_report_endpoint_url": "https://riot.im/bugreports/submit",
+    "bug_report_endpoint_url": "https://element.io/bugreports/submit",
     "enableLabs": true,
     "roomDirectory": {
         "servers": [

etc/services/env.dist

@@ -3,6 +3,8 @@ SERVICE_SYNAPSE_BIND_PORT_FEDERATION_API=127.0.0.1:42028
 
 SERVICE_ELEMENT_WEB_BIND_PORT_HTTP=127.0.0.1:42025
 
+SERVICE_CONTINUWUITY_BIND_PORT_CLIENT_API=127.0.0.1:42030
+
 SERVICE_OLLAMA_BIND_PORT_HTTP=127.0.0.1:42026
 
 # See https://localai.io/basics/container/#all-in-one-images for the list of available images

etc/services/ollama/compose.yml

@@ -1,6 +1,6 @@
 services:
   ollama:
-    image: docker.io/ollama/ollama:0.3.9
+    image: docker.io/ollama/ollama:0.30.11
     restart: unless-stopped
     ports:
       - "${SERVICE_OLLAMA_BIND_PORT_HTTP}:11434"

etc/services/synapse/compose.yml

@@ -1,6 +1,6 @@
 services:
   postgres:
-    image: docker.io/postgres:16.3-alpine
+    image: docker.io/postgres:18.4-alpine
     user: ${UID}:${GID}
     restart: unless-stopped
     environment:
@@ -8,12 +8,13 @@ services:
      POSTGRES_PASSWORD: synapse-password
      POSTGRES_DB: homeserver
      POSTGRES_INITDB_ARGS: --lc-collate C --lc-ctype C --encoding UTF8
+     PGDATA: /data
     volumes:
-    - ./postgres:/var/lib/postgresql/data
+    - ./postgres:/data
     - /etc/passwd:/etc/passwd:ro
 
   synapse:
-    image: ghcr.io/element-hq/synapse:v1.114.0
+    image: ghcr.io/element-hq/synapse:v1.155.0
     user: "${UID}:${GID}"
     restart: unless-stopped
     entrypoint: python
@@ -22,19 +23,9 @@ services:
     - "${SERVICE_SYNAPSE_BIND_PORT_CLIENT_API}:8008"
     - "${SERVICE_SYNAPSE_BIND_PORT_FEDERATION_API}:8008"
     volumes:
-    - ../../etc/services/core/synapse/config:/config:ro
+    - ../../etc/services/synapse/config:/config:ro
     - ./synapse/media-store:/media-store
 
-  element-web:
-    image: docker.io/vectorim/element-web:v1.11.77
-    user: "${UID}:${GID}"
-    restart: unless-stopped
-    ports:
-      - "${SERVICE_ELEMENT_WEB_BIND_PORT_HTTP}:8080"
-    volumes:
-    - ../../etc/services/core/element-web/nginx.conf:/etc/nginx/nginx.conf:ro
-    - ../../etc/services/core/element-web/config.json:/app/config.json:ro
-
 networks:
   default:
     name: ${NETWORK_NAME}

etc/services/synapse/config/homeserver.yaml

@@ -579,7 +579,7 @@ rc_login:
 #
 #federation_rr_transactions_per_room_per_second: 50
 
-
+enable_authenticated_media: true
 
 # Directory where uploaded images and attachments are stored.
 #

justfile

@@ -2,10 +2,33 @@ project_name := "baibot"
 container_image_name := "localhost/baibot"
 project_container_network := "baibot"
 
+admin_username := "admin"
+admin_password := "admin"
+bot_username := "baibot"
+bot_password := "baibot"
+
+homeserver := `cat var/homeserver 2>/dev/null || echo continuwuity`
+
+mise_data_dir := env("MISE_DATA_DIR", justfile_directory() / "var/mise")
+mise_trusted_config_paths := justfile_directory() / "mise.toml"
+
 # Show help by default
 default:
 	@just --list --justfile {{ justfile() }}
 
+# Selects which homeserver implementation to use (continuwuity or synapse)
+homeserver-init value:
+	#!/bin/sh
+	mkdir -p {{ justfile_directory() }}/var
+	echo {{ value }} > {{ justfile_directory() }}/var/homeserver
+	echo ""
+	echo "⚠️  If you had already prepared your app configuration (var/app/local/config.yml or var/app/container/config.yml),"
+	echo "    you will need to update it manually or delete it and re-run the prepare step."
+	echo "    You should also delete var/app/local/data and/or var/app/container/data,"
+	echo "    as old application state is not compatible across homeserver implementations."
+	echo ""
+	echo "⚠️  If Element Web was already prepared, delete var/services/element-web/ to regenerate its config."
+
 # Builds and runs a development binary
 run-locally *extra_args: app-local-prepare
 	RUST_BACKTRACE=1 \
@@ -13,7 +36,8 @@ run-locally *extra_args: app-local-prepare
 	BAIBOT_PERSISTENCE_DATA_DIR_PATH={{ justfile_directory() }}/var/app/local/data \
 	cargo run -- {{ extra_args }}
 
-run-in-container *extra_args: app-container-prepare build-container-image
+# Builds and runs the bot in a container
+run-in-container *extra_args: app-container-prepare build-container-image-debug
 	/usr/bin/env docker run \
 	-it \
 	--rm \
@@ -25,12 +49,16 @@ run-in-container *extra_args: app-container-prepare build-container-image
 	--env BAIBOT_PERSISTENCE_DATA_DIR_PATH=/data \
 	--mount type=bind,src={{ justfile_directory() }}/var/app/container/config.yml,dst=/app/config.yml,ro \
 	--mount type=bind,src={{ justfile_directory() }}/var/app/container/data,dst=/data \
-	{{ container_image_name }} {{ extra_args }}
+	{{ container_image_name }}:latest {{ extra_args }}
 
 # Runs tests
 test *extra_args:
 	RUST_BACKTRACE=1 cargo test {{ extra_args }}
 
+# Formats the code
+fmt:
+	RUST_BACKTRACE=1 cargo fmt --all
+
 # Builds a debug binary (target/debug/*)
 build-debug *extra_args:
 	RUST_BACKTRACE=1 cargo build {{ extra_args }}
@@ -38,9 +66,16 @@ build-debug *extra_args:
 # Builds an optimized release binary (target/release/*)
 build-release *extra_args: (build-debug "--release")
 
-# Builds a container image
-build-container-image tag='latest':
+# Builds a container image (debug mode)
+build-container-image-debug tag='latest': (_build-container-image "false" tag)
+
+# Builds a container image (release mode)
+build-container-image-release tag='latest': (_build-container-image "true" tag)
+
+_build-container-image release_build tag:
 	/usr/bin/env docker build \
+	--build-arg RELEASE_BUILD={{ release_build }} \
+	-f {{ justfile_directory() }}/Dockerfile \
 	-t {{ container_image_name }}:{{ tag }} \
 	.
 
@@ -53,9 +88,13 @@ docker-compose services_type *extra_args:
 	-p {{ project_name }}-{{ services_type }} \
 	{{ extra_args }}
 
-# Runs a docker-compose command against the core services
-docker-compose-core *extra_args:
-	just docker-compose core {{ extra_args }}
+# Runs a docker-compose command against the synapse services
+docker-compose-synapse *extra_args:
+	just docker-compose synapse {{ extra_args }}
+
+# Runs a docker-compose command against the element-web services
+docker-compose-element-web *extra_args:
+	just docker-compose element-web {{ extra_args }}
 
 # Runs a docker-compose command against the localai services
 docker-compose-localai *extra_args:
@@ -65,17 +104,52 @@ docker-compose-localai *extra_args:
 docker-compose-ollama *extra_args:
 	just docker-compose ollama {{ extra_args }}
 
-# Runs all core dependency components (in the background)
-services-start: services-prepare (docker-compose-core "up" "-d")
+# Runs a docker-compose command against the continuwuity services
+docker-compose-continuwuity *extra_args:
+	just docker-compose continuwuity {{ extra_args }}
 
-# Stops all core dependency components
-services-stop: (docker-compose-core "down")
+# Runs the homeserver and Element Web (in the background)
+services-start: services-prepare
+	just -f {{ justfile_directory() }}/justfile {{ homeserver }}-start
+	just -f {{ justfile_directory() }}/justfile element-web-start
 
-# Tails the logs for all running core services
-services-tail-logs: (docker-compose-core "logs" "-f")
+# Stops Element Web and the homeserver
+services-stop:
+	just -f {{ justfile_directory() }}/justfile element-web-stop
+	just -f {{ justfile_directory() }}/justfile {{ homeserver }}-stop
 
-# Prepares the core services for running
-services-prepare: _prepare-var-services-env _prepare-var-services-postgres _prepare-var-services-synapse _prepare-container-network
+# Tails the logs for the homeserver and Element Web
+services-tail-logs:
+	just -f {{ justfile_directory() }}/justfile {{ homeserver }}-tail-logs
+
+# Prepares the homeserver and Element Web for running
+services-prepare:
+	just -f {{ justfile_directory() }}/justfile {{ homeserver }}-prepare
+	just -f {{ justfile_directory() }}/justfile element-web-prepare
+
+# Runs Synapse (in the background)
+synapse-start: synapse-prepare (docker-compose-synapse "up" "-d")
+
+# Stops Synapse
+synapse-stop: (docker-compose-synapse "down")
+
+# Tails the logs for Synapse
+synapse-tail-logs: (docker-compose-synapse "logs" "-f")
+
+# Prepares Synapse for running
+synapse-prepare: _prepare-var-services-env _prepare-var-services-postgres _prepare-var-services-synapse _prepare-container-network
+
+# Runs Element Web (in the background)
+element-web-start: element-web-prepare (docker-compose-element-web "up" "-d")
+
+# Stops Element Web
+element-web-stop: (docker-compose-element-web "down")
+
+# Tails the logs for Element Web
+element-web-tail-logs: (docker-compose-element-web "logs" "-f")
+
+# Prepares Element Web for running
+element-web-prepare: _prepare-var-services-env _prepare-var-services-element-web _prepare-container-network
 
 # Runs LocalAI (in the background)
 localai-start: localai-prepare (docker-compose-localai "up" "-d")
@@ -101,6 +175,27 @@ ollama-tail-logs: (docker-compose-ollama "logs" "-f")
 # Prepares Ollama for running
 ollama-prepare: _prepare-var-services-env _prepare-var-services-ollama _prepare-container-network
 
+# Runs Continuwuity (in the background)
+continuwuity-start: continuwuity-prepare (docker-compose-continuwuity "up" "-d")
+
+# Stops Continuwuity
+continuwuity-stop: (docker-compose-continuwuity "down")
+
+# Tails the logs for Continuwuity
+continuwuity-tail-logs: (docker-compose-continuwuity "logs" "-f")
+
+# Prepares Continuwuity for running
+continuwuity-prepare: _prepare-var-services-env _prepare-var-services-continuwuity _prepare-container-network
+
+# Registers a user on Continuwuity via the Matrix Client-Server API
+continuwuity-register-user username password:
+	{{ justfile_directory() }}/etc/services/continuwuity/register-user.sh {{ justfile_directory() }}/var/services/env {{ username }} {{ password }}
+
+# Prepares the Continuwuity user accounts
+continuwuity-users-prepare: continuwuity-prepare
+	just -f {{ justfile_directory() }}/justfile continuwuity-register-user "{{ admin_username }}" "{{ admin_password }}"
+	just -f {{ justfile_directory() }}/justfile continuwuity-register-user "{{ bot_username }}" "{{ bot_password }}"
+
 # Pulls an Ollama model
 ollama-pull-model model_id:
 	just -f {{ justfile_directory() }}/justfile docker-compose-ollama \
@@ -114,16 +209,20 @@ app-local-prepare: _prepare-var-app-local-config_yml _prepare-var-app-local-data
 app-container-prepare: _prepare-var-app-container-config_yml _prepare-var-app-container-data
 
 # Prepares the user accounts
-users-prepare: services-prepare
-	just -f {{ justfile_directory() }}/justfile synapse-register-admin-user "admin" "admin"
-	just -f {{ justfile_directory() }}/justfile synapse-register-regular-user "baibot" "baibot"
+users-prepare:
+	just -f {{ justfile_directory() }}/justfile {{ homeserver }}-users-prepare
+
+# Prepares the Synapse user accounts
+synapse-users-prepare: synapse-prepare
+	just -f {{ justfile_directory() }}/justfile synapse-register-admin-user "{{ admin_username }}" "{{ admin_password }}"
+	just -f {{ justfile_directory() }}/justfile synapse-register-regular-user "{{ bot_username }}" "{{ bot_password }}"
 
 # Starts a Postgres CLI (psql)
-postgres-cli: services-prepare (docker-compose-core "exec" "postgres" "/bin/sh" "-c" "'PGUSER=synapse PGPASSWORD=synapse-password PGDATABASE=homeserver psql -h postgres'")
+postgres-cli: synapse-prepare (docker-compose-synapse "exec" "postgres" "/bin/sh" "-c" "'PGUSER=synapse PGPASSWORD=synapse-password PGDATABASE=homeserver psql -h postgres'")
 
-# Creates an administrator user
-synapse-register-admin-user username password: services-prepare
-	just -f {{ justfile_directory() }}/justfile docker-compose-core \
+# Creates an administrator user on Synapse
+synapse-register-admin-user username password: synapse-prepare
+	just -f {{ justfile_directory() }}/justfile docker-compose-synapse \
 		exec synapse \
 		register_new_matrix_user \
 		--admin \
@@ -132,9 +231,9 @@ synapse-register-admin-user username password: services-prepare
 		-c /config/homeserver.yaml \
 		http://localhost:8008
 
-# Create a regular user
-synapse-register-regular-user username password: services-prepare
-	just -f {{ justfile_directory() }}/justfile docker-compose-core \
+# Creates a regular user on Synapse
+synapse-register-regular-user username password: synapse-prepare
+	just -f {{ justfile_directory() }}/justfile docker-compose-synapse \
 		exec synapse \
 		register_new_matrix_user \
 		--no-admin \
@@ -147,6 +246,44 @@ synapse-register-regular-user username password: services-prepare
 clippy *extra_args:
 	cargo clippy {{ extra_args }}
 
+# Checks that the code compiles without building
+check:
+	cargo check
+
+# Invokes mise with the project-local data directory
+mise *args: _ensure_mise_data_directory
+	#!/bin/sh
+	export MISE_DATA_DIR="{{ mise_data_dir }}"
+	export MISE_TRUSTED_CONFIG_PATHS="{{ mise_trusted_config_paths }}"
+	mise {{ args }}
+
+# Runs prek (pre-commit hooks manager) with the given arguments
+prek *args: _ensure_mise_tools_installed
+	@just --justfile {{ justfile() }} mise exec -- prek {{ args }}
+
+# Runs pre-commit hooks on staged files
+prek-run-on-staged *args: _ensure_mise_tools_installed
+	@just --justfile {{ justfile() }} mise exec -- prek run {{ args }}
+
+# Runs pre-commit hooks on all files
+prek-run-on-all *args: _ensure_mise_tools_installed
+	@just --justfile {{ justfile() }} mise exec -- prek run --all-files {{ args }}
+
+# Installs the git pre-commit hook (runs prek automatically before each commit)
+prek-install-git-pre-commit-hook: _ensure_mise_tools_installed
+	@just --justfile {{ justfile() }} mise exec -- prek install
+
+# Internal - ensures var/mise directory exists
+_ensure_mise_data_directory:
+	#!/bin/sh
+	if [ ! -d "{{ mise_data_dir }}" ]; then
+		mkdir -p "{{ mise_data_dir }}"
+	fi
+
+# Internal - ensures mise tools are installed
+_ensure_mise_tools_installed: _ensure_mise_data_directory
+	@just --justfile {{ justfile() }} mise install --quiet
+
 _prepare-var-services-env:
 	#!/bin/sh
 	cd {{ justfile_directory() }};
@@ -176,6 +313,22 @@ _prepare-var-services-synapse:
 		mkdir -p var/services/synapse/media-store
 	fi
 
+_prepare-var-services-element-web:
+	#!/bin/sh
+	cd {{ justfile_directory() }};
+
+	if [ ! -f var/services/element-web/config.json ]; then
+		mkdir -p var/services/element-web
+		cp {{ justfile_directory() }}/etc/services/element-web/config.json.dist var/services/element-web/config.json
+
+		homeserver="{{ homeserver }}"
+		if [ "$homeserver" = "continuwuity" ]; then
+			sed --in-place 's|__HOMESERVER_CLIENT_URL__|http://continuwuity.127.0.0.1.nip.io:42030|g' var/services/element-web/config.json
+		elif [ "$homeserver" = "synapse" ]; then
+			sed --in-place 's|__HOMESERVER_CLIENT_URL__|http://synapse.127.0.0.1.nip.io:42020|g' var/services/element-web/config.json
+		fi
+	fi
+
 _prepare-var-services-ollama:
 	#!/bin/sh
 	cd {{ justfile_directory() }};
@@ -184,6 +337,14 @@ _prepare-var-services-ollama:
 		mkdir -p var/services/ollama
 	fi
 
+_prepare-var-services-continuwuity:
+	#!/bin/sh
+	cd {{ justfile_directory() }};
+
+	if [ ! -f var/services/continuwuity ]; then
+		mkdir -p var/services/continuwuity/data
+	fi
+
 _prepare-var-services-localai:
 	#!/bin/sh
 	cd {{ justfile_directory() }};
@@ -207,6 +368,15 @@ _prepare-var-app-local-config_yml:
 	if [ ! -f var/app/local/config.yml ]; then
 		mkdir -p var/app/local
 		cp {{ justfile_directory() }}/etc/app/config.yml.dist var/app/local/config.yml
+
+		homeserver="{{ homeserver }}"
+		if [ "$homeserver" = "continuwuity" ]; then
+			sed --in-place 's/__HOMESERVER_SERVER_NAME__/continuwuity.127.0.0.1.nip.io/g' var/app/local/config.yml
+			sed --in-place 's|__HOMESERVER_URL__|http://continuwuity.127.0.0.1.nip.io:42030|g' var/app/local/config.yml
+		elif [ "$homeserver" = "synapse" ]; then
+			sed --in-place 's/__HOMESERVER_SERVER_NAME__/synapse.127.0.0.1.nip.io/g' var/app/local/config.yml
+			sed --in-place 's|__HOMESERVER_URL__|http://synapse.127.0.0.1.nip.io:42020|g' var/app/local/config.yml
+		fi
 	fi
 
 _prepare-var-app-local-data:
@@ -224,7 +394,18 @@ _prepare-var-app-container-config_yml:
 	if [ ! -f var/app/container/config.yml ]; then
 		mkdir -p var/app/container
 		cp {{ justfile_directory() }}/etc/app/config.yml.dist var/app/container/config.yml
-		sed --in-place 's/synapse.127.0.0.1.nip.io:42020/synapse:8008/g' var/app/container/config.yml
+
+		homeserver="{{ homeserver }}"
+		if [ "$homeserver" = "continuwuity" ]; then
+			sed --in-place 's/__HOMESERVER_SERVER_NAME__/continuwuity.127.0.0.1.nip.io/g' var/app/container/config.yml
+			sed --in-place 's|__HOMESERVER_URL__|http://continuwuity.127.0.0.1.nip.io:42030|g' var/app/container/config.yml
+			sed --in-place 's/continuwuity.127.0.0.1.nip.io:42030/continuwuity:6167/g' var/app/container/config.yml
+		elif [ "$homeserver" = "synapse" ]; then
+			sed --in-place 's/__HOMESERVER_SERVER_NAME__/synapse.127.0.0.1.nip.io/g' var/app/container/config.yml
+			sed --in-place 's|__HOMESERVER_URL__|http://synapse.127.0.0.1.nip.io:42020|g' var/app/container/config.yml
+			sed --in-place 's/synapse.127.0.0.1.nip.io:42020/synapse:8008/g' var/app/container/config.yml
+		fi
+
 		sed --in-place 's/127.0.0.1:42026/ollama:11434/g' var/app/container/config.yml
 		sed --in-place 's/127.0.0.1:42027/localai:8080/g' var/app/container/config.yml
 	fi
@@ -236,4 +417,3 @@ _prepare-var-app-container-data:
 	if [ ! -f var/app/container/data ]; then
 		mkdir -p var/app/container/data
 	fi
-

mise.toml

@@ -0,0 +1,6 @@
+[tools]
+prek = "0.4.5"
+
+[settings]
+# Disable automatic trust prompts - we trust this config
+yes = true

renovate.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
+	"extends": [
+		"config:recommended"
+	],
+	"labels": [
+		"dependencies"
+	]
+}

rust-toolchain.toml

@@ -0,0 +1,4 @@
+[toolchain]
+channel = "1.96.0"
+components = ["rustfmt", "clippy"]
+profile = "default"

src/agent/definition.rs

@@ -33,11 +33,11 @@ pub struct AgentDefinition {
     )]
     pub provider: AgentProvider,
 
-    pub config: serde_yaml::Value,
+    pub config: serde_yaml_ng::Value,
 }
 
 impl AgentDefinition {
-    pub fn new(id: String, provider: AgentProvider, config: serde_yaml::Value) -> Self {
+    pub fn new(id: String, provider: AgentProvider, config: serde_yaml_ng::Value) -> Self {
         Self {
             id,
             provider,

src/agent/instantiation.rs

@@ -1,6 +1,6 @@
 use super::{
-    provider::{self, ControllerType},
     AgentDefinition, AgentProvider, PublicIdentifier,
+    provider::{self, ControllerType},
 };
 
 // Dead-code is allowed. We do not use these enum struct payloads directly,
@@ -15,7 +15,7 @@ pub enum Error {
     // Contains the error from the constructor function
     ConstructionFailed(anyhow::Error),
     // Contains the error from the YAML deserialization function
-    Yaml(serde_yaml::Error),
+    Yaml(serde_yaml_ng::Error),
 }
 
 pub type Result<T> = std::result::Result<T, Error>;
@@ -69,7 +69,7 @@ pub(super) fn create(
 pub fn create_from_provider_and_yaml_value_config(
     provider: &AgentProvider,
     identifier: &PublicIdentifier,
-    config: serde_yaml::Value,
+    config: serde_yaml_ng::Value,
 ) -> Result<AgentInstance> {
     let definition = AgentDefinition::new(identifier.prefixless(), provider.to_owned(), config);
 
@@ -79,7 +79,7 @@ pub fn create_from_provider_and_yaml_value_config(
 fn create_controller_from_provider_and_json_value_config(
     agent_id: &str,
     provider: &AgentProvider,
-    config: serde_yaml::Value,
+    config: serde_yaml_ng::Value,
 ) -> Result<ControllerType> {
     match provider {
         AgentProvider::Anthropic => {
@@ -109,46 +109,53 @@ fn create_controller_from_provider_and_json_value_config(
         AgentProvider::TogetherAI => {
             provider::openai_compat::create_controller_from_yaml_value_config(agent_id, config)
         }
+        AgentProvider::Venice => {
+            provider::venice::create_controller_from_yaml_value_config(agent_id, config)
+        }
     }
 }
 
-pub fn default_config_for_provider(provider: &AgentProvider) -> serde_yaml::Value {
+pub fn default_config_for_provider(provider: &AgentProvider) -> serde_yaml_ng::Value {
     match provider {
         AgentProvider::Anthropic => {
             let config = super::provider::anthropic::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
         AgentProvider::Groq => {
             let config = super::provider::groq::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
         AgentProvider::LocalAI => {
             let config = super::provider::localai::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
         AgentProvider::Mistral => {
             let config = super::provider::mistral::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
         AgentProvider::Ollama => {
             let config = super::provider::ollama::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
         AgentProvider::OpenAI => {
             let config = super::provider::openai::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
         AgentProvider::OpenAICompat => {
             let config = super::provider::openai_compat::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
         AgentProvider::OpenRouter => {
             let config = super::provider::openrouter::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
         AgentProvider::TogetherAI => {
             let config = super::provider::togetherai::default_config();
-            serde_yaml::to_value(config).expect("Failed to serialize config")
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
+        }
+        AgentProvider::Venice => {
+            let config = super::provider::venice::default_config();
+            serde_yaml_ng::to_value(config).expect("Failed to serialize config")
         }
     }
 }

src/agent/manager.rs

@@ -1,7 +1,7 @@
-use super::instantiation;
-use super::instantiation::AgentInstance;
 use super::AgentDefinition;
 use super::PublicIdentifier;
+use super::instantiation;
+use super::instantiation::AgentInstance;
 use crate::entity::RoomConfigContext;
 
 #[derive(Debug)]

src/agent/mod.rs

@@ -11,11 +11,15 @@ pub use manager::Manager;
 
 pub use definition::AgentDefinition;
 
-pub use instantiation::create_from_provider_and_yaml_value_config;
-pub use instantiation::default_config_for_provider;
 pub use instantiation::AgentInstance;
 pub use instantiation::Error as AgentInstantiationError;
 pub use instantiation::Result as AgentInstantiationResult;
+pub use instantiation::create_from_provider_and_yaml_value_config;
+pub use instantiation::default_config_for_provider;
 
 pub use provider::{AgentProvider, AgentProviderInfo, ControllerTrait};
 pub use purpose::AgentPurpose;
+
+pub(super) fn default_prompt() -> &'static str {
+    "You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation's start is: {{ baibot_conversation_start_time_utc }}."
+}

src/agent/provider/anthropic/config.rs

@@ -1,8 +1,6 @@
 use serde::{Deserialize, Serialize};
 
-use anthropic_rs::models::claude::ClaudeModel;
-
-use crate::agent::provider::ConfigTrait;
+use crate::agent::{default_prompt, provider::ConfigTrait};
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Config {
@@ -28,6 +26,9 @@ impl ConfigTrait for Config {
         if self.base_url.is_empty() {
             return Err("The base URL must not be empty.".to_owned());
         }
+        if !self.base_url.ends_with("/v1") {
+            return Err("The base URL must end with '/v1'.".to_owned());
+        }
         if self.api_key.is_empty() {
             return Err("The API key must not be empty.".to_owned());
         }
@@ -58,7 +59,7 @@ impl Default for TextGenerationConfig {
     fn default() -> Self {
         Self {
             model_id: default_text_model_id(),
-            prompt: Some("You are a brief, but helpful bot.".to_owned()),
+            prompt: Some(default_prompt().to_owned()),
             temperature: super::super::default_temperature(),
             max_response_tokens: 8192,
             max_context_tokens: 204_800,
@@ -67,5 +68,5 @@ impl Default for TextGenerationConfig {
 }
 
 fn default_text_model_id() -> String {
-    ClaudeModel::Claude35Sonnet.as_str().to_owned()
+    "claude-3-7-sonnet-20250219".to_owned()
 }

src/agent/provider/anthropic/controller.rs

@@ -1,30 +1,28 @@
 use std::fmt::Debug;
-use std::str::FromStr;
 use std::sync::Arc;
 
-use anthropic_rs::completion::message::ContentType;
-use anthropic_rs::{
-    client::Client as AnthropicClient, config::Config as AnthropicConfig,
-    models::claude::ClaudeModel,
-};
+use anthropic::client::{Client, ClientBuilder};
+use anthropic::types::ContentBlock;
 
 use super::super::ControllerTrait;
-use crate::agent::provider::entity::{
-    ImageGenerationResult, PingResult, TextGenerationParams, TextGenerationResult,
-    TextToSpeechParams, TextToSpeechResult,
-};
-use crate::agent::provider::{ImageGenerationParams, SpeechToTextParams, SpeechToTextResult};
 use crate::agent::AgentPurpose;
+use crate::agent::provider::entity::{
+    ImageEditResult, ImageGenerationResult, ImageSource, PingResult, TextGenerationParams,
+    TextGenerationResult, TextToSpeechParams, TextToSpeechResult,
+};
+use crate::agent::provider::{
+    ImageEditParams, ImageGenerationParams, SpeechToTextParams, SpeechToTextResult,
+};
 use crate::conversation::llm::{
-    shorten_messages_list_to_context_size, Author as LLMAuthor, Conversation as LLMConversation,
-    Message as LLMMessage,
+    Author as LLMAuthor, Conversation as LLMConversation, Message as LLMMessage,
+    MessageContent as LLMMessageContent, TokenEstimate, shorten_messages_list_to_context_size,
 };
 use crate::strings;
 
 use super::config::Config;
 
 struct ControllerInner {
-    client: AnthropicClient,
+    client: Client,
 }
 
 #[derive(Clone)]
@@ -43,18 +41,20 @@ impl Debug for Controller {
 
 impl Controller {
     pub fn new(config: Config) -> anyhow::Result<Self> {
-        let anthropic_config =
-            AnthropicConfig::new(config.api_key.clone()).with_base_url(config.base_url.clone());
+        // The previous library that we used expected a base URL that ends with "/v1"
+        // (e.g. "https://api.anthropic.com/v1"), while the new one doesn't.
+        //
+        // To keep backward compatibility, we don't ask people to change their configuration
+        // and rather adapt by removing the "/v1" from the base URL.
+        if !config.base_url.ends_with("/v1") {
+            return Err(anyhow::anyhow!("base_url must end with '/v1'"));
+        }
 
-        let client = match AnthropicClient::new(anthropic_config) {
-            Ok(client) => client,
-            Err(err) => {
-                return Err(anyhow::anyhow!(
-                    "Failed to create Anthropic client: {}",
-                    err.to_string()
-                ));
-            }
-        };
+        let base_url = &config.base_url[..config.base_url.len() - 3];
+        let client = ClientBuilder::default()
+            .api_base(base_url.to_string())
+            .api_key(config.api_key.clone())
+            .build()?;
 
         Ok(Self {
             config,
@@ -71,7 +71,9 @@ impl ControllerTrait for Controller {
 
         let messages = vec![LLMMessage {
             author: LLMAuthor::User,
-            message_text: "Hello!".to_string(),
+            sender_id: None,
+            content: LLMMessageContent::Text("Hello!".to_string()),
+            timestamp: chrono::Utc::now(),
         }];
 
         let conversation = LLMConversation { messages };
@@ -95,31 +97,43 @@ impl ControllerTrait for Controller {
             ));
         };
 
-        let prompt_text = params
-            .prompt_override
-            .unwrap_or(self.text_generation_prompt().unwrap_or("".to_owned()))
-            .trim()
-            .to_owned();
+        let prompt_text = params.prompt_variables.format(
+            params
+                .prompt_override
+                .unwrap_or(self.text_generation_prompt().unwrap_or("".to_owned()))
+                .trim(),
+        );
 
         let prompt_message = if prompt_text.is_empty() {
             None
         } else {
             Some(LLMMessage {
                 author: LLMAuthor::Prompt,
-                message_text: prompt_text,
+                sender_id: None,
+                content: LLMMessageContent::Text(prompt_text),
+                timestamp: chrono::Utc::now(),
             })
         };
 
+        // Avoid the situation where multiple user or assistant messages are sent consecutively,
+        // to avoid errors like:
+        // > API error: Error response: error Api error: invalid_request_error messages: roles must alternate between "user" and "assistant", but found multiple "user" roles in a row
+        // as reported here: https://github.com/etkecc/baibot/issues/13
+        //
+        // As https://docs.anthropic.com/en/api/messages says:
+        // > Our models are trained to operate on alternating user and assistant conversational turns.
+        let conversation = conversation.combine_consecutive_messages();
+
         let mut conversation_messages = conversation.messages;
 
         if params.context_management_enabled {
             tracing::trace!("Shortening messages list to context size");
 
             conversation_messages = shorten_messages_list_to_context_size(
-                &text_generation_config.model_id,
+                TokenEstimate::Approximate,
                 &prompt_message,
                 conversation_messages,
-                text_generation_config.max_response_tokens,
+                Some(text_generation_config.max_response_tokens),
                 text_generation_config.max_context_tokens,
             );
 
@@ -130,29 +144,19 @@ impl ControllerTrait for Controller {
 
         let mut request = super::utils::create_anthropic_message_request(conversation_messages);
 
-        let model = match ClaudeModel::from_str(&text_generation_config.model_id) {
-            Ok(model) => model,
-            Err(err) => {
-                tracing::debug!(?err, "Failed to parse model ID");
-
-                return Err(anyhow::anyhow!(
-                    "Failed to parse model ID: {}",
-                    &text_generation_config.model_id
-                ));
-            }
-        };
-
         let temperature = params
             .temperature_override
             .unwrap_or(text_generation_config.temperature);
 
-        if let Some(prompt_message) = prompt_message {
-            request.system = Some(prompt_message.message_text);
+        if let Some(prompt_message) = prompt_message
+            && let LLMMessageContent::Text(text) = &prompt_message.content
+        {
+            request.system = text.clone();
         }
 
-        request.model = model;
-        request.temperature = Some(temperature);
-        request.max_tokens = text_generation_config.max_response_tokens;
+        request.model = text_generation_config.model_id.clone();
+        request.temperature = Some(temperature as f64);
+        request.max_tokens = text_generation_config.max_response_tokens as usize;
 
         if let Ok(request_as_json) = serde_json::to_string(&request) {
             tracing::trace!(
@@ -163,19 +167,20 @@ impl ControllerTrait for Controller {
             );
         }
 
-        let response = self.inner.client.create_message(request).await?;
+        let response = self.inner.client.messages(request).await?;
 
         tracing::trace!(?response, "Got response from Anthropic create message API");
 
         // response.content usually contains a single element, but we support handling multiple to account for all possibilities
         let mut text_parts = vec![];
         for content in response.content {
-            let content_type = content.content_type;
-
-            match content_type {
-                ContentType::Text => {
-                    text_parts.push(content.text);
-                } // There are no other content types to handle yet, but there may be in the future
+            match content {
+                ContentBlock::Text { text } => {
+                    text_parts.push(text);
+                }
+                ContentBlock::Image { .. } => {
+                    text_parts.push("The model responded with an image".to_string());
+                }
             }
         }
 
@@ -207,6 +212,15 @@ impl ControllerTrait for Controller {
         Err(anyhow::anyhow!("Image generation not supported"))
     }
 
+    async fn create_image_edit(
+        &self,
+        _prompt: &str,
+        _images: Vec<ImageSource>,
+        _params: ImageEditParams,
+    ) -> anyhow::Result<ImageEditResult> {
+        Err(anyhow::anyhow!("Image editing is not supported"))
+    }
+
     async fn text_to_speech(
         &self,
         _input: &str,
@@ -225,20 +239,25 @@ impl ControllerTrait for Controller {
         }
     }
 
-    fn text_generation_prompt(&self) -> Option<String> {
-        let Some(text_generation_config) = &self.config.text_generation else {
-            return None;
-        };
+    fn text_generation_model_id(&self) -> Option<String> {
+        self.config
+            .text_generation
+            .as_ref()
+            .map(|config| config.model_id.to_owned())
+    }
 
-        text_generation_config.prompt.clone()
+    fn text_generation_prompt(&self) -> Option<String> {
+        self.config
+            .text_generation
+            .as_ref()
+            .and_then(|config| config.prompt.clone())
     }
 
     fn text_generation_temperature(&self) -> Option<f32> {
-        let Some(text_generation_config) = &self.config.text_generation else {
-            return None;
-        };
-
-        Some(text_generation_config.temperature)
+        self.config
+            .text_generation
+            .as_ref()
+            .map(|config| config.temperature)
     }
 
     fn text_to_speech_voice(&self) -> Option<String> {

src/agent/provider/anthropic/mod.rs

@@ -7,17 +7,17 @@ pub use controller::Controller;
 
 use super::super::AgentInstantiationError;
 use super::super::AgentInstantiationResult;
-use super::controller::ControllerType;
 use super::ConfigTrait;
+use super::controller::ControllerType;
 
 pub fn create_controller_from_yaml_value_config(
     agent_id: &str,
-    config: serde_yaml::Value,
+    config: serde_yaml_ng::Value,
 ) -> AgentInstantiationResult<ControllerType> {
     let config = match &config {
-        serde_yaml::Value::Mapping(_) => {
+        serde_yaml_ng::Value::Mapping(_) => {
             let config: Config =
-                serde_yaml::from_value(config).map_err(AgentInstantiationError::Yaml)?;
+                serde_yaml_ng::from_value(config).map_err(AgentInstantiationError::Yaml)?;
 
             config
                 .validate()

src/agent/provider/anthropic/utils.rs

@@ -1,8 +1,12 @@
-use anthropic_rs::completion::message::{Content, ContentType, Message, MessageRequest, Role};
+use anthropic::types::{
+    ContentBlock, ImageSource, Message, MessagesRequest, MessagesRequestBuilder, Role,
+};
 
-use crate::conversation::llm::{Author as LLMAuthor, Message as LLMMessage};
+use crate::conversation::llm::{
+    Author as LLMAuthor, Message as LLMMessage, MessageContent as LLMMessageContent,
+};
 
-pub(super) fn create_anthropic_message_request(llm_messages: Vec<LLMMessage>) -> MessageRequest {
+pub(super) fn create_anthropic_message_request(llm_messages: Vec<LLMMessage>) -> MessagesRequest {
     let mut messages = vec![];
 
     for message in llm_messages {
@@ -14,19 +18,33 @@ pub(super) fn create_anthropic_message_request(llm_messages: Vec<LLMMessage>) ->
             }
         };
 
-        let content = vec![Content {
-            content_type: ContentType::Text,
-            text: message.message_text,
-        }];
+        let content = match &message.content {
+            LLMMessageContent::Text(text) => vec![ContentBlock::Text { text: text.clone() }],
+            LLMMessageContent::Image(image_details) => {
+                vec![ContentBlock::Image {
+                    source: ImageSource::Base64 {
+                        media_type: image_details.mime.to_string(),
+                        data: crate::utils::base64::base64_encode(&image_details.data),
+                    },
+                }]
+            }
+            LLMMessageContent::File(file_details) => {
+                tracing::warn!(
+                    "The Anthropic provider's library does not support file/document content. This file message ({}) will be skipped.",
+                    file_details.filename(),
+                );
+                continue;
+            }
+        };
 
         let message = Message { role, content };
 
         messages.push(message);
     }
 
-    MessageRequest {
-        stream: false,
-        messages,
-        ..Default::default()
-    }
+    MessagesRequestBuilder::default()
+        .messages(messages)
+        .stream(false)
+        .build()
+        .expect("Failed to build messages request")
 }

src/agent/provider/controller.rs

@@ -1,11 +1,11 @@
 use crate::{agent::AgentPurpose, conversation::llm::Conversation};
 
 use super::{
+    ImageEditParams, ImageGenerationParams, SpeechToTextParams, SpeechToTextResult,
     entity::{
-        ImageGenerationResult, PingResult, TextGenerationParams, TextGenerationResult,
-        TextToSpeechParams, TextToSpeechResult,
+        ImageEditResult, ImageGenerationResult, ImageSource, PingResult, TextGenerationParams,
+        TextGenerationResult, TextToSpeechParams, TextToSpeechResult,
     },
-    ImageGenerationParams, SpeechToTextParams, SpeechToTextResult,
 };
 
 pub trait ControllerTrait {
@@ -13,6 +13,8 @@ pub trait ControllerTrait {
 
     fn ping(&self) -> impl std::future::Future<Output = anyhow::Result<PingResult>> + Send;
 
+    fn text_generation_model_id(&self) -> Option<String>;
+
     fn text_generation_prompt(&self) -> Option<String>;
 
     fn text_generation_temperature(&self) -> Option<f32>;
@@ -40,6 +42,13 @@ pub trait ControllerTrait {
         params: ImageGenerationParams,
     ) -> impl std::future::Future<Output = anyhow::Result<ImageGenerationResult>> + Send;
 
+    fn create_image_edit(
+        &self,
+        prompt: &str,
+        images: Vec<ImageSource>,
+        params: ImageEditParams,
+    ) -> impl std::future::Future<Output = anyhow::Result<ImageEditResult>> + Send;
+
     fn text_to_speech(
         &self,
         text: &str,
@@ -52,6 +61,7 @@ pub enum ControllerType {
     OpenAI(Box<super::openai::Controller>),
     OpenAICompat(Box<super::openai_compat::Controller>),
     Anthropic(Box<super::anthropic::Controller>),
+    Venice(Box<super::venice::Controller>),
 }
 
 impl ControllerTrait for ControllerType {
@@ -60,6 +70,16 @@ impl ControllerTrait for ControllerType {
             ControllerType::OpenAI(controller) => controller.supports_purpose(purpose),
             ControllerType::OpenAICompat(controller) => controller.supports_purpose(purpose),
             ControllerType::Anthropic(controller) => controller.supports_purpose(purpose),
+            ControllerType::Venice(controller) => controller.supports_purpose(purpose),
+        }
+    }
+
+    fn text_generation_model_id(&self) -> Option<String> {
+        match &self {
+            ControllerType::OpenAI(controller) => controller.text_generation_model_id(),
+            ControllerType::OpenAICompat(controller) => controller.text_generation_model_id(),
+            ControllerType::Anthropic(controller) => controller.text_generation_model_id(),
+            ControllerType::Venice(controller) => controller.text_generation_model_id(),
         }
     }
 
@@ -68,6 +88,7 @@ impl ControllerTrait for ControllerType {
             ControllerType::OpenAI(controller) => controller.text_generation_prompt(),
             ControllerType::OpenAICompat(controller) => controller.text_generation_prompt(),
             ControllerType::Anthropic(controller) => controller.text_generation_prompt(),
+            ControllerType::Venice(controller) => controller.text_generation_prompt(),
         }
     }
 
@@ -76,6 +97,7 @@ impl ControllerTrait for ControllerType {
             ControllerType::OpenAI(controller) => controller.text_to_speech_voice(),
             ControllerType::OpenAICompat(controller) => controller.text_to_speech_voice(),
             ControllerType::Anthropic(controller) => controller.text_to_speech_voice(),
+            ControllerType::Venice(controller) => controller.text_to_speech_voice(),
         }
     }
 
@@ -84,6 +106,7 @@ impl ControllerTrait for ControllerType {
             ControllerType::OpenAI(controller) => controller.text_to_speech_speed(),
             ControllerType::OpenAICompat(controller) => controller.text_to_speech_speed(),
             ControllerType::Anthropic(controller) => controller.text_to_speech_speed(),
+            ControllerType::Venice(controller) => controller.text_to_speech_speed(),
         }
     }
 
@@ -92,6 +115,7 @@ impl ControllerTrait for ControllerType {
             ControllerType::OpenAI(controller) => controller.text_generation_temperature(),
             ControllerType::OpenAICompat(controller) => controller.text_generation_temperature(),
             ControllerType::Anthropic(controller) => controller.text_generation_temperature(),
+            ControllerType::Venice(controller) => controller.text_generation_temperature(),
         }
     }
 
@@ -100,6 +124,7 @@ impl ControllerTrait for ControllerType {
             ControllerType::OpenAI(controller) => controller.ping().await,
             ControllerType::OpenAICompat(controller) => controller.ping().await,
             ControllerType::Anthropic(controller) => controller.ping().await,
+            ControllerType::Venice(controller) => controller.ping().await,
         }
     }
 
@@ -118,6 +143,9 @@ impl ControllerTrait for ControllerType {
             ControllerType::Anthropic(controller) => {
                 controller.generate_text(conversation, params).await
             }
+            ControllerType::Venice(controller) => {
+                controller.generate_text(conversation, params).await
+            }
         }
     }
 
@@ -137,6 +165,9 @@ impl ControllerTrait for ControllerType {
             ControllerType::Anthropic(controller) => {
                 controller.speech_to_text(mime_type, media, params).await
             }
+            ControllerType::Venice(controller) => {
+                controller.speech_to_text(mime_type, media, params).await
+            }
         }
     }
 
@@ -153,6 +184,29 @@ impl ControllerTrait for ControllerType {
             ControllerType::Anthropic(controller) => {
                 controller.generate_image(prompt, params).await
             }
+            ControllerType::Venice(controller) => controller.generate_image(prompt, params).await,
+        }
+    }
+
+    async fn create_image_edit(
+        &self,
+        prompt: &str,
+        images: Vec<ImageSource>,
+        params: ImageEditParams,
+    ) -> anyhow::Result<ImageEditResult> {
+        match &self {
+            ControllerType::OpenAI(controller) => {
+                controller.create_image_edit(prompt, images, params).await
+            }
+            ControllerType::OpenAICompat(controller) => {
+                controller.create_image_edit(prompt, images, params).await
+            }
+            ControllerType::Anthropic(controller) => {
+                controller.create_image_edit(prompt, images, params).await
+            }
+            ControllerType::Venice(controller) => {
+                controller.create_image_edit(prompt, images, params).await
+            }
         }
     }
 
@@ -167,6 +221,7 @@ impl ControllerTrait for ControllerType {
                 controller.text_to_speech(text, params).await
             }
             ControllerType::Anthropic(controller) => controller.text_to_speech(text, params).await,
+            ControllerType::Venice(controller) => controller.text_to_speech(text, params).await,
         }
     }
 }

src/agent/provider/entity/agent_provider.rs

@@ -11,6 +11,7 @@ pub enum AgentProvider {
     OpenAICompat,
     OpenRouter,
     TogetherAI,
+    Venice,
 }
 
 impl AgentProvider {
@@ -25,6 +26,7 @@ impl AgentProvider {
             &Self::OpenAICompat,
             &Self::OpenRouter,
             &Self::TogetherAI,
+            &Self::Venice,
         ]
     }
 
@@ -39,6 +41,7 @@ impl AgentProvider {
             Self::OpenAICompat => "openai-compatible",
             Self::OpenRouter => "openrouter",
             Self::TogetherAI => "together-ai",
+            Self::Venice => "venice",
         }
     }
 
@@ -53,6 +56,7 @@ impl AgentProvider {
             "openai-compatible" => Ok(Self::OpenAICompat),
             "openrouter" => Ok(Self::OpenRouter),
             "together-ai" => Ok(Self::TogetherAI),
+            "venice" => Ok(Self::Venice),
             _ => Err("Unexpected string value"),
         }
     }
@@ -67,9 +71,9 @@ impl AgentProvider {
                 wiki_url: Some("https://en.wikipedia.org/wiki/Anthropic"),
                 sign_up_url: Some("https://console.anthropic.com/"),
                 models_list_url: Some("https://docs.anthropic.com/en/docs/about-claude/models"),
-                supported_purposes: vec![
-                    AgentPurpose::TextGeneration,
-                ],
+                supported_purposes: vec![AgentPurpose::TextGeneration],
+                text_generation_supports_vision: true,
+                text_generation_supports_tools: false,
             },
             Self::Groq => AgentProviderInfo {
                 id: Self::Groq.to_static_str(),
@@ -79,15 +83,14 @@ impl AgentProvider {
                 wiki_url: Some("https://en.wikipedia.org/wiki/Groq"),
                 sign_up_url: Some("https://console.groq.com/login"),
                 models_list_url: Some("https://console.groq.com/docs/models"),
-                supported_purposes: vec![
-                    AgentPurpose::TextGeneration,
-                    AgentPurpose::SpeechToText,
-                ],
+                supported_purposes: vec![AgentPurpose::TextGeneration, AgentPurpose::SpeechToText],
+                text_generation_supports_vision: false,
+                text_generation_supports_tools: false,
             },
             Self::LocalAI => AgentProviderInfo {
                 id: Self::LocalAI.to_static_str(),
                 name: "LocalAI",
-                description: "LocalAI is the free, Open Source OpenAI alternative. LocalAI act as a drop-in replacement REST API that’s compatible with OpenAI API specifications for local inferencing. It allows you to run LLMs, generate images, audio (and not only) locally or on-prem with consumer grade hardware, supporting multiple model families and architectures.",
+                description: "LocalAI is the free, Open Source OpenAI alternative. LocalAI act as a drop-in replacement REST API that's compatible with OpenAI API specifications for local inferencing. It allows you to run LLMs, generate images, audio (and not only) locally or on-prem with consumer grade hardware, supporting multiple model families and architectures.",
                 homepage_url: Some("https://localai.io/"),
                 wiki_url: None,
                 sign_up_url: None,
@@ -97,6 +100,8 @@ impl AgentProvider {
                     AgentPurpose::TextToSpeech,
                     AgentPurpose::SpeechToText,
                 ],
+                text_generation_supports_vision: false,
+                text_generation_supports_tools: false,
             },
             Self::Mistral => AgentProviderInfo {
                 id: Self::Mistral.to_static_str(),
@@ -106,9 +111,9 @@ impl AgentProvider {
                 wiki_url: Some("https://en.wikipedia.org/wiki/Mistral_AI"),
                 sign_up_url: Some("https://auth.mistral.ai/ui/registration"),
                 models_list_url: Some("https://docs.mistral.ai/getting-started/models/"),
-                supported_purposes: vec![
-                    AgentPurpose::TextGeneration,
-                ],
+                supported_purposes: vec![AgentPurpose::TextGeneration],
+                text_generation_supports_vision: false,
+                text_generation_supports_tools: false,
             },
             Self::Ollama => AgentProviderInfo {
                 id: Self::Ollama.to_static_str(),
@@ -118,9 +123,9 @@ impl AgentProvider {
                 wiki_url: None,
                 sign_up_url: None,
                 models_list_url: Some("https://ollama.com/library"),
-                supported_purposes: vec![
-                    AgentPurpose::TextGeneration,
-                ],
+                supported_purposes: vec![AgentPurpose::TextGeneration],
+                text_generation_supports_vision: false,
+                text_generation_supports_tools: false,
             },
             Self::OpenAI => AgentProviderInfo {
                 id: Self::OpenAI.to_static_str(),
@@ -136,6 +141,8 @@ impl AgentProvider {
                     AgentPurpose::TextToSpeech,
                     AgentPurpose::SpeechToText,
                 ],
+                text_generation_supports_vision: true,
+                text_generation_supports_tools: true,
             },
             Self::OpenAICompat => AgentProviderInfo {
                 id: Self::OpenAICompat.to_static_str(),
@@ -151,6 +158,8 @@ impl AgentProvider {
                     AgentPurpose::TextToSpeech,
                     AgentPurpose::SpeechToText,
                 ],
+                text_generation_supports_vision: false,
+                text_generation_supports_tools: false,
             },
             Self::OpenRouter => AgentProviderInfo {
                 id: Self::OpenRouter.to_static_str(),
@@ -160,9 +169,9 @@ impl AgentProvider {
                 wiki_url: None,
                 sign_up_url: Some("https://openrouter.ai/"),
                 models_list_url: Some("https://openrouter.ai/models"),
-                supported_purposes: vec![
-                    AgentPurpose::TextGeneration,
-                ],
+                supported_purposes: vec![AgentPurpose::TextGeneration],
+                text_generation_supports_vision: false,
+                text_generation_supports_tools: false,
             },
             Self::TogetherAI => AgentProviderInfo {
                 id: Self::TogetherAI.to_static_str(),
@@ -172,9 +181,28 @@ impl AgentProvider {
                 wiki_url: None,
                 sign_up_url: Some("https://api.together.ai/signup"),
                 models_list_url: Some("https://api.together.xyz/models"),
+                supported_purposes: vec![AgentPurpose::TextGeneration],
+                text_generation_supports_vision: false,
+                text_generation_supports_tools: false,
+            },
+            Self::Venice => AgentProviderInfo {
+                id: Self::Venice.to_static_str(),
+                name: "Venice",
+                description: "Venice AI runs inference on Venice-controlled GPUs or zero-data-retention partner infrastructure and stores no prompts or responses. It serves frontier proprietary and open-source models with text-generation (including vision), speech-to-text, text-to-speech, native image generation and editing, and native web search.",
+                homepage_url: Some("https://venice.ai"),
+                wiki_url: None,
+                sign_up_url: Some("https://venice.ai"),
+                models_list_url: Some("https://api.venice.ai/api/v1/models"),
                 supported_purposes: vec![
+                    AgentPurpose::ImageGeneration,
                     AgentPurpose::TextGeneration,
+                    AgentPurpose::TextToSpeech,
+                    AgentPurpose::SpeechToText,
                 ],
+                text_generation_supports_vision: true,
+                // Venice does native web search via `venice_parameters`, NOT baibot's built-in
+                // tools mechanism (the OpenAI web_search/code_interpreter block), so this is false.
+                text_generation_supports_tools: false,
             },
         }
     }
@@ -195,4 +223,6 @@ pub struct AgentProviderInfo {
     pub sign_up_url: Option<&'static str>,
     pub models_list_url: Option<&'static str>,
     pub supported_purposes: Vec<AgentPurpose>,
+    pub text_generation_supports_vision: bool,
+    pub text_generation_supports_tools: bool,
 }

src/agent/provider/entity/image.rs

@@ -0,0 +1,63 @@
+use mxlink::mime;
+
+#[derive(Default)]
+pub struct ImageGenerationParams {
+    pub smallest_size_possible: bool,
+
+    pub cheaper_model_switching_allowed: bool,
+
+    pub cheaper_quality_switching_allowed: bool,
+}
+
+impl ImageGenerationParams {
+    pub fn with_smallest_size_possible(mut self, value: bool) -> Self {
+        self.smallest_size_possible = value;
+        self
+    }
+
+    pub fn with_cheaper_model_switching_allowed(mut self, value: bool) -> Self {
+        self.cheaper_model_switching_allowed = value;
+        self
+    }
+
+    pub fn with_cheaper_quality_switching_allowed(mut self, value: bool) -> Self {
+        self.cheaper_quality_switching_allowed = value;
+        self
+    }
+}
+
+pub struct ImageGenerationResult {
+    pub bytes: Vec<u8>,
+    pub mime_type: mime::Mime,
+    pub revised_prompt: Option<String>,
+}
+
+#[derive(Default)]
+pub struct ImageEditParams {}
+
+pub struct ImageEditResult {
+    pub bytes: Vec<u8>,
+    pub mime_type: mime::Mime,
+}
+
+pub struct ImageSource {
+    pub filename: String,
+    pub bytes: Vec<u8>,
+    pub mime_type: mime::Mime,
+}
+
+impl ImageSource {
+    pub fn new(filename: String, bytes: Vec<u8>, mime_type: mime::Mime) -> Self {
+        Self {
+            filename,
+            bytes,
+            mime_type,
+        }
+    }
+}
+
+impl From<ImageSource> for async_openai::types::images::ImageInput {
+    fn from(value: ImageSource) -> Self {
+        async_openai::types::images::ImageInput::from_vec_u8(value.filename, value.bytes)
+    }
+}

src/agent/provider/entity/image_generation.rs

@@ -1,31 +0,0 @@
-#[derive(Default)]
-pub struct ImageGenerationParams {
-    pub size_override: Option<String>,
-
-    pub cheaper_model_switching_allowed: bool,
-
-    pub cheaper_quality_switching_allowed: bool,
-}
-
-impl ImageGenerationParams {
-    pub fn with_size_override(mut self, value: Option<String>) -> Self {
-        self.size_override = value;
-        self
-    }
-
-    pub fn with_cheaper_model_switching_allowed(mut self, value: bool) -> Self {
-        self.cheaper_model_switching_allowed = value;
-        self
-    }
-
-    pub fn with_cheaper_quality_switching_allowed(mut self, value: bool) -> Self {
-        self.cheaper_quality_switching_allowed = value;
-        self
-    }
-}
-
-pub struct ImageGenerationResult {
-    pub bytes: Vec<u8>,
-    pub mime_type: mxlink::mime::Mime,
-    pub revised_prompt: Option<String>,
-}

src/agent/provider/entity/mod.rs

@@ -1,13 +1,17 @@
 mod agent_provider;
-mod image_generation;
+mod image;
 mod ping;
 mod speech_to_text;
 mod text_generation;
 mod text_to_speech;
 
 pub use agent_provider::{AgentProvider, AgentProviderInfo};
-pub use image_generation::{ImageGenerationParams, ImageGenerationResult};
+pub use image::{
+    ImageEditParams, ImageEditResult, ImageGenerationParams, ImageGenerationResult, ImageSource,
+};
 pub use ping::PingResult;
 pub use speech_to_text::{SpeechToTextParams, SpeechToTextResult};
-pub use text_generation::{TextGenerationParams, TextGenerationResult};
+pub use text_generation::{
+    TextGenerationParams, TextGenerationPromptVariables, TextGenerationResult,
+};
 pub use text_to_speech::{TextToSpeechParams, TextToSpeechResult};

src/agent/provider/entity/text_generation/mod.rs

@@ -1,8 +1,13 @@
+mod prompt_variables;
+
+pub use prompt_variables::TextGenerationPromptVariables;
+
 #[derive(Default)]
 pub struct TextGenerationParams {
     pub context_management_enabled: bool,
     pub prompt_override: Option<String>,
     pub temperature_override: Option<f32>,
+    pub prompt_variables: TextGenerationPromptVariables,
 }
 
 pub struct TextGenerationResult {

src/agent/provider/entity/text_generation/prompt_variables.rs

@@ -0,0 +1,107 @@
+use chrono::{DateTime, Utc};
+use std::collections::HashMap;
+
+#[derive(Clone)]
+pub struct TextGenerationPromptVariables {
+    map: HashMap<String, String>,
+}
+
+impl Default for TextGenerationPromptVariables {
+    fn default() -> Self {
+        let now = Utc::now();
+        Self::new("unnamed", "unknown-model", now, Some(now))
+    }
+}
+
+impl TextGenerationPromptVariables {
+    pub fn new(
+        bot_name: &str,
+        model_id: &str,
+        now_time: DateTime<Utc>,
+        conversation_start_time: Option<DateTime<Utc>>,
+    ) -> Self {
+        let mut map = HashMap::new();
+
+        map.insert("baibot_name".to_string(), bot_name.to_string());
+        map.insert("baibot_model_id".to_string(), model_id.to_string());
+        map.insert("baibot_now_utc".to_string(), format_utc_time(now_time));
+
+        let baibot_conversation_start_time_utc = match conversation_start_time {
+            Some(conversation_start_time) => format_utc_time(conversation_start_time),
+            None => "unknown".to_string(),
+        };
+
+        map.insert(
+            "baibot_conversation_start_time_utc".to_string(),
+            baibot_conversation_start_time_utc,
+        );
+
+        Self { map }
+    }
+
+    pub fn format(&self, text: &str) -> String {
+        let mut formatted_text = text.to_string();
+
+        for (key, value) in &self.map {
+            let placeholder = format!("{{{{ {} }}}}", key);
+            formatted_text = formatted_text.replace(&placeholder, value);
+        }
+
+        formatted_text
+    }
+}
+
+fn format_utc_time(time: DateTime<Utc>) -> String {
+    time.format("%Y-%m-%d (%A), %H:%M:%S UTC").to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::{TimeZone, Timelike};
+
+    #[test]
+    fn test_new() {
+        // Intentionally injecting some sub-seconds to ensure formatting would ignore them.
+        let now_utc = Utc
+            .with_ymd_and_hms(2024, 9, 20, 18, 34, 15)
+            .unwrap()
+            .with_nanosecond(250000000)
+            .unwrap();
+
+        let conversation_start_time_utc = Utc
+            .with_ymd_and_hms(2024, 9, 19, 18, 34, 15)
+            .unwrap()
+            .with_nanosecond(250000000)
+            .unwrap();
+
+        let variables = TextGenerationPromptVariables::new(
+            "baibot",
+            "gpt-4o",
+            now_utc,
+            Some(conversation_start_time_utc),
+        );
+
+        assert_eq!(
+            variables.map.get("baibot_name"),
+            Some(&"baibot".to_string())
+        );
+        assert_eq!(
+            variables.map.get("baibot_model_id"),
+            Some(&"gpt-4o".to_string())
+        );
+        assert_eq!(
+            variables.map.get("baibot_now_utc"),
+            Some(&format_utc_time(now_utc))
+        );
+        assert_eq!(
+            variables.map.get("baibot_conversation_start_time_utc"),
+            Some(&format_utc_time(conversation_start_time_utc))
+        );
+
+        let prompt = "Hello, I'm {{ baibot_name }} using {{ baibot_model_id }}. The date/time now is {{ baibot_now_utc }} and this conversation started at {{ baibot_conversation_start_time_utc }}.";
+        let expected = "Hello, I'm baibot using gpt-4o. The date/time now is 2024-09-20 (Friday), 18:34:15 UTC and this conversation started at 2024-09-19 (Thursday), 18:34:15 UTC.";
+
+        assert_eq!(variables.format(prompt), expected);
+    }
+}

src/agent/provider/groq/mod.rs

@@ -15,7 +15,7 @@ pub fn default_config() -> Config {
     if let Some(ref mut config) = config.text_generation.as_mut() {
         config.model_id = "llama3-70b-8192".to_owned();
         config.max_context_tokens = 131_072;
-        config.max_response_tokens = 4096;
+        config.max_response_tokens = Some(4096);
     }
 
     if let Some(ref mut config) = config.speech_to_text.as_mut() {

src/agent/provider/localai/mod.rs

@@ -1,6 +1,5 @@
-// LocalAI is based on OpenAI (async-openai), because it seems to be fully compatible.
-// Moreover, openai_api_rust does not support speech-to-text, so if we wish to use this feature
-// we need to stick to async-openai.
+// At the time of testing, LocalAI can be powered by `openai`, but we use `openai_compat` for better reliability
+// in the event of future updates to `async-openai`.
 
 use super::openai_compat::Config;
 
@@ -14,7 +13,7 @@ pub fn default_config() -> Config {
     if let Some(ref mut config) = config.text_generation.as_mut() {
         config.model_id = "gpt-4".to_owned();
         config.max_context_tokens = 128_000;
-        config.max_response_tokens = 4096;
+        config.max_response_tokens = Some(4096);
     }
 
     if let Some(ref mut config) = config.text_to_speech.as_mut() {

src/agent/provider/mod.rs

@@ -10,6 +10,7 @@ pub mod openai;
 pub mod openai_compat;
 pub(super) mod openrouter;
 pub(super) mod togetherai;
+pub mod venice;
 
 fn default_temperature() -> f32 {
     1.0
@@ -20,6 +21,7 @@ pub use controller::{ControllerTrait, ControllerType};
 pub use config::ConfigTrait;
 
 pub use entity::{
-    AgentProvider, AgentProviderInfo, ImageGenerationParams, PingResult, SpeechToTextParams,
-    SpeechToTextResult, TextGenerationParams, TextToSpeechParams,
+    AgentProvider, AgentProviderInfo, ImageEditParams, ImageGenerationParams, ImageSource,
+    PingResult, SpeechToTextParams, SpeechToTextResult, TextGenerationParams,
+    TextGenerationPromptVariables, TextToSpeechParams,
 };

src/agent/provider/ollama/mod.rs

@@ -17,7 +17,7 @@ pub fn default_config() -> Config {
     if let Some(ref mut config) = config.text_generation.as_mut() {
         config.model_id = "gemma2:2b".to_owned();
         config.max_context_tokens = 128_000;
-        config.max_response_tokens = 4096;
+        config.max_response_tokens = Some(4096);
     }
 
     config

src/agent/provider/openai/config.rs

@@ -1,6 +1,7 @@
 use serde::{Deserialize, Serialize};
 
-use crate::agent::provider::ConfigTrait;
+use super::OPENAI_IMAGE_MODEL_GPT_IMAGE_2;
+use crate::agent::{default_prompt, provider::ConfigTrait};
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Config {
@@ -56,26 +57,43 @@ pub struct TextGenerationConfig {
     pub temperature: f32,
 
     #[serde(default)]
-    pub max_response_tokens: u32,
+    pub max_response_tokens: Option<u32>,
+
+    #[serde(default)]
+    pub max_completion_tokens: Option<u32>,
 
     #[serde(default)]
     pub max_context_tokens: u32,
+
+    #[serde(default)]
+    pub tools: ToolsConfig,
 }
 
 impl Default for TextGenerationConfig {
     fn default() -> Self {
         Self {
             model_id: default_text_model_id(),
-            prompt: Some("You are a brief, but helpful bot.".to_owned()),
+            prompt: Some(default_prompt().to_owned()),
             temperature: super::super::default_temperature(),
-            max_response_tokens: 16_384,
-            max_context_tokens: 128_000,
+            max_response_tokens: None,
+            max_completion_tokens: Some(128_000),
+            max_context_tokens: 400_000,
+            tools: ToolsConfig::default(),
         }
     }
 }
 
 fn default_text_model_id() -> String {
-    "gpt-4o-2024-08-06".to_owned()
+    "gpt-5.4".to_owned()
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct ToolsConfig {
+    #[serde(default)]
+    pub web_search: bool,
+
+    #[serde(default)]
+    pub code_interpreter: bool,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -99,16 +117,16 @@ fn default_speech_to_text_model_id() -> String {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TextToSpeechConfig {
     #[serde(default = "default_text_to_speech_model_id")]
-    pub model_id: async_openai::types::SpeechModel,
+    pub model_id: async_openai::types::audio::SpeechModel,
 
     #[serde(default = "default_text_to_speech_voice")]
-    pub voice: async_openai::types::Voice,
+    pub voice: async_openai::types::audio::Voice,
 
     #[serde(default = "default_text_to_speech_speed")]
     pub speed: f32,
 
     #[serde(default = "default_text_to_speech_response_format")]
-    pub response_format: async_openai::types::SpeechResponseFormat,
+    pub response_format: async_openai::types::audio::SpeechResponseFormat,
 }
 
 impl Default for TextToSpeechConfig {
@@ -122,22 +140,22 @@ impl Default for TextToSpeechConfig {
     }
 }
 
-fn default_text_to_speech_model_id() -> async_openai::types::SpeechModel {
-    async_openai::types::SpeechModel::Tts1Hd
+fn default_text_to_speech_model_id() -> async_openai::types::audio::SpeechModel {
+    async_openai::types::audio::SpeechModel::Tts1Hd
 }
 
-fn default_text_to_speech_voice() -> async_openai::types::Voice {
-    async_openai::types::Voice::Onyx
+fn default_text_to_speech_voice() -> async_openai::types::audio::Voice {
+    async_openai::types::audio::Voice::Onyx
 }
 
 fn default_text_to_speech_speed() -> f32 {
     1.0
 }
 
-fn default_text_to_speech_response_format() -> async_openai::types::SpeechResponseFormat {
+fn default_text_to_speech_response_format() -> async_openai::types::audio::SpeechResponseFormat {
     // The API defaults to mp3, but we prefer Opus because it's smaller.
     // Our clients should all have support for it.
-    async_openai::types::SpeechResponseFormat::Opus
+    async_openai::types::audio::SpeechResponseFormat::Opus
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -145,19 +163,19 @@ pub struct ImageGenerationConfig {
     pub model_id: String,
 
     #[serde(default = "default_image_style")]
-    pub style: async_openai::types::ImageStyle,
+    pub style: Option<async_openai::types::images::ImageStyle>,
 
     #[serde(default = "default_image_size")]
-    pub size: async_openai::types::ImageSize,
+    pub size: Option<async_openai::types::images::ImageSize>,
 
     #[serde(default = "default_image_quality")]
-    pub quality: async_openai::types::ImageQuality,
+    pub quality: Option<async_openai::types::images::ImageQuality>,
 }
 
 impl Default for ImageGenerationConfig {
     fn default() -> Self {
         Self {
-            model_id: "dall-e-3".to_owned(),
+            model_id: OPENAI_IMAGE_MODEL_GPT_IMAGE_2.to_owned(),
             style: default_image_style(),
             size: default_image_size(),
             quality: default_image_quality(),
@@ -168,23 +186,29 @@ impl Default for ImageGenerationConfig {
 impl ImageGenerationConfig {
     pub fn model_id_as_openai_image_model(
         &self,
-    ) -> Result<async_openai::types::ImageModel, String> {
+    ) -> Result<async_openai::types::images::ImageModel, String> {
         match self.model_id.as_str() {
-            "dall-e-2" => Ok(async_openai::types::ImageModel::DallE2),
-            "dall-e-3" => Ok(async_openai::types::ImageModel::DallE3),
-            other => Ok(async_openai::types::ImageModel::Other(other.to_owned())),
+            "dall-e-2" => Ok(async_openai::types::images::ImageModel::DallE2),
+            "dall-e-3" => Ok(async_openai::types::images::ImageModel::DallE3),
+            "gpt-image-1" => Ok(async_openai::types::images::ImageModel::GptImage1),
+            "gpt-image-1.5" => Ok(async_openai::types::images::ImageModel::GptImage1dot5),
+            "gpt-image-1-mini" => Ok(async_openai::types::images::ImageModel::GptImage1Mini),
+            "gpt-image-2" => Ok(async_openai::types::images::ImageModel::GptImage2),
+            other => Ok(async_openai::types::images::ImageModel::Other(
+                other.to_owned(),
+            )),
         }
     }
 }
 
-fn default_image_style() -> async_openai::types::ImageStyle {
-    async_openai::types::ImageStyle::Vivid
+fn default_image_style() -> Option<async_openai::types::images::ImageStyle> {
+    None
 }
 
-fn default_image_size() -> async_openai::types::ImageSize {
-    async_openai::types::ImageSize::S1024x1024
+fn default_image_size() -> Option<async_openai::types::images::ImageSize> {
+    None
 }
 
-fn default_image_quality() -> async_openai::types::ImageQuality {
-    async_openai::types::ImageQuality::Standard
+fn default_image_quality() -> Option<async_openai::types::images::ImageQuality> {
+    None
 }

src/agent/provider/openai/controller.rs

@@ -1,37 +1,42 @@
 use std::ops::Deref;
 
 use async_openai::{
+    Client as OpenAIClient,
     config::OpenAIConfig,
     types::{
-        ChatCompletionRequestMessage, CreateChatCompletionRequestArgs, CreateImageRequestArgs,
-        CreateSpeechRequestArgs, CreateTranscriptionRequestArgs,
+        audio::{AudioInput, CreateSpeechRequestArgs, CreateTranscriptionRequestArgs},
+        images::{
+            CreateImageEditRequestArgs, CreateImageRequestArgs, Image, ImageInput, ImageModel,
+            ImageResponseFormat,
+        },
+        responses::{
+            CodeInterpreterContainerAuto, CodeInterpreterTool, CodeInterpreterToolContainer,
+            CreateResponseArgs, OutputItem, OutputMessageContent, Tool, WebSearchTool,
+        },
     },
-    Client as OpenAIClient,
 };
 
 use super::super::ControllerTrait;
 use crate::{
-    agent::{
-        provider::{
-            entity::{ImageGenerationResult, PingResult, TextToSpeechParams, TextToSpeechResult},
-            openai::utils::convert_string_to_enum,
-        },
-        AgentPurpose,
+    agent::provider::{
+        ImageEditParams, ImageGenerationParams, SpeechToTextParams, SpeechToTextResult,
+        entity::{TextGenerationParams, TextGenerationResult},
     },
-    strings,
+    conversation::llm::{
+        Author as LLMAuthor, Conversation as LLMConversation, Message as LLMMessage,
+        MessageContent as LLMMessageContent, TokenEstimate, shorten_messages_list_to_context_size,
+    },
+    utils::base64::base64_decode,
 };
 use crate::{
     agent::{
-        provider::{
-            entity::{TextGenerationParams, TextGenerationResult},
-            ImageGenerationParams, SpeechToTextParams, SpeechToTextResult,
+        AgentPurpose,
+        provider::entity::{
+            ImageEditResult, ImageGenerationResult, ImageSource, PingResult, TextToSpeechParams,
+            TextToSpeechResult,
         },
-        utils::base64_decode,
-    },
-    conversation::llm::{
-        shorten_messages_list_to_context_size, Author as LLMAuthor,
-        Conversation as LLMConversation, Message as LLMMessage,
     },
+    strings,
 };
 
 use super::config::Config;
@@ -62,7 +67,9 @@ impl ControllerTrait for Controller {
 
         let messages = vec![LLMMessage {
             author: LLMAuthor::User,
-            message_text: "Hello!".to_string(),
+            sender_id: None,
+            content: LLMMessageContent::Text("Hello!".to_string()),
+            timestamp: chrono::Utc::now(),
         }];
 
         let conversation = LLMConversation { messages };
@@ -86,18 +93,21 @@ impl ControllerTrait for Controller {
             ));
         };
 
-        let prompt_text = params
-            .prompt_override
-            .unwrap_or(self.text_generation_prompt().unwrap_or("".to_owned()))
-            .trim()
-            .to_owned();
+        let prompt_text = params.prompt_variables.format(
+            params
+                .prompt_override
+                .unwrap_or(self.text_generation_prompt().unwrap_or("".to_owned()))
+                .trim(),
+        );
 
         let prompt_message = if prompt_text.is_empty() {
             None
         } else {
             Some(LLMMessage {
                 author: LLMAuthor::Prompt,
-                message_text: prompt_text,
+                sender_id: None,
+                content: LLMMessageContent::Text(prompt_text),
+                timestamp: chrono::Utc::now(),
             })
         };
 
@@ -107,7 +117,7 @@ impl ControllerTrait for Controller {
             tracing::trace!("Shortening messages list to context size");
 
             conversation_messages = shorten_messages_list_to_context_size(
-                &text_generation_config.model_id,
+                TokenEstimate::Tiktoken(&text_generation_config.model_id),
                 &prompt_message,
                 conversation_messages,
                 text_generation_config.max_response_tokens,
@@ -121,54 +131,76 @@ impl ControllerTrait for Controller {
             conversation_messages.insert(0, prompt_message);
         }
 
-        let openai_conversation_messages: Vec<ChatCompletionRequestMessage> =
-            super::utils::convert_llm_messages_to_openai_messages(conversation_messages);
+        let input =
+            super::utils::convert_llm_messages_to_openai_response_input(conversation_messages);
 
-        let messages_count = openai_conversation_messages.len();
+        let messages_count = match &input {
+            async_openai::types::responses::InputParam::Items(items) => items.len(),
+            _ => 1,
+        };
 
         let temperature = params
             .temperature_override
             .unwrap_or(text_generation_config.temperature);
 
-        let request = CreateChatCompletionRequestArgs::default()
-            .max_tokens(text_generation_config.max_response_tokens)
+        let mut request_builder = CreateResponseArgs::default();
+
+        request_builder
             .model(&text_generation_config.model_id)
             .temperature(temperature)
-            .messages(openai_conversation_messages)
-            .build()?;
+            .input(input);
+
+        let mut tools = Vec::new();
+        if text_generation_config.tools.web_search {
+            tools.push(Tool::WebSearch(WebSearchTool::default()));
+        }
+        if text_generation_config.tools.code_interpreter {
+            tools.push(Tool::CodeInterpreter(CodeInterpreterTool {
+                container: CodeInterpreterToolContainer::Auto(
+                    CodeInterpreterContainerAuto::default(),
+                ),
+            }));
+        }
+
+        if !tools.is_empty() {
+            request_builder.tools(tools);
+        }
+
+        if let Some(max_response_tokens) = text_generation_config.max_response_tokens {
+            request_builder.max_output_tokens(max_response_tokens);
+        } else if let Some(max_completion_tokens) = text_generation_config.max_completion_tokens {
+            request_builder.max_output_tokens(max_completion_tokens);
+        }
+
+        let request = request_builder.build()?;
 
         if let Ok(request_as_json) = serde_json::to_string(&request) {
             tracing::trace!(
                 model = format!("{:?}", request.model),
                 ?messages_count,
                 request = request_as_json,
-                "Sending OpenAI chat completion API request"
+                "Sending OpenAI response API request"
             );
         }
 
-        let response = self.client.chat().create(request).await?;
+        let response = self.client.responses().create(request).await?;
 
-        tracing::trace!(
-            ?response,
-            "Got response from the OpenAI chat completion API"
-        );
+        tracing::trace!(?response, "Got response from the OpenAI response API");
 
-        // We only request 1 result, so there should only be 1 choice.
-        if let Some(choice) = response.choices.into_iter().next() {
-            match choice.message.content {
-                Some(text) => {
-                    return Ok(TextGenerationResult { text });
-                }
-                None => {
-                    return Err(anyhow::anyhow!(
-                        "No content was found in the response choice from the OpenAI chat completion API"
-                    ));
+        for item in response.output {
+            if let OutputItem::Message(message) = item {
+                for content in message.content {
+                    if let OutputMessageContent::OutputText(text_content) = content {
+                        return Ok(TextGenerationResult {
+                            text: text_content.text,
+                        });
+                    }
                 }
             }
         }
 
         Err(anyhow::anyhow!(
-            "No response messages choices were returned from the OpenAI chat completion API"
+            "No response messages choices were returned from the OpenAI response API"
         ))
     }
 
@@ -192,12 +224,7 @@ impl ControllerTrait for Controller {
 
         let request = CreateTranscriptionRequestArgs::default()
             .model(&speech_to_text_config.model_id)
-            .file(async_openai::types::AudioInput {
-                source: async_openai::types::InputSource::VecU8 {
-                    filename,
-                    vec: media,
-                },
-            })
+            .file(AudioInput::from_vec_u8(filename, media))
             .language(language.clone())
             .build()?;
 
@@ -207,7 +234,7 @@ impl ControllerTrait for Controller {
             "Sending OpenAI speech-to-text API request"
         );
 
-        let response = self.client.audio().transcribe(request).await?;
+        let response = self.client.audio().transcription().create(request).await?;
 
         tracing::trace!(
             ?response,
@@ -239,11 +266,13 @@ impl ControllerTrait for Controller {
         let model = if params.cheaper_model_switching_allowed {
             // Switch to a cheaper model
             match original_model {
-                async_openai::types::ImageModel::DallE2 => async_openai::types::ImageModel::DallE2,
-                async_openai::types::ImageModel::DallE3 => async_openai::types::ImageModel::DallE2,
-                async_openai::types::ImageModel::Other(_) => {
-                    async_openai::types::ImageModel::DallE2
-                }
+                ImageModel::DallE2 => ImageModel::DallE2,
+                ImageModel::DallE3 => ImageModel::DallE2,
+                ImageModel::GptImage1 => ImageModel::GptImage1Mini,
+                ImageModel::GptImage1dot5 => ImageModel::GptImage1Mini,
+                ImageModel::GptImage1Mini => ImageModel::GptImage1Mini,
+                ImageModel::GptImage2 => ImageModel::GptImage1Mini,
+                ImageModel::Other(_) => ImageModel::DallE2,
             }
         } else {
             original_model
@@ -252,33 +281,72 @@ impl ControllerTrait for Controller {
         let quality = if params.cheaper_quality_switching_allowed {
             // Switch to a cheaper quality
             match &image_generation_config.quality {
-                async_openai::types::ImageQuality::Standard => {
-                    async_openai::types::ImageQuality::Standard
-                }
-                async_openai::types::ImageQuality::HD => {
-                    async_openai::types::ImageQuality::Standard
-                }
+                Some(quality) => match quality {
+                    async_openai::types::images::ImageQuality::Standard => {
+                        Some(async_openai::types::images::ImageQuality::Standard)
+                    }
+                    async_openai::types::images::ImageQuality::HD => {
+                        Some(async_openai::types::images::ImageQuality::Standard)
+                    }
+                    // New quality levels - keep as-is or downgrade to Standard
+                    async_openai::types::images::ImageQuality::High => {
+                        Some(async_openai::types::images::ImageQuality::Standard)
+                    }
+                    async_openai::types::images::ImageQuality::Medium => {
+                        Some(async_openai::types::images::ImageQuality::Medium)
+                    }
+                    async_openai::types::images::ImageQuality::Low => {
+                        Some(async_openai::types::images::ImageQuality::Low)
+                    }
+                    async_openai::types::images::ImageQuality::Auto => {
+                        Some(async_openai::types::images::ImageQuality::Auto)
+                    }
+                },
+                None => None,
             }
         } else {
             image_generation_config.quality.clone()
         };
 
-        let size = params
-            .size_override
-            .map(|s| {
-                convert_string_to_enum::<async_openai::types::ImageSize>(&s)
-                    .unwrap_or(image_generation_config.size)
-            })
-            .unwrap_or(image_generation_config.size);
+        let size = if params.smallest_size_possible {
+            Some(get_sticker_size(&model))
+        } else {
+            image_generation_config.size.clone()
+        };
 
-        let request = CreateImageRequestArgs::default()
-            .model(model)
-            .prompt(prompt.to_owned())
-            .response_format(async_openai::types::ImageResponseFormat::B64Json)
-            .size(size)
-            .style(image_generation_config.style.clone())
-            .quality(quality)
-            .build()?;
+        let response_format = match model.clone() {
+            ImageModel::DallE2 => Some(ImageResponseFormat::B64Json),
+            ImageModel::DallE3 => Some(ImageResponseFormat::B64Json),
+            // gpt-image-1 only outputs base64 and we don't need to specify the response format.
+            // In fact, specifying the response format results in an error.
+            ImageModel::GptImage1 => None,
+            ImageModel::GptImage1Mini => None,
+            ImageModel::GptImage1dot5 => None,
+            ImageModel::GptImage2 => None,
+            ImageModel::Other(_) => Some(ImageResponseFormat::B64Json),
+        };
+
+        let mut request_builder = CreateImageRequestArgs::default();
+
+        request_builder.model(model).prompt(prompt.to_owned());
+
+        if let Some(response_format) = response_format {
+            request_builder.response_format(response_format);
+        }
+
+        if let Some(style) = &image_generation_config.style {
+            request_builder.style(style.clone());
+        }
+
+        if let Some(quality) = quality {
+            request_builder.quality(quality.clone());
+        }
+
+        if let Some(size) = size {
+            request_builder.size(size);
+        }
+
+        let request = request_builder.build()?;
 
         tracing::trace!(
             ?prompt,
@@ -289,15 +357,15 @@ impl ControllerTrait for Controller {
             "Sending OpenAI image generation API request"
         );
 
-        let response = self.client.images().create(request).await?;
+        let response = self.client.images().generate(request).await?;
 
         if let Some(image) = response.data.into_iter().next() {
             match image.deref() {
-                async_openai::types::Image::B64Json {
+                Image::B64Json {
                     b64_json,
                     revised_prompt,
                 } => {
-                    let bytes = base64_decode(b64_json)?;
+                    let bytes = base64_decode(b64_json.as_ref())?;
 
                     return Ok(ImageGenerationResult {
                         bytes,
@@ -316,6 +384,109 @@ impl ControllerTrait for Controller {
         ))
     }
 
+    async fn create_image_edit(
+        &self,
+        prompt: &str,
+        images: Vec<ImageSource>,
+        _params: ImageEditParams,
+    ) -> anyhow::Result<ImageEditResult> {
+        let Some(image_generation_config) = &self.config.image_generation else {
+            return Err(anyhow::anyhow!(
+                strings::agent::no_configuration_for_purpose_so_cannot_be_used(
+                    &AgentPurpose::ImageGeneration
+                ),
+            ));
+        };
+
+        if images.is_empty() {
+            return Err(anyhow::anyhow!("No image sources provided"));
+        }
+
+        let mut image_inputs: Vec<ImageInput> = Vec::new();
+        for image in images {
+            image_inputs.push(image.into());
+        }
+
+        let dalle2_size = match image_generation_config.size {
+            Some(async_openai::types::images::ImageSize::S256x256) => {
+                Some(async_openai::types::images::ImageSize::S256x256)
+            }
+            Some(async_openai::types::images::ImageSize::S512x512) => {
+                Some(async_openai::types::images::ImageSize::S512x512)
+            }
+            Some(async_openai::types::images::ImageSize::S1024x1024) => {
+                Some(async_openai::types::images::ImageSize::S1024x1024)
+            }
+            _ => None,
+        };
+
+        let model = image_generation_config
+            .model_id_as_openai_image_model()
+            .map_err(|err| anyhow::anyhow!(err))?;
+
+        let response_format = match model.clone() {
+            ImageModel::DallE2 => Some(ImageResponseFormat::B64Json),
+            ImageModel::DallE3 => Some(ImageResponseFormat::B64Json),
+            // gpt-image-1 only outputs base64 and we don't need to specify the response format.
+            // In fact, specifying the response format results in an error.
+            ImageModel::GptImage1 => None,
+            ImageModel::GptImage1Mini => None,
+            ImageModel::GptImage1dot5 => None,
+            ImageModel::GptImage2 => None,
+            ImageModel::Other(_) => Some(ImageResponseFormat::B64Json),
+        };
+
+        let mut request_builder = CreateImageEditRequestArgs::default();
+
+        request_builder
+            .image(image_inputs)
+            .prompt(prompt.to_owned())
+            .model(model);
+
+        if let Some(size) = dalle2_size {
+            request_builder.size(size);
+        }
+
+        if let Some(response_format) = response_format {
+            request_builder.response_format(response_format);
+        }
+
+        let request = request_builder
+            .build()
+            .map_err(|e| anyhow::anyhow!("Failed to build CreateImageEditRequest: {}", e))?;
+
+        tracing::trace!(
+            model = format!("{:?}", request.model),
+            size = format!("{:?}", request.size),
+            response_format = format!("{:?}", request.response_format),
+            "Sending OpenAI image edit API request"
+        );
+
+        let response = self.client.images().edit(request).await?;
+
+        if let Some(image_data) = response.data.into_iter().next() {
+            match image_data.deref() {
+                Image::B64Json { b64_json, .. } => {
+                    let bytes = base64_decode(b64_json.as_ref())?;
+                    return Ok(ImageEditResult {
+                        bytes,
+                        mime_type: mxlink::mime::IMAGE_PNG,
+                    });
+                }
+                Image::Url { url, .. } => {
+                    tracing::warn!(?url, "Received URL instead of B64Json for image edit");
+                    return Err(anyhow::anyhow!(
+                        "Unexpected image type (URL) when B64Json was requested"
+                    ));
+                }
+            }
+        }
+
+        Err(anyhow::anyhow!(
+            "The OpenAI image edit API returned no images"
+        ))
+    }
+
     async fn text_to_speech(
         &self,
         input: &str,
@@ -333,7 +504,7 @@ impl ControllerTrait for Controller {
 
         let voice = if let Some(voice_string) = params.voice_override {
             // This is a hacky way to construct a Voice enum from the string we have.
-            let voice: serde_json::Result<async_openai::types::Voice> =
+            let voice: serde_json::Result<async_openai::types::audio::Voice> =
                 serde_json::from_str(&format!("\"{}\"", voice_string));
             match voice {
                 Ok(voice) => voice,
@@ -373,7 +544,7 @@ impl ControllerTrait for Controller {
             "Sending OpenAI text-to-speech API request"
         );
 
-        let result = self.client.audio().speech(request).await?;
+        let result = self.client.audio().speech().create(request).await?;
 
         Ok(TextToSpeechResult {
             bytes: result.bytes.into(),
@@ -391,20 +562,25 @@ impl ControllerTrait for Controller {
         }
     }
 
-    fn text_generation_prompt(&self) -> Option<String> {
-        let Some(text_generation_config) = &self.config.text_generation else {
-            return None;
-        };
+    fn text_generation_model_id(&self) -> Option<String> {
+        self.config
+            .text_generation
+            .as_ref()
+            .map(|config| config.model_id.to_owned())
+    }
 
-        text_generation_config.prompt.clone()
+    fn text_generation_prompt(&self) -> Option<String> {
+        self.config
+            .text_generation
+            .as_ref()
+            .and_then(|config| config.prompt.clone())
     }
 
     fn text_generation_temperature(&self) -> Option<f32> {
-        let Some(text_generation_config) = &self.config.text_generation else {
-            return None;
-        };
-
-        Some(text_generation_config.temperature)
+        self.config
+            .text_generation
+            .as_ref()
+            .map(|config| config.temperature)
     }
 
     fn text_to_speech_voice(&self) -> Option<String> {
@@ -427,15 +603,15 @@ impl ControllerTrait for Controller {
 }
 
 fn response_format_to_mime_type(
-    response_format: &async_openai::types::SpeechResponseFormat,
+    response_format: &async_openai::types::audio::SpeechResponseFormat,
 ) -> Option<mxlink::mime::Mime> {
     let content_type = match response_format {
-        async_openai::types::SpeechResponseFormat::Mp3 => "audio/mp3".to_owned(),
-        async_openai::types::SpeechResponseFormat::Wav => "audio/wav".to_owned(),
-        async_openai::types::SpeechResponseFormat::Opus => "audio/ogg".to_owned(),
-        async_openai::types::SpeechResponseFormat::Aac => "audio/aac".to_owned(),
-        async_openai::types::SpeechResponseFormat::Flac => "audio/flac".to_owned(),
-        async_openai::types::SpeechResponseFormat::Pcm => "audio/L8".to_owned(),
+        async_openai::types::audio::SpeechResponseFormat::Mp3 => "audio/mp3".to_owned(),
+        async_openai::types::audio::SpeechResponseFormat::Wav => "audio/wav".to_owned(),
+        async_openai::types::audio::SpeechResponseFormat::Opus => "audio/ogg".to_owned(),
+        async_openai::types::audio::SpeechResponseFormat::Aac => "audio/aac".to_owned(),
+        async_openai::types::audio::SpeechResponseFormat::Flac => "audio/flac".to_owned(),
+        async_openai::types::audio::SpeechResponseFormat::Pcm => "audio/L8".to_owned(),
     };
 
     match content_type.parse() {
@@ -463,3 +639,18 @@ fn audio_mime_type_to_file_name(mime_type: &mxlink::mime::Mime) -> Option<String
 
     Some(format!("audio.{}", file_extension))
 }
+
+/// Returns the smallest supported size for stickers based on what the image model supports.
+fn get_sticker_size(model: &ImageModel) -> async_openai::types::images::ImageSize {
+    use async_openai::types::images::ImageSize;
+
+    match model {
+        ImageModel::DallE2 => ImageSize::S256x256,
+        ImageModel::DallE3 => ImageSize::S1024x1024,
+        ImageModel::GptImage1 => ImageSize::S1024x1024,
+        ImageModel::GptImage1Mini => ImageSize::S1024x1024,
+        ImageModel::GptImage1dot5 => ImageSize::S1024x1024,
+        ImageModel::GptImage2 => ImageSize::S1024x1024,
+        ImageModel::Other(_) => ImageSize::S1024x1024,
+    }
+}

src/agent/provider/openai/mod.rs

@@ -13,17 +13,19 @@ pub(super) use config::TextToSpeechConfig;
 
 use super::super::AgentInstantiationError;
 use super::super::AgentInstantiationResult;
-use super::controller::ControllerType;
 use super::ConfigTrait;
+use super::controller::ControllerType;
+
+pub const OPENAI_IMAGE_MODEL_GPT_IMAGE_2: &str = "gpt-image-2";
 
 pub fn create_controller_from_yaml_value_config(
     agent_id: &str,
-    config: serde_yaml::Value,
+    config: serde_yaml_ng::Value,
 ) -> AgentInstantiationResult<ControllerType> {
     let config = match &config {
-        serde_yaml::Value::Mapping(_) => {
+        serde_yaml_ng::Value::Mapping(_) => {
             let config: Config =
-                serde_yaml::from_value(config).map_err(AgentInstantiationError::Yaml)?;
+                serde_yaml_ng::from_value(config).map_err(AgentInstantiationError::Yaml)?;
 
             config
                 .validate()

src/agent/provider/openai/utils.rs

@@ -1,55 +1,64 @@
-use async_openai::types::{
-    ChatCompletionRequestAssistantMessageArgs, ChatCompletionRequestMessage,
-    ChatCompletionRequestSystemMessageArgs, ChatCompletionRequestUserMessageArgs,
+use async_openai::types::responses::{
+    EasyInputContent, EasyInputMessage, ImageDetail, InputContent, InputFileArgs,
+    InputImageContent, InputItem, InputParam, MessageType, Role,
 };
 
-use crate::conversation::llm::{Author as LLMAuthor, Message as LLMMessage};
+use crate::conversation::llm::{
+    Author as LLMAuthor, Message as LLMMessage, MessageContent as LLMMessageContent,
+};
+use crate::utils::base64::base64_encode;
 
-pub fn convert_llm_messages_to_openai_messages(
+pub fn convert_llm_messages_to_openai_response_input(
     conversation_messages: Vec<LLMMessage>,
-) -> Vec<ChatCompletionRequestMessage> {
-    let mut openai_conversation_messages: Vec<ChatCompletionRequestMessage> =
-        Vec::with_capacity(conversation_messages.len());
+) -> InputParam {
+    let mut items = Vec::with_capacity(conversation_messages.len());
 
     for message in conversation_messages {
-        openai_conversation_messages.push(convert_llm_message_to_openai_message(message));
+        let role = match message.author {
+            LLMAuthor::Prompt => Role::System,
+            LLMAuthor::Assistant => Role::Assistant,
+            LLMAuthor::User => Role::User,
+        };
+
+        let content = match message.content {
+            LLMMessageContent::Text(text) => EasyInputContent::Text(text),
+            LLMMessageContent::Image(image_details) => {
+                let image_url = format!(
+                    "data:{};base64,{}",
+                    image_details.mime,
+                    base64_encode(&image_details.data)
+                );
+
+                EasyInputContent::ContentList(vec![InputContent::InputImage(InputImageContent {
+                    image_url: Some(image_url),
+                    detail: ImageDetail::Auto,
+                    file_id: None,
+                })])
+            }
+            LLMMessageContent::File(file_details) => {
+                let file_data = format!(
+                    "data:{};base64,{}",
+                    file_details.mime,
+                    base64_encode(&file_details.data)
+                );
+
+                let file_content = InputFileArgs::default()
+                    .file_data(file_data)
+                    .filename(file_details.filename())
+                    .build()
+                    .expect("Failed to build InputFileContent");
+
+                EasyInputContent::ContentList(vec![InputContent::InputFile(file_content)])
+            }
+        };
+
+        items.push(InputItem::EasyMessage(EasyInputMessage {
+            r#type: MessageType::Message,
+            role,
+            content,
+            phase: None,
+        }));
     }
 
-    openai_conversation_messages
-}
-
-fn convert_llm_message_to_openai_message(llm_message: LLMMessage) -> ChatCompletionRequestMessage {
-    match llm_message.author {
-        LLMAuthor::Prompt => ChatCompletionRequestSystemMessageArgs::default()
-            .content(llm_message.message_text)
-            .build()
-            .expect("Failed building OpenAI system message")
-            .into(),
-        LLMAuthor::Assistant => ChatCompletionRequestAssistantMessageArgs::default()
-            .content(llm_message.message_text)
-            .build()
-            .expect("Failed building OpenAI assistant message")
-            .into(),
-        LLMAuthor::User => ChatCompletionRequestUserMessageArgs::default()
-            .content(llm_message.message_text)
-            .build()
-            .expect("Failed building OpenAI user message")
-            .into(),
-    }
-}
-
-pub(super) fn convert_string_to_enum<T>(value: &str) -> Result<T, String>
-where
-    T: serde::de::DeserializeOwned,
-{
-    // This is a hacky way to construct an enum from the string we have.
-    let enum_result: serde_json::Result<T> = serde_json::from_str(&format!("\"{}\"", value));
-    match enum_result {
-        Ok(enum_result) => Ok(enum_result),
-        Err(err) => {
-            tracing::debug!(?err, "Failed to parse into enum");
-
-            Err(format!("The value ({}) is not supported.", value))
-        }
-    }
+    InputParam::Items(items)
 }

src/agent/provider/openai_compat/config.rs

@@ -1,5 +1,6 @@
 use serde::{Deserialize, Serialize};
 
+use crate::agent::default_prompt;
 use crate::agent::provider::openai::{
     ImageGenerationConfig as OpenAIImageGenerationConfig,
     SpeechToTextConfig as OpenAISpeechToTextConfig,
@@ -65,7 +66,7 @@ pub struct TextGenerationConfig {
     pub temperature: f32,
 
     #[serde(default)]
-    pub max_response_tokens: u32,
+    pub max_response_tokens: Option<u32>,
 
     #[serde(default)]
     pub max_context_tokens: u32,
@@ -75,9 +76,9 @@ impl Default for TextGenerationConfig {
     fn default() -> Self {
         Self {
             model_id: default_text_model_id(),
-            prompt: Some("You are a brief, but helpful bot.".to_owned()),
+            prompt: Some(default_prompt().to_owned()),
             temperature: super::super::default_temperature(),
-            max_response_tokens: 4096,
+            max_response_tokens: Some(4096),
             max_context_tokens: 128_000,
         }
     }
@@ -92,7 +93,9 @@ impl TryInto<OpenAITextGenerationConfig> for TextGenerationConfig {
             prompt: self.prompt,
             temperature: self.temperature,
             max_response_tokens: self.max_response_tokens,
+            max_completion_tokens: None,
             max_context_tokens: self.max_context_tokens,
+            tools: Default::default(),
         })
     }
 }
@@ -159,13 +162,14 @@ impl TryInto<OpenAITextToSpeechConfig> for TextToSpeechConfig {
     type Error = String;
 
     fn try_into(self) -> Result<OpenAITextToSpeechConfig, Self::Error> {
-        let model_id = convert_string_to_enum::<async_openai::types::SpeechModel>(&self.model_id)?;
+        let model_id =
+            convert_string_to_enum::<async_openai::types::audio::SpeechModel>(&self.model_id)?;
 
-        let voice = convert_string_to_enum::<async_openai::types::Voice>(&self.voice)?;
+        let voice = convert_string_to_enum::<async_openai::types::audio::Voice>(&self.voice)?;
 
-        let response_format = convert_string_to_enum::<async_openai::types::SpeechResponseFormat>(
-            &self.response_format,
-        )?;
+        let response_format = convert_string_to_enum::<
+            async_openai::types::audio::SpeechResponseFormat,
+        >(&self.response_format)?;
 
         Ok(OpenAITextToSpeechConfig {
             model_id,
@@ -222,21 +226,27 @@ impl TryInto<OpenAIImageGenerationConfig> for ImageGenerationConfig {
 
     fn try_into(self) -> Result<OpenAIImageGenerationConfig, Self::Error> {
         let size = if let Some(size) = &self.size {
-            convert_string_to_enum::<async_openai::types::ImageSize>(size)?
+            Some(convert_string_to_enum::<
+                async_openai::types::images::ImageSize,
+            >(size)?)
         } else {
-            async_openai::types::ImageSize::S1024x1024
+            None
         };
 
         let style = if let Some(style) = &self.style {
-            convert_string_to_enum::<async_openai::types::ImageStyle>(style)?
+            Some(convert_string_to_enum::<
+                async_openai::types::images::ImageStyle,
+            >(style)?)
         } else {
-            async_openai::types::ImageStyle::Vivid
+            None
         };
 
         let quality = if let Some(quality) = &self.quality {
-            convert_string_to_enum::<async_openai::types::ImageQuality>(quality)?
+            Some(convert_string_to_enum::<
+                async_openai::types::images::ImageQuality,
+            >(quality)?)
         } else {
-            async_openai::types::ImageQuality::Standard
+            None
         };
 
         Ok(OpenAIImageGenerationConfig {

src/agent/provider/openai_compat/controller.rs

@@ -3,24 +3,28 @@ use etke_openai_api_rust::chat::{ChatApi, ChatBody};
 use etke_openai_api_rust::images::{ImagesApi, ImagesBody};
 use etke_openai_api_rust::{Auth, Message, OpenAI};
 
+const SMALLEST_IMAGE_SIZE: &str = "256x256";
+
 use super::super::ControllerTrait;
-use crate::agent::utils::base64_decode;
+use crate::utils::base64::base64_decode;
 use crate::{
     agent::provider::{
+        ImageEditParams, ImageGenerationParams, ImageSource, SpeechToTextParams,
+        SpeechToTextResult,
         entity::{TextGenerationParams, TextGenerationResult},
-        ImageGenerationParams, SpeechToTextParams, SpeechToTextResult,
     },
     conversation::llm::{
-        shorten_messages_list_to_context_size, Author as LLMAuthor,
-        Conversation as LLMConversation, Message as LLMMessage,
+        Author as LLMAuthor, Conversation as LLMConversation, Message as LLMMessage,
+        MessageContent as LLMMessageContent, TokenEstimate, shorten_messages_list_to_context_size,
     },
 };
 use crate::{
     agent::{
-        provider::entity::{
-            ImageGenerationResult, PingResult, TextToSpeechParams, TextToSpeechResult,
-        },
         AgentPurpose,
+        provider::entity::{
+            ImageEditResult, ImageGenerationResult, PingResult, TextToSpeechParams,
+            TextToSpeechResult,
+        },
     },
     strings,
 };
@@ -60,7 +64,9 @@ impl ControllerTrait for Controller {
 
         let messages = vec![LLMMessage {
             author: LLMAuthor::User,
-            message_text: "Hello!".to_string(),
+            sender_id: None,
+            content: LLMMessageContent::Text("Hello!".to_string()),
+            timestamp: chrono::Utc::now(),
         }];
 
         let conversation = LLMConversation { messages };
@@ -84,18 +90,21 @@ impl ControllerTrait for Controller {
             ));
         };
 
-        let prompt_text = params
-            .prompt_override
-            .unwrap_or(self.text_generation_prompt().unwrap_or("".to_owned()))
-            .trim()
-            .to_owned();
+        let prompt_text = params.prompt_variables.format(
+            params
+                .prompt_override
+                .unwrap_or(self.text_generation_prompt().unwrap_or("".to_owned()))
+                .trim(),
+        );
 
         let prompt_message = if prompt_text.is_empty() {
             None
         } else {
             Some(LLMMessage {
                 author: LLMAuthor::Prompt,
-                message_text: prompt_text,
+                sender_id: None,
+                content: LLMMessageContent::Text(prompt_text),
+                timestamp: chrono::Utc::now(),
             })
         };
 
@@ -105,7 +114,7 @@ impl ControllerTrait for Controller {
             tracing::trace!("Shortening messages list to context size");
 
             conversation_messages = shorten_messages_list_to_context_size(
-                &text_generation_config.model_id,
+                TokenEstimate::Approximate,
                 &prompt_message,
                 conversation_messages,
                 text_generation_config.max_response_tokens,
@@ -130,12 +139,15 @@ impl ControllerTrait for Controller {
 
         let max_tokens = text_generation_config
             .max_response_tokens
-            .try_into()
-            .expect("Failed converting max_response_tokens from u32 to i32");
+            .map(|max_response_tokens| {
+                max_response_tokens
+                    .try_into()
+                    .expect("Failed converting max_response_tokens from u32 to i32")
+            });
 
         let request = ChatBody {
             model: text_generation_config.model_id.clone(),
-            max_tokens: Some(max_tokens),
+            max_tokens,
             temperature: Some(temperature),
             top_p: None,
             n: Some(1),
@@ -295,9 +307,11 @@ impl ControllerTrait for Controller {
         // when they span multiple lines.
         let prompt = prompt.replace("\n", " ");
 
-        let size: Option<String> = params
-            .size_override
-            .or_else(|| image_generation_config.size.clone());
+        let size: Option<String> = if params.smallest_size_possible {
+            Some(SMALLEST_IMAGE_SIZE.to_owned())
+        } else {
+            image_generation_config.size.clone()
+        };
 
         let request = ImagesBody {
             model: Some(image_generation_config.model_id.to_owned()),
@@ -360,6 +374,17 @@ impl ControllerTrait for Controller {
         ))
     }
 
+    async fn create_image_edit(
+        &self,
+        _prompt: &str,
+        _images: Vec<ImageSource>,
+        _params: ImageEditParams,
+    ) -> anyhow::Result<ImageEditResult> {
+        Err(anyhow::anyhow!(
+            "The OpenAI image edit API is not supported by the OpenAI-compat provider"
+        ))
+    }
+
     async fn text_to_speech(
         &self,
         input: &str,
@@ -409,20 +434,25 @@ impl ControllerTrait for Controller {
         }
     }
 
-    fn text_generation_prompt(&self) -> Option<String> {
-        let Some(text_generation_config) = &self.config.text_generation else {
-            return None;
-        };
+    fn text_generation_model_id(&self) -> Option<String> {
+        self.config
+            .text_generation
+            .as_ref()
+            .map(|config| config.model_id.to_owned())
+    }
 
-        text_generation_config.prompt.clone()
+    fn text_generation_prompt(&self) -> Option<String> {
+        self.config
+            .text_generation
+            .as_ref()
+            .and_then(|config| config.prompt.clone())
     }
 
     fn text_generation_temperature(&self) -> Option<f32> {
-        let Some(text_generation_config) = &self.config.text_generation else {
-            return None;
-        };
-
-        Some(text_generation_config.temperature)
+        self.config
+            .text_generation
+            .as_ref()
+            .map(|config| config.temperature)
     }
 
     fn text_to_speech_voice(&self) -> Option<String> {

src/agent/provider/openai_compat/mod.rs

@@ -21,17 +21,17 @@ pub use controller::Controller;
 
 use super::super::AgentInstantiationError;
 use super::super::AgentInstantiationResult;
-use super::controller::ControllerType;
 use super::ConfigTrait;
+use super::controller::ControllerType;
 
 pub fn create_controller_from_yaml_value_config(
     agent_id: &str,
-    config: serde_yaml::Value,
+    config: serde_yaml_ng::Value,
 ) -> AgentInstantiationResult<ControllerType> {
     let config = match &config {
-        serde_yaml::Value::Mapping(_) => {
+        serde_yaml_ng::Value::Mapping(_) => {
             let config: Config =
-                serde_yaml::from_value(config).map_err(AgentInstantiationError::Yaml)?;
+                serde_yaml_ng::from_value(config).map_err(AgentInstantiationError::Yaml)?;
 
             config
                 .validate()
@@ -56,7 +56,7 @@ pub fn default_config() -> Config {
 
     if let Some(text_generation) = &mut config.text_generation {
         text_generation.model_id = "some-model".to_string();
-        text_generation.max_response_tokens = 4096;
+        text_generation.max_response_tokens = Some(4096);
         text_generation.max_context_tokens = 128_000;
     }
 

src/agent/provider/openai_compat/utils.rs

@@ -2,7 +2,9 @@ use etke_openai_api_rust::{Message, Role};
 
 use crate::agent::provider::openai::Config as OpenAIConfig;
 
-use crate::conversation::llm::{Author as LLMAuthor, Message as LLMMessage};
+use crate::conversation::llm::{
+    Author as LLMAuthor, Message as LLMMessage, MessageContent as LLMMessageContent,
+};
 
 pub fn convert_llm_messages_to_openai_messages(
     conversation_messages: Vec<LLMMessage>,
@@ -11,22 +13,39 @@ pub fn convert_llm_messages_to_openai_messages(
         Vec::with_capacity(conversation_messages.len());
 
     for message in conversation_messages {
-        openai_conversation_messages.push(convert_llm_message_to_openai_message(message));
+        let openai_message = convert_llm_message_to_openai_message(message);
+        if let Some(openai_message) = openai_message {
+            openai_conversation_messages.push(openai_message);
+        }
     }
 
     openai_conversation_messages
 }
 
-fn convert_llm_message_to_openai_message(llm_message: LLMMessage) -> Message {
+fn convert_llm_message_to_openai_message(llm_message: LLMMessage) -> Option<Message> {
     let role = match llm_message.author {
         LLMAuthor::Prompt => Role::System,
         LLMAuthor::Assistant => Role::Assistant,
         LLMAuthor::User => Role::User,
     };
 
-    Message {
-        role,
-        content: llm_message.message_text,
+    match &llm_message.content {
+        LLMMessageContent::Text(text) => Some(Message {
+            role,
+            content: text.clone(),
+        }),
+        LLMMessageContent::Image(_image_details) => {
+            tracing::warn!(
+                "The OpenAI-compat provider's library does not support image content. This image message will be skipped."
+            );
+            None
+        }
+        LLMMessageContent::File(_file_details) => {
+            tracing::warn!(
+                "The OpenAI-compat provider's library does not support file content. This file message will be skipped."
+            );
+            None
+        }
     }
 }
 

src/agent/provider/openrouter/mod.rs

@@ -14,7 +14,7 @@ pub fn default_config() -> Config {
     if let Some(ref mut config) = config.text_generation.as_mut() {
         config.model_id = "mattshumer/reflection-70b:free".to_owned();
         config.max_context_tokens = 8192;
-        config.max_response_tokens = 2048;
+        config.max_response_tokens = Some(2048);
     }
 
     config

src/agent/provider/togetherai/mod.rs

@@ -14,7 +14,7 @@ pub fn default_config() -> Config {
     if let Some(ref mut config) = config.text_generation.as_mut() {
         config.model_id = "meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo".to_owned();
         config.max_context_tokens = 8192;
-        config.max_response_tokens = 2048;
+        config.max_response_tokens = Some(2048);
     }
 
     config

src/agent/provider/venice/audio.rs

@@ -0,0 +1,156 @@
+use crate::agent::AgentPurpose;
+use crate::agent::provider::entity::{TextToSpeechParams, TextToSpeechResult};
+use crate::agent::provider::{SpeechToTextParams, SpeechToTextResult};
+use crate::strings;
+
+use super::config::Config;
+use super::wire::{SpeechRequest, TranscriptionResponse};
+
+pub async fn speech_to_text(
+    config: &Config,
+    http: &reqwest::Client,
+    mime_type: &mxlink::mime::Mime,
+    media: Vec<u8>,
+    params: SpeechToTextParams,
+) -> anyhow::Result<SpeechToTextResult> {
+    let Some(speech_to_text_config) = &config.speech_to_text else {
+        return Err(anyhow::anyhow!(
+            strings::agent::no_configuration_for_purpose_so_cannot_be_used(
+                &AgentPurpose::SpeechToText
+            ),
+        ));
+    };
+
+    // Unlike the openai_compat path (which writes the audio to a temp file because its library
+    // can't take bytes), reqwest's multipart takes the bytes directly.
+    let part = reqwest::multipart::Part::bytes(media)
+        .file_name("audio")
+        .mime_str(mime_type.as_ref())?;
+
+    let mut form = reqwest::multipart::Form::new()
+        .part("file", part)
+        .text("model", speech_to_text_config.model_id.clone())
+        .text("response_format", "json");
+
+    if let Some(language) = &params.language_override {
+        form = form.text("language", language.clone());
+    }
+
+    let url = format!(
+        "{}/audio/transcriptions",
+        config.base_url.trim_end_matches('/')
+    );
+
+    tracing::trace!(
+        model_id = speech_to_text_config.model_id,
+        language = ?params.language_override,
+        "Sending Venice audio transcription API request"
+    );
+
+    let response = http
+        .post(&url)
+        .bearer_auth(&config.api_key)
+        .multipart(form)
+        .send()
+        .await?;
+
+    let status = response.status();
+    if !status.is_success() {
+        // Body to the server log only, not into the returned error (which reaches the Matrix room).
+        let body = response.text().await.unwrap_or_default();
+        tracing::warn!(%status, body, "Venice audio transcription request failed");
+        return Err(anyhow::anyhow!(
+            "Venice audio transcription request failed with status {status}"
+        ));
+    }
+
+    let response: TranscriptionResponse = response.json().await?;
+
+    Ok(SpeechToTextResult {
+        text: response.text,
+    })
+}
+
+pub async fn text_to_speech(
+    config: &Config,
+    http: &reqwest::Client,
+    input: &str,
+    params: TextToSpeechParams,
+) -> anyhow::Result<TextToSpeechResult> {
+    let Some(text_to_speech_config) = &config.text_to_speech else {
+        return Err(anyhow::anyhow!(
+            strings::agent::no_configuration_for_purpose_so_cannot_be_used(
+                &AgentPurpose::TextToSpeech
+            ),
+        ));
+    };
+
+    // Per-call overrides win over the configured defaults.
+    let voice = params
+        .voice_override
+        .or_else(|| text_to_speech_config.voice.clone());
+    let speed = params.speed_override.or(text_to_speech_config.speed);
+
+    let response_format = text_to_speech_config.response_format.clone();
+    let mime_type = response_format_to_mime_type(response_format.as_deref());
+
+    let request = SpeechRequest {
+        model: text_to_speech_config.model_id.clone(),
+        input: input.to_owned(),
+        voice,
+        speed,
+        response_format,
+        prompt: text_to_speech_config.prompt.clone(),
+        temperature: text_to_speech_config.temperature,
+        top_p: text_to_speech_config.top_p,
+    };
+
+    let url = format!("{}/audio/speech", config.base_url.trim_end_matches('/'));
+
+    tracing::trace!(
+        model_id = text_to_speech_config.model_id,
+        voice = ?request.voice,
+        "Sending Venice text-to-speech API request"
+    );
+
+    let response = http
+        .post(&url)
+        .bearer_auth(&config.api_key)
+        .json(&request)
+        .send()
+        .await?;
+
+    let status = response.status();
+    if !status.is_success() {
+        // Body to the server log only, not into the returned error (which reaches the Matrix room).
+        let body = response.text().await.unwrap_or_default();
+        tracing::warn!(%status, body, "Venice text-to-speech request failed");
+        return Err(anyhow::anyhow!(
+            "Venice text-to-speech request failed with status {status}"
+        ));
+    }
+
+    // The speech endpoint answers with raw binary audio; read the body directly.
+    let bytes = response.bytes().await?.to_vec();
+
+    Ok(TextToSpeechResult { bytes, mime_type })
+}
+
+/// Map a Venice TTS `response_format` to its MIME type. Defaults to `audio/mpeg` (the
+/// IANA-registered MP3 type, RFC 3003) when the format is unset, matching Venice's own `mp3`
+/// default. This deliberately uses `audio/mpeg` rather than the `audio/mp3` alias the openai
+/// provider emits; baibot's downstream audio-filename mapping treats both as `.mp3`.
+fn response_format_to_mime_type(response_format: Option<&str>) -> mxlink::mime::Mime {
+    let raw = match response_format.unwrap_or("mp3") {
+        "mp3" => "audio/mpeg",
+        "opus" => "audio/ogg",
+        "aac" => "audio/aac",
+        "flac" => "audio/flac",
+        "wav" => "audio/wav",
+        "pcm" => "audio/L8",
+        _ => "audio/mpeg",
+    };
+
+    raw.parse()
+        .unwrap_or(mxlink::mime::APPLICATION_OCTET_STREAM)
+}

src/agent/provider/venice/chat.rs

@@ -0,0 +1,351 @@
+use std::collections::hash_map::DefaultHasher;
+use std::hash::{Hash, Hasher};
+use std::sync::OnceLock;
+
+use regex::Regex;
+
+use crate::agent::AgentPurpose;
+use crate::agent::provider::entity::{TextGenerationParams, TextGenerationResult};
+use crate::conversation::llm::{
+    Author as LLMAuthor, Conversation as LLMConversation, Message as LLMMessage,
+    MessageContent as LLMMessageContent, TokenEstimate, shorten_messages_list_to_context_size,
+};
+use crate::strings;
+
+use super::config::{Config, WebSearchMode};
+use super::utils::convert_llm_messages_to_venice;
+use super::wire::{ChatCompletionRequest, ChatCompletionResponse, WebSearchCitation};
+
+pub async fn generate_text(
+    config: &Config,
+    http: &reqwest::Client,
+    unsupported: &super::recovery::UnsupportedFieldsCache,
+    conversation: LLMConversation,
+    params: TextGenerationParams,
+) -> anyhow::Result<TextGenerationResult> {
+    let Some(text_generation_config) = &config.text_generation else {
+        return Err(anyhow::anyhow!(
+            strings::agent::no_configuration_for_purpose_so_cannot_be_used(
+                &AgentPurpose::TextGeneration
+            ),
+        ));
+    };
+
+    let prompt_text = params.prompt_variables.format(
+        params
+            .prompt_override
+            .unwrap_or(text_generation_config.prompt.clone().unwrap_or_default())
+            .trim(),
+    );
+
+    // Prompt-cache routing key. Hash ONLY conversation-stable inputs: the rendered system prompt
+    // and the conversation start time. Folding in anything per-turn (message content, the current
+    // time, the message count) would mint a fresh key every turn, miss the cache every lookup, and
+    // pay full price plus the hashing cost. The start time is rendered explicitly here so the key
+    // stays stable even when the user's prompt template never mentions the time variable; an
+    // unknown start time renders "unknown" and simply keys on the prompt alone.
+    let conversation_start_time = params
+        .prompt_variables
+        .format("{{ baibot_conversation_start_time_utc }}");
+    let prompt_cache_key = derive_prompt_cache_key(&prompt_text, &conversation_start_time);
+
+    let prompt_message = if prompt_text.is_empty() {
+        None
+    } else {
+        Some(LLMMessage {
+            author: LLMAuthor::Prompt,
+            sender_id: None,
+            content: LLMMessageContent::Text(prompt_text),
+            timestamp: chrono::Utc::now(),
+        })
+    };
+
+    let mut conversation_messages = conversation.messages;
+
+    if params.context_management_enabled {
+        conversation_messages = shorten_messages_list_to_context_size(
+            TokenEstimate::Approximate,
+            &prompt_message,
+            conversation_messages,
+            text_generation_config.max_response_tokens,
+            text_generation_config.max_context_tokens,
+        );
+    }
+
+    if let Some(prompt_message) = prompt_message {
+        conversation_messages.insert(0, prompt_message);
+    }
+
+    let messages = convert_llm_messages_to_venice(conversation_messages)?;
+
+    let temperature = params
+        .temperature_override
+        .unwrap_or(text_generation_config.temperature);
+
+    // When web search is active, ask Venice to return structured search results so we can render
+    // readable citations from them. Respect an explicit user choice and only fill the flag when
+    // the user left it unset.
+    let venice_parameters = text_generation_config
+        .venice_parameters
+        .clone()
+        .map(|mut vp| {
+            let web_search_active = matches!(
+                vp.enable_web_search,
+                Some(WebSearchMode::On | WebSearchMode::Auto)
+            );
+            if web_search_active && vp.return_search_results_as_documents.is_none() {
+                vp.return_search_results_as_documents = Some(true);
+            }
+            vp
+        });
+
+    let mut request = ChatCompletionRequest {
+        model: text_generation_config.model_id.clone(),
+        messages,
+        temperature: Some(temperature),
+        // Web search rides entirely inside `venice_parameters`; there is no `tools` array here.
+        // `max_tokens` is deprecated on Venice in favor of `max_completion_tokens`.
+        max_completion_tokens: text_generation_config.max_response_tokens,
+        top_p: text_generation_config.top_p,
+        frequency_penalty: text_generation_config.frequency_penalty,
+        presence_penalty: text_generation_config.presence_penalty,
+        repetition_penalty: text_generation_config.repetition_penalty,
+        reasoning_effort: text_generation_config.reasoning_effort.clone(),
+        prompt_cache_key: Some(prompt_cache_key),
+        prompt_cache_retention: text_generation_config.prompt_cache_retention.clone(),
+        venice_parameters,
+    };
+
+    let url = format!("{}/chat/completions", config.base_url.trim_end_matches('/'));
+
+    let model_id = text_generation_config.model_id.clone();
+
+    // Proactively drop fields this model has already rejected earlier in this process, so a known
+    // mismatch costs zero wasted round-trips after the first discovery. Venice's body is
+    // `additionalProperties: false`, so sending a known-unsupported field would 400 again.
+    for field in unsupported.known_for(&model_id) {
+        super::recovery::strip_droppable_field(&mut request, &field);
+    }
+
+    // Send with bounded auto-recovery. When Venice 400s because a model does not support an optional
+    // knob, it names the field (`field: '...'`); if that field is one we may safely drop, we strip
+    // it, remember the rejection for this model, and retry. The loop is bounded: each retry clears a
+    // distinct droppable field (strip returns false once it is gone), so after at most
+    // `DROPPABLE_FIELDS.len()` retries the request either succeeds or surfaces the error.
+    let response = loop {
+        tracing::trace!(
+            model = model_id,
+            messages_count = request.messages.len(),
+            "Sending Venice chat completion API request"
+        );
+
+        let response = http
+            .post(&url)
+            .bearer_auth(&config.api_key)
+            .json(&request)
+            .send()
+            .await?;
+
+        let status = response.status();
+        if status.is_success() {
+            break response;
+        }
+
+        // Always log the body server-side: Venice explains a rejected strict body there.
+        let body = response.text().await.unwrap_or_default();
+        tracing::warn!(%status, body, "Venice chat completion request failed");
+
+        // Recover from a strict-body 400 over an unsupported optional knob: strip the named field
+        // and retry. Only fields in `DROPPABLE_FIELDS` are eligible, so a meaning-bearing knob (a
+        // sampling parameter) is never silently dropped; that case falls through to surface below.
+        if status == reqwest::StatusCode::BAD_REQUEST
+            && let Some(field) = super::recovery::parse_rejected_field(&body)
+            && super::recovery::strip_droppable_field(&mut request, &field)
+        {
+            unsupported.record(&model_id, &field);
+            tracing::info!(
+                model = model_id,
+                field,
+                "Venice rejected an unsupported field; dropping it and retrying"
+            );
+            continue;
+        }
+
+        // A 413 almost always means an attached file pushed the request past Venice's size limit.
+        if status == reqwest::StatusCode::PAYLOAD_TOO_LARGE {
+            return Err(anyhow::anyhow!(
+                "The request was too large for Venice, most likely an attached file over the 25MB limit."
+            ));
+        }
+
+        // A 400 is a complaint about the request baibot built, so the body is safe and useful to
+        // surface: it tells the operator (e.g. at agent-create time) exactly which field or value
+        // Venice rejected, instead of an opaque status. Other statuses keep the body OUT of the
+        // returned error, since it can carry account / rate-limit details that shouldn't reach the
+        // room.
+        if status == reqwest::StatusCode::BAD_REQUEST {
+            return Err(anyhow::anyhow!(
+                "Venice rejected the request (400 Bad Request): {}",
+                super::recovery::extract_error_message(&body)
+            ));
+        }
+
+        return Err(anyhow::anyhow!(
+            "Venice chat completion request failed with status {status}"
+        ));
+    };
+
+    let response: ChatCompletionResponse = response.json().await?;
+
+    let citations = response
+        .venice_parameters
+        .map(|vp| vp.web_search_citations)
+        .unwrap_or_default();
+
+    let Some(choice) = response.choices.into_iter().next() else {
+        return Err(anyhow::anyhow!(
+            "No choices were returned from the Venice chat completion API"
+        ));
+    };
+
+    let Some(content) = choice.message.content else {
+        return Err(anyhow::anyhow!(
+            "No message content was returned from the Venice chat completion API"
+        ));
+    };
+
+    let text = render_with_citations(content, &citations);
+    let text = append_reasoning(
+        text,
+        choice.message.reasoning_content,
+        text_generation_config.show_reasoning,
+    );
+
+    Ok(TextGenerationResult { text })
+}
+
+/// Builds the prompt-cache routing key from conversation-stable inputs. `DefaultHasher::new()` is a
+/// fixed-seed SipHasher (keys 0,0), so it is deterministic across processes and restarts: identical
+/// inputs always produce the same key, which is what lets a restarted bot keep hitting the warm
+/// cache. The algorithm is not guaranteed stable across Rust std versions, so a rebuild on a new
+/// toolchain can shift every key once, a one-time cache warm-up with no correctness effect.
+pub(super) fn derive_prompt_cache_key(prompt_text: &str, conversation_start_time: &str) -> String {
+    let mut hasher = DefaultHasher::new();
+    prompt_text.hash(&mut hasher);
+    conversation_start_time.hash(&mut hasher);
+    format!("{:016x}", hasher.finish())
+}
+
+/// Appends the model's thinking to the reply only when the deployment opts in via `show_reasoning`.
+/// `reasoning_content` is a field separate from the answer `content` (it is unaffected by
+/// `strip_thinking_response`, which only strips inline `<think>` blocks from `content`), so reading
+/// it here is independent of that knob. Default-off matches today's behavior: thinking never reaches
+/// a room that did not ask for it.
+///
+/// The thinking renders as a Matrix-native collapsible `<details>` block: folded by default, one
+/// click to expand, so it stays out of the way of the answer instead of dumping a wall of reasoning
+/// inline. This survives the send path: the reply goes through markdown (`send_text_markdown`),
+/// whose pulldown-cmark pass writes raw HTML verbatim rather than escaping it, and ruma's HTML
+/// sanitizer allow-lists `<details>`/`<summary>`. Clients that do not render `<details>` degrade to
+/// showing the summary and reasoning inline, so nothing is lost there either.
+pub(super) fn append_reasoning(
+    text: String,
+    reasoning_content: Option<String>,
+    show_reasoning: bool,
+) -> String {
+    if !show_reasoning {
+        return text;
+    }
+
+    match reasoning_content {
+        Some(reasoning) if !reasoning.trim().is_empty() => {
+            // The blank lines around the trimmed reasoning keep it a separate markdown block from
+            // the surrounding `<details>`/`</details>` HTML blocks, so the reasoning itself still
+            // renders as markdown (lists, code, emphasis) inside the collapsible.
+            let reasoning = reasoning.trim();
+            format!(
+                "{text}\n\n<details><summary>💭 Reasoning</summary>\n\n{reasoning}\n\n</details>"
+            )
+        }
+        _ => text,
+    }
+}
+
+/// Rewrites Venice's inline `^n^` citation superscripts into readable `[n]` references and appends
+/// a `Sources:` list of markdown links, one per citation in order. Returns the content unchanged
+/// when web search returned no citations, so non-search replies are never touched.
+///
+/// Citation `title` and `url` come from scraped web pages, so they are attacker-influenced. The
+/// title is escaped so it cannot break out of the markdown link label, and the URL is used as a
+/// link target only when it is a clean `http(s)` URL with no markdown-breaking characters;
+/// otherwise the citation renders as plain text. This stops a hostile page title or URL from
+/// injecting a spoofed clickable link into the room.
+pub(super) fn render_with_citations(content: String, citations: &[WebSearchCitation]) -> String {
+    if citations.is_empty() {
+        return content;
+    }
+
+    let mut text = rewrite_citation_superscripts(&content);
+
+    let mut sources = String::from("\n\nSources:");
+    for (index, citation) in citations.iter().enumerate() {
+        let n = index + 1;
+        let title = escape_markdown_link_text(&citation.title);
+        match sanitize_link_url(&citation.url) {
+            // A citation that arrived with no title still renders as a usable link by showing the
+            // URL as the link text, rather than an empty `[]( )` label.
+            Some(url) if title.is_empty() => sources.push_str(&format!("\n[{n}] [{url}]({url})")),
+            Some(url) => sources.push_str(&format!("\n[{n}] [{title}]({url})")),
+            None if !title.is_empty() => sources.push_str(&format!("\n[{n}] {title}")),
+            None => sources.push_str(&format!("\n[{n}] (source unavailable)")),
+        }
+    }
+
+    text.push_str(&sources);
+    text
+}
+
+/// Venice marks web-search citations with superscript runs in the reply text: a single `^1^`, a
+/// comma list `^1,2^`, or a caret-chained run `^2^3^10^` where consecutive citations share a
+/// caret. The whole run has to be matched at once: a per-citation pattern (string or regex)
+/// consumes the shared caret on the first match and orphans the rest (`^2^3^` would leave `3^`).
+/// So this matches each full run and expands it to one `[n]` per citation (`^2^3^` -> `[2][3]`).
+fn rewrite_citation_superscripts(content: &str) -> String {
+    static RUN: OnceLock<Regex> = OnceLock::new();
+    let run = RUN.get_or_init(|| {
+        Regex::new(r"\^\d+(?:[,^]\d+)*\^").expect("citation superscript regex is valid")
+    });
+
+    run.replace_all(content, |caps: &regex::Captures| {
+        caps[0]
+            .split(['^', ','])
+            .filter(|piece| !piece.is_empty())
+            .map(|n| format!("[{n}]"))
+            .collect::<String>()
+    })
+    .into_owned()
+}
+
+/// Escapes the characters that would let citation title text break out of a markdown link label,
+/// and folds newlines to spaces so a multi-line title cannot inject extra markdown structure.
+fn escape_markdown_link_text(text: &str) -> String {
+    text.replace('\\', "\\\\")
+        .replace('[', "\\[")
+        .replace(']', "\\]")
+        .replace(['\r', '\n'], " ")
+}
+
+/// Returns the URL as a markdown link target only when it is a clean `http(s)` URL with no
+/// characters that would break the `(...)` destination or smuggle a different scheme. Anything else
+/// returns `None`, so the caller renders the citation as plain text instead of a link.
+fn sanitize_link_url(url: &str) -> Option<String> {
+    let url = url.trim();
+    let is_http = url.starts_with("https://") || url.starts_with("http://");
+    let is_clean = !url.contains(['(', ')', '<', '>', ' ', '\t', '\r', '\n']);
+
+    if is_http && is_clean {
+        Some(url.to_owned())
+    } else {
+        None
+    }
+}

src/agent/provider/venice/config.rs

@@ -0,0 +1,410 @@
+use serde::{Deserialize, Serialize};
+
+use crate::agent::{default_prompt, provider::ConfigTrait};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Config {
+    pub base_url: String,
+
+    pub api_key: String,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub text_generation: Option<TextGenerationConfig>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub speech_to_text: Option<SpeechToTextConfig>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub text_to_speech: Option<TextToSpeechConfig>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub image_generation: Option<ImageGenerationConfig>,
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            base_url: "https://api.venice.ai/api/v1".to_owned(),
+            api_key: "YOUR_API_KEY_HERE".to_owned(),
+            text_generation: Some(TextGenerationConfig::default()),
+            speech_to_text: Some(SpeechToTextConfig::default()),
+            text_to_speech: Some(TextToSpeechConfig::default()),
+            image_generation: Some(ImageGenerationConfig::default()),
+        }
+    }
+}
+
+impl ConfigTrait for Config {
+    fn validate(&self) -> Result<(), String> {
+        if self.base_url.is_empty() {
+            return Err("The base URL must not be empty.".to_owned());
+        }
+
+        Ok(())
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TextGenerationConfig {
+    #[serde(default = "default_text_model_id")]
+    pub model_id: String,
+
+    #[serde(default)]
+    pub prompt: Option<String>,
+
+    #[serde(default = "super::super::default_temperature")]
+    pub temperature: f32,
+
+    #[serde(default)]
+    pub max_response_tokens: Option<u32>,
+
+    #[serde(default)]
+    pub max_context_tokens: u32,
+
+    /// Sampling and reasoning knobs that live at the top level of Venice's `/chat/completions`
+    /// body, not inside the `venice_parameters` bag. Venice silently ignores a top-level knob
+    /// placed in the bag, so these sit here as siblings and map straight to top-level wire fields
+    /// in `chat.rs`. Each is omitted from the request when unset.
+    #[serde(default)]
+    pub top_p: Option<f32>,
+
+    #[serde(default)]
+    pub frequency_penalty: Option<f32>,
+
+    #[serde(default)]
+    pub presence_penalty: Option<f32>,
+
+    #[serde(default)]
+    pub repetition_penalty: Option<f32>,
+
+    #[serde(default)]
+    pub reasoning_effort: Option<String>,
+
+    /// Prompt-cache retention window (`default`, `extended`, or `24h`). This carries a named
+    /// default rather than a bare `#[serde(default)]` (which would yield `None`), so a config that
+    /// omits the key still ships `24h` and keeps caching on. Caching is the per-deployment cost
+    /// lever, so the omitted-key case must not silently disable it. The value here must agree with
+    /// the `Default` impl below.
+    #[serde(default = "default_prompt_cache_retention")]
+    pub prompt_cache_retention: Option<String>,
+
+    /// When set, the model's `reasoning_content` (its thinking) is appended to the reply. Off by
+    /// default to match today's `strip_thinking_response: true` behavior, so existing deployments
+    /// see no change.
+    #[serde(default)]
+    pub show_reasoning: bool,
+
+    /// Venice-specific request knobs, serialized 1:1 into the `venice_parameters` bag on the
+    /// wire. Any unset field is omitted, so Venice applies its own server-side default.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub venice_parameters: Option<VeniceParameters>,
+}
+
+impl Default for TextGenerationConfig {
+    fn default() -> Self {
+        Self {
+            model_id: default_text_model_id(),
+            prompt: Some(default_prompt().to_owned()),
+            temperature: super::super::default_temperature(),
+            // Reserved output budget: sent as the response cap AND subtracted from the context
+            // window when trimming history. Mirrors the openai_compat sibling's default.
+            max_response_tokens: Some(4096),
+            // Matches Venice's own `availableContextTokens` (131072) and the non-OpenAI sibling
+            // providers (ollama/localai/mistral all default to 128_000).
+            max_context_tokens: 128_000,
+            // Sampling knobs stay None so Venice applies its own server-side default. Caching is
+            // the one exception: retention defaults to 24h here so a programmatic default caches
+            // out of the box, agreeing with the `#[serde(default = ...)]` on the field.
+            top_p: None,
+            frequency_penalty: None,
+            presence_penalty: None,
+            repetition_penalty: None,
+            reasoning_effort: None,
+            prompt_cache_retention: default_prompt_cache_retention(),
+            show_reasoning: false,
+            // A usable starting point, not an everything-set dump: only these three are sent;
+            // every other knob stays None so Venice applies its own default (omitting != false).
+            venice_parameters: Some(VeniceParameters {
+                enable_web_search: Some(WebSearchMode::Auto),
+                strip_thinking_response: Some(true),
+                enable_e2ee: Some(false),
+                ..Default::default()
+            }),
+        }
+    }
+}
+
+fn default_text_model_id() -> String {
+    "kimi-k2-5".to_owned()
+}
+
+/// Defaults prompt-cache retention to 24h so caching is on unless a config explicitly opts out.
+/// A bare `#[serde(default)]` would deserialize an omitted key to `None`, which disables caching;
+/// this keeps the cost lever engaged for configs that never mention it.
+fn default_prompt_cache_retention() -> Option<String> {
+    Some("24h".to_owned())
+}
+
+/// The full `venice_parameters` knob set, mirroring Venice's `ChatCompletionRequest`
+/// schema field-for-field. Every field is optional with `skip_serializing_if`, so the
+/// request never carries a knob the user didn't set (the body is `additionalProperties: false`,
+/// and an unset knob simply omits rather than sending `null`).
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct VeniceParameters {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enable_web_search: Option<WebSearchMode>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enable_web_citations: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enable_web_scraping: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub include_venice_system_prompt: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub include_search_results_in_stream: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub return_search_results_as_documents: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enable_x_search: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enable_e2ee: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub character_slug: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub strip_thinking_response: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub disable_thinking: Option<bool>,
+
+    /// Response verbosity (`low`, `medium`, `high`). Venice accepts this both top-level and inside
+    /// the bag; it lives here so the top-level config stays lean, and Venice reads it from the bag.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub verbosity: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum WebSearchMode {
+    Auto,
+    On,
+    Off,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SpeechToTextConfig {
+    #[serde(default = "default_speech_to_text_model_id")]
+    pub model_id: String,
+}
+
+impl Default for SpeechToTextConfig {
+    fn default() -> Self {
+        Self {
+            model_id: default_speech_to_text_model_id(),
+        }
+    }
+}
+
+fn default_speech_to_text_model_id() -> String {
+    "nvidia/parakeet-tdt-0.6b-v3".to_owned()
+}
+
+/// `/audio/speech` (`CreateSpeechRequestSchema`) request knobs. Only `model_id` is required on
+/// the wire; everything else is optional with `skip_serializing_if` so an unset knob is omitted
+/// rather than sent as `null` (the body is `additionalProperties: false`). `voice` is a free
+/// `Option<String>`, not a closed enum: Venice's voice set spans dozens of model-specific names
+/// plus arbitrary cloned-voice handles (`vv_<id>`), so an enum would reject valid handles.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TextToSpeechConfig {
+    #[serde(default = "default_text_to_speech_model_id")]
+    pub model_id: String,
+
+    #[serde(
+        default = "default_text_to_speech_voice",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub voice: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub speed: Option<f32>,
+
+    #[serde(
+        default = "default_text_to_speech_response_format",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub response_format: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prompt: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<f32>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub top_p: Option<f32>,
+}
+
+impl Default for TextToSpeechConfig {
+    fn default() -> Self {
+        Self {
+            model_id: default_text_to_speech_model_id(),
+            voice: default_text_to_speech_voice(),
+            speed: None,
+            response_format: default_text_to_speech_response_format(),
+            prompt: None,
+            temperature: None,
+            top_p: None,
+        }
+    }
+}
+
+fn default_text_to_speech_model_id() -> String {
+    "tts-kokoro".to_owned()
+}
+
+fn default_text_to_speech_voice() -> Option<String> {
+    Some("af_sky".to_owned())
+}
+
+fn default_text_to_speech_response_format() -> Option<String> {
+    Some("mp3".to_owned())
+}
+
+/// `/image/generate` (`GenerateImageRequest`) request knobs, mirroring Venice's schema
+/// field-for-field. Only `model_id` is required; every other knob is optional with
+/// `skip_serializing_if` so unset knobs are omitted (the body is `additionalProperties: false`).
+/// The full knob set is deliberate: the native `/image/generate` endpoint is the flagship's
+/// reason to exist over the knob-dropping OpenAI-compat path, so the knobs ARE the feature.
+/// The deprecated `inpaint` knob is intentionally absent.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ImageGenerationConfig {
+    #[serde(default = "default_image_generation_model_id")]
+    pub model_id: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub negative_prompt: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cfg_scale: Option<f32>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub steps: Option<u32>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub style_preset: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub seed: Option<i64>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub safe_mode: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hide_watermark: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub format: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub width: Option<u32>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub height: Option<u32>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub aspect_ratio: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub resolution: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub quality: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub lora_strength: Option<u32>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub embed_exif_metadata: Option<bool>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enable_web_search: Option<bool>,
+
+    /// Image-edit settings, nested here because baibot has a single `ImageGeneration` purpose
+    /// and edit shares its config gate. The gen and edit model sets are disjoint, so edit
+    /// carries its own model field.
+    #[serde(default)]
+    pub edit: ImageEditSettings,
+}
+
+impl Default for ImageGenerationConfig {
+    fn default() -> Self {
+        Self {
+            model_id: default_image_generation_model_id(),
+            negative_prompt: None,
+            cfg_scale: None,
+            steps: None,
+            style_preset: None,
+            seed: None,
+            safe_mode: None,
+            hide_watermark: None,
+            format: None,
+            width: None,
+            height: None,
+            aspect_ratio: None,
+            resolution: None,
+            quality: None,
+            lora_strength: None,
+            embed_exif_metadata: None,
+            enable_web_search: None,
+            edit: ImageEditSettings::default(),
+        }
+    }
+}
+
+fn default_image_generation_model_id() -> String {
+    "chroma".to_owned()
+}
+
+/// `/image/edit` (`EditImageRequest`) request knobs, mirroring Venice's schema. The source image
+/// and prompt are supplied per-call (not config), so only the model and the output-shaping knobs
+/// live here. Each knob is optional with `skip_serializing_if`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ImageEditSettings {
+    #[serde(default = "default_image_edit_model_id")]
+    pub model_id: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_format: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub aspect_ratio: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub resolution: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub safe_mode: Option<bool>,
+}
+
+impl Default for ImageEditSettings {
+    fn default() -> Self {
+        Self {
+            model_id: default_image_edit_model_id(),
+            output_format: None,
+            aspect_ratio: None,
+            resolution: None,
+            safe_mode: None,
+        }
+    }
+}
+
+fn default_image_edit_model_id() -> String {
+    "firered-image-edit".to_owned()
+}

src/agent/provider/venice/controller.rs

@@ -0,0 +1,167 @@
+use crate::agent::AgentPurpose;
+use crate::agent::provider::entity::{
+    ImageEditResult, ImageGenerationResult, ImageSource, PingResult, TextGenerationParams,
+    TextGenerationResult, TextToSpeechParams, TextToSpeechResult,
+};
+use crate::agent::provider::{
+    ImageEditParams, ImageGenerationParams, SpeechToTextParams, SpeechToTextResult,
+};
+use crate::conversation::llm::{
+    Author as LLMAuthor, Conversation as LLMConversation, Message as LLMMessage,
+    MessageContent as LLMMessageContent,
+};
+
+use super::super::ControllerTrait;
+use super::config::Config;
+use super::recovery::UnsupportedFieldsCache;
+
+#[derive(Debug, Clone)]
+pub struct Controller {
+    config: Config,
+    http: reqwest::Client,
+    // Per-model record of chat fields this Venice deployment has rejected as unsupported, learned at
+    // runtime. `Arc`-backed inside, so the `Clone` derive shares one cache across all clones of an
+    // agent's controller.
+    unsupported_fields: UnsupportedFieldsCache,
+}
+
+impl Controller {
+    pub fn new(config: Config) -> Self {
+        // Image generation and text-to-speech can run long, so give the client a generous timeout
+        // instead of reqwest's default (none). `build` only fails on TLS/system init; fall back to
+        // the infallible `Client::new()` so this constructor stays infallible.
+        let http = reqwest::Client::builder()
+            .timeout(std::time::Duration::from_secs(120))
+            .build()
+            .unwrap_or_else(|_| reqwest::Client::new());
+
+        // Process-global per-deployment cache rather than a fresh one: dynamic agents rebuild their
+        // controller on every message, so an instance-owned cache would never retain a learned
+        // rejection and the same unsupported field would 400 (and warn) on every turn.
+        let unsupported_fields = UnsupportedFieldsCache::shared_for(&config.base_url);
+
+        Self {
+            config,
+            http,
+            unsupported_fields,
+        }
+    }
+}
+
+impl ControllerTrait for Controller {
+    async fn ping(&self) -> anyhow::Result<PingResult> {
+        if !self.supports_purpose(AgentPurpose::TextGeneration) {
+            return Ok(PingResult::Inconclusive);
+        }
+
+        // Mirror the openai/openai_compat ping: a real "Hello!" round-trip exercises the strict
+        // /chat/completions body and auth, so a successful ping proves text generation works.
+        let messages = vec![LLMMessage {
+            author: LLMAuthor::User,
+            sender_id: None,
+            content: LLMMessageContent::Text("Hello!".to_string()),
+            timestamp: chrono::Utc::now(),
+        }];
+
+        let conversation = LLMConversation { messages };
+
+        self.generate_text(conversation, TextGenerationParams::default())
+            .await?;
+
+        Ok(PingResult::Successful)
+    }
+
+    async fn generate_text(
+        &self,
+        conversation: LLMConversation,
+        params: TextGenerationParams,
+    ) -> anyhow::Result<TextGenerationResult> {
+        super::chat::generate_text(
+            &self.config,
+            &self.http,
+            &self.unsupported_fields,
+            conversation,
+            params,
+        )
+        .await
+    }
+
+    async fn speech_to_text(
+        &self,
+        mime_type: &mxlink::mime::Mime,
+        media: Vec<u8>,
+        params: SpeechToTextParams,
+    ) -> anyhow::Result<SpeechToTextResult> {
+        super::audio::speech_to_text(&self.config, &self.http, mime_type, media, params).await
+    }
+
+    async fn generate_image(
+        &self,
+        prompt: &str,
+        params: ImageGenerationParams,
+    ) -> anyhow::Result<ImageGenerationResult> {
+        super::images::generate_image(&self.config, &self.http, prompt, params).await
+    }
+
+    async fn create_image_edit(
+        &self,
+        prompt: &str,
+        images: Vec<ImageSource>,
+        params: ImageEditParams,
+    ) -> anyhow::Result<ImageEditResult> {
+        super::images::create_image_edit(&self.config, &self.http, prompt, images, params).await
+    }
+
+    async fn text_to_speech(
+        &self,
+        input: &str,
+        params: TextToSpeechParams,
+    ) -> anyhow::Result<TextToSpeechResult> {
+        super::audio::text_to_speech(&self.config, &self.http, input, params).await
+    }
+
+    fn supports_purpose(&self, purpose: AgentPurpose) -> bool {
+        match purpose {
+            AgentPurpose::TextGeneration => self.config.text_generation.is_some(),
+            AgentPurpose::SpeechToText => self.config.speech_to_text.is_some(),
+            AgentPurpose::TextToSpeech => self.config.text_to_speech.is_some(),
+            AgentPurpose::ImageGeneration => self.config.image_generation.is_some(),
+            AgentPurpose::CatchAll => true,
+        }
+    }
+
+    fn text_generation_model_id(&self) -> Option<String> {
+        self.config
+            .text_generation
+            .as_ref()
+            .map(|config| config.model_id.to_owned())
+    }
+
+    fn text_generation_prompt(&self) -> Option<String> {
+        self.config
+            .text_generation
+            .as_ref()
+            .and_then(|config| config.prompt.clone())
+    }
+
+    fn text_generation_temperature(&self) -> Option<f32> {
+        self.config
+            .text_generation
+            .as_ref()
+            .map(|config| config.temperature)
+    }
+
+    fn text_to_speech_voice(&self) -> Option<String> {
+        self.config
+            .text_to_speech
+            .as_ref()
+            .and_then(|config| config.voice.clone())
+    }
+
+    fn text_to_speech_speed(&self) -> Option<f32> {
+        self.config
+            .text_to_speech
+            .as_ref()
+            .and_then(|config| config.speed)
+    }
+}

src/agent/provider/venice/images.rs

@@ -0,0 +1,190 @@
+use crate::agent::AgentPurpose;
+use crate::agent::provider::entity::{ImageEditResult, ImageGenerationResult, ImageSource};
+use crate::agent::provider::{ImageEditParams, ImageGenerationParams};
+use crate::strings;
+use crate::utils::base64::{base64_decode, base64_encode};
+
+use super::config::Config;
+use super::wire::{EditImageRequest, GenerateImageRequest, GenerateImageResponse};
+
+/// Generate an image via Venice's native `/image/generate` endpoint.
+///
+/// This is the base64-in-JSON path: we pin `return_binary: false` so Venice answers with a JSON
+/// envelope (`GenerateImageResponse`) carrying the image as a base64 string, which we decode. The
+/// sibling `create_image_edit` is the *other* response shape (raw binary); the two must not be
+/// crossed. `params` is advisory only; the Venice config drives the request.
+pub async fn generate_image(
+    config: &Config,
+    http: &reqwest::Client,
+    prompt: &str,
+    _params: ImageGenerationParams,
+) -> anyhow::Result<ImageGenerationResult> {
+    let Some(image_generation_config) = &config.image_generation else {
+        return Err(anyhow::anyhow!(
+            strings::agent::no_configuration_for_purpose_so_cannot_be_used(
+                &AgentPurpose::ImageGeneration
+            ),
+        ));
+    };
+
+    let request = GenerateImageRequest {
+        model: image_generation_config.model_id.clone(),
+        prompt: prompt.to_owned(),
+        // Pinned: baibot wants exactly one image, returned as base64-in-JSON so `GenerateImageResponse`
+        // can decode it. Flipping `return_binary` would make Venice answer with raw binary and break
+        // the JSON decode below, so neither knob is configurable.
+        return_binary: false,
+        variants: 1,
+        negative_prompt: image_generation_config.negative_prompt.clone(),
+        cfg_scale: image_generation_config.cfg_scale,
+        steps: image_generation_config.steps,
+        style_preset: image_generation_config.style_preset.clone(),
+        seed: image_generation_config.seed,
+        safe_mode: image_generation_config.safe_mode,
+        hide_watermark: image_generation_config.hide_watermark,
+        format: image_generation_config.format.clone(),
+        width: image_generation_config.width,
+        height: image_generation_config.height,
+        aspect_ratio: image_generation_config.aspect_ratio.clone(),
+        resolution: image_generation_config.resolution.clone(),
+        quality: image_generation_config.quality.clone(),
+        lora_strength: image_generation_config.lora_strength,
+        embed_exif_metadata: image_generation_config.embed_exif_metadata,
+        enable_web_search: image_generation_config.enable_web_search,
+    };
+
+    let url = format!("{}/image/generate", config.base_url.trim_end_matches('/'));
+
+    // The prompt is user content; keep it out of logs (mirrors the STT/TTS paths).
+    tracing::trace!(
+        model_id = image_generation_config.model_id,
+        "Sending Venice image generation API request"
+    );
+
+    let response = http
+        .post(&url)
+        .bearer_auth(&config.api_key)
+        .json(&request)
+        .send()
+        .await?;
+
+    let status = response.status();
+    if !status.is_success() {
+        // Body to the server log only, not into the returned error (which reaches the Matrix room).
+        let body = response.text().await.unwrap_or_default();
+        tracing::warn!(%status, body, "Venice image generation request failed");
+        return Err(anyhow::anyhow!(
+            "Venice image generation request failed with status {status}"
+        ));
+    }
+
+    let response: GenerateImageResponse = response.json().await?;
+
+    tracing::trace!(request_id = ?response.id, "Venice image generation succeeded");
+
+    let Some(image_base64) = response.images.into_iter().next() else {
+        return Err(anyhow::anyhow!(
+            "The Venice image generation API returned no images"
+        ));
+    };
+
+    // Swallow the decode error's detail (it can echo input bytes/offsets); the returned error
+    // reaches the Matrix room, so it stays generic while the real cause goes to the server log.
+    let bytes = base64_decode(&image_base64).map_err(|decode_err| {
+        tracing::warn!(%decode_err, "Venice image generation returned undecodable base64");
+        anyhow::anyhow!("Venice image generation returned invalid base64 image data")
+    })?;
+
+    Ok(ImageGenerationResult {
+        bytes,
+        mime_type: image_format_to_mime_type(image_generation_config.format.as_deref()),
+        revised_prompt: None,
+    })
+}
+
+/// Edit an image via Venice's native `/image/edit` endpoint.
+///
+/// This is the raw-binary path: the request is JSON carrying the source image as a base64 string
+/// (Venice's `image` field is `anyOf` upload/base64/URL; we send base64, no multipart), and the
+/// response body IS the edited image bytes (no JSON envelope). `params` is advisory only.
+pub async fn create_image_edit(
+    config: &Config,
+    http: &reqwest::Client,
+    prompt: &str,
+    images: Vec<ImageSource>,
+    _params: ImageEditParams,
+) -> anyhow::Result<ImageEditResult> {
+    let Some(image_generation_config) = &config.image_generation else {
+        return Err(anyhow::anyhow!(
+            strings::agent::no_configuration_for_purpose_so_cannot_be_used(
+                &AgentPurpose::ImageGeneration
+            ),
+        ));
+    };
+
+    let edit_config = &image_generation_config.edit;
+
+    let Some(source) = images.into_iter().next() else {
+        return Err(anyhow::anyhow!("No image sources provided"));
+    };
+
+    let request = EditImageRequest {
+        model: edit_config.model_id.clone(),
+        prompt: prompt.to_owned(),
+        image: base64_encode(&source.bytes),
+        output_format: edit_config.output_format.clone(),
+        aspect_ratio: edit_config.aspect_ratio.clone(),
+        resolution: edit_config.resolution.clone(),
+        safe_mode: edit_config.safe_mode,
+    };
+
+    let url = format!("{}/image/edit", config.base_url.trim_end_matches('/'));
+
+    // The prompt is user content; keep it out of logs (mirrors the STT/TTS paths).
+    tracing::trace!(
+        model_id = edit_config.model_id,
+        "Sending Venice image edit API request"
+    );
+
+    let response = http
+        .post(&url)
+        .bearer_auth(&config.api_key)
+        .json(&request)
+        .send()
+        .await?;
+
+    let status = response.status();
+    if !status.is_success() {
+        // Body to the server log only, not into the returned error (which reaches the Matrix room).
+        let body = response.text().await.unwrap_or_default();
+        tracing::warn!(%status, body, "Venice image edit request failed");
+        return Err(anyhow::anyhow!(
+            "Venice image edit request failed with status {status}"
+        ));
+    }
+
+    // The edit endpoint answers with raw binary image bytes, so read the body directly instead of
+    // parsing JSON. The actual format comes from the response Content-Type header; fall back to the
+    // configured `output_format` when the header is missing or unparseable.
+    let mime_type = response
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .and_then(|value| value.parse::<mxlink::mime::Mime>().ok())
+        .unwrap_or_else(|| image_format_to_mime_type(edit_config.output_format.as_deref()));
+
+    let bytes = response.bytes().await?.to_vec();
+
+    Ok(ImageEditResult { bytes, mime_type })
+}
+
+/// Map a Venice image `format`/`output_format` value (`jpeg`/`png`/`webp`) to its MIME type.
+/// Venice defaults to `webp` when the format is unset, so an absent value maps to `image/webp`.
+fn image_format_to_mime_type(format: Option<&str>) -> mxlink::mime::Mime {
+    match format.unwrap_or("webp") {
+        "jpeg" | "jpg" => mxlink::mime::IMAGE_JPEG,
+        "png" => mxlink::mime::IMAGE_PNG,
+        // No mxlink::mime constant for webp; parse it, falling back to PNG on any surprise value.
+        _ => "image/webp".parse().unwrap_or(mxlink::mime::IMAGE_PNG),
+    }
+}

src/agent/provider/venice/mod.rs

@@ -0,0 +1,48 @@
+mod audio;
+mod chat;
+mod config;
+mod controller;
+mod images;
+mod recovery;
+mod utils;
+mod wire;
+
+#[cfg(test)]
+mod tests;
+
+pub use config::Config;
+pub use controller::Controller;
+
+use super::super::AgentInstantiationError;
+use super::super::AgentInstantiationResult;
+use super::ConfigTrait;
+use super::controller::ControllerType;
+
+pub fn create_controller_from_yaml_value_config(
+    agent_id: &str,
+    config: serde_yaml_ng::Value,
+) -> AgentInstantiationResult<ControllerType> {
+    let config = match &config {
+        serde_yaml_ng::Value::Mapping(_) => {
+            let config: Config =
+                serde_yaml_ng::from_value(config).map_err(AgentInstantiationError::Yaml)?;
+
+            config
+                .validate()
+                .map_err(AgentInstantiationError::ConfigFailsValidation)?;
+
+            config
+        }
+        _ => {
+            return Err(AgentInstantiationError::ConfigForAgentIsNotAMapping(
+                agent_id.to_owned(),
+            ));
+        }
+    };
+
+    Ok(ControllerType::Venice(Box::new(Controller::new(config))))
+}
+
+pub fn default_config() -> Config {
+    Config::default()
+}

src/agent/provider/venice/recovery.rs

@@ -0,0 +1,312 @@
+//! Auto-recovery for Venice's strict request bodies.
+//!
+//! Venice's `/chat/completions` body is `additionalProperties: false`, so a model that does not
+//! support an optional knob rejects the whole request with a 400 instead of ignoring the field.
+//! Some knobs are documented as model-specific ("for supported models") and are pure
+//! optimization/tuning hints: dropping them changes nothing about the answer, only loses the
+//! optimization. When such a field is the reason for a 400, we strip it and retry, then remember
+//! the rejection per model so later requests skip the field (and the wasted round-trip) entirely.
+//!
+//! Universal sampling knobs (`temperature`, `top_p`, the penalties, `max_completion_tokens`) are
+//! deliberately NOT recoverable here: dropping one silently changes the model's output, so a model
+//! that rejects one is a real configuration problem the operator must see, not paper over.
+
+use std::collections::{HashMap, HashSet};
+use std::sync::{Arc, OnceLock, RwLock};
+
+use regex::Regex;
+
+use super::wire::ChatCompletionRequest;
+
+/// Top-level chat-completion fields baibot may drop to recover from a 400. Each is documented by
+/// Venice as model-specific or as a routing hint, and is meaning-preserving to omit (Venice falls
+/// back to its server-side default):
+/// - `prompt_cache_retention` — "extends retention ... for supported models" (cache TTL only)
+/// - `reasoning_effort` — "control reasoning effort level for supported models"
+/// - `prompt_cache_key` — cache-routing hint; dropping it only forfeits a cache-hit optimization
+///
+/// Recovery operates on TOP-LEVEL request fields only. Sub-fields inside the `venice_parameters`
+/// bag (`disable_thinking`, `enable_e2ee`, `character_slug`, …) are intentionally absent: a model
+/// that rejects one surfaces a clear 400 to the operator rather than being auto-stripped. Adding a
+/// new bag field does not extend recovery to it; only a name listed here is droppable.
+pub(super) const DROPPABLE_FIELDS: &[&str] = &[
+    "prompt_cache_retention",
+    "prompt_cache_key",
+    "reasoning_effort",
+];
+
+/// Per-model record of fields a Venice model has rejected as unsupported, learned at runtime from
+/// 400 responses. The `Arc` is shared across `Controller` clones, so a rejection learned once is
+/// seen by every clone of the same agent. The cache is process-lived only: a restart re-learns on
+/// the first request to each model, which costs one extra round-trip and nothing else, so there is
+/// no persistence to keep in sync with config changes.
+#[derive(Debug, Clone, Default)]
+pub(super) struct UnsupportedFieldsCache {
+    inner: Arc<RwLock<HashMap<String, HashSet<String>>>>,
+}
+
+/// Process-global registry of per-deployment caches, keyed by Venice base URL. A `Controller` is
+/// rebuilt from its config on every message for dynamic (global/room-local) agents (see
+/// `agent::manager::available_room_agents_by_room_config_context`), so a cache stored on the
+/// controller would be reset each message and the "process-lived" intent above would never hold.
+/// The registry lets a rebuilt controller re-attach to the same cache. Keyed by base URL because
+/// "which fields a model rejects" is a property of the deployment+model, not of the agent instance:
+/// agents on the same Venice deployment share learnings, while a distinct deployment keeps its own,
+/// so a model name that supports a field on one deployment is never proactively stripped against
+/// another.
+fn registry() -> &'static RwLock<HashMap<String, UnsupportedFieldsCache>> {
+    static REGISTRY: OnceLock<RwLock<HashMap<String, UnsupportedFieldsCache>>> = OnceLock::new();
+    REGISTRY.get_or_init(|| RwLock::new(HashMap::new()))
+}
+
+impl UnsupportedFieldsCache {
+    /// The process-global cache for `base_url`, created on first use and shared by every controller
+    /// for that deployment thereafter. This is what makes a learned rejection survive the
+    /// per-message controller rebuild. A poisoned registry lock degrades to an isolated cache:
+    /// correctness holds, only cross-controller sharing is lost for that call.
+    pub(super) fn shared_for(base_url: &str) -> Self {
+        if let Ok(map) = registry().read()
+            && let Some(cache) = map.get(base_url)
+        {
+            return cache.clone();
+        }
+
+        match registry().write() {
+            Ok(mut map) => map.entry(base_url.to_owned()).or_default().clone(),
+            Err(_) => Self::default(),
+        }
+    }
+
+    /// Fields already known unsupported for `model_id`. Returns an empty set on an unknown model or
+    /// a poisoned lock, so a cache failure degrades to "strip nothing proactively" rather than
+    /// breaking the request path.
+    pub(super) fn known_for(&self, model_id: &str) -> HashSet<String> {
+        self.inner
+            .read()
+            .ok()
+            .and_then(|map| map.get(model_id).cloned())
+            .unwrap_or_default()
+    }
+
+    /// Records that `model_id` rejected `field`. A poisoned lock is ignored: failing to memoize only
+    /// means the next request re-discovers the rejection, never a wrong result.
+    pub(super) fn record(&self, model_id: &str, field: &str) {
+        if let Ok(mut map) = self.inner.write() {
+            map.entry(model_id.to_owned())
+                .or_default()
+                .insert(field.to_owned());
+        }
+    }
+}
+
+/// Parses the offending field name out of a Venice 400 body. A field the schema does not allow is
+/// reported as `... field: 'prompt_cache_retention', value: '...'`, so this matches the `field: '..'`
+/// marker wherever it sits in the message. Returns `None` when the body carries no such marker (a
+/// different 400 class, e.g. a missing required field), so the caller surfaces that error instead.
+///
+/// Returns only the FIRST `field: '..'` match by design. If Venice ever names several rejected
+/// fields in one body, the retry loop strips this one, retries, and rediscovers the next on the
+/// following 400 — bounded and correct. Do not switch to `captures_iter` to "batch" them without
+/// re-checking the loop's per-field termination bound in `chat.rs`.
+pub(super) fn parse_rejected_field(body: &str) -> Option<String> {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    let re =
+        RE.get_or_init(|| Regex::new(r"field: '([^']+)'").expect("rejected-field regex is valid"));
+    re.captures(body)
+        .map(|caps| caps[1].to_owned())
+        .filter(|field| !field.is_empty())
+}
+
+/// Clears `field` from the request when it is one baibot may safely drop and it is currently set.
+/// Returns `true` only when a value was actually removed, which is what bounds the retry loop: once
+/// a field is `None`, a repeat rejection for the same name returns `false` and the caller stops
+/// instead of retrying forever. A field outside [`DROPPABLE_FIELDS`] always returns `false`, so a
+/// meaning-bearing knob is never silently dropped.
+pub(super) fn strip_droppable_field(request: &mut ChatCompletionRequest, field: &str) -> bool {
+    if !DROPPABLE_FIELDS.contains(&field) {
+        return false;
+    }
+    match field {
+        "prompt_cache_retention" => request.prompt_cache_retention.take().is_some(),
+        "prompt_cache_key" => request.prompt_cache_key.take().is_some(),
+        "reasoning_effort" => request.reasoning_effort.take().is_some(),
+        _ => false,
+    }
+}
+
+/// Pulls a human-readable message out of a Venice error body for surfacing in the room. Venice's
+/// usual envelope is `{"error": "..."}`; some OpenAI-compatible paths nest `{"error": {"message":
+/// "..."}}`. Falls back to the trimmed raw body (length-capped so a large body cannot flood the
+/// room) and finally to a fixed string for an empty body, so the caller always has something to
+/// show.
+pub(super) fn extract_error_message(body: &str) -> String {
+    let trimmed = body.trim();
+    if trimmed.is_empty() {
+        return "no response body".to_owned();
+    }
+
+    if let Ok(value) = serde_json::from_str::<serde_json::Value>(trimmed) {
+        if let Some(msg) = value.get("error").and_then(|e| e.as_str()) {
+            return msg.to_owned();
+        }
+        if let Some(msg) = value
+            .get("error")
+            .and_then(|e| e.get("message"))
+            .and_then(|m| m.as_str())
+        {
+            return msg.to_owned();
+        }
+    }
+
+    const MAX: usize = 500;
+    if trimmed.chars().count() > MAX {
+        trimmed.chars().take(MAX).collect::<String>() + "…"
+    } else {
+        trimmed.to_owned()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn full_request() -> ChatCompletionRequest {
+        ChatCompletionRequest {
+            model: "venice-uncensored".to_owned(),
+            messages: vec![],
+            temperature: Some(0.7),
+            max_completion_tokens: Some(1024),
+            top_p: None,
+            frequency_penalty: None,
+            presence_penalty: None,
+            repetition_penalty: None,
+            reasoning_effort: Some("high".to_owned()),
+            prompt_cache_key: Some("cafef00d".to_owned()),
+            prompt_cache_retention: Some("24h".to_owned()),
+            venice_parameters: None,
+        }
+    }
+
+    #[test]
+    fn parses_the_rejected_field_from_a_real_venice_body() {
+        let body = r#"{"error":"Extra inputs are not permitted, field: 'prompt_cache_retention', value: 'default'","request_id":"qM_DmKSXKF07wRxmQJ-hc"}"#;
+        assert_eq!(
+            parse_rejected_field(body).as_deref(),
+            Some("prompt_cache_retention")
+        );
+    }
+
+    #[test]
+    fn returns_no_field_when_the_body_has_no_field_marker() {
+        // A different 400 class (e.g. a genuinely malformed request) carries no `field: '..'`
+        // marker, so there is nothing to strip and the caller must surface the error instead.
+        assert_eq!(parse_rejected_field(r#"{"error":"Invalid request"}"#), None);
+        assert_eq!(parse_rejected_field(""), None);
+    }
+
+    #[test]
+    fn strips_a_droppable_field_once_then_reports_no_progress() {
+        let mut request = full_request();
+
+        // First strip clears the field and reports progress, so the caller retries.
+        assert!(strip_droppable_field(
+            &mut request,
+            "prompt_cache_retention"
+        ));
+        assert!(request.prompt_cache_retention.is_none());
+
+        // A repeat rejection for the same (now absent) field reports no progress: this is what
+        // stops the retry loop instead of spinning forever.
+        assert!(!strip_droppable_field(
+            &mut request,
+            "prompt_cache_retention"
+        ));
+    }
+
+    #[test]
+    fn refuses_to_strip_a_meaning_bearing_field() {
+        let mut request = full_request();
+
+        // `temperature` is universal and changes the output; a rejection for it must surface, never
+        // be silently dropped. The whole droppable set is the only thing strip will touch.
+        assert!(!strip_droppable_field(&mut request, "temperature"));
+        assert_eq!(request.temperature, Some(0.7));
+
+        assert!(!strip_droppable_field(
+            &mut request,
+            "max_completion_tokens"
+        ));
+        assert_eq!(request.max_completion_tokens, Some(1024));
+
+        for field in DROPPABLE_FIELDS {
+            assert!(
+                strip_droppable_field(&mut full_request(), field),
+                "every advertised droppable field must actually be strippable: {field}"
+            );
+        }
+    }
+
+    #[test]
+    fn cache_records_per_model_and_isolates_models() {
+        let cache = UnsupportedFieldsCache::default();
+        assert!(cache.known_for("venice-uncensored").is_empty());
+
+        cache.record("venice-uncensored", "prompt_cache_retention");
+        cache.record("venice-uncensored", "reasoning_effort");
+
+        let known = cache.known_for("venice-uncensored");
+        assert!(known.contains("prompt_cache_retention"));
+        assert!(known.contains("reasoning_effort"));
+
+        // A rejection learned for one model must not leak to another.
+        assert!(cache.known_for("kimi-k2-5").is_empty());
+    }
+
+    #[test]
+    fn shared_for_survives_controller_rebuild_and_isolates_deployments() {
+        // Distinct, test-only base URLs so the process-global registry can't collide with another
+        // test running in parallel.
+        let url_a = "https://shared-for-test-a.invalid/api/v1";
+        let url_b = "https://shared-for-test-b.invalid/api/v1";
+
+        // A controller rebuilt for the same deployment (a fresh `shared_for` call, as happens per
+        // message for dynamic agents) re-attaches to the SAME cache, so an earlier learning holds.
+        let first = UnsupportedFieldsCache::shared_for(url_a);
+        first.record("model-x", "reasoning_effort");
+
+        let rebuilt = UnsupportedFieldsCache::shared_for(url_a);
+        assert!(
+            rebuilt.known_for("model-x").contains("reasoning_effort"),
+            "a rebuilt controller for the same deployment must see the earlier rejection"
+        );
+
+        // A different deployment keeps its own learnings: a model name that rejects a field on one
+        // Venice must not silence/strip it on another.
+        let other_deployment = UnsupportedFieldsCache::shared_for(url_b);
+        assert!(
+            other_deployment.known_for("model-x").is_empty(),
+            "rejections must not leak across deployments"
+        );
+    }
+
+    #[test]
+    fn extracts_a_human_message_from_error_envelopes() {
+        assert_eq!(
+            extract_error_message(r#"{"error":"Extra inputs are not permitted","request_id":"x"}"#),
+            "Extra inputs are not permitted"
+        );
+
+        // OpenAI-style nested envelope.
+        assert_eq!(
+            extract_error_message(r#"{"error":{"message":"context length exceeded"}}"#),
+            "context length exceeded"
+        );
+
+        // Unknown shape falls back to the raw body; empty falls back to a fixed string.
+        assert_eq!(
+            extract_error_message("plain text failure"),
+            "plain text failure"
+        );
+        assert_eq!(extract_error_message("   "), "no response body");
+    }
+}

src/agent/provider/venice/tests.rs

@@ -0,0 +1,549 @@
+use mxlink::matrix_sdk::ruma::OwnedMxcUri;
+use mxlink::matrix_sdk::ruma::events::room::message::{
+    FileMessageEventContent, ImageMessageEventContent,
+};
+use mxlink::mime;
+
+use super::super::ControllerTrait;
+use crate::agent::AgentPurpose;
+use crate::conversation::llm::{
+    Author as LLMAuthor, FileDetails, ImageDetails, Message as LLMMessage,
+    MessageContent as LLMMessageContent,
+};
+
+use super::chat::{append_reasoning, derive_prompt_cache_key, render_with_citations};
+use super::config::{Config, TextGenerationConfig, VeniceParameters, WebSearchMode};
+use super::controller::Controller;
+use super::utils::convert_llm_messages_to_venice;
+use super::wire::{
+    ChatCompletionRequest, ContentPart, EditImageRequest, GenerateImageRequest, MessageContent,
+    SpeechRequest, WebSearchCitation,
+};
+
+#[test]
+fn config_round_trips_with_venice_parameters() {
+    let yaml = r#"
+base_url: https://api.venice.ai/api/v1
+api_key: test-key
+text_generation:
+  model_id: kimi-k2-5
+  temperature: 0.7
+  max_response_tokens: 1024
+  max_context_tokens: 65536
+  venice_parameters:
+    enable_web_search: "auto"
+    enable_web_citations: true
+speech_to_text:
+  model_id: nvidia/parakeet-tdt-0.6b-v3
+"#;
+
+    let config: Config = serde_yaml_ng::from_str(yaml).expect("config should deserialize");
+
+    let tg = config.text_generation.expect("text_generation present");
+    let vp = tg.venice_parameters.expect("venice_parameters present");
+
+    assert!(matches!(vp.enable_web_search, Some(WebSearchMode::Auto)));
+    assert_eq!(vp.enable_web_citations, Some(true));
+    assert_eq!(vp.character_slug, None);
+
+    // The bag must serialize the enum to the exact wire string, and an unset knob must be ABSENT
+    // (not `null`) so the strict `additionalProperties: false` body is honored.
+    let json = serde_json::to_string(&vp).expect("serialize venice_parameters");
+    assert!(
+        json.contains("\"enable_web_search\":\"auto\""),
+        "web search should be the literal \"auto\": {json}"
+    );
+    assert!(
+        !json.contains("character_slug"),
+        "an unset knob must be omitted entirely: {json}"
+    );
+    assert!(
+        !json.contains("null"),
+        "no nulls belong in the body: {json}"
+    );
+}
+
+#[test]
+fn converts_text_image_and_file_to_content_parts() {
+    let messages = vec![
+        LLMMessage {
+            author: LLMAuthor::User,
+            sender_id: None,
+            timestamp: chrono::Utc::now(),
+            content: LLMMessageContent::Text("describe this".to_owned()),
+        },
+        LLMMessage {
+            author: LLMAuthor::User,
+            sender_id: None,
+            timestamp: chrono::Utc::now(),
+            content: LLMMessageContent::Image(ImageDetails::new(
+                ImageMessageEventContent::plain(
+                    "pic.png".to_owned(),
+                    OwnedMxcUri::from("mxc://example.com/abc"),
+                ),
+                mime::IMAGE_PNG,
+                vec![1, 2, 3],
+            )),
+        },
+        LLMMessage {
+            author: LLMAuthor::User,
+            sender_id: None,
+            timestamp: chrono::Utc::now(),
+            content: LLMMessageContent::File(FileDetails::new(
+                FileMessageEventContent::plain(
+                    "doc.pdf".to_owned(),
+                    OwnedMxcUri::from("mxc://example.com/def"),
+                ),
+                mime::APPLICATION_PDF,
+                vec![4, 5, 6],
+            )),
+        },
+    ];
+
+    let converted = convert_llm_messages_to_venice(messages).expect("conversion should succeed");
+
+    // Text, image, AND file all survive now: the file is no longer warn-skipped.
+    assert_eq!(converted.len(), 3);
+
+    match &converted[0].content {
+        MessageContent::Text(text) => assert_eq!(text, "describe this"),
+        other => panic!("expected bare text, got {other:?}"),
+    }
+
+    match &converted[1].content {
+        MessageContent::Parts(parts) => match &parts[0] {
+            ContentPart::ImageUrl { image_url } => assert!(
+                image_url.url.starts_with("data:image/png;base64,"),
+                "image should be inlined as a data URI: {}",
+                image_url.url
+            ),
+            other => panic!("expected an image part, got {other:?}"),
+        },
+        other => panic!("expected image parts, got {other:?}"),
+    }
+
+    match &converted[2].content {
+        MessageContent::Parts(parts) => match &parts[0] {
+            ContentPart::File { file } => {
+                assert!(
+                    file.file_data.starts_with("data:application/pdf;base64,"),
+                    "file should be inlined as a data URI: {}",
+                    file.file_data
+                );
+                assert_eq!(file.filename.as_deref(), Some("doc.pdf"));
+            }
+            other => panic!("expected a file part, got {other:?}"),
+        },
+        other => panic!("expected file parts, got {other:?}"),
+    }
+}
+
+#[test]
+fn supports_purpose_truth_table() {
+    let config: Config = serde_yaml_ng::from_str(
+        r#"
+base_url: https://api.venice.ai/api/v1
+api_key: test-key
+text_generation:
+  model_id: kimi-k2-5
+speech_to_text:
+  model_id: nvidia/parakeet-tdt-0.6b-v3
+"#,
+    )
+    .expect("config should deserialize");
+
+    let controller = Controller::new(config);
+
+    assert!(controller.supports_purpose(AgentPurpose::TextGeneration));
+    assert!(controller.supports_purpose(AgentPurpose::SpeechToText));
+    assert!(controller.supports_purpose(AgentPurpose::CatchAll));
+    assert!(!controller.supports_purpose(AgentPurpose::TextToSpeech));
+    assert!(!controller.supports_purpose(AgentPurpose::ImageGeneration));
+}
+
+#[test]
+fn supports_purpose_true_when_image_and_tts_blocks_present() {
+    let config: Config = serde_yaml_ng::from_str(
+        r#"
+base_url: https://api.venice.ai/api/v1
+api_key: test-key
+text_to_speech:
+  model_id: tts-kokoro
+image_generation:
+  model_id: chroma
+"#,
+    )
+    .expect("config should deserialize");
+
+    let controller = Controller::new(config);
+
+    assert!(controller.supports_purpose(AgentPurpose::TextToSpeech));
+    assert!(controller.supports_purpose(AgentPurpose::ImageGeneration));
+}
+
+#[test]
+fn speech_request_serializes_voice_and_omits_unset() {
+    let request = SpeechRequest {
+        model: "tts-kokoro".to_owned(),
+        input: "hello".to_owned(),
+        voice: Some("af_sky".to_owned()),
+        speed: None,
+        response_format: Some("mp3".to_owned()),
+        prompt: None,
+        temperature: None,
+        top_p: None,
+    };
+
+    let json = serde_json::to_string(&request).expect("serialize SpeechRequest");
+
+    assert!(
+        json.contains("\"voice\":\"af_sky\""),
+        "voice should be present: {json}"
+    );
+    assert!(
+        !json.contains("temperature"),
+        "an unset knob must be omitted (not null): {json}"
+    );
+    assert!(
+        !json.contains("null"),
+        "no nulls belong in the body: {json}"
+    );
+}
+
+#[test]
+fn generate_image_request_pins_flags_and_omits_unset() {
+    let request = GenerateImageRequest {
+        model: "chroma".to_owned(),
+        prompt: "a cat".to_owned(),
+        return_binary: false,
+        variants: 1,
+        negative_prompt: None,
+        cfg_scale: None,
+        steps: None,
+        style_preset: None,
+        seed: None,
+        safe_mode: None,
+        hide_watermark: None,
+        format: None,
+        width: None,
+        height: None,
+        aspect_ratio: None,
+        resolution: None,
+        quality: None,
+        lora_strength: None,
+        embed_exif_metadata: None,
+        enable_web_search: None,
+    };
+
+    let json = serde_json::to_string(&request).expect("serialize GenerateImageRequest");
+
+    assert!(json.contains("\"model\":\"chroma\""), "{json}");
+    assert!(
+        json.contains("\"return_binary\":false"),
+        "return_binary must be pinned false: {json}"
+    );
+    assert!(
+        json.contains("\"variants\":1"),
+        "variants must be pinned 1: {json}"
+    );
+    assert!(
+        !json.contains("cfg_scale"),
+        "an unset knob must be omitted: {json}"
+    );
+    assert!(
+        !json.contains("null"),
+        "no nulls belong in the body: {json}"
+    );
+}
+
+#[test]
+fn edit_image_request_carries_model_and_base64_image() {
+    let request = EditImageRequest {
+        model: "firered-image-edit".to_owned(),
+        prompt: "make it a sunrise".to_owned(),
+        image: "aGVsbG8=".to_owned(),
+        output_format: None,
+        aspect_ratio: None,
+        resolution: None,
+        safe_mode: None,
+    };
+
+    let json = serde_json::to_string(&request).expect("serialize EditImageRequest");
+
+    assert!(json.contains("\"model\":\"firered-image-edit\""), "{json}");
+    assert!(
+        json.contains("\"image\":\"aGVsbG8=\""),
+        "the base64 image string must be present: {json}"
+    );
+    assert!(
+        !json.contains("output_format"),
+        "an unset knob must be omitted: {json}"
+    );
+}
+
+#[test]
+fn web_search_mode_off_deserializes_from_bare_yaml_off() {
+    // `off` is a YAML-1.1 boolean but a plain string under serde_yaml_ng's YAML-1.2 core schema,
+    // so it deserializes straight into the lowercase `WebSearchMode::Off`. This pins that the
+    // sample config and docs can use the bare, unquoted `off` without it parsing as a boolean.
+    let params: VeniceParameters =
+        serde_yaml_ng::from_str("enable_web_search: off").expect("bare `off` should deserialize");
+
+    assert!(matches!(params.enable_web_search, Some(WebSearchMode::Off)));
+}
+
+#[test]
+fn request_places_sampling_top_level_and_verbosity_in_the_bag() {
+    // The whole config-shape decision in one assertion: top-level knobs serialize at the top
+    // level, the dual-position `verbosity` serializes inside the bag. Venice silently ignores a
+    // top-level knob misplaced into the bag, so this is the guard against a silent no-op.
+    let request = ChatCompletionRequest {
+        model: "kimi-k2-5".to_owned(),
+        messages: vec![],
+        temperature: Some(0.5),
+        max_completion_tokens: Some(1024),
+        top_p: Some(0.5),
+        frequency_penalty: None,
+        presence_penalty: None,
+        repetition_penalty: None,
+        reasoning_effort: Some("high".to_owned()),
+        prompt_cache_key: Some("00000000cafef00d".to_owned()),
+        prompt_cache_retention: Some("24h".to_owned()),
+        venice_parameters: Some(VeniceParameters {
+            verbosity: Some("high".to_owned()),
+            ..Default::default()
+        }),
+    };
+
+    let json = serde_json::to_value(&request).expect("serialize request");
+
+    assert_eq!(json["top_p"], 0.5);
+    assert_eq!(json["reasoning_effort"], "high");
+    assert_eq!(json["prompt_cache_retention"], "24h");
+    assert_eq!(json["prompt_cache_key"], "00000000cafef00d");
+
+    assert!(
+        json.get("verbosity").is_none(),
+        "verbosity must not be a top-level field: {json}"
+    );
+    assert_eq!(json["venice_parameters"]["verbosity"], "high");
+    assert!(
+        json["venice_parameters"].get("top_p").is_none(),
+        "top_p must not be inside the bag: {json}"
+    );
+}
+
+#[test]
+fn config_defaults_prompt_cache_retention_to_24h() {
+    // The programmatic default.
+    assert_eq!(
+        TextGenerationConfig::default()
+            .prompt_cache_retention
+            .as_deref(),
+        Some("24h")
+    );
+
+    // A config that omits the key must ALSO default to 24h, via the named serde default. A bare
+    // `#[serde(default)]` would yield None here and silently disable caching for such configs.
+    let tg: TextGenerationConfig = serde_yaml_ng::from_str("model_id: kimi-k2-5\n")
+        .expect("minimal config should deserialize");
+    assert_eq!(
+        tg.prompt_cache_retention.as_deref(),
+        Some("24h"),
+        "an omitted retention key must still default to 24h"
+    );
+}
+
+#[test]
+fn cache_key_is_stable_for_same_inputs_and_varies_otherwise() {
+    let key = derive_prompt_cache_key("system prompt", "2024-09-20 (Friday), 18:34:15 UTC");
+
+    // Identical inputs produce an identical key: this is what keeps turn 5 routing to the warm
+    // server holding turns 1-4 (and what survives a process restart).
+    assert_eq!(
+        key,
+        derive_prompt_cache_key("system prompt", "2024-09-20 (Friday), 18:34:15 UTC"),
+        "identical inputs must produce an identical key"
+    );
+    assert_eq!(key.len(), 16, "the key is a 16-char hex string");
+    assert!(key.chars().all(|c| c.is_ascii_hexdigit()));
+
+    // A different conversation start time or a different prompt must change the key.
+    assert_ne!(
+        key,
+        derive_prompt_cache_key("system prompt", "2024-09-21 (Saturday), 09:00:00 UTC"),
+        "a different start time must change the key"
+    );
+    assert_ne!(
+        key,
+        derive_prompt_cache_key("other prompt", "2024-09-20 (Friday), 18:34:15 UTC"),
+        "a different prompt must change the key"
+    );
+}
+
+#[test]
+fn citations_render_inline_refs_and_a_sources_block() {
+    let citations = vec![WebSearchCitation {
+        title: "Example Source".to_owned(),
+        url: "https://example.com/a".to_owned(),
+    }];
+
+    let rendered = render_with_citations("the sky is blue^1^".to_owned(), &citations);
+
+    assert!(
+        rendered.contains("the sky is blue[1]"),
+        "inline ^1^ becomes [1]: {rendered}"
+    );
+    assert!(
+        rendered.contains("Sources:"),
+        "a Sources block is appended: {rendered}"
+    );
+    assert!(
+        rendered.contains("[1] [Example Source](https://example.com/a)"),
+        "the source renders as a markdown link: {rendered}"
+    );
+}
+
+#[test]
+fn citations_absent_leaves_content_untouched() {
+    let content = "plain answer, no web search".to_owned();
+    assert_eq!(render_with_citations(content.clone(), &[]), content);
+}
+
+#[test]
+fn citation_title_and_url_cannot_inject_markdown() {
+    // A hostile page sets its title to break out of the link label and its URL to a non-http
+    // scheme. Neither may produce a spoofed clickable link in the room.
+    let citations = vec![WebSearchCitation {
+        title: "evil](http://phish.example) take".to_owned(),
+        url: "javascript:alert(1)".to_owned(),
+    }];
+
+    let rendered = render_with_citations("result^1^".to_owned(), &citations);
+
+    assert!(
+        rendered.contains("evil\\](http://phish.example) take"),
+        "the title's brackets must be escaped so it cannot close the link label: {rendered}"
+    );
+    assert!(
+        !rendered.contains("(javascript:alert(1))"),
+        "a non-http(s) URL must never become a markdown link target: {rendered}"
+    );
+}
+
+#[test]
+fn chained_and_comma_citation_runs_each_expand_to_separate_refs() {
+    let citations = vec![
+        WebSearchCitation {
+            title: "One".to_owned(),
+            url: "https://example.com/1".to_owned(),
+        },
+        WebSearchCitation {
+            title: "Two".to_owned(),
+            url: "https://example.com/2".to_owned(),
+        },
+        WebSearchCitation {
+            title: "Three".to_owned(),
+            url: "https://example.com/3".to_owned(),
+        },
+    ];
+
+    // Caret-chained run: Venice shares the caret between consecutive citations (`^2^3^`). The whole
+    // run must expand, not just the first, with no orphaned `3^` left behind.
+    let chained = render_with_citations("alpha^2^3^ and beta^1^".to_owned(), &citations);
+    assert!(
+        chained.contains("alpha[2][3] and beta[1]"),
+        "a chained ^2^3^ run must expand to [2][3] with no orphaned caret: {chained}"
+    );
+
+    // Comma run.
+    let comma = render_with_citations("gamma^1,3^".to_owned(), &citations);
+    assert!(
+        comma.contains("gamma[1][3]"),
+        "a comma ^1,3^ run must expand to [1][3]: {comma}"
+    );
+
+    // Multi-digit citation indices survive intact.
+    let multidigit = render_with_citations("delta^2^10^".to_owned(), &citations);
+    assert!(
+        multidigit.contains("delta[2][10]"),
+        "a multi-digit chained run must expand to [2][10]: {multidigit}"
+    );
+}
+
+#[test]
+fn malformed_citation_degrades_instead_of_failing() {
+    // A citation arriving without a `url` must still deserialize (to an empty default) rather than
+    // failing the whole response parse and losing an otherwise-good answer.
+    let parsed: WebSearchCitation = serde_json::from_str(r#"{"title":"Only a title"}"#)
+        .expect("a citation missing `url` should still deserialize");
+    assert_eq!(parsed.url, "");
+
+    // Rendering citations with missing fields stays graceful: no empty `[]()` link, no panic.
+    let citations = vec![
+        WebSearchCitation {
+            title: String::new(),
+            url: "https://example.com/u".to_owned(),
+        },
+        WebSearchCitation {
+            title: String::new(),
+            url: String::new(),
+        },
+    ];
+    let rendered = render_with_citations("answer^1^2^".to_owned(), &citations);
+    assert!(
+        rendered.contains("[1] [https://example.com/u](https://example.com/u)"),
+        "a citation with no title falls back to the URL as link text: {rendered}"
+    );
+    assert!(
+        rendered.contains("[2] (source unavailable)"),
+        "a citation with neither title nor URL renders a placeholder: {rendered}"
+    );
+}
+
+#[test]
+fn reasoning_is_appended_only_when_show_reasoning_is_set() {
+    let base = "the answer".to_owned();
+
+    // Off (the default): thinking is dropped, never reaching the room.
+    let off = append_reasoning(base.clone(), Some("secret thinking".to_owned()), false);
+    assert_eq!(off, "the answer");
+
+    // On: thinking is appended below the answer in a collapsible <details> block (folded by
+    // default, expandable in clients that support it).
+    let on = append_reasoning(base.clone(), Some("  visible thinking  ".to_owned()), true);
+    assert!(on.starts_with("the answer"));
+    assert!(on.contains("<details><summary>💭 Reasoning</summary>"));
+    assert!(on.contains("</details>"));
+    // The reasoning sits as its own markdown block (blank lines around it) and is trimmed.
+    assert!(on.contains("\n\nvisible thinking\n\n"));
+
+    // On but empty or missing reasoning: nothing is appended.
+    assert_eq!(
+        append_reasoning(base.clone(), Some("   ".to_owned()), true),
+        "the answer"
+    );
+    assert_eq!(append_reasoning(base.clone(), None, true), "the answer");
+}
+
+#[test]
+fn oversized_file_is_rejected() {
+    let messages = vec![LLMMessage {
+        author: LLMAuthor::User,
+        sender_id: None,
+        timestamp: chrono::Utc::now(),
+        content: LLMMessageContent::File(FileDetails::new(
+            FileMessageEventContent::plain(
+                "big.pdf".to_owned(),
+                OwnedMxcUri::from("mxc://example.com/big"),
+            ),
+            mime::APPLICATION_PDF,
+            vec![0u8; 25 * 1024 * 1024 + 1],
+        )),
+    }];
+
+    assert!(
+        convert_llm_messages_to_venice(messages).is_err(),
+        "a file over the 25MB limit must be rejected"
+    );
+}

src/agent/provider/venice/utils.rs

@@ -0,0 +1,81 @@
+use crate::conversation::llm::{
+    Author as LLMAuthor, Message as LLMMessage, MessageContent as LLMMessageContent,
+};
+use crate::utils::base64::base64_encode;
+
+use super::wire::{ChatMessage, ContentPart, FilePart, ImageUrl, MessageContent};
+
+/// Venice's documented file-input ceiling is 25MB on the decoded bytes (swagger `file_data`).
+/// We check it here so an oversized file gets a clear message instead of an opaque 413 from the
+/// API; the 413 status branch in `chat.rs` is the backstop if a file slips past this guard.
+const MAX_FILE_BYTES: usize = 25 * 1024 * 1024;
+
+pub fn convert_llm_messages_to_venice(
+    messages: Vec<LLMMessage>,
+) -> anyhow::Result<Vec<ChatMessage>> {
+    let mut venice_messages: Vec<ChatMessage> = Vec::with_capacity(messages.len());
+
+    for message in messages {
+        venice_messages.push(convert_llm_message_to_venice(message)?);
+    }
+
+    Ok(venice_messages)
+}
+
+fn convert_llm_message_to_venice(message: LLMMessage) -> anyhow::Result<ChatMessage> {
+    let role = match message.author {
+        LLMAuthor::Prompt => "system",
+        LLMAuthor::Assistant => "assistant",
+        LLMAuthor::User => "user",
+    };
+
+    match message.content {
+        LLMMessageContent::Text(text) => Ok(ChatMessage {
+            role: role.to_owned(),
+            content: MessageContent::Text(text),
+        }),
+        LLMMessageContent::Image(image_details) => {
+            // Inline the image as a base64 data URI, the same shape the OpenAI vision content
+            // part uses. This is the gap the openai_compat provider can't fill (it drops images).
+            let data_uri = format!(
+                "data:{};base64,{}",
+                image_details.mime,
+                base64_encode(&image_details.data)
+            );
+
+            Ok(ChatMessage {
+                role: role.to_owned(),
+                content: MessageContent::Parts(vec![ContentPart::ImageUrl {
+                    image_url: ImageUrl { url: data_uri },
+                }]),
+            })
+        }
+        LLMMessageContent::File(file_details) => {
+            // Inline the file as a base64 data URI in a `file` content part. This is the input
+            // type the openai_compat provider drops; baibot already extracts the bytes upstream.
+            // The message reaches the room, so it carries no user-controlled filename: a crafted
+            // name could otherwise inject markdown (a spoofed link) into the bot's reply.
+            if file_details.data.len() > MAX_FILE_BYTES {
+                return Err(anyhow::anyhow!(
+                    "The attached file is too large for Venice (the limit is 25MB)."
+                ));
+            }
+
+            let data_uri = format!(
+                "data:{};base64,{}",
+                file_details.mime,
+                base64_encode(&file_details.data)
+            );
+
+            Ok(ChatMessage {
+                role: role.to_owned(),
+                content: MessageContent::Parts(vec![ContentPart::File {
+                    file: FilePart {
+                        file_data: data_uri,
+                        filename: Some(file_details.filename()),
+                    },
+                }]),
+            })
+        }
+    }
+}

src/agent/provider/venice/wire.rs

@@ -0,0 +1,273 @@
+//! Serde structs modeling Venice's `/chat/completions`, `/audio/transcriptions`,
+//! `/audio/speech`, `/image/generate`, and `/image/edit` wire shapes. Request types are
+//! `Serialize`-only (we build them, Venice never sends them back); response types are
+//! `Deserialize`-only. Keeping the split means the untagged request content enum is never on a
+//! deserialize path, so a surprise response shape can't fail to match it.
+//!
+//! Field names match Venice's schema 1:1 (so the config's `model_id` becomes `model` here). Every
+//! request body is `additionalProperties: false`, so optional knobs carry `skip_serializing_if`
+//! to omit rather than send `null`. `/audio/speech` and `/image/edit` return raw binary (no
+//! response struct); only `/image/generate` returns JSON (`GenerateImageResponse`).
+
+use serde::{Deserialize, Serialize};
+
+use super::config::VeniceParameters;
+
+#[derive(Debug, Serialize)]
+pub struct ChatCompletionRequest {
+    pub model: String,
+
+    pub messages: Vec<ChatMessage>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<f32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_completion_tokens: Option<u32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub top_p: Option<f32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub frequency_penalty: Option<f32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub presence_penalty: Option<f32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub repetition_penalty: Option<f32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub reasoning_effort: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_key: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_retention: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub venice_parameters: Option<VeniceParameters>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ChatMessage {
+    pub role: String,
+
+    pub content: MessageContent,
+}
+
+/// A message body is either a bare string or a list of content parts. Venice accepts both; we
+/// send the parts form when a message carries an image or a file (baibot keeps text, images, and
+/// files in separate messages, so a parts list holds a single image part or file part).
+#[derive(Debug, Serialize)]
+#[serde(untagged)]
+pub enum MessageContent {
+    Text(String),
+    Parts(Vec<ContentPart>),
+}
+
+#[derive(Debug, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ContentPart {
+    ImageUrl { image_url: ImageUrl },
+    File { file: FilePart },
+}
+
+#[derive(Debug, Serialize)]
+pub struct ImageUrl {
+    /// A `data:<mime>;base64,<data>` URI for inline images.
+    pub url: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct FilePart {
+    /// A `data:<mime>;base64,<data>` URI carrying the file bytes inline.
+    pub file_data: String,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub filename: Option<String>,
+}
+
+/// Standard OpenAI-shaped chat completion response. We read `choices[0].message.content` and,
+/// when web search is on, the structured `venice_parameters.web_search_citations` (requested via
+/// `return_search_results_as_documents`) to rewrite the inline `^n^` superscripts into readable
+/// `[n]` references plus a `Sources:` block. `reasoning_content` carries the model's thinking when
+/// the model exposes it; it is appended only when `show_reasoning` is set.
+#[derive(Debug, Deserialize)]
+pub struct ChatCompletionResponse {
+    pub choices: Vec<ChatChoice>,
+
+    #[serde(default)]
+    pub venice_parameters: Option<ResponseVeniceParameters>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ChatChoice {
+    pub message: ResponseMessage,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ResponseMessage {
+    #[serde(default)]
+    pub content: Option<String>,
+
+    #[serde(default)]
+    pub reasoning_content: Option<String>,
+}
+
+/// The `venice_parameters` envelope on a chat-completion *response*, distinct from the request-side
+/// `VeniceParameters` bag. Only the citation list is read; other response-side fields are ignored.
+#[derive(Debug, Deserialize, Default)]
+pub struct ResponseVeniceParameters {
+    #[serde(default)]
+    pub web_search_citations: Vec<WebSearchCitation>,
+}
+
+/// Only the `title` and `url` are read (for rendering the `Sources:` block). Venice also returns
+/// `content` and `date` per citation; serde drops them, the same way the response structs above
+/// ignore the response fields baibot does not use. Both fields default to empty so a single
+/// citation that arrives without one (schema drift on scraped results) degrades gracefully in the
+/// rendered list instead of failing the whole response deserialization.
+#[derive(Debug, Deserialize)]
+pub struct WebSearchCitation {
+    #[serde(default)]
+    pub title: String,
+
+    #[serde(default)]
+    pub url: String,
+}
+
+/// `/audio/transcriptions` response. We read `text`; the optional `duration`/`timestamps` the
+/// API can return are not used in v1.
+#[derive(Debug, Deserialize)]
+pub struct TranscriptionResponse {
+    pub text: String,
+}
+
+/// `/audio/speech` (`CreateSpeechRequestSchema`) request. `input` and `model` are always sent;
+/// the rest are omitted when unset. The response is raw binary audio, so there is no response
+/// struct.
+#[derive(Debug, Serialize)]
+pub struct SpeechRequest {
+    pub model: String,
+
+    pub input: String,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub voice: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub speed: Option<f32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub response_format: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub prompt: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<f32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub top_p: Option<f32>,
+}
+
+/// `/image/generate` (`GenerateImageRequest`) request. `return_binary` is pinned `false` and
+/// `variants` to `1` by the builder: baibot wants exactly one image returned as base64-in-JSON,
+/// which `GenerateImageResponse` then decodes. Flipping `return_binary` would make Venice answer
+/// with raw binary and break that JSON decode, so it is not configurable.
+#[derive(Debug, Serialize)]
+pub struct GenerateImageRequest {
+    pub model: String,
+
+    pub prompt: String,
+
+    pub return_binary: bool,
+
+    pub variants: u32,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub negative_prompt: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cfg_scale: Option<f32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub steps: Option<u32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub style_preset: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub seed: Option<i64>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub safe_mode: Option<bool>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub hide_watermark: Option<bool>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub format: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub width: Option<u32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub height: Option<u32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub aspect_ratio: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub resolution: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub quality: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub lora_strength: Option<u32>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub embed_exif_metadata: Option<bool>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enable_web_search: Option<bool>,
+}
+
+/// `/image/generate` response when `return_binary` is false: a JSON envelope carrying the images
+/// as base64 strings. We read `images[0]`; `request`/`timing` and other fields are ignored. `id`
+/// is telemetry only (logged, never used for correctness), so it is optional: a response that
+/// carries usable `images` must not fail to deserialize just because the telemetry field drifted.
+#[derive(Debug, Deserialize)]
+pub struct GenerateImageResponse {
+    #[serde(default)]
+    pub id: Option<String>,
+    pub images: Vec<String>,
+}
+
+/// `/image/edit` (`EditImageRequest`) request. The source `image` is a base64-encoded string
+/// (Venice's `image` field is `anyOf` upload/base64/URL; we send base64-in-JSON, no multipart).
+/// The response is raw binary, so there is no response struct.
+#[derive(Debug, Serialize)]
+pub struct EditImageRequest {
+    pub model: String,
+
+    pub prompt: String,
+
+    /// Base64-encoded source image bytes.
+    pub image: String,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub output_format: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub aspect_ratio: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub resolution: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub safe_mode: Option<bool>,
+}

src/agent/utils.rs

@@ -1,5 +1,3 @@
-use base64::{engine::general_purpose::STANDARD, Engine as _};
-
 use crate::{
     agent::{
         AgentInstance, AgentPurpose, ControllerTrait, Manager as AgentManager, PublicIdentifier,
@@ -140,7 +138,3 @@ async fn get_global_agent_id_for_purpose(
         .handler
         .get_by_purpose_with_catch_all_fallback(purpose)
 }
-
-pub(crate) fn base64_decode(base64_string: &str) -> Result<Vec<u8>, base64::DecodeError> {
-    STANDARD.decode(base64_string)
-}

src/bot/implementation.rs

@@ -1,14 +1,17 @@
+use std::fs;
 use std::sync::Arc;
 use std::{future::Future, pin::Pin};
 
-use mxlink::matrix_sdk::media::{MediaFormat, MediaRequest};
-use mxlink::matrix_sdk::ruma::{
-    events::room::MediaSource, MilliSecondsSinceUnixEpoch, OwnedUserId,
-};
 use mxlink::matrix_sdk::Room;
+use mxlink::matrix_sdk::media::{MediaFormat, MediaRequestParameters};
+use mxlink::matrix_sdk::ruma::api::client::profile::{AvatarUrl, DisplayName};
+use mxlink::matrix_sdk::ruma::{
+    MilliSecondsSinceUnixEpoch, OwnedUserId, events::room::MediaSource,
+};
 
 use mxlink::{
     InitConfig, LoginConfig, LoginCredentials, LoginEncryption, MatrixLink, PersistenceConfig,
+    TypingNoticeGuard,
 };
 
 use mxlink::helpers::account_data_config::{
@@ -16,12 +19,13 @@ use mxlink::helpers::account_data_config::{
     RoomConfigManager as AccountDataRoomConfigManager,
 };
 use mxlink::helpers::encryption::Manager as EncryptionManager;
+use mxlink::mime::Mime;
 
 use crate::agent::Manager as AgentManager;
 use crate::entity::catch_up_marker::{
     CatchUpMarker, CatchUpMarkerManager, DelayedCatchUpMarkerManager,
 };
-use crate::entity::cfg::Config;
+use crate::entity::cfg::{Avatar, Config, ConfigUserAuth};
 use crate::entity::globalconfig::{GlobalConfig, GlobalConfigurationManager};
 use crate::entity::roomconfig::{RoomConfig, RoomConfigurationManager};
 
@@ -139,6 +143,10 @@ impl Bot {
         &self.inner.config.command_prefix
     }
 
+    pub(crate) fn post_join_self_introduction_enabled(&self) -> bool {
+        self.inner.config.room.post_join_self_introduction_enabled
+    }
+
     pub(crate) fn homeserver_name(&self) -> &str {
         &self.inner.config.homeserver.server_name
     }
@@ -171,6 +179,24 @@ impl Bot {
         self.matrix_link().user_id()
     }
 
+    pub(crate) async fn user_display_name_in_room(&self, room: &Room) -> Option<String> {
+        let bot_display_name = self
+            .room_display_name_fetcher()
+            .own_display_name_in_room(room)
+            .await;
+
+        match bot_display_name {
+            Ok(value) => value,
+            Err(err) => {
+                tracing::warn!(
+                    ?err,
+                    "Failed to fetch bot display name. Proceeding without it"
+                );
+                None
+            }
+        }
+    }
+
     pub(crate) fn reacting(&self) -> super::reacting::Reacting {
         super::reacting::Reacting::new(self.clone())
     }
@@ -210,6 +236,14 @@ impl Bot {
             .await
     }
 
+    pub(crate) async fn start_typing_notice(&self, room: &Room) -> TypingNoticeGuard {
+        self.inner
+            .matrix_link
+            .rooms()
+            .start_typing_notice(room)
+            .await
+    }
+
     pub async fn start(&self) -> anyhow::Result<()> {
         self.rooms().attach_event_handlers().await;
         self.messaging().attach_event_handlers().await;
@@ -254,24 +288,27 @@ impl Bot {
     async fn do_prepare_profile(&self) -> anyhow::Result<()> {
         tracing::debug!("Preparing profile..");
 
+        let desired_display_name = self.inner.config.user.name.clone();
+
         let account = self.inner.matrix_link.client().account();
         let media = self.inner.matrix_link.client().media();
 
-        let desired_display_name = self.inner.config.user.name.clone();
-
         let profile = account
-            .get_profile()
+            .fetch_user_profile()
             .await
             .map_err(|e| anyhow::anyhow!("Failed fetching profile: {:?}", e))?;
 
-        let should_update_display_name = match &profile.displayname {
+        let current_display_name = profile.get_static::<DisplayName>()?;
+        let current_avatar_url = profile.get_static::<AvatarUrl>()?;
+
+        let should_update_display_name = match &current_display_name {
             Some(displayname) => displayname != &desired_display_name,
             None => true,
         };
 
         if should_update_display_name {
             tracing::info!(
-                ?profile.displayname,
+                ?current_display_name,
                 ?desired_display_name,
                 "Updating display name.."
             );
@@ -281,34 +318,72 @@ impl Bot {
             }
         }
 
-        let should_update_avatar = match &profile.avatar_url {
-            Some(avatar_url) => {
-                let request = MediaRequest {
-                    source: MediaSource::Plain(avatar_url.to_owned()),
-                    format: MediaFormat::File,
-                };
-
-                let content = media
-                    .get_media_content(&request, true)
-                    .await
-                    .map_err(|e| anyhow::anyhow!("Failed fetching existing avatar: {:?}", e))?;
-
-                content.as_slice() != LOGO_BYTES
+        let desired_avatar: Option<(Vec<u8>, Mime)> = match &self.inner.config.user.avatar {
+            Avatar::Keep => {
+                tracing::info!("Avatar configured to keep current, skipping avatar management");
+                None
+            }
+            Avatar::Default => {
+                tracing::info!("Avatar configured to use default");
+                Some((
+                    LOGO_BYTES.to_vec(),
+                    LOGO_MIME_TYPE
+                        .parse()
+                        .expect("Failed parsing mime type for logo"),
+                ))
+            }
+            Avatar::Custom(avatar_path) => {
+                tracing::info!(?avatar_path, "Avatar configured to use custom path");
+                let bytes = fs::read(avatar_path).map_err(|e| {
+                    anyhow::anyhow!("Failed reading avatar from {:?}: {:?}", avatar_path, e)
+                })?;
+                let mime = mime_guess::from_path(avatar_path).first_or_octet_stream();
+                tracing::debug!(?mime, bytes_len = bytes.len(), "Loaded custom avatar");
+                Some((bytes, mime))
             }
-            None => true,
         };
 
-        if should_update_avatar {
-            tracing::info!("Updating avatar..");
+        if let Some((desired_bytes, mime_type)) = desired_avatar {
+            let should_update_avatar = match &current_avatar_url {
+                Some(avatar_url) => {
+                    tracing::debug!(?avatar_url, "Fetching current avatar to compare");
+                    let request = MediaRequestParameters {
+                        source: MediaSource::Plain(avatar_url.to_owned()),
+                        format: MediaFormat::File,
+                    };
 
-            let mime_type = LOGO_MIME_TYPE
-                .parse()
-                .expect("Failed parsing mime type for logo");
+                    let content = media
+                        .get_media_content(&request, true)
+                        .await
+                        .map_err(|e| anyhow::anyhow!("Failed fetching existing avatar: {:?}", e))?;
 
-            account
-                .upload_avatar(&mime_type, LOGO_BYTES.to_vec())
-                .await
-                .map_err(|e| anyhow::anyhow!("Failed uploading avatar: {:?}", e))?;
+                    let needs_update = content.as_slice() != desired_bytes;
+
+                    tracing::debug!(
+                        current_bytes_len = content.len(),
+                        desired_bytes_len = desired_bytes.len(),
+                        ?needs_update,
+                        "Compared current and desired avatar"
+                    );
+
+                    needs_update
+                }
+                None => {
+                    tracing::debug!("No current avatar set, will upload");
+                    true
+                }
+            };
+
+            if should_update_avatar {
+                tracing::info!("Updating avatar..");
+                account
+                    .upload_avatar(&mime_type, desired_bytes)
+                    .await
+                    .map_err(|e| anyhow::anyhow!("Failed uploading avatar: {:?}", e))?;
+                tracing::info!("Avatar updated successfully");
+            } else {
+                tracing::debug!("Avatar already up to date, skipping upload");
+            }
         }
 
         Ok(())
@@ -320,10 +395,22 @@ async fn create_matrix_link(config: &Config) -> anyhow::Result<MatrixLink> {
     let session_encryption_key = config.persistence.session_encryption_key()?;
     let db_dir_path: std::path::PathBuf = config.persistence.db_dir_path()?;
 
-    let login_creds = LoginCredentials::UserPassword(
-        config.user.mxid_localpart.to_owned(),
-        config.user.password.to_owned(),
-    );
+    let user_auth = config.user.auth_config(&config.homeserver.server_name)?;
+
+    let login_creds = match user_auth {
+        ConfigUserAuth::UserPassword { username, password } => {
+            LoginCredentials::UserPassword(username, password)
+        }
+        ConfigUserAuth::AccessToken {
+            user_id,
+            device_id,
+            access_token,
+        } => LoginCredentials::AccessToken {
+            user_id,
+            device_id,
+            access_token,
+        },
+    };
 
     let login_encryption = LoginEncryption::new(
         config.user.encryption.recovery_passphrase.clone(),