Feature: download the Inquire conversation as a Word document

[branch1337]

Description

A person using Inquire can ask questions across recordings and read the answers on the page. The turns live in inquireChatMessages (templates/inquire.html:778). Leaving the page, refreshing, or pressing Clear All drops them. Clear All assigns that array to [] and also clears the filter selections (templates/inquire.html:1177-1191). Nothing writes the questions or the answers to the server. POST /api/inquire/sessions stores a name and filter ids (src/api/inquire.py:92-116), and the Inquire page never calls it. InquireSession has columns for tags, speakers, dates, and recording ids, and no column for messages or folders (src/models/inquire.py:13-45).

Transcript, summary, notes, and the chat on one recording each have a download. The recording chat posts the on-screen turns to POST /recording/<id>/download/chat and receives one Word file (src/api/recordings.py:475-609, client at static/js/modules/composables/chat.js:360-377). The button is the download icon in the chat header, shown only when chatMessages.length > 0 (templates/components/detail/floating-chat.html:52-56). Inquire has no such control. The conversation column (templates/inquire.html:428-431) goes from the empty state straight into the message list.

The workaround is to copy the bubbles by hand. The answers are markdown, the page renders HTML, and a copy from the screen drops the structure the recording chat already keeps.

Affected Version

v0.10.19-alpha

Requested Feature

From the Inquire page, the person downloads the conversation on screen as one Word document. The control is one icon button, with no format menu. It sits on a thin bar at the top of the conversation column, above the scroller at templates/inquire.html:431. It uses the same classes as the recording chat button (btn btn--icon btn--sm and fas fa-download). The accessible name is a new string, inquire.downloadConversation. It does not reuse buttons.downloadChat ("Download chat as Word document", static/locales/en.json:894), which refers to the chat on one transcription.

The button is shown when at least one turn has a non-empty string content. hasActiveFilters (templates/inquire.html:807-814) stays the condition for the filter chips and the "Filters active" hint. Filters can be set while the message list is still the empty state (templates/inquire.html:438), and in that state the button stays hidden. Clear All empties the list, so the button disappears with the turns.

The click posts the turns already on screen. It does not call the model, does not search chunks, and does not create an InquireSession. The request is POST /api/inquire/download with the session cookie and the X-CSRFToken header the Inquire chat call already sends (templates/inquire.html:1030-1034). The JSON body has two fields.

messages is a list of {role, content} for every turn whose content is a non-empty string, in screen order. A user turn is pushed before the request (templates/inquire.html:1004), and assistant text is appended on each SSE delta (templates/inquire.html:1117). A download during streaming therefore contains the question and whatever of the answer has already arrived. Stop keeps that partial text (templates/inquire.html:1147-1149), and the file includes it. The page does not send html, steps, activitySummary, sources, or memoryState.

filters is optional. The page fills it from the selections in inquireFilters (templates/inquire.html:732-739), using the names already drawn next to the checkboxes, not the id numbers and not the count pills. Tag ids (templates/inquire.html:294) are mapped through availableFilters.tags to tag.name (templates/inquire.html:296). Folder ids (templates/inquire.html:315) are mapped to folder.name (templates/inquire.html:317). Speakers are already names (templates/inquire.html:337-339). Dates are the YYYY-MM-DD values of dateFrom and dateTo, and only the ends that are set. An id that is no longer in availableFilters is skipped. A group with no remaining names is omitted. When every group is empty, the field is omitted. The recording checkbox list is inside an HTML comment (templates/inquire.html:368-385), so selectedRecordings stays [] on this page. The page does not add a recordings group. The route still accepts one if a caller sends names.

The response is one Word document. The media type is application/vnd.openxmlformats-officedocument.wordprocessingml.document. Content-Disposition is attachment; filename="inquire.docx". The name is fixed. Filter text and recording titles never enter it. The file is returned by docx_attachment_response from #554, which calls send_file with as_attachment=False and then sets the header. test_download_chat_with_messages_returns_docx records that flipping as_attachment to True on a BytesIO returns 500 (tests/test_cov_recordings_read.py:1755-1776). inquire.docx is ASCII, so the header is the plain filename form.

The document shape follows the recording chat file, without a recording title and without a reasoning section:

• A level-0 heading, Inquire, written with add_unicode_heading.
• A paragraph Export Date: YYYY-MM-DD HH:MM, from now_local(user_timezone(current_user)) (src/utils/timezones.py:98-100 and src/utils/timezones.py:43-46), written with add_unicode_paragraph. That is the same clock the recording chat uses for Chat Export Date (src/api/recordings.py:528-530). A user with no valid timezone gets the deployment zone, which is what user_timezone already returns.
• One paragraph of the filter groups that were sent, in the order tags, folders, speakers, recordings, dates. Each group is Label: a, b. Groups are joined with ; . Example: Tags: Planning; Speakers: Ada; Dates: 2026-01-01, 2026-01-31. The count pills on the sidebar (templates/inquire.html:397-419) stay counts. They show "2 tags" and "Date range active", and the file shows the names and the dates.
• Then each kept turn, written by append_conversation_turn: a bold You: , Assistant: , or the title-cased role, then the turn's markdown passed through process_markdown_to_docx (src/services/document.py:11), then one blank paragraph. Role labels stay the English words the recording chat hardcodes (src/api/recordings.py:540-551). The interface language translates the button, not those labels. Inquire does not pass thinking, so the file has no [Model Reasoning] paragraph.

Citation links that are already inside content stay there. process_markdown_to_docx writes a markdown link as the link text followed by the URL in parentheses (src/services/document.py:81-83). It does not create a Word hyperlink. The Sources list the page builds in HTML (templates/inquire.html:968-986) is not part of content, and the file does not add a second sources section from message.sources (templates/inquire.html:932). Agent steps (templates/inquire.html:509-526) and the compacted-memory divider (templates/inquire.html:485-501) are not sections of the file. data.thinking on the Inquire stream updates the status line and is not stored on the turn (templates/inquire.html:1102-1105).

Refusals:

• No session, on this /api/ path: 401 with code authentication_required (src/app.py:1010-1014).
• ENABLE_INQUIRE_MODE off: 403 with code inquire_disabled, the same body inquire_chat returns (src/api/inquire.py:843-844). The flag is read in this module (src/api/inquire.py:28), default false. The page itself redirects when the flag is off (src/api/inquire.py:51-57). The route still checks.
• Body missing, or messages absent: 400 with code no_messages_provided.
• messages an empty list, not a list, or a list whose turns all lack a non-empty string content: 400 with code no_messages_to_download.
• A failure while building the file: 500 with code word_document_failed.

api_error returns error in the interface language and a stable code (src/utils/localization.py:355-362). Tests assert code. no_messages_provided and no_messages_to_download already exist (static/locales/en.json:3361-3362). word_document_failed is the code download_chat_word already returns (src/api/recordings.py:607-609). No new error code.

These stay as they are. The recording chat file still has the recording title, the recording date, the thinking block, the blank line between turns, and a filename taken from the title. This request moves that turn loop onto append_conversation_turn and leaves the visible chat file the same. inquire_chat and inquire_stream still stream the answer. POST /api/v1/inquire (src/api/api_v1.py:3240-3255) still answers a question and, when the mode is off, still returns 403 with code feature_disabled. InquireSession is unchanged. Transcript, summary, notes, and the on-disk auto-export of a recording are unchanged. There is no new environment variable.

Proposed Implementation

Apply #554 first. This request depends on it. That request adds ensure_unicode_font, add_unicode_heading, add_unicode_paragraph, and docx_attachment_response in src/services/document.py, and points the summary, notes, and chat downloads at them. This request does not define those four functions again. Implementing this file first leaves the imports unresolved.

The route goes on inquire_bp, next to inquire_chat (src/api/inquire.py:839-860). That blueprint already serves every web Inquire call: the page, sessions, search, chat, and available filters. One route there covers the page. Copying a second download onto inquire_v1 would put the file on the versioned API, which this request leaves alone.

Two arrows leave the Inquire page. The new one returns the file from the turns already on screen. The existing one still returns the stream. POST /api/v1/inquire and POST /recording/<id>/download/chat have no arrow in this diagram.

sequenceDiagram
    actor Person
    participant Page as Inquire page
    participant Download as POST /api/inquire/download
    participant Chat as POST /api/inquire/chat

    Person->>Page: Click the download icon
    Page->>Download: role and content from inquireChatMessages, plus filter names
    Note over Download: No model call, no chunk read, no InquireSession
    Download-->>Person: inquire.docx

    Person->>Page: Ask a question
    Page->>Chat: question and history
    Chat-->>Page: text/event-stream

Loading

send_file, jsonify, request, current_app, login_required, current_user, and api_error are already imported in src/api/inquire.py:13-20. ENABLE_INQUIRE_MODE is already the module flag at src/api/inquire.py:28. The Word helpers are imported from src.services.document inside the try, next to Document, the same way a failure to build the file becomes word_document_failed.

This request also adds conversation_role_label and append_conversation_turn to src/services/document.py. The recording chat is the first caller (src/api/recordings.py:533-563). Inquire is the second. The loop leaves download_chat_word and both routes call the one function. download_chat_word passes message.get('role', 'unknown'), message.get('content', ''), and message.get('thinking', '') with no extra coercion, so a chat turn whose role is an empty string still renders the way it does now.

def conversation_role_label(role):
    """The English role names the recording chat Word file already writes."""
    if role == 'user':
        return 'You'
    if role == 'assistant':
        return 'Assistant'
    return str(role).title()


def append_conversation_turn(doc, role, content, thinking=''):
    """One turn: a bold role label, optional assistant reasoning, then markdown.

    A blank paragraph follows the turn, as download_chat_word does today.
    thinking is written only for an assistant turn, and only when it is non-empty.
    """
    paragraph = doc.add_paragraph()
    run = paragraph.add_run(f'{conversation_role_label(role)}: ')
    run.bold = True
    if thinking and role == 'assistant':
        reasoning = doc.add_paragraph()
        reasoning.add_run('[Model Reasoning]\n').italic = True
        reasoning.add_run(thinking).italic = True
        doc.add_paragraph('')
    process_markdown_to_docx(doc, content)
    doc.add_paragraph('')

#554 edits download_summary_word and the heading block inside download_chat_word, so the line numbers below move. In v0.10.19-alpha the loop is src/api/recordings.py:533-563. After that request, replace the for message in messages loop in download_chat_word with:

for message in messages:
    append_conversation_turn(
        doc,
        message.get('role', 'unknown'),
        message.get('content', ''),
        message.get('thinking', ''),
    )

The Inquire route and its filter helpers live in src/api/inquire.py:

_INQUIRE_FILTER_GROUPS = (
    ('tags', 'Tags'),
    ('folders', 'Folders'),
    ('speakers', 'Speakers'),
    ('recordings', 'Recordings'),
    ('dates', 'Dates'),
)


def _inquire_filter_line(filters):
    """One paragraph of the labels the page already resolved, or '' when nothing is set."""
    if not isinstance(filters, dict):
        return ''
    parts = []
    for key, label in _INQUIRE_FILTER_GROUPS:
        value = filters.get(key)
        if isinstance(value, str):
            items = [value.strip()] if value.strip() else []
        elif isinstance(value, list):
            items = [item.strip() for item in value if isinstance(item, str) and item.strip()]
        else:
            items = []
        if items:
            parts.append(f'{label}: {", ".join(items)}')
    return '; '.join(parts)


def _inquire_download_turns(messages):
    """Role and content of turns that have something to write. Other fields are ignored."""
    if not isinstance(messages, list):
        return []
    turns = []
    for message in messages:
        if not isinstance(message, dict):
            continue
        content = message.get('content')
        if not isinstance(content, str) or content == '':
            continue
        role = message.get('role', 'unknown')
        if not isinstance(role, str) or role == '':
            role = 'unknown'
        turns.append((role, content))
    return turns


@inquire_bp.route('/api/inquire/download', methods=['POST'])
@login_required
def download_inquire_conversation():
    """Download the on-screen Inquire conversation as a Word document."""
    if not ENABLE_INQUIRE_MODE:
        return jsonify(api_error('inquire_disabled')), 403

    data = request.json
    if not data or 'messages' not in data:
        return jsonify(api_error('no_messages_provided')), 400

    messages = data['messages']
    if not messages:
        return jsonify(api_error('no_messages_to_download')), 400

    turns = _inquire_download_turns(messages)
    if not turns:
        return jsonify(api_error('no_messages_to_download')), 400

    try:
        from docx import Document
        from src.services.document import (
            add_unicode_heading, add_unicode_paragraph, append_conversation_turn,
            docx_attachment_response,
        )
        from src.utils.timezones import now_local, user_timezone

        doc = Document()
        add_unicode_heading(doc, 'Inquire', 0)
        exported = now_local(user_timezone(current_user)).strftime('%Y-%m-%d %H:%M')
        add_unicode_paragraph(doc, f'Export Date: {exported}')
        filter_line = _inquire_filter_line(data.get('filters'))
        if filter_line:
            add_unicode_paragraph(doc, filter_line)
        for role, content in turns:
            append_conversation_turn(doc, role, content)

        return docx_attachment_response(doc, 'inquire.docx', 'inquire.docx')
    except Exception as e:
        current_app.logger.error(f"Error generating inquire Word document: {e}")
        return jsonify(api_error('word_document_failed')), 500

Leave the recording chat's title, dates, filename, and access check in download_chat_word (src/api/recordings.py:477-609). Leave inquire_v1 (src/api/api_v1.py:3240-3255) as the versioned question API. Leave create_inquire_session (src/api/inquire.py:92-116) and InquireSession.to_dict (src/models/inquire.py:33-45) as the filter-only session. Leave downloadChat (static/js/modules/composables/chat.js:360-404) as the client of the recording route. The Inquire page is a separate Vue app and does not import that composable.

On the page, add canDownloadInquire and downloadInquireConversation in the same setup() and return them from the object at templates/inquire.html:1315. canDownloadInquire is true when some entry of inquireChatMessages has a non-empty string content. The bar is the first child of the conversation column at templates/inquire.html:428, before the scroller. The column is hidden lg:flex only while the filter drawer is open, and flex otherwise (templates/inquire.html:428-429), so the button is on screen whenever that column is. Do not put a second button in the filter sidebar.

downloadInquireConversation builds messages as role and content only, builds filters as described above, and fetches /api/inquire/download with Content-Type: application/json and X-CSRFToken from the ref at templates/inquire.html:726. On a non-OK response it reads the JSON error and shows it through setGlobalError, which the chat path already uses (templates/inquire.html:1150-1153). On success it downloads the blob. The saved name is inquire.docx.

Add inquire.downloadConversation in the inquire object, after dateRangeActive (static/locales/en.json:1876). English value: Download conversation as Word document. Add the same key in de.json, es.json, fr.json, pt-BR.json, ru.json, and zh.json, which already translate inquire.clearAll.

In docs/user-guide/inquire-mode.md, after the date-range paragraph (docs/user-guide/inquire-mode.md:39) and before "Asking Effective Questions" (docs/user-guide/inquire-mode.md:41), add a short paragraph. It says the download icon above the conversation saves the questions and answers on screen as a Word file named inquire.docx, that the icon is absent until a turn exists, and that the file names the selected tags, folders, speakers, and dates. It says Clear All removes the conversation and the icon. It does not describe a format menu or a saved server-side transcript.

Tests go in a new file, speakr.git/tests/test_inquire_download.py. They do not join tests/test_cov_inquire.py or tests/test_cov_recordings_read.py. The new file sets app.config['WTF_CSRF_ENABLED'] = False the way tests/test_cov_inquire.py:34 does, and signs the session the way _login does there (tests/test_cov_inquire.py:79-84). Creating a user is enough. The route does not read Recording. Patch src.api.inquire.ENABLE_INQUIRE_MODE. Patch src.utils.timezones.now_local to a fixed naive datetime so the export line is exact. Read the file with docx.Document over a BytesIO of resp.data, and join paragraph.text.

• test_inquire_download_missing_messages_400: json={} returns 400 and code no_messages_provided.
• test_inquire_download_empty_messages_400: json={"messages": []} returns 400 and code no_messages_to_download.
• test_inquire_download_blank_turns_400: a list of {"role": "assistant", "content": ""} and a non-dict entry returns 400 and code no_messages_to_download.
• test_inquire_download_returns_docx: two turns, one with **roadmap**, return 200, a content type containing wordprocessingml, and Content-Disposition attachment; filename="inquire.docx". The paragraph text contains Inquire, Export Date: 2026-03-04 15:06, You:, Assistant:, the question, and roadmap.
• test_inquire_download_writes_filter_labels: filters tags: ["Planning"], folders: ["Client"], speakers: ["Ada"], recordings: ["Standup"], dates: ["2026-01-01", "2026-01-31"] produce one paragraph Tags: Planning; Folders: Client; Speakers: Ada; Recordings: Standup; Dates: 2026-01-01, 2026-01-31.
• test_inquire_download_omits_empty_filter_line: a body with no filters, and a body with filters: {"tags": [], "dates": ""}, do not contain Tags: or Dates:.
• test_inquire_download_ignores_steps_memory_and_html: steps, html, sources, and a top-level conversation_memory whose text is secret-memory do not appear. The content string does.
• test_inquire_download_disabled_403: the flag false returns 403 and code inquire_disabled, including when messages is missing. The mode check is first.
• test_inquire_download_requires_login: no session returns 401 and code authentication_required.
• test_inquire_download_keeps_non_ascii: content 预算 and a filter Tags: 会议 are both present in the paragraph text.
• test_inquire_download_generator_failure_500: Document raising returns 500 and code word_document_failed.

Add test_download_chat_turn_writer_keeps_thinking in tests/test_cov_recordings_read.py, beside test_download_chat_with_messages_returns_docx (tests/test_cov_recordings_read.py:1755-1776). Post one user turn and one assistant turn whose thinking is hidden-reasoning and whose content is The **roadmap**. Open the docx and assert the joined paragraph text contains You:, Assistant:, [Model Reasoning], hidden-reasoning, and roadmap. The existing chat tests only check status and content type, so they would still pass if the moved loop dropped the reasoning paragraph.

test_download_chat_with_messages_returns_docx, test_download_chat_empty_messages_400, and test_download_chat_missing_key_400 stay in tests/test_cov_recordings_read.py and still cover the recording route. test_chat_disabled_403 stays in tests/test_cov_inquire.py.

Run the new file from speakr.git with python -m pytest tests/test_inquire_download.py tests/test_cov_recordings_read.py::test_download_chat_with_messages_returns_docx tests/test_cov_recordings_read.py::test_download_chat_turn_writer_keeps_thinking tests/test_cov_recordings_read.py::test_download_chat_empty_messages_400 tests/test_cov_recordings_read.py::test_download_chat_missing_key_400.

Expected Behavior

• With Inquire enabled and at least one non-empty turn, the conversation column shows one download icon. The click saves inquire.docx. The file heading is Inquire, then the export time in the current user's zone, then the questions and answers that were on screen. A blank paragraph follows each turn, the same spacer the recording chat already writes (src/api/recordings.py:563).
• A bold, list, or heading in an answer is a Word heading, list, or bold run, because the markdown goes through process_markdown_to_docx. A citation written as a markdown link in the answer appears as its text and URL. The HTML Sources list under the bubble is not repeated.
• While a reply is streaming, the file contains the user turn and the assistant text received so far. After Stop, it contains that partial answer. After the stream finishes, it contains the full answer, including the truncation note the page appends to content when the SSE event says truncated (templates/inquire.html:1123-1127).
• With tags, folders, speakers, or dates selected, the file has one filter paragraph of those names and dates. With no filters, there is no filter paragraph and no empty Tags: line. The sidebar pills are unchanged and still show counts.
• With an empty conversation, including the welcome state and the state after Clear All, the icon is absent. Posting an empty list, a missing messages field, or only blank turns returns 400 and does not return a file.
• A signed-out POST /api/inquire/download returns 401 and authentication_required. With the mode off, the page redirects to the recordings index as it does now (src/api/inquire.py:55-57), and the route returns 403 and inquire_disabled.
• POST /recording/<id>/download/chat still returns the same status codes. The file still has the recording title in the heading, Chat Export Date in the metadata, and [Model Reasoning] when the assistant turn carries thinking. POST /api/v1/inquire is unchanged. POST /api/inquire/chat still returns the SSE stream. POST /api/inquire/sessions still stores filters only. An InquireSession row is not created by a download.
• A non-ASCII answer and a non-ASCII filter name are readable in the Word text. The filename stays inquire.docx.

Root Cause Analysis

The Inquire conversation is browser state. sendInquireChatMessage (templates/inquire.html:1000-1048) posts the new question and a sliced history to /api/inquire/chat, then appends deltas to inquireChatMessages. The only persistence beside that array is memoryState, which holds a summary of folded turns (templates/inquire.html:788-794) and is sent back as conversation_memory on the next question (templates/inquire.html:1040). Clear All wipes both (templates/inquire.html:1184-1189). The session model never receives the turns (src/models/inquire.py:16-25).

The Word download that already exists is keyed by a recording. download_chat_word loads that recording, rejects a caller who cannot read it, and builds the file from the posted messages (src/api/recordings.py:485-496). An Inquire thread has no recording id. Putting the Inquire file on that route would invent one. inquire_chat is the call that already sees every web Inquire question (src/api/inquire.py:839-860), and it returns text/event-stream. The download is a sibling route on inquire_bp, the same split the recording page uses between its chat and download_chat_word.

inquire_v1 looks like the other Inquire entry and is not this path. It takes question, filters, and history, calls inquire_stream, and returns a model answer (src/api/api_v1.py:3243-3255). Its disabled response uses feature_disabled, not inquire_disabled. A download there would be a new versioned operation and would still not see the on-screen HTML, the agent timeline, or the memory divider.

Additional Context

Apply #554 before this request. The Inquire route calls add_unicode_heading, add_unicode_paragraph, and docx_attachment_response, which that request adds. This request then adds append_conversation_turn and switches the recording chat loop over to it.

The recording filter markup is commented out (templates/inquire.html:368-385). selectedRecordings remains in the client state and is still posted to chat as filter_recording_ids (templates/inquire.html:1044), but the page has no control that fills it. This request does not uncomment that picker. A recordings group appears in the file only when the posted filters.recordings list has names.

InquireSession has no filter_folders column. Folder ids exist only in the page and in the chat request (templates/inquire.html:1042). The download reads the names the page sends. It does not start storing folder filters on the session, and it does not start storing the conversation.

The group headings inside the file (Tags, Folders, Speakers, Recordings, Dates, You, Assistant, Inquire, Export Date) are English, matching the recording chat file. Translating them would make this file differ from that one. The button string is translated.

No new setting belongs in config/env.asr.example. The gate remains ENABLE_INQUIRE_MODE. python-docx is already the library download_chat_word imports. This request does not add a plain-text, Markdown, or PDF download, a format menu, a versioned API download, or a write of the conversation into the auto-export directory.

[murtaza-nasir]

Thank you. The Inquire page now has a conversation header with Download and Clear conversation buttons, shown once the conversation has content. The conversation is downloaded as inquire.docx, with the export time, the active filters and links to the cited recordings, and each answer can also be downloaded on its own. Nothing is stored on the server. This will be included in the next release.

[branch1337]

Thank you for taking the time to consider my suggestions and for approving them. I really appreciate all the work you put into improving Speakr!