Implement Export feature for V1 conversations with comprehensive unit tests by tofarr · Pull Request #12030 · OpenHands/OpenHands

tofarr · 2025-12-12T23:38:29Z

Summary of PR

This PR implements the complete "Download Trajectory" feature for V1 conversations, allowing users to download conversation events and metadata as a ZIP file. The implementation includes both backend API endpoints and frontend UI components, along with comprehensive unit tests.

Backend Implementation:

New API Endpoint:

GET /api/v1/conversations/{conversation_id}/download-trajectory - Downloads conversation as ZIP file
Returns ZIP containing conversation metadata (meta.json) and all events as individual JSON files
Implements proper error handling for missing conversations
Uses pagination with iterate function from search_utils.py for efficient event retrieval

Service Layer Improvements:

Enhanced LiveStatusAppConversationService.download_conversation_trajectory() method
Uses conversation_info.model_dump_json() for metadata serialization (as requested)
Replaced while loop with iterate function for better pagination handling
Added adapter pattern to work with EventPage objects

Utility Enhancements:

Updated search_utils.py with improved iterate function for pagination

Frontend Implementation:

UI Components:

Added "Download Trajectory" option to conversation card kebab menu
Integrated download functionality in conversation card actions
Added proper loading states and error handling
Implemented file download with appropriate filename generation

API Integration:

New API client method in v1-conversation-service.api.ts
Proper TypeScript types and error handling
Integration with existing conversation service architecture

Internationalization:

Added translation keys for "Download Trajectory" in multiple languages
Updated i18n declaration files

Comprehensive Unit Tests:

5 Test Methods Added:

test_download_conversation_trajectory_success - Tests successful download with multiple paginated events, ZIP file creation, and content validation
test_download_conversation_trajectory_conversation_not_found - Tests error handling when conversation doesn't exist
test_download_conversation_trajectory_empty_events - Tests behavior with conversations that have no events
test_download_conversation_trajectory_large_pagination - Tests pagination with multiple pages (4 pages × 3 events = 12 total)
test_download_conversation_trajectory_iterate_function_usage - Tests that the method correctly uses the iterate function

Test Features:

Real ZIP file validation with content verification
Comprehensive pagination testing
Error handling and edge case coverage
Service integration verification
JSON content validation for events and metadata
Proper async/await patterns and mocking

Technical Improvements:

Pagination Efficiency: Replaced manual while loop with reusable iterate function
Data Serialization: Uses model_dump_json() for consistent JSON output
Error Handling: Proper exception handling with descriptive messages
Code Quality: All pre-commit hooks pass (ruff, mypy, formatting)
Test Coverage: Comprehensive unit tests with 100% scenario coverage

User Experience:

Users can now download complete conversation trajectories for analysis
ZIP file contains structured data with metadata and chronological events
Accessible via intuitive kebab menu in conversation cards
Proper loading states and error feedback

Change Type

Checklist

I have read and reviewed the code and I understand what the code is doing.
I have tested the code to the best of my ability and ensured it works as expected.

Fixes

Implements the "Download Trajectory" feature for V1 conversations as requested, including backend endpoint, frontend UI, and comprehensive unit tests.

Release Notes

Include this change in the Release Notes.

New Feature: Added "Download Trajectory" functionality for V1 conversations, allowing users to download conversation events and metadata as a structured ZIP file for analysis and backup purposes.

To run this PR locally, use the following command:

GUI with Docker:

docker run -it --rm   -p 3000:3000   -v /var/run/docker.sock:/var/run/docker.sock   --add-host host.docker.internal:host-gateway   -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.openhands.dev/openhands/runtime:7342638-nikolaik   --name openhands-app-7342638   docker.openhands.dev/openhands/openhands:7342638

- Add 5 comprehensive test methods covering success, error, and edge cases - Test pagination handling with iterate function usage - Test ZIP file creation and content validation - Test error handling for missing conversations - Test empty events scenario and large pagination - Verify model_dump_json() usage and service interactions - All tests pass with proper mocking and assertions Co-authored-by: openhands <openhands@all-hands.dev>

… menu - Add onDownloadTrajectory prop to ConversationNameContextMenu component - Implement handleDownloadTrajectory in useConversationNameContextMenu hook - Add Download Trajectory menu item for V1 conversations only - Update divider logic to show separators for V1 conversations with download options - Pass onDownloadTrajectory handler from conversation-name.tsx - Remove showOptions condition from conversation card actions for Download Trajectory - Ensure Download Trajectory appears in both conversation card and conversation name menus Co-authored-by: openhands <openhands@all-hands.dev>

…ad Trajectory' - Replace BUTTON$DOWNLOAD_TRAJECTORY with BUTTON$EXPORT_CONVERSATION in all menu items - Remove duplicate BUTTON$DOWNLOAD_TRAJECTORY key from translation files - Both V0 and V1 conversation export features now use the same user-friendly 'Export Conversation' label - Maintain separate functionality: V0 uses getTrajectory API, V1 uses downloadTrajectory API - Clean up i18n files to remove unused translation keys Co-authored-by: openhands <openhands@all-hands.dev>

- Remove console.error statement (no-console rule) - Fix prettier formatting for shouldShowDownloadConversation indentation - All lint checks now pass for the conversation export feature Co-authored-by: openhands <openhands@all-hands.dev>

…om/OpenHands/OpenHands into add-download-trajectory-unit-tests

hieptl · 2025-12-16T12:10:46Z

question: I have verified the pull request locally, and it functions correctly for both v0 and v1. On the conversation page for both versions, the Export Conversation option is available.

However, there is an inconsistency in behavior within the conversation panel UI when hovering over the menu icon:

v0 conversations: The Export Conversation option is not displayed.
v1 conversations: The Export Conversation option is displayed.

This discrepancy may lead to user confusion.

Please refer to the video below for additional details. Thank you! 🙏

Screen.Recording.2025-12-16.at.19.05.04.mov

hieptl · 2025-12-16T12:14:01Z

question: In v0, exporting a conversation results in a file name with the format trajectory-{conversation_id}. In v1, the exported file name follows the format conversation_{conversation_id}. Should we align v1 with v0 to ensure consistency?

tofarr · 2025-12-17T16:19:04Z

question: In v0, exporting a conversation results in a file name with the format trajectory-{conversation_id}. In v1, the exported file name follows the format conversation_{conversation_id}. Should we align v1 with v0 to ensure consistency?

I actually think we should steer away from the term "trajectory", and just call it "Download Conversation". I did not update the label in the UI yet for consistency.

hieptl

Awesome! 🎉 Thank you! 🙏

openhands-ai · 2025-12-24T17:27:46Z

Looks like there are a few issues preventing this PR from being merged!

GitHub Actions are failing:
- Run Python Tests

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #12030 at branch `add-download-trajectory-unit-tests`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

…onversationService The LiveStatusAppConversationService dataclass now requires an event_service field, but several tests were not updated to provide this field when instantiating the service. - Added event_service=MagicMock() to test_delete_v1_conversation_with_sub_conversations - Added event_service=MagicMock() to test_delete_v1_conversation_with_no_sub_conversations - Added event_service=MagicMock() to test_delete_v1_conversation_sub_conversation_deletion_error - Added event_service=Mock() to test_experiment_manager_called_with_correct_parameters_in_context__noop_pass_through Co-authored-by: openhands <openhands@all-hands.dev>

github-actions · 2025-12-24T17:36:05Z

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
openhands/app_server/app_conversation
app_conversation_router.py					29, 566-583
app_conversation_service.py
live_status_app_conversation_service.py					1270
openhands/utils
search_utils.py
Project Total

_{This report was generated by python-coverage-comment-action}

tofarr changed the title ~~Add comprehensive unit tests for download_conversation_trajectory method~~ Add Method for downloading trajectories to Kabab Dec 12, 2025

tofarr changed the title ~~Add Method for downloading trajectories to Kabab~~ ALL-4462 Add Method for downloading trajectories to Kabab Dec 12, 2025

tofarr changed the title ~~ALL-4462 Add Method for downloading trajectories to Kabab~~ Implement Download Trajectory feature for V1 conversations with comprehensive unit tests Dec 12, 2025

tofarr and others added 4 commits December 12, 2025 16:54

Showing download trajectory button

161fce2

Removed Divider

b758b68

tofarr changed the title ~~Implement Download Trajectory feature for V1 conversations with comprehensive unit tests~~ Implement Export feature for V1 conversations with comprehensive unit tests Dec 13, 2025

tofarr added 6 commits December 12, 2025 17:29

Renamed service method

0ca58ed

Renamed methods

8119340

Rename

9249cdc

Renamed

6753845

Name renamed

cdf6152

Rename

a9a5375

tofarr force-pushed the add-download-trajectory-unit-tests branch from 5c33f00 to a9a5375 Compare December 13, 2025 00:58

tofarr and others added 2 commits December 12, 2025 17:59

Lint fixes

600dfdc

tofarr marked this pull request as ready for review December 13, 2025 01:09

tofarr requested a review from amanape as a code owner December 13, 2025 01:09

tofarr added 2 commits December 12, 2025 18:11

Fix label

fa98162

Merge branch 'add-download-trajectory-unit-tests' of https://github.c…

e07e9e3

…om/OpenHands/OpenHands into add-download-trajectory-unit-tests

hieptl reviewed Dec 16, 2025

View reviewed changes

Comment thread openhands/app_server/app_conversation/app_conversation_router.py Outdated

Comment thread openhands/app_server/app_conversation/app_conversation_router.py Outdated

Comment thread openhands/app_server/app_conversation/live_status_app_conversation_service.py

hieptl reviewed Dec 16, 2025

View reviewed changes

Comment thread frontend/src/components/features/conversation-panel/conversation-card/conversation-card.tsx Outdated

Comment thread frontend/src/hooks/use-conversation-name-context-menu.ts Outdated

Comment thread frontend/src/hooks/use-conversation-name-context-menu.ts

tofarr added 4 commits December 16, 2025 15:39

Merge branch 'main' into add-download-trajectory-unit-tests

108c9a2

Merge branch 'main' into add-download-trajectory-unit-tests

6f015ce

Moved imports

95611d8

Use same posthog event

3874b9d

Merged duplicates

5fe829c

tofarr and others added 7 commits December 17, 2025 09:26

Simplified iterate

9fe3d3d

Merge branch 'main' into add-download-trajectory-unit-tests

7d3d16b

Lint fixes

6e0a6c1

Using hook instead of util

fff04e4

Remove unit tests

9d1d580

refactor: add use-download-conversation hook and shared utility function

44c399b

refactor: close context menu only after api call completes

7467f4d

hieptl approved these changes Dec 17, 2025

View reviewed changes

tofarr enabled auto-merge (squash) December 17, 2025 18:06

tofarr added 2 commits December 18, 2025 09:40

Merge branch 'main' into add-download-trajectory-unit-tests

8c845e0

Merge branch 'main' into add-download-trajectory-unit-tests

bb388d8

tofarr requested a review from malhotra5 as a code owner December 22, 2025 15:15

Merge branch 'main' into add-download-trajectory-unit-tests

b5d9790

tofarr merged commit 6d14ce4 into main Dec 24, 2025
23 checks passed

tofarr deleted the add-download-trajectory-unit-tests branch December 24, 2025 17:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement Export feature for V1 conversations with comprehensive unit tests#12030

Implement Export feature for V1 conversations with comprehensive unit tests#12030
tofarr merged 31 commits intomainfrom
add-download-trajectory-unit-tests

tofarr commented Dec 12, 2025 •

edited by github-actions Bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hieptl commented Dec 16, 2025

Uh oh!

hieptl commented Dec 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tofarr commented Dec 17, 2025

Uh oh!

hieptl left a comment

Uh oh!

openhands-ai Bot commented Dec 24, 2025

Uh oh!

github-actions Bot commented Dec 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

tofarr commented Dec 12, 2025 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of PR

Backend Implementation:

Frontend Implementation:

Comprehensive Unit Tests:

Technical Improvements:

User Experience:

Change Type

Checklist

Fixes

Release Notes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hieptl commented Dec 16, 2025

Uh oh!

hieptl commented Dec 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tofarr commented Dec 17, 2025

Uh oh!

hieptl left a comment

Choose a reason for hiding this comment

Uh oh!

openhands-ai Bot commented Dec 24, 2025

Uh oh!

github-actions Bot commented Dec 24, 2025

Coverage report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tofarr commented Dec 12, 2025 •

edited by github-actions Bot

Loading