Good-to-have: improve scoped SDK workflows and multimodal developer experience

[syaheer]

Context

Building and live-testing a small Android consumer against VModal.configure(...).scope(...) showed that the scoped facade works as an application boundary, but consuming apps still recreate several workflows that belong naturally in the SDK.

This issue contains enhancements only. Confirmed defects are tracked separately.

Proposed SDK enhancements

1. Typed search results

Replace or supplement SearchResponse.data: List<Any?> with a forward-compatible SearchResult containing common filename, stream, timestamp, frame, caption, OCR, ASR, score, modality, and image-coordinate fields, while retaining raw fields.

2. Searchable-moment API

Provide a high-level API that combines scoped search with thumbnail resolution:

suspend fun VModalScope.searchMoments(
    query: String,
    options: SearchMomentsOptions = SearchMomentsOptions(),
): List<SearchMoment>

3. Cancellation-aware index polling

Provide a terminal-state-aware Flow with configurable interval, timeout, retry/backoff policy, and cancellation:

fun VModalScope.indexStatusEvents(
    jobId: String,
    options: IndexPollingOptions = IndexPollingOptions(),
): Flow<IndexStatusEvent>

4. Optional upload-to-index workflow

Provide a high-level Flow for upload progress, upload completion, index submission, index progress, completion, and failure while retaining granular APIs.

5. Typed index states and configuration

Replace raw status/configuration strings with forward-compatible enums or sealed types for status, index type, modality, insert mode, and version strategy.

6. Index idempotency

Allow callers to supply an idempotency key or reuse an active job with the same scope and configuration, preventing accidental duplicate backend work.

7. Collection/index readiness discovery

Expose whether content exists, which index versions are ready, and which search modalities are available:

suspend fun VModalScope.readiness(): ContentReadiness

8. Provider-only scoped configuration

Allow production apps to configure the facade without supplying a placeholder static key:

VModal.configure(projectId = "clipfind", apiKeyProvider = provider)

9. Credential-expiration support

Expose typed expiration/retryability information and document a safe one-time refresh path that never blindly replays mutations.

10. Search pagination helper

Provide a Flow, sequence-like API, or Paging adapter that manages offset, limit, and cntTotal while preserving rank.

11. Score semantics

Document score direction and model-specific ranges. Expose raw scores plus an optional normalized relevance value so OCR, ASR, and image results can be presented consistently.

12. Capability discovery

Allow clients to discover supported modalities, multipart availability, models, and optional endpoints before submitting work.

13. Progressive search results

Optionally emit text hits before thumbnail resolution completes rather than blocking presentation on all image requests.

14. Richer index diagnostics and cancellation

Where supported by the backend, expose progress, failure code, sanitized message, retryability, timestamps, and backend job cancellation.

15. Upload validation and next-action metadata

Add preflight validation for supported media, size, filenames, and reopenability. Include the normalized asset identifier and whether indexing is required in upload completion results.

16. Structured safe diagnostics

Expose request ID, operation name, retryability, and related job ID without exposing credentials, payloads, or signed URLs.

17. Reusable contract fixtures

Ship fake transports and representative JSON fixtures so consuming apps can test upload, indexing, search, image resolution, cancellation, and pagination without live credentials.

18. Scoped cleanup helpers

Provide dry-run-first cleanup for obsolete test content, expired uploads, and old index versions within one immutable scope.

Suggested priority

1. Typed search results and typed index state
2. Cancellation-aware index polling
3. Search-to-thumbnail workflow
4. Index idempotency and readiness discovery
5. Provider-only configuration
6. Upload-to-index orchestration and pagination

Acceptance criteria

• Common search hits require no unchecked application casts.
• Apps do not duplicate terminal-state parsing and polling loops.
• A documented high-level path exists from upload to searchable, displayable moments.
• Credential rotation works without a placeholder static key.
• Existing granular APIs remain source-compatible.

Related

Confirmed SDK defects discovered during the same integration audit are tracked in a separate issue.