feat(session): add memory extraction preview API

[yeyitech]

Summary

• add POST /api/v1/sessions/{session_id}/extract-preview to preview extracted memory candidates without writing memory files
• expose the new capability through embedded and HTTP Python clients
• document the new API in both English and Chinese session docs
• add API / SDK regression tests for the preview flow

Why

OpenViking positions itself as an observable context database, but today session memory extraction is still mostly a black box: developers can commit and inspect the final result after writes, yet they cannot easily inspect what the extraction stage would produce before persistence.

This feature fills that gap by returning:

• current live message count and estimated tokens
• the latest completed archive overview used as extraction context
• an archive summary preview for the current live messages
• raw extracted candidate memories grouped by category

That makes memory debugging, prompt iteration, and agent integration much easier without mutating storage.

API

New endpoint:

• POST /api/v1/sessions/{session_id}/extract-preview

Returned payload includes:

• session_id
• message_count
• estimated_message_tokens
• latest_archive_overview
• archive_summary_preview
• counts_by_category
• candidates

Validation

• python3 -m py_compile openviking/session/compressor.py openviking/service/session_service.py openviking/server/routers/sessions.py openviking/client/local.py openviking/async_client.py openviking/sync_client.py openviking_cli/client/base.py openviking_cli/client/http.py openviking_cli/client/sync_http.py tests/server/test_api_sessions.py tests/server/test_http_client_sdk.py
• ad hoc ASGI script validation for POST /api/v1/sessions/{session_id}/extract-preview
• ad hoc AsyncHTTPClient.preview_memory_extraction() validation against a live uvicorn server

Notes

I also added pytest coverage for the new API and SDK path, but full local pytest execution is currently blocked by an environment-specific pytest-asyncio collection bug (AttributeError: 'Package' object has no attribute 'obj') in this machine's setup.

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🏅 Score: 92

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 No multiple PR themes

⚡ Recommended focus areas for review Missing JSON serialization The new preview endpoint returns the result directly without using _to_jsonable, which could cause JSON serialization failures if latest_archive_overview or other result fields are not JSON-serializable. This is inconsistent with other endpoints like extract_session which use _to_jsonable. result = await service.sessions.preview_extract(session_id, _ctx) return Response(status="ok", result=result)

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Use _to_jsonable for response result Apply _to_jsonable to the result before returning it in the response, matching the pattern used in the extract_session endpoint. This ensures consistent JSON serialization of the response payload and avoids potential errors with non-serializable objects. openviking/server/routers/sessions.py [240-241] result = await service.sessions.preview_extract(session_id, _ctx) -return Response(status="ok", result=result) +return Response(status="ok", result=_to_jsonable(result)) Suggestion importance[1-10]: 8 __ Why: The suggestion ensures consistent JSON serialization with the existing extract_session endpoint, preventing potential runtime errors from non-serializable objects in the response.	Medium

[yeyitech]

Updated based on the review suggestion. The extract-preview response now goes through , and I added a regression test to cover serialization of custom result objects.

[yeyitech]

Updated based on the review suggestion. The extract-preview response now goes through _to_jsonable, and I added a regression test to cover serialization of custom result objects.