Skip to content

V- Modal AI: Visual Video / Image Search - Flutter Video SDK

Release Flutter SDK from c3426840f3c0c5245b0028fa9bca2a29c336b77e

vmodal-release-app4ef3a72a0bab
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ec454f4..6ee528f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,7 @@
## 1.1.0
+- Added ordered asynchronous batch search with mini-batch ownership, bounded
+ worker concurrency, preflight validation, and cooperative cancellation.
- Streamed signed upload bodies with awaited socket backpressure, exact file
ranges, source-version checks, and bounded body/response timeouts.
- Enforced one signed-upload concurrency budget across bulk multipart tasks and
diff --git a/RELEASE_METADATA b/RELEASE_METADATA
index e4cf292..040271f 100644
--- a/RELEASE_METADATA
+++ b/RELEASE_METADATA
@@ -1 +1 @@
-Source-vmx-api: 7dd88239fd2e7a3f0c94b89e18ceaa003f233a32
+Source-vmx-api: c3426840f3c0c5245b0028fa9bca2a29c336b77e
diff --git a/SOURCE_MANIFEST.sha256 b/SOURCE_MANIFEST.sha256
index 5c5629d..c4d91de 100644
--- a/SOURCE_MANIFEST.sha256
+++ b/SOURCE_MANIFEST.sha256
@@ -2,19 +2,19 @@ e789cd4d1bed8a78ec8014c5c5913e300f81b63ea56a56aacb0dfec3b5e7ce2b ./.flutter-ver
fbbda2e7e29bbd860539a9ca18c478f3b02de140f25a872c19a6dbecd11bc94b ./.github/workflows/publish.yml
a98f72526420d47e76b9b4e67ac86acd06b7088ad1f4c35617b11b09e59346ea ./.gitleaks.toml
5115d06bd9913f466d50fcbf8ad8890372349060c54a4581f3481ea084cfdec6 ./.pubignore
-c2d0f70729c0293aaf35ea6c0d701dbda4a97b0bc0f7d08b7e29845b24944255 ./CHANGELOG.md
+8087660c63935bd64fedee0cbf615a7aa706dea9649b945d7404903df03332af ./CHANGELOG.md
37b7148216ac6090e36adfb699d642b8dd1e1b8ba99870e65e88733947a59fa6 ./LICENSE
d63378f391ef251ea0afb8841c6886841cab25352d845630c1a117f83e281723 ./README.md
-a7c75e0532999a4f8c486aa112bf83d89461b1a0fdfc18a55a4e41553b63f705 ./RELEASE_METADATA
+58968890f9f778e6301b09005e9a9cbf60f9714c696e5e371ac9bab3fda8553c ./RELEASE_METADATA
def7e4f643adff5b01b877b6a7fa5b2381612b693c0bf06bd232ee0f7197d342 ./analysis_options.yaml
8c2d096dc399d9bea2fcc5ae19d987e7458c8503cf2a7edf1f1497ae00d681aa ./build.sh
4f18642680fb433554a5523d00bd99e0d650af340bcaebe628f59f63ac84e458 ./dartdoc_options.yaml
75461620cf3a062f4dad10e034952b82cca461b483788de1f46c539aca8b0f0f ./doc/manage_api_key.md
a66d39da0983a994474fa516f81fd41bbb131efbd69c955891a41781a76daf24 ./doc/performance.md
cae6114908952cf81a908b7fcc8c0ba4ce3f866e9dbaf974303273f334e0e3f6 ./doc/release.md
-7d849dcf1d4c8537ee33e8fdd6282d3bbe2244e68a9c997dcaf77f23db1b5562 ./doc/sdk_contract.md
+79ef7a2c5e695699a5d784af5ec72a515401bf7d21f632a2ccc1e973db230e10 ./doc/sdk_contract.md
2c07c5319044416d722732f731cc709fc6f6f3e375861bb6b5326a8768258de5 ./doc/sdk_doc.md
-6139d92cf19577ec2d920daa5416d2982e425f63639f858201c91caf39b109bf ./doc/search_app.md
+c0f878afdfd9f8b9914d60ce1c7bc15a54d2c8631826a3a6d17907d4c2ada846 ./doc/search_app.md
7b0acfc01cfa4c8bf3af8aeb19741e65b8e9406935d9ab8e0f4cb84547483e55 ./doc/transcode_360.md
e246ed229511a24a1ee7e98529c203ef90d1d352290ce8486caebe05683db3a0 ./env.sh
c5ce516b547327aab5b6fa27a523d4c76e66294ada3248b293c54b9595cd3a87 ./example/01_full_app/.metadata
@@ -103,7 +103,7 @@ d3e03d9a72a499659c70f2296115d1d3138b9370a017e027d8255f85f7fb1c5c ./lib/src/cont
873d969cfed5c725d34df0fd0c8769462b56992cf523710fcf741a81fa1bbcad ./lib/src/errors.dart
027174edd680e69e067453695f62680fd90b16c78f74a6999ab926cd2fd257dc ./lib/src/http.dart
7670598bf28a23808d0e0bd3e3ea1ec7270fbc450caef2ecc1c0ab0921d17538 ./lib/src/models.dart
-248cc2f57edbcd5c8686ea03854403d704a3d8c18086dc525a5609226728ad92 ./lib/src/resources.dart
+92d2769b42db1062f91c49573af5537793ec98de07c0cf71de074a288816aabd ./lib/src/resources.dart
43770c621bffccf69eacebd1e3b297503ca288093c848f0e8ccbd118d7f0d88a ./lib/src/routes.dart
27056230065682f3ea3aa747c39c08950dcdca87387f4733adfad18f4b345b06 ./lib/src/routes.g.dart
42331852249c8f99874a5e3889c752fd344ad8a5301ede246d5a4fbccb4191f2 ./lib/src/transcode.dart
@@ -131,7 +131,7 @@ d132b6dceb89804a47418245845547a25fcf8f89f56b292ee70a404d63364865 ./test/fakes.d
959b19196513005ffd19bded8e4a2867a0fa84c8e85eae84aeebcc7fc70f8f88 ./test/multipart_upload_test.dart
348b9581f6262acaaf96012a3d57685b0b45c3663c1497f14135663de7a60954 ./test/new_api_surface_test.dart
58222c7f00e8aa8070df89d59278ce0d18842f53a7544261aa4a63ae4b1dd608 ./test/regression_manifest_test.dart
-13fc92ce0d804731aaee7a3bf3b145cb213d67a2ff18ebc271a32f2aba404679 ./test/resources_models_test.dart
+8c87a4645a2e329477d070277f64b617da14ac90163bb734fbb5326c1a97a5c3 ./test/resources_models_test.dart
8619ce113bb8669612f9a2a16b1b334ac68435c5972e84828a789511467fcb77 ./test/shell_scripts_test.dart
deacf67ef61894d8fd7d3cdd7648bace527917fe2097c65140286d324ec8b1aa ./test/transcode_upload_test.dart
7f62ef6965a51fee7123689003432dd013936b4189504222333cedb55c82dcc2 ./test/transport_test.dart
diff --git a/doc/sdk_contract.md b/doc/sdk_contract.md
index e9f3ee5..4dcca63 100644
--- a/doc/sdk_contract.md
+++ b/doc/sdk_contract.md
@@ -10,7 +10,7 @@ behavior. `test/fixtures/routes_contract.json` is the reviewed normalized mirror
| Scoped facade | `VModal.configure`, `VModal.fromClient`, `VModalProject.scope`, `listCollections`, `close` | Preferred additive API |
| Scoped operations | `upload`, `uploadMetadata`, `search`, `addAssets`, `updateAsset`, index lifecycle, collection deletion | Immutable organization; delegates to resources |
| Client/auth | `health`, `authCheck`, `auth.me` | Active; gateway bearer only |
-| Searches | `searchVideo(SearchRequest)` | Active; exact Python/Android defaults |
+| Searches | `searchVideo(SearchRequest)`, `searchBatch(List<SearchRequest>)` | Active; exact single-search contract and bounded client-side batch scheduling |
| Collections | `listGroups`, `uploadFile`, `uploadMetadataJsonl`, `addAssets`, `updateDescription`, `delete` | Active |
| Signed upload | `videoUpload`, `videoUploadBulk` | Active; signed single is default |
| Indexes | `jobsList`, `createIndex`, `indexStatus`, `deleteIndex` | Active |
diff --git a/doc/search_app.md b/doc/search_app.md
index c6103b2..36f009c 100644
--- a/doc/search_app.md
+++ b/doc/search_app.md
@@ -92,3 +92,23 @@ application client merely because a page was disposed.
If application logic inspects a structured error body, server filesystem paths
are replaced with `****` before the exception reaches the application. Do not
render the remaining raw server detail as user-facing copy.
+
+For independent low-level searches, use `client.searches.searchBatch(...)`.
+`batchSize` controls the contiguous mini-batch owned by a worker, while
+`nWorker` is the maximum number of search requests in flight. Results retain
+the input order even when network responses complete in another order:
+
+```dart
+final cancellation = CancellationToken();
+final results = await client.searches.searchBatch(
+ requests,
+ batchSize: 8,
+ nWorker: 3,
+ cancellation: cancellation,
+);
+```
+
+Keep the token with the screen, controller, or session that owns the batch.
+Cancel and await active batches before clearing or replacing authentication
+credentials, logging out, or closing `VmodalClient`. The batch helper never
+cancels a caller-owned token after an item failure and does not retry searches.
diff --git a/lib/src/resources.dart b/lib/src/resources.dart
index cb95b39..7ae2406 100644
--- a/lib/src/resources.dart
+++ b/lib/src/resources.dart
@@ -71,6 +71,95 @@ class SearchesResource {
),
);
}
+
+ /// Runs [batchQueryInput] through [searchVideo] with bounded concurrency.
+ ///
+ /// Each worker processes contiguous mini-batches of [batchSize] requests
+ /// serially. At most [nWorker] searches are in flight, and results retain
+ /// their input order. The caller owns [cancellation] and may share it with
+ /// other operations.
+ Future<List<SearchResponse>> searchBatch(
+ List<SearchRequest> batchQueryInput, {
+ int batchSize = 10,
+ int nWorker = 4,
+ CancellationToken? cancellation,
+ }) async {
+ if (batchSize <= 0) {
+ throw const ValidationException('batchSize must be greater than zero');
+ }
+ if (nWorker <= 0) {
+ throw const ValidationException('nWorker must be greater than zero');
+ }
+
+ final requests = List<SearchRequest>.of(batchQueryInput, growable: false);
+ for (final request in requests) {
+ request.validate();
+ }
+ if (requests.isEmpty) return <SearchResponse>[];
+
+ final results = List<SearchResponse?>.filled(requests.length, null);
+ final failures = <_BatchFailure>[];
+ var nextStart = 0;
+ var stopped = false;
+
+ void recordFailure(int index, Object error, StackTrace stackTrace) {
+ failures.add(_BatchFailure(index, error, stackTrace));
+ stopped = true;
+ }
+
+ Future<void> worker() async {
+ while (true) {
+ if (stopped) return;
+ try {
+ cancellation?.throwIfCanceled();
+ } on Object catch (error, stackTrace) {
+ recordFailure(nextStart, error, stackTrace);
+ return;
+ }
+ if (stopped || nextStart >= requests.length) return;
+
+ final start = nextStart;
+ final end = min(start + batchSize, requests.length);
+ nextStart = end;
+ for (var index = start; index < end; index++) {
+ if (stopped) return;
+ try {
+ cancellation?.throwIfCanceled();
+ results[index] = await searchVideo(
+ requests[index],
+ cancellation: cancellation,
+ );
+ } on Object catch (error, stackTrace) {
+ recordFailure(index, error, stackTrace);
+ return;
+ }
+ }
+ }
+ }
+
+ final batchCount = (requests.length + batchSize - 1) ~/ batchSize;
+ await Future.wait(<Future<void>>[
+ for (var index = 0; index < min(nWorker, batchCount); index++) worker(),
+ ]);
+
+ if (failures.isNotEmpty) {
+ failures.sort(
+ (_BatchFailure left, _BatchFailure right) =>
+ left.index.compareTo(right.index),
+ );
+ final failure = failures.first;
+ Error.throwWithStackTrace(failure.error, failure.stackTrace);
+ }
+ return <SearchResponse>[for (final result in results) result!];
+ }
+}
+
+final class _BatchFailure {
+ const _BatchFailure(this.index, this.error, this.stackTrace);
+
+ final int index;
+ final Object error;
+ final StackTrace stackTrace;
}
/// Collection discovery, mutation, and media-upload operations.
diff --git a/test/resources_models_test.dart b/test/resources_models_test.dart
index 6b79093..d514221 100644
--- a/test/resources_models_test.dart
+++ b/test/resources_models_test.dart
@@ -1,3 +1,4 @@
+import 'dart:async';
import 'dart:convert';
import 'dart:io';
@@ -6,6 +7,14 @@ import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';
import 'fakes.dart';
+int searchIndex(VmodalRequest request) {
+ final body = request.jsonBody! as Map<String, Object?>;
+ return int.parse((body['query_text']! as String).split('-').last);
+}
+
+VmodalResponse searchResponse(int index) =>
+ jsonResponse('{"data":[],"cnt_actual":$index,"cnt_total":$index}');
+
void main() {
test(
'search serialization preserves exact defaults and snake case',
@@ -30,6 +39,282 @@ void main() {
},
);
+ test('batch search preserves input order after mixed completion', () async {
+ final started = Completer<void>();
+ final gates = List<Completer<void>>.generate(3, (_) => Completer<void>());
+ var calls = 0;
+ final fake = HandlerTransport((VmodalRequest _) async {
+ final index = calls;
+ calls++;
+ if (calls == 3) started.complete();
+ await gates[index].future;
+ return searchResponse(index);
+ });
+ final client = VmodalClient(
+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),
+ transport: fake,
+ signedUploadTransport: FakeSignedUploadTransport(),
+ );
+ final future = client.searches.searchBatch(
+ List<SearchRequest>.generate(
+ 3,
+ (_) => const SearchRequest(queryText: 'duplicate'),
+ ),
+ batchSize: 1,
+ nWorker: 3,
+ );
+ await started.future;
+ gates[2].complete();
+ gates[0].complete();
+ gates[1].complete();
+ final results = await future;
+ expect(results.map((SearchResponse value) => value.cntActual), <int>[
+ 0,
+ 1,
+ 2,
+ ]);
+ });
+
+ test('batch search keeps worker concurrency at or below nWorker', () async {
+ final started = List<Completer<void>>.generate(
+ 11,
+ (_) => Completer<void>(),
+ );
+ final gates = List<Completer<void>>.generate(11, (_) => Completer<void>());
+ var active = 0;
+ var maxActive = 0;
+ final fake = HandlerTransport((VmodalRequest request) async {
+ final index = searchIndex(request);
+ active++;
+ if (active > maxActive) maxActive = active;
+ started[index].complete();
+ try {
+ await gates[index].future;
+ return searchResponse(index);
+ } finally {
+ active--;
+ }
+ });
+ final client = VmodalClient(
+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),
+ transport: fake,
+ signedUploadTransport: FakeSignedUploadTransport(),
+ );
+ final future = client.searches.searchBatch(
+ List<SearchRequest>.generate(
+ 11,
+ (int index) => SearchRequest(queryText: 'query-$index'),
+ ),
+ batchSize: 2,
+ nWorker: 3,
+ );
+
+ await Future.wait(<Future<void>>[
+ started[0].future,
+ started[2].future,
+ started[4].future,
+ ]);
+ gates[0].complete();
+ gates[2].complete();
+ gates[4].complete();
+ await Future.wait(<Future<void>>[
+ started[1].future,
+ started[3].future,
+ started[5].future,
+ ]);
+ gates[1].complete();
+ gates[3].complete();
+ gates[5].complete();
+ await Future.wait(<Future<void>>[
+ started[6].future,
+ started[8].future,
+ started[10].future,
+ ]);
+ gates[6].complete();
+ gates[8].complete();
+ gates[10].complete();
+ await Future.wait(<Future<void>>[started[7].future, started[9].future]);
+ gates[7].complete();
+ gates[9].complete();
+ expect(await future, hasLength(11));
+ expect(maxActive, 3);
+ });
+
+ test('batch search executes each worker mini-batch serially', () async {
+ final started = List<Completer<void>>.generate(4, (_) => Completer<void>());
+ final gates = List<Completer<void>>.generate(4, (_) => Completer<void>());
+ final fake = HandlerTransport((VmodalRequest request) async {
+ final index = searchIndex(request);
+ started[index].complete();
+ await gates[index].future;
+ return searchResponse(index);
+ });
+ final client = VmodalClient(
+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),
+ transport: fake,
+ signedUploadTransport: FakeSignedUploadTransport(),
+ );
+ final future = client.searches.searchBatch(
+ List<SearchRequest>.generate(
+ 4,
+ (int index) => SearchRequest(queryText: 'query-$index'),
+ ),
+ batchSize: 2,
+ nWorker: 2,
+ );
+ await Future.wait(<Future<void>>[started[0].future, started[2].future]);
+ expect(started[1].isCompleted, isFalse);
+ expect(started[3].isCompleted, isFalse);
+ gates[0].complete();
+ await started[1].future;
+ expect(started[3].isCompleted, isFalse);
+ gates[1].complete();
+ gates[2].complete();
+ await started[3].future;
+ gates[3].complete();
+ expect(await future, hasLength(4));
+ });
+
+ test('batch search empty and invalid inputs stay local', () async {
+ final fake = FakeTransport();
+ final client = VmodalClient(
+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),
+ transport: fake,
+ signedUploadTransport: FakeSignedUploadTransport(),
+ );
+ expect(await client.searches.searchBatch(<SearchRequest>[]), isEmpty);
+ await expectLater(
+ client.searches.searchBatch(<SearchRequest>[], batchSize: 0),
+ throwsA(isA<ValidationException>()),
+ );
+ await expectLater(
+ client.searches.searchBatch(<SearchRequest>[], nWorker: 0),
+ throwsA(isA<ValidationException>()),
+ );
+ await expectLater(
+ client.searches.searchBatch(const <SearchRequest>[
+ SearchRequest(queryText: 'valid'),
+ SearchRequest(),
+ ]),
+ throwsA(isA<ValidationException>()),
+ );
+ expect(fake.requests, isEmpty);
+ });
+
+ test('batch failure stops scheduling and reports lowest input', () async {
+ final started = List<Completer<void>>.generate(8, (_) => Completer<void>());
+ final gates = List<Completer<void>>.generate(8, (_) => Completer<void>());
+ final token = CancellationToken();
+ final fake = HandlerTransport((VmodalRequest request) async {
+ final index = searchIndex(request);
+ started[index].complete();
+ await gates[index].future;
+ if (index == 2 || index == 4) {
+ throw ApiException('failure-$index', statusCode: 500);
+ }
+ return searchResponse(index);
+ });
+ final client = VmodalClient(
+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),
+ transport: fake,
+ signedUploadTransport: FakeSignedUploadTransport(),
+ );
+ final future = client.searches.searchBatch(
+ List<SearchRequest>.generate(
+ 8,
+ (int index) => SearchRequest(queryText: 'query-$index'),
+ ),
+ batchSize: 2,
+ nWorker: 3,
+ cancellation: token,
+ );
+ final expected = expectLater(
+ future,
+ throwsA(
+ isA<ApiException>().having(
+ (ApiException value) => value.message,
+ 'message',
+ 'failure-2',
+ ),
+ ),
+ );
+ await Future.wait(<Future<void>>[
+ started[0].future,
+ started[2].future,
+ started[4].future,
+ ]);
+ gates[4].complete();
+ gates[2].complete();
+ gates[0].complete();
+ await expected;
+ expect(fake.requests, hasLength(3));
+ expect(token.isCanceled, isFalse);
+ });
+
+ test(
+ 'batch cancellation reaches active requests and stops scheduling',
+ () async {
+ final started = <Completer<void>>[Completer<void>(), Completer<void>()];
+ final fake = HandlerTransport((VmodalRequest request) async {
+ final index = searchIndex(request);
+ started[index == 0 ? 0 : 1].complete();
+ await request.cancellation.whenCanceled;
+ request.cancellation.throwIfCanceled();
+ return searchResponse(index);
+ });
+ final token = CancellationToken();
+ final client = VmodalClient(
+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),
+ transport: fake,
+ signedUploadTransport: FakeSignedUploadTransport(),
+ );
+ final future = client.searches.searchBatch(
+ List<SearchRequest>.generate(
+ 6,
+ (int index) => SearchRequest(queryText: 'query-$index'),
+ ),
+ batchSize: 2,
+ nWorker: 2,
+ cancellation: token,
+ );
+ final expected = expectLater(future, throwsA(isA<OperationCanceled>()));
+ await Future.wait(<Future<void>>[started[0].future, started[1].future]);
+ token.cancel();
+ await expected;
+ expect(fake.requests, hasLength(2));
+ expect(
+ fake.requests.every(
+ (VmodalRequest request) => request.cancellation.isCanceled,
+ ),
+ isTrue,
+ );
+ },
+ );
+
+ test('batch search reuses the normal route and request JSON', () async {
+ final fake = FakeTransport()
+ ..addResponse(jsonResponse('{"data":[],"cnt_actual":0,"cnt_total":0}'));
+ final client = VmodalClient(
+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),
+ transport: fake,
+ signedUploadTransport: FakeSignedUploadTransport(),
+ );
+ const input = SearchRequest(
+ queryText: 'batch contract',
+ groupName: 'travel',
+ streamName: 'camera',
+ limit: 7,
+ );
+ expect(
+ await client.searches.searchBatch(<SearchRequest>[input]),
+ hasLength(1),
+ );
+ final request = fake.requests.single;
+ expect(request.method, 'POST');
+ expect(request.uri.path, endsWith('/api/external/v1/search'));
+ expect(request.jsonBody, input.toJson());
+ });
+
test('model validation and numeric coercion match mobile contract', () {
expect(
() => const SearchRequest().validate(),