ollama_chat 0.0.121 → 0.0.123

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e457507428f39cb5f1641783d067f1424a1dca8908cc30e8331d05e141c68f2e
-  data.tar.gz: 9c14299158dec444c3debd7ba133678c04324a6985f26110ce779da37bdf295a
+  metadata.gz: f2d0c5676e03433f245a21795872a9d7bd64357306ec691de3012195b5403bef
+  data.tar.gz: 933dca2b53647c523b9849d958cc1625106c97500caf2814bc731458a0e683f4
 SHA512:
-  metadata.gz: eafc7e3075b48d10dc9ad7ac1654cdb5af4e2c7b235cf2ff4e8ad4240518c77afc02167689c831987b25c9ac07d68f2a758d6d85d9bc4a1bad4537decc01ef26
-  data.tar.gz: 9492a500da2006ef57212e0f1a68444e35d94be81ad2a5abbd041daf73d9a3087af9873d36264182c77a7b76d3825697eaea45189dd69b227178df569c558c23
+  metadata.gz: 4589b5f1cf689bb35bdf26c288e59f40b87ef926eaf7f91e187c3fa729958c9d042f784eb3bf9a4b6e64966c201312713c2e20607291c6aabc10d306cf4cf272
+  data.tar.gz: 19102c3d01a2ebb4bb14b8ea617b09a7e168d0175225024a490dc85e23b41ce3c7eba249d82cc671f5530da0090e945f8f6358d17ca7f6b7587a413002e27dc2

data/CHANGES.md

@@ -1,5 +1,216 @@
 # Changes
 
+## 2026-09-25 v0.0.123
+
+### Added
+
+*   README section 5 documenting `/conversation compact`: token-aware
+    keep-recent budget, safe & retryable behavior, visible before/after
+    metrics, and iterative re-compaction.
+*   Three-step context escalation ladder in the README: `/conversation
+    compact` first, then `/conversation report` + `/clear` + `/input path`
+    as the preferred second step, and `/conversation clean` as the emergency
+    exit.
+*   `execute_shell` tool to the Filesystem row in the README, noted as running
+    shell commands as a last resort.
+*   `execute_jira_twg` tool to the Web/External row in the README for running
+    Jira CLI queries via `twg`.
+*   `lookup_group` tool to the Knowledge row in the README for retrieving prior
+    conversation groups by UUID.
+*   Speech Services (ASR) section documenting `OLLAMA_CHAT_ASR_URL`,
+    `OLLAMA_CHAT_ASR_CONVERT_COMMAND`, and `OLLAMA_CHAT_ASR_MODEL`.
+*   Audio Playback section documenting `OLLAMA_CHAT_AUDIO_PLAYER_CONFIG`.
+*   Invidious (YouTube Proxy) section documenting `OLLAMA_CHAT_INVIDIOUS_URL`,
+    `OLLAMA_CHAT_INVIDIOUS_COMPANION_KEY`, and
+    `OLLAMA_CHAT_INVIDIOUS_CAPTION_LANGUAGES`.
+*   `markdown:` keyword argument (default `true`) to
+    `kramdown_markdown_remove`; when `false`, skips the `kramdown_ansi_parse`
+    step while still removing emoji, ANSI, and box-drawing characters.
+*   Explanatory comment block to `eval_template` in
+    `lib/ollama_chat/tools/execute_grep.rb` clarifying that the `cmd` config
+    value is a Ruby string template whose `#{...}` interpolations are resolved
+    against the method's local parameters via `eval`.
+*   `cleaned` string prefix in `save_conversation` so the `STDOUT`/`STDERR`
+    confirmation messages read "Saved cleaned conversation to…" when `clean:
+    true` is passed.
+*   "Cancelled." message when the user skips saving in conversation report and
+    summarize flows.
+
+### Changed
+
+*   Renamed `report_session` to `generate_conversation_report` to clarify it
+    only builds the report text.
+*   Reworked `report_conversation` to always display in the pager first, then
+    optionally save to a file; removed the `save:` keyword argument.
+*   Reworked `summarize_conversation` in `session_management.rb` to always
+    render via `use_pager` first, then optionally save via `ask_for_filename?`
+    and `should_overwrite?`.
+*   Removed the `save:` keyword argument from `summarize_conversation` and the
+    `-f` flag from the `/conversation` command dispatch in `commands.rb`.
+*   Tightened the `/conversation` regex from `(?:[sf]|c)` to `[sc]` and updated
+    the `options:` help text to drop `-f save`.
+*   Changed "Nothing to summarize!" and "Nothing to report!" output from
+    `STDERR` to `STDOUT`.
+*   `kramdown_markdown_remove` now strips `\p{Extended_Pictographic}` emoji
+    before any further processing, preventing TTS engines from vocalizing them.
+*   `kramdown_markdown_remove` in `lib/ollama_chat/kramdown_ansi.rb` now strips
+    Unicode box-drawing characters (`U+2500`..`U+257F`) that kramdown renders
+    as table borders, preventing TTS engines from stammering on them.
+*   Collapses resulting multi-space runs and strips leading/trailing whitespace
+    in `kramdown_markdown_remove`.
+*   Moved the `kramdown_markdown_remove` call from `flush_buffer` into
+    `enqueue_tts` in `lib/ollama_chat/tts.rb` so all enqueue paths are covered,
+    passing `markdown: @chat.markdown.on?`.
+*   `multipart_form_data` in `lib/ollama_chat/asr.rb` now returns a hash
+    containing only `headers:`, `expects:`, and `body:`, which are the actual
+    Excon request options, instead of merging `rest` (`model:`, `language:`)
+    into the returned options hash.
+*   Updated YARD documentation to reflect the new parameter and emoji stripping
+    behavior.
+*   Updated `spec/ollama_chat/asr_spec.rb` expectations from
+    `hash_including(model: ...)` / `hash_including(language: ...)` to
+    `hash_including(body: kind_of(String))` to match the new option shape.
+*   Updated `commands_spec.rb` to remove the obsolete `/conversation summarize
+    -f` and `/conversation report -f` specs and drop `save:` from expectations.
+*   Updated `session_management_spec.rb` for the new show-then-save flow,
+    `STDOUT` stream, and `Cancelled.` expectation.
+*   Updated the corresponding expectation in `conversation_spec.rb` to match
+    the new message text.
+*   Renamed former section 5 "Session Reports" to section 6 "Conversation
+    Reports" to match the actual command name.
+*   Updated Conversation Archiving section from `/session summarize` to
+    `/conversation summarize`, removed obsolete `-f` flag reference, and
+    described the show-then-save flow.
+
+### Fixed
+*   Fixed `TTS_URL` to `OLLAMA_CHAT_TTS_URL` to match the actual env var name
+    in `oc.rb`.
+*   Wrapped `@prefix` with `Regexp.quote()` in `RedisCache#unpre` to ensure the
+    prefix is always matched as a literal string.
+*   Fixed typos in height validation error message.
+
+### Removed
+*   `context_spook` from development dependencies in `Rakefile` and
+    `ollama_chat.gemspec`.
+*   The `-f` flag from the `/report` command in `commands.rb`.
+
+## 2026-09-25 v0.0.122
+
+## Features
+
+*   **Per-model thinking-state support**: Added support for per-model thinking
+    states via the `/api/show` endpoint.
+    *   Replaced the `THINK_MODE_STATES` constant with a `think_mode_states`
+        method that reads `@model_metadata&.thinking&.full?(:values)` to return
+        a per-model subset, falling back to the full superset for
+        pre-**0.34.3** Ollama or non-thinking models.
+    *   Added `normalize_think_state` helper to canonicalize boolean
+        (`true`/`false`) and string (`"low"`/`"high"`/`"max"`) thinking values.
+    *   Added `:thinking` field to `ModelMetadata` data class.
+    *   Implemented think-mode clamping in `use_model` to disable thinking for
+        non-thinking models or clamp to the model's default when the current
+        level is unavailable.
+    *   Converted `DatabaseStateSelector` `states`/`off` to support `Proc` via
+        `ask_and_send_or_self(:call, @chat)`.
+    *   Converted `think_mode` and `voices` selectors in
+        `setup_state_selectors` to lambda-based `states:`.
+    *   Added `Thinking` display line to `info_model`.
+*   **Invidious YouTube captions**: Added `OllamaChat::Invidious` to fetch
+    video metadata and transcripts from an Invidious companion instance.
+    *   Uses `POST /companion/youtubei/v1/player` for `videoDetails` and
+        `captionTracks`.
+    *   Selects the best caption track by priority-ordered language regexes.
+    *   Fetches timedtext XML and extracts `<text>` elements via `Nokogiri`,
+        decoding double-encoded HTML entities.
+    *   Returns a formatted markdown header + transcript as a text IO.
+*   **Unified HTTP handling**: Added `HTTPHandling#request_url_response` to
+    consolidate `Excon.new` call sites, merging `http_options` (SSL, proxy)
+    with caller-supplied options.
+    *   Updated `ASR.transcribe`, `TTS.voices`, `TTS#fetch_tts`,
+        `GenerateImage#post_url`, `GenerateImage#get_url`, `GetURL#execute`,
+        `Invidious.fetch_video_info`, and `SourceFetching#fetch_source` to
+        route through this method.
+    *   Extracted audio/video MIME regex into `HAS_AUDIO` constant shared by
+        `parse_source` and the `get_url` tool.
+    *   Split `Fetcher` `middlewares` into class-level `self.middlewares` and
+        instance delegate; added `RedirectFollower` to the default stack.
+    *   Added `middlewares:` to streaming `excon` requests in `fetcher.rb`.
+*   **One-shot voice notification**: Added `OllamaChat::Speaker` concern
+    providing `speak(text, background:)` and `cancel_speaking`.
+    *   `OllamaChat::TTS` and `OllamaChat::Say` now include
+        `OllamaChat::Speaker`.
+    *   Added `Chat#speak` facade to resolve the configured voice handler.
+    *   `Dialog#readline_prompt` and `Dialog#confirm?` now speak the prompt
+        with a 10-second delay.
+    *   `Tools::PatchFile` announces "You can review the patch for the file …
+        now!" before opening `vimdiff`.
+    *   `AudioPlayer#start` redirects `ffplay` stdout/stderr to `/dev/null`.
+*   **ASR transcription pipeline**: Added `OllamaChat::ASR` client for
+    audio/video transcription.
+    *   Uploads audio/video as multipart form-data to the audio.cpp
+        `/v1/audio/transcriptions` endpoint.
+    *   Converts video sources to 16 kHz mono PCM WAV via a configurable
+        `ffmpeg` command (`CONVERT_COMMAND`).
+    *   Added `OC::OLLAMA::CHAT::ASR` config module with `URL`,
+        `CONVERT_COMMAND`, and `MODEL` settings.
+    *   Extended `/input` command with `-l <language>` option.
+    *   Routed `audio/*`, `video/*`, and specific `application/` MIME types
+        into `parse_audio`.
+    *   Added `Fetcher::ResponseMetadata.as_text(text)` factory for synthetic
+        `text/plain` IO responses.
+    *   Replaced hardcoded timeouts in `lib/ollama_chat/tts.rb` with values
+        from `config.timeouts`.
+*   **Audio/Video support in `get_url`**: Added `language` parameter to the
+    `get_url` tool definition for optional transcription hints.
+    *   Pre-transcribes `audio/*` and `video/*` sources via `chat.parse_audio`
+        before content-type dispatch.
+    *   Threads `language:` kwarg into `chat.import_source`.
+*   **Prompt management enhancements**:
+    *   Added `reset_prompt_count` and `choose_and_reset_count` to
+        `lib/ollama_chat/prompt_management.rb`.
+    *   Added `/prompt reset count` command.
+    *   Added `count:` keyword argument to `choose_prompt` to increment
+        `metadata['use_count']`.
+    *   Changed `all_prompts` sort to `use_count` descending, falling back to
+        name for tie-breaking.
+    *   Added `-i` summary instruction flag to `/input` command to prompt for
+        an optional instruction.
+    *   Added `instruction` parameter to `get_url` summarizing, threading it
+        through `summarize_source` and `summarize`.
+*   **Config-driven default persona**: Added `persona.default_name` to
+    `default_config.yml`.
+    *   Updated `initial_persona_name` in `personae_management.rb` to fall back
+        to `config.persona&.default_name`.
+
+## Improvements
+
+*   **CI and Dependencies**:
+    *   Added `ffmpeg` to the CI Docker image.
+    *   Added `nokogiri ~> 1.0` dependency.
+    *   Bumped `tins ~> 1.58`.
+    *   Added `require 'ollama_chat/utils/utf8_converter'` in
+        `png_metadata_extractor.rb`.
+    *   Reorganized `require` statements in `lib/ollama_chat/utils.rb`
+        alphabetically.
+*   **Error Handling**:
+    *   In `lib/ollama_chat/asr.rb`, capture the return value of `system` to
+        detect missing executables and print a clear "not found in PATH"
+        message.
+    *   Extract executable name via `Shellwords.split(cmd).first` for error
+        messages.
+*   **Documentation**:
+    *   Updated `ollama_chat` description in README to be more concise and
+        user-focused.
+    *   Updated YARD in `session.rb`, `state_selectors.rb`, and
+        `think_control.rb` to reference `Chat#think_mode_states`.
+
+## Bug Fixes
+
+*   **Pager Spec**: Changed `expect(Tins::Terminal).to receive(:lines)` to
+    `allow(Tins::Terminal).to receive(:lines)` in
+    `spec/ollama_chat/message_list_spec.rb` and removed the `skip 'no tty'`
+    guard.
+
 ## 2026-09-18 v0.0.121
 
 * Added `**_kwargs` splat to `Say.voices` to prevent `ArgumentError` when the

data/README.md

@@ -2,8 +2,8 @@
 
 ## Description
 
-**ollama_chat** is a chat client, that can be used to connect to an ollama
-server and enter chat conversations with the LLMs provided by it.
+**ollama_chat** is a terminal chat client that connects to an Ollama
+server and lets you converse with the LLMs it provides.
 
 ## Documentation
 
@@ -62,7 +62,7 @@ The following environment variables can be used to configure behavior:
 - `OLLAMA_URL` - Base URL for Ollama server (default: `http://localhost:11434`)
 - `OLLAMA_HOST` - Base hostname for Ollama server (default: `localhost:11434`)
 - `OLLAMA_SEARXNG_URL` - SearxNG search endpoint URL
-- `TTS_URL` - Base URL for the [audio.cpp](https://github.com/0xshug0/audio.cpp) TTS server (default: `http://localhost:8880`)
+- `OLLAMA_CHAT_TTS_URL` - Base URL for the [audio.cpp](https://github.com/0xshug0/audio.cpp) TTS server (default: `http://localhost:8880`)
 
 #### Chat Settings
 - `OLLAMA_CHAT_MODEL` - Default model to use (e.g., `llama3.1`)
@@ -75,6 +75,19 @@ The following environment variables can be used to configure behavior:
 - `OLLAMA_CHAT_LOG_DATABASE` - Database log file path (default: `$XDG_STATE_HOME/database.log`)
 - `OLLAMA_CHAT_LOG_TAIL_LINES` - Max lines to retain in log files (default: `10000`)
 
+#### Speech Services (ASR)
+- `OLLAMA_CHAT_ASR_URL` - Base URL for the ASR (Speech-to-Text) service (default: `http://localhost:8880`)
+- `OLLAMA_CHAT_ASR_CONVERT_COMMAND` - Shell command template to convert video to 16 kHz mono PCM WAV; use `%{input}` / `%{output}` as placeholders (default: `ffmpeg -y -i %{input} -vn -acodec pcm_s16le -ar 16000 -ac 1 %{output}`)
+- `OLLAMA_CHAT_ASR_MODEL` - ASR model identifier (default: `qwen3-asr-1.7b`)
+
+#### Audio Playback
+- `OLLAMA_CHAT_AUDIO_PLAYER_CONFIG` - JSON object with `command`, `frequency`, `bits`, `pause` keys controlling the ffplay-based TTS audio player
+
+#### Invidious (YouTube Proxy)
+- `OLLAMA_CHAT_INVIDIOUS_URL` - Base URL for an Invidious instance
+- `OLLAMA_CHAT_INVIDIOUS_COMPANION_KEY` - Bearer token for the Invidious companion player API (required when `URL` is set)
+- `OLLAMA_CHAT_INVIDIOUS_CAPTION_LANGUAGES` - JSON array of language-code regexes for caption selection priority (default: `["\\Aen\\z","\\Aen-","\\Ade\\z","\\Ade-"]`)
+
 #### Tool Configuration
 - `OLLAMA_CHAT_TOOLS_TEST_RUNNER` - Configured test runner for `run_tests` (default: `rspec`)
 - `OLLAMA_CHAT_TOOLS_CTAGS_TOOL` - Path to the ctags tool
@@ -243,14 +256,57 @@ switch. The profile system allows you to manage "Live" vs "Saved" settings:
     "bake" those live settings into a permanent profile using `options from
     session`.
 
-#### 4. Conversation Archiving (`/session summarize`)
+#### 4. Conversation Archiving (`/conversation summarize`)
 
 Turn your long-form brainstorming sessions into structured documents. The
-`/session summarize` command can distill an entire conversation into a concise
-summary.
+`/conversation summarize` command distills an entire conversation into a
+concise summary, displayed in the pager first, then optionally saved.
 *   **Quick View**: Use `-s` for a one-sentence executive summary.
-*   **Archiving**: Use `-f <filename>` to dump the full summary directly into a
-    Markdown file, creating an automatic journal of your project's evolution.
+*   **Archiving**: After the summary is displayed, you are prompted for a
+    filename to save it as a Markdown file, creating an automatic journal
+    of your project's evolution.
+
+#### 5. Context Compaction (`/conversation compact`)
+
+Long sessions inevitably fill up the model's context window. The
+`/conversation compact` command summarizes older messages into a single
+compact summary while preserving recent exchanges, freeing up space for
+continued work.
+
+*   **Token-aware**: The keep-recent budget is derived from the active
+    model's context length, so it adapts automatically.
+*   **Safe & retryable**: If the LLM summarization fails, the message list
+    is left untouched and you can simply retry.
+*   **Visible metrics**: After compaction, a report shows summarized
+    message count, summary size, and context usage before/after.
+*   **Iterative**: Repeated compactions merge into the existing summary
+    rather than stacking multiple summary messages.
+
+Run it whenever context usage climbs into the red zone (visible in the
+runtime info gauge) — the model stays sharp and the conversation keeps
+flowing.
+
+If compaction alone isn't enough, a practical escalation ladder:
+
+1. **`/conversation compact`** — summarize old messages, keep recent tail.
+   Try this first; it's the least destructive.
+2. **`/conversation report`** → **`/clear`** → **`/input path
+    standup.md`** — generate a standup-style report, save it, clear
+    the messages, then feed the report back as context. Do this
+    before `clean`, because `clean` strips the tool output and
+    thinking that make a good report.
+3. **`/conversation clean`** — strips tool results, images, and
+    thinking content from all messages. More radical, but the
+    conversation structure and text remain intact. The emergency
+    exit: if context is so stuffed that even a report can't fit,
+    `clean` carves out enough room for anything to work again.
+
+#### 6. Conversation Reports (`/conversation report`)
+
+Generate a structured report from your conversation using configurable
+prompt templates. The report is displayed in the pager first, then
+optionally saved to a file. Particularly useful for daily standup summaries
+— run it at the end of the day and save the output for your team sync.
 
 ### Using a Persona
 
@@ -467,12 +523,12 @@ context, manipulate files, and retrieve external information.
 
 | Category | Tools | Description |
 | :--- | :--- | :--- |
-| **Filesystem** | `read_file`, `write_file`, `patch_file`, `delete_file`, `move_file`, `directory_structure`, `execute_grep` | Read, write, and search files within allowed directories. |
+| **Filesystem** | `read_file`, `write_file`, `patch_file`, `delete_file`, `move_file`, `directory_structure`, `execute_grep`, `execute_shell` | Read, write, and search files within allowed directories; run shell commands as a last resort. |
 | **Ruby/Dev** | `resolve_tag`, `execute_ri`, `gem_path_lookup`, `run_tests`, `eval_ruby` | Introspect Ruby code, check documentation, and run test suites. |
-| **Web/External** | `search_web`, `get_url`, `browse`, `get_rfc`, `get_cve`, `get_endoflife`, `get_ghr`, `get_jira_issue` | Access the internet, fetch specific URLs, and look up technical standards. |
+| **Web/External** | `search_web`, `get_url`, `browse`, `get_rfc`, `get_cve`, `get_endoflife`, `get_ghr`, `get_jira_issue`, `execute_jira_twg` | Access the internet, fetch specific URLs, and look up technical standards; run Jira CLI queries via `twg`. |
 | **System/Util** | `get_time`, `get_location`, `get_current_weather`, `generate_password`, `compute_bmi`, `roll_dice` | General utility functions for time, location, and simple calculations. |
 | **Editor/Clip** | `copy_to_clipboard`, `paste_from_clipboard`, `paste_into_editor`, `open_file_in_editor` | Bridge the gap between the chat and the system clipboard or editor. |
-| **Knowledge** | `search_knowledge`, `file_context` | Semantic search for specific snippets vs. broad retrieval of structured project context. |
+| **Knowledge** | `search_knowledge`, `file_context`, `lookup_group` | Semantic search for specific snippets, broad retrieval of structured project context, or retrieving prior message groups by UUID. |
 | **Multimodal** | `generate_image` | Generate images via a local ComfyUI server. |
 
 ***Note on Knowledge Tools**: Use `search_knowledge` for precise,

data/Rakefile

@@ -49,7 +49,7 @@ GemHadar do
   dependency             'reverse_markdown',      '~> 3.0'
   dependency             'kramdown-ansi',         '~> 0.5'
   dependency             'complex_config',        '~> 0.22', '>= 0.22.2'
-  dependency             'tins',                  '~> 1.57'
+  dependency             'tins',                  '~> 1.58'
   dependency             'search_ui',             '>= 0.2'
   dependency             'amatch',                '~> 0.4'
   dependency             'pdf-reader',            '~> 2.0'
@@ -61,13 +61,13 @@ GemHadar do
   dependency             'rubyzip',               '~> 3.0'
   dependency             'sequel',                '~> 5.0'
   dependency             'file-tail',             '~> 1.4'
+  dependency             'nokogiri',              '~> 1.0'
   development_dependency 'all_images',            '~> 0.12'
   development_dependency 'rspec',                 '~> 3.2'
   development_dependency 'kramdown',              '~> 2.0'
   development_dependency 'webmock'
   development_dependency 'debug'
   development_dependency 'simplecov'
-  development_dependency 'context_spook'
   development_dependency 'utils'
 
   licenses << 'MIT'

data/lib/ollama_chat/asr.rb

@@ -0,0 +1,110 @@
+require 'securerandom'
+
+# Standalone ASR (Speech-to-Text) transcription client for audio.cpp.
+#
+# Transcribes audio or video sources by uploading them as multipart
+# form-data to the audio.cpp `/v1/audio/transcriptions` endpoint.
+# Video sources are first converted to 16 kHz mono WAV via ffmpeg.
+#
+# @example Transcribing a WAV source
+#   text = OllamaChat::ASR.transcribe(source_io, chat:)
+#
+# @example Transcribing an MP4 video (ffmpeg extraction)
+#   text = OllamaChat::ASR.transcribe(source_io, chat:)
+module OllamaChat
+  class ASR
+    class << self
+      # Transcribes audio/video content via the audio.cpp ASR endpoint.
+      #
+      # @param source_io [IO] the audio/video source stream
+      #   (must respond to #content_type and be seekable)
+      # @param language [String, nil] optional language hint
+      #   (e.g. "en", "de") passed as the `language` form field
+      # @param chat [OllamaChat::Chat] the chat instance (for HTTP middleware)
+      #
+      # @return [String, nil] the transcribed text, or nil on failure
+      def transcribe(source_io, chat:, language: nil)
+        asr_url   = OC::OLLAMA::CHAT::ASR::URL
+        asr_model = OC::OLLAMA::CHAT::ASR::MODEL
+        input = Tempfile.new(['asr_in'])
+        wav   = Tempfile.new(['asr', '.wav'])
+        begin
+          IO.copy_stream(source_io, input)
+          input.flush
+
+          cmd = OC::OLLAMA::CHAT::ASR::CONVERT_COMMAND % {
+            input: input.path, output: wav.path
+          }
+          executable = Shellwords.split(cmd).first
+          result     = system(cmd, out: File::NULL, err: File::NULL)
+          if result.nil?
+            STDERR.puts "ASR: #{executable} not found in PATH."
+            return
+          end
+          unless File.size(wav.path) > 0
+            STDERR.puts "ASR: #{executable} produced no output."
+            return
+          end
+
+          url       = "#{asr_url}/v1/audio/transcriptions"
+          form_data = multipart_form_data(wav.path, model: asr_model, language:)
+          chat.request_url_response(:post, url, **form_data) do |response|
+            return JSON.parse(response.body)['text']
+          end
+        ensure
+          input.close!
+          wav&.close!
+        end
+      rescue JSON::ParserError, Excon::Error => e
+        if response = e.ask_and_send(:response)
+          status = response.status
+          result = JSON.parse(response.body) rescue nil
+        end
+        chat.log(:error, e, data: { status:, result: })
+        STDERR.puts "ASR transcription failed: #{e.message}"
+        nil
+      end
+
+      private
+
+      # Builds a multipart/form-data request body for the ASR endpoint.
+      #
+      # Constructs the wire format manually (boundary, text field parts,
+      # file part) so the result can be splatted directly into
+      # {HTTPHandling#request_url_response}.
+      #
+      # @param file_path [String] path to the WAV file to upload
+      # @param rest [Hash] additional form fields (e.g. `model:`,
+      #   `language:`); `nil` values are omitted via `compact`
+      #
+      # @return [Hash] Excon-compatible options with `:headers`
+      #   (Content-Type including the generated boundary), `:expects`
+      #   (200), and `:body` (the assembled multipart string)
+      def multipart_form_data(file_path, **rest)
+        path     = Pathname.new(file_path)
+        body     = ''
+        boundary = SecureRandom.hex(8)
+
+        rest.compact.each do |field_name, field_value|
+          body << "--#{boundary}\r\n"
+          body << "Content-Disposition: form-data; name=\"#{field_name}\"\r\n\r\n"
+          body << "#{field_value}\r\n"
+        end
+
+        body << "--#{boundary}" << Excon::CR_NL
+        body << %{Content-Disposition: form-data; name="file"; filename="#{path.basename}"} << Excon::CR_NL
+        body << 'Content-Type: audio/wav' << Excon::CR_NL
+        body << Excon::CR_NL
+        body << path.binread
+        body << Excon::CR_NL
+        body << "--#{boundary}--" << Excon::CR_NL
+
+        {
+          headers: { 'Content-Type' => %{multipart/form-data; boundary="#{boundary}"} },
+          expects: 200,
+          body:    ,
+        }
+      end
+    end
+  end
+end

data/lib/ollama_chat/chat.rb

@@ -162,15 +162,14 @@ class OllamaChat::Chat
   # @return [OllamaChat::RedisCache, nil] the cache instance
   attr_reader :cache
 
-
   # Returns the voice handler class based on the configuration.
   #
   # This method resolves the voice handler class specified in the config.
-  # If running within RSpec, it returns an empty array to avoid side effects.
+  # If running within RSpec, it returns nil to avoid side effects.
   #
-  # @return [Class, Array] the voice handler class or an empty array if in test mode
+  # @return [Class, NilClass] the voice handler class or nil if in test mode
   def voice_handler
-    defined?(RSpec) and return []
+    defined?(RSpec) and return nil
     case config.voice.handler
     when 'OllamaChat::TTS'
       OllamaChat::TTS
@@ -295,6 +294,30 @@ class OllamaChat::Chat
     content
   end
 
+  # Synthesizes and plays a short voice notification using the session's
+  # current voice.
+  #
+  # This is the chat-level facade for one-shot speech: it resolves the
+  # active voice, instantiates the configured voice handler, and delegates
+  # to its `#speak` method. It is a no-op when the voice switch is off,
+  # no voice is selected, or the handler lacks `#speak`.
+  #
+  # @param text [String] the text to speak
+  # @param background [Boolean, Integer] pass `true` for an immediate
+  #   background thread, `false` for inline, or a numeric delay in
+  #   seconds (e.g. `10`) to spawn a background thread that sleeps
+  #   before speaking
+  #
+  # @return [OllamaChat::TTS, OllamaChat::Say, nil] the voice handler
+  #   instance when a background thread was spawned (so callers can call
+  #   `cancel_speaking`), or `nil` for inline playback or when voice is off
+  def speak(text, background: true)
+    voice.on? or return
+    voice = session.current_voice.full? or return
+    voice_handler.method_defined?(:speak) or return
+    voice_handler.new(chat: self, voice:).speak(text, background:)
+  end
+
   # Returns a human-readable string representation of the Chat object,
   # including the class name and the base URL.
   #