Skip to content

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

22.1 KB
Raw Blame
import 'dart:io';
import 'dart:math';
import 'dart:typed_data';

import 'errors.dart';
import 'http.dart';
import 'models.dart';
import 'routes.dart';
import 'transport.dart';
import 'upload.dart';
import 'utils.dart';

/// Authentication, identity, and service-health operations.
class AuthResource {
  /// @nodoc
  AuthResource(this.http);

  /// @nodoc
  final VmodalHttp http;

  /// Returns service health metadata.
  Future<HealthResponse> health({CancellationToken? cancellation}) async =>
      HealthResponse(
        await http.request(
          'GET',
          Routes.full(Routes.health),
          cancellation: cancellation,
        ),
      );

  /// Returns `true` when the authenticated health check completes.
  Future<bool> authCheck({CancellationToken? cancellation}) async {
    await health(cancellation: cancellation);
    return true;
  }

  /// Resolves the profile associated with the current API key.
  Future<UserProfile> me({CancellationToken? cancellation}) async =>
      UserProfile(
        await http.requestUsers(
          'GET',
          Routes.usersFull(Routes.authMe),
          cancellation: cancellation,
        ),
      );
}

/// Multimodal media-search operations.
class SearchesResource {
  /// @nodoc
  SearchesResource(this.http);

  /// @nodoc
  final VmodalHttp http;

  /// Validates [request] and returns matching media results.
  ///
  /// Use [CancellationToken.cancel] when the owning screen is disposed or a
  /// newer query supersedes this one.
  Future<SearchResponse> searchVideo(
    SearchRequest request, {
    CancellationToken? cancellation,
  }) async {
    request.validate();
    return SearchResponse(
      await http.request(
        'POST',
        Routes.full(Routes.searchClient),
        json: request.toJson(),
        cancellation: cancellation,
      ),
    );
  }

  /// 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.
class CollectionsResource {
  /// @nodoc
  CollectionsResource(this.http, this.signedUploads);

  /// @nodoc
  final VmodalHttp http;

  /// @nodoc
  final SignedUploadTransport signedUploads;

  /// Lists collections, optionally filtered by [mode].
  Future<GroupsResponse> listGroups({
    String? mode,
    CancellationToken? cancellation,
  }) async => GroupsResponse(
    await http.request(
      'GET',
      Routes.full(Routes.groups),
      params: <String, Object?>{if (mode != null) 'mode': mode},
      cancellation: cancellation,
    ),
  );

  /// Uploads a small file as one SDK request.
  ///
  /// Prefer [CollectionUploads.videoUpload] for signed uploads with progress
  /// and cancellation.
  Future<UploadResponse> uploadFile(
    VmodalFilePart part, {
    String groupName = '',
    String mode = 'vid_file',
    String streamName = 'astream',
    String description = '',
    List<String> tag = const <String>[],
    String? videoFilename,
    String? metadataText,
    List<String>? metadataTags,
    String? startDatetimeUser,
    bool reProcess = false,
    CancellationToken? cancellation,
  }) async {
    validateCctvUpload(
      mode: mode,
      sourceFileName: part.fileName,
      videoFilename: videoFilename,
      startDatetimeUser: startDatetimeUser,
    );
    final publicName = strCctvVideoFilename(
      part.fileName,
      videoFilename,
      startDatetimeUser,
    );
    return UploadResponse(
      await http.request(
        'POST',
        Routes.full(Routes.upload),
        data: <String, Object?>{
          'mode': mode,
          'group_name': groupName,
          'stream_name': streamName,
          'description': description,
          if (tag.isNotEmpty) 'tag': tag,
          if (publicName != null) 'video_filename': publicName,
          if (metadataText != null) 'metadata_text': metadataText,
          if (metadataTags != null) 'metadata_tags': metadataTags,
          if (startDatetimeUser != null)
            'start_datetime_user': startDatetimeUser,
          're_process': reProcess,
        },
        files: <VmodalFilePart>[part],
        cancellation: cancellation,
      ),
    );
  }

  /// Always throws [FeatureDisabled] before any transport call.
  Never uploadFolder() => throw const FeatureDisabled(
    'folder upload is disabled on server (cannot scan remote PC/laptop)',
  );

  /// Uploads JSON Lines metadata and returns the accepted metadata result.
  Future<MetadataParquetUploadResponse> uploadMetadataJsonl(
    VmodalFilePart part, {
    String mode = 'img_file',
    String groupName = '',
    String streamName = '',
    String writeMode = 'append',
    bool allowOverlap = false,
    CancellationToken? cancellation,
  }) async {
    final form = <String, Object?>{
      'mode': mode,
      'group_name': groupName,
      'stream_name': streamName,
      'write_mode': writeMode,
      'allow_overlap': '$allowOverlap',
      if (http.config.normalizedMode == 'direct')
        'user_id': http.config.normalizedUserId,
    };
    Map<String, Object?> raw;
    try {
      raw = await http.request(
        'POST',
        Routes.full(Routes.uploadMetadataJsonl),
        data: form,
        files: <VmodalFilePart>[part],
        cancellation: cancellation,
      );
    } on ApiException catch (error) {
      if (error.statusCode != 404) rethrow;
      raw = await http.request(
        'POST',
        Routes.uploadMetadataItemParquetInternal,
        data: form,
        files: <VmodalFilePart>[part],
        cancellation: cancellation,
      );
    }
    return MetadataParquetUploadResponse(raw);
  }

  /// Adds existing [assetIds] to a collection after local validation.
  Future<CollectionAddAssetsResponse> addAssets({
    required String collectionId,
    required List<String> assetIds,
    required String mode,
    required String groupName,
    String streamName = 'astream',
    CancellationToken? cancellation,
  }) async {
    final request = CollectionAddAssetsRequest(
      collectionId: collectionId,
      assetIds: assetIds,
      mode: mode,
      groupName: groupName,
      streamName: streamName,
    );
    request.validate();
    final path = Routes.collectionAddAssets.replaceAll(
      '{collection_id}',
      Uri.encodeComponent(collectionId),
    );
    return CollectionAddAssetsResponse(
      await http.request(
        'POST',
        Routes.full(path),
        json: request.toJson(),
        cancellation: cancellation,
      ),
    );
  }

  /// Updates the description and/or tags for one collection item.
  Future<CollectionDescriptionUpdateResponse> updateDescription({
    required String groupName,
    required String mode,
    required String streamName,
    required String filenameSanitized,
    String? description,
    List<String>? tag,
    CancellationToken? cancellation,
  }) async => CollectionDescriptionUpdateResponse(
    await http.request(
      'POST',
      Routes.full(Routes.collectionDescriptionUpdate),
      data: <String, Object?>{
        'group_name': groupName,
        'mode': mode,
        'stream_name': streamName,
        'filename_sanitized': filenameSanitized,
        if (description != null) 'description': description,
        if (tag != null) 'tag': tag,
      },
      cancellation: cancellation,
    ),
  );

  /// Deletes collection data according to [scope].
  ///
  /// Use [dryRun] to inspect the operation before setting [confirm] for a
  /// destructive deletion.
  Future<DeleteCollectionResponse> delete({
    required String groupName,
    required String mode,
    String scope = 'all',
    bool dryRun = false,
    bool confirm = false,
    CancellationToken? cancellation,
  }) async {
    final request = DeleteCollectionRequest(
      groupName: groupName,
      mode: mode,
      scope: scope,
      dryRun: dryRun,
      confirm: confirm,
    );
    request.validate();
    return DeleteCollectionResponse(
      await http.request(
        'DELETE',
        Routes.full(Routes.collectionDelete),
        json: request.toJson(),
        cancellation: cancellation,
      ),
    );
  }

  /// Always throws [FeatureDisabled]; uploads create collections implicitly.
  Never create() => throw const FeatureDisabled(
    'no server endpoint; upload creates collection implicitly',
  );

  /// Always throws [FeatureDisabled]; collection editing is not available.
  Never edit() => throw const FeatureDisabled(
    'no server endpoint; upload creates collection implicitly',
  );

  /// Always throws [FeatureDisabled] before any transport call.
  Never autoIndexGet() => throw const FeatureDisabled(
    'collection auto_index is disabled on server',
  );

  /// Always throws [FeatureDisabled] before any transport call.
  Never autoIndexSet() => throw const FeatureDisabled(
    'collection auto_index is disabled on server',
  );
}

/// Index lifecycle operations for searchable collections.
class IndexesResource {
  /// @nodoc
  IndexesResource(this.http);

  /// @nodoc
  final VmodalHttp http;

  /// Lists index jobs with optional filters.
  ///
  /// [limit] must be between 1 and 1000.
  Future<IndexationJobsListResponse> jobsList({
    String? status,
    String? mode,
    String? groupName,
    int limit = 200,
    CancellationToken? cancellation,
  }) async {
    if (limit < 1 || limit > 1000) {
      throw const ValidationException('limit must be between 1 and 1000');
    }
    return IndexationJobsListResponse(
      await http.request(
        'GET',
        Routes.full(Routes.indexationJobs),
        params: <String, Object?>{
          'limit': limit,
          if (status != null) 'status': status,
          if (mode != null) 'mode': mode,
          if (groupName != null) 'group_name': groupName,
        },
        cancellation: cancellation,
      ),
    );
  }

  /// Validates and starts an indexation job.
  Future<IndexationSubmitResponse> createIndex(
    IndexationSubmitRequest request, {
    CancellationToken? cancellation,
  }) async {
    request.validate();
    return IndexationSubmitResponse(
      await http.request(
        'POST',
        Routes.full(Routes.indexationSubmit),
        json: request.toJson(),
        cancellation: cancellation,
      ),
    );
  }

  /// Returns the latest known state for [jobId].
  Future<IndexationStatusResponse> indexStatus(
    String jobId, {
    CancellationToken? cancellation,
  }) async {
    final clean = strRequired(jobId, 'job_id');
    final path = Routes.indexationStatus.replaceAll(
      '{job_id}',
      Uri.encodeComponent(clean),
    );
    try {
      return IndexationStatusResponse(
        await http.request(
          'GET',
          Routes.full(path),
          cancellation: cancellation,
        ),
      );
    } on ApiException catch (error) {
      if (error.statusCode != 404) rethrow;
      final jobs = await jobsList(limit: 1000, cancellation: cancellation);
      final row = objectList(jobs.raw['data'])
          .where((Map<String, Object?> value) => '${value['job_id']}' == clean)
          .firstOrNull;
      if (row == null) rethrow;
      return IndexationStatusResponse(row);
    }
  }

  /// Validates and deletes the selected index data.
  Future<IndexationDeleteResponse> deleteIndex(
    IndexationDeleteRequest request, {
    CancellationToken? cancellation,
  }) async {
    request.validate();
    return IndexationDeleteResponse(
      await http.request(
        'DELETE',
        Routes.full(Routes.indexationDelete),
        json: request.toJson(),
        cancellation: cancellation,
      ),
    );
  }

  /// Always throws [FeatureDisabled] before any transport call.
  Never embeddingModels() => throw const FeatureDisabled(
    'embedding models endpoint is disabled on server',
  );
}

/// Usage and operational-statistics queries for the active identity.
class AdminResource {
  /// @nodoc
  AdminResource(this.http);

  /// @nodoc
  final VmodalHttp http;

  /// Returns user-level search statistics.
  Future<AdminUserStatsResponse> userStats({
    CancellationToken? cancellation,
  }) async => AdminUserStatsResponse(
    await http.request(
      'GET',
      Routes.full(Routes.adminUserStats),
      cancellation: cancellation,
    ),
  );

  /// Returns usage for [date], or the service default period when blank.
  Future<UsageUserDetail> usage({
    String date = '',
    CancellationToken? cancellation,
  }) async => UsageUserDetail(
    await http.requestUsers(
      'GET',
      Routes.usersFull(Routes.adminUsage),
      params: <String, Object?>{
        if (date.trim().isNotEmpty) 'date': date.trim(),
      },
      cancellation: cancellation,
    ),
  );

  /// Returns current cache and limiter statistics.
  Future<CacheStats> cacheStats({CancellationToken? cancellation}) async =>
      CacheStats(
        await http.requestUsers(
          'GET',
          Routes.usersFull(Routes.adminCacheStats),
          cancellation: cancellation,
        ),
      );
}

/// Advanced signed object-upload preparation operations.
class R2Resource {
  /// @nodoc
  R2Resource(this.http);

  /// @nodoc
  final VmodalHttp http;

  /// Creates a temporary upload grant for one file.
  Future<PresignedUploadResponse> presignUploadFile({
    required String mode,
    required String groupName,
    required String streamName,
    required String modality,
    required String filename,
    int expiresIn = 900,
    CancellationToken? cancellation,
  }) async => PresignedUploadResponse(
    await http.requestUsers(
      'GET',
      Routes.usersFull(Routes.r2UploadFile),
      params: <String, Object?>{
        'mode': mode,
        'group_name': groupName,
        'stream_name': streamName,
        'modality': modality,
        'filename': filename,
        'expires_in': expiresIn,
      },
      cancellation: cancellation,
    ),
  );

  /// Creates temporary upload grants for all [filenames].
  Future<PresignedFolderResponse> presignUploadFolderVideo({
    required String mode,
    required String groupName,
    required String streamName,
    required List<String> filenames,
    int expiresIn = 900,
    CancellationToken? cancellation,
  }) async => PresignedFolderResponse(
    await http.requestUsers(
      'POST',
      Routes.usersFull(Routes.r2UploadFolderVideo),
      json: <String, Object?>{
        'mode': mode,
        'group_name': groupName,
        'stream_name': streamName,
        'filenames': filenames,
        'expires_in': expiresIn,
      },
      cancellation: cancellation,
    ),
  );
}

/// Image-location and image-download operations.
class ImagesResource {
  /// @nodoc
  ImagesResource(this.http);

  /// @nodoc
  final VmodalHttp http;

  /// Resolves a temporary URL for one stored image.
  Future<ImageUrlResponse> getUrl({
    required String mode,
    required String groupName,
    required String modality,
    required String filename,
    String streamName = 'astream',
    Object? tsUnix13digits,
    String? userid,
    CancellationToken? cancellation,
  }) async => ImageUrlResponse(
    await http.request(
      'POST',
      Routes.full(Routes.imageGetUrl),
      json: <String, Object?>{
        'mode': mode,
        'group_name': groupName,
        'modality': modality,
        'stream_name': streamName,
        'filename': filename,
        if (tsUnix13digits != null) 'ts_unix_13digits': '$tsUnix13digits',
        if (http.config.normalizedMode == 'direct' &&
            (userid?.trim().isNotEmpty ?? false))
          'userid': userid,
      },
      cancellation: cancellation,
    ),
  );

  /// Resolves image URLs for [records] in one call.
  ///
  /// Identity fields in records are ignored outside direct mode.
  Future<ImageUrlBulkResponse> getUrlBulk(
    List<Map<String, Object?>> records, {
    String? userid,
    CancellationToken? cancellation,
  }) async {
    final safe = http.config.normalizedMode == 'direct'
        ? records
        : records
              .map(
                (Map<String, Object?> row) => Map<String, Object?>.from(row)
                  ..remove('userid')
                  ..remove('user_id'),
              )
              .toList();
    return ImageUrlBulkResponse(
      await http.request(
        'POST',
        Routes.full(Routes.imageGetUrlBulk),
        json: <String, Object?>{
          'records': safe,
          if (http.config.normalizedMode == 'direct' &&
              (userid?.trim().isNotEmpty ?? false))
            'userid': userid,
        },
        cancellation: cancellation,
      ),
    );
  }

  /// Downloads image bytes from a previously returned temporary URL.
  Future<Uint8List> getImageFromUrl(
    String urlPreSigned, {
    String? userid,
    int? maxBytes,
    CancellationToken? cancellation,
  }) => http.requestBytes(
    'POST',
    Routes.full(Routes.imageGetImage),
    json: <String, Object?>{
      'url_pre_signed': urlPreSigned,
      if (http.config.normalizedMode == 'direct' &&
          (userid?.trim().isNotEmpty ?? false))
        'userid': userid,
    },
    maxBytes: maxBytes,
    cancellation: cancellation,
  );

  /// Streams an image into a caller-owned [sink] without closing it.
  Future<void> writeImageFromUrl(
    String urlPreSigned,
    IOSink sink, {
    String? userid,
    int? maxBytes,
    CancellationToken? cancellation,
  }) => http.requestBytesToSink(
    'POST',
    Routes.full(Routes.imageGetImage),
    sink: sink,
    json: <String, Object?>{
      'url_pre_signed': urlPreSigned,
      if (http.config.normalizedMode == 'direct' &&
          (userid?.trim().isNotEmpty ?? false))
        'userid': userid,
    },
    maxBytes: maxBytes,
    cancellation: cancellation,
  );

  /// Atomically downloads an image into [destination].
  Future<File> saveImageFromUrl(
    String urlPreSigned,
    File destination, {
    String? userid,
    int? maxBytes,
    CancellationToken? cancellation,
  }) async {
    final temp = File(
      '${destination.path}.${DateTime.now().microsecondsSinceEpoch}-'
      '${Random.secure().nextInt(1 << 32)}.tmp',
    );
    final sink = temp.openWrite();
    try {
      await writeImageFromUrl(
        urlPreSigned,
        sink,
        userid: userid,
        maxBytes: maxBytes,
        cancellation: cancellation,
      );
      await sink.flush();
      await sink.close();
      await temp.rename(destination.path);
      return destination;
    } on Object catch (error, stack) {
      try {
        await sink.close();
      } on Object {
        // The sink may already be closed after a source-stream error.
      }
      if (await temp.exists()) await temp.delete();
      Error.throwWithStackTrace(error, stack);
    }
  }

  /// Downloads several images represented by [urls].
  Future<ImageGetBulkResponse> getImageBulkFromUrls(
    List<String> urls, {
    String? userid,
    CancellationToken? cancellation,
  }) async => ImageGetBulkResponse(
    await http.request(
      'POST',
      Routes.full(Routes.imageGetImageBulk),
      json: <String, Object?>{
        'urls': urls,
        if (http.config.normalizedMode == 'direct' &&
            (userid?.trim().isNotEmpty ?? false))
          'userid': userid,
      },
      cancellation: cancellation,
    ),
  );
}

/// Disabled Google Drive compatibility surface.
class GDriveResource {
  /// Always throws [FeatureDisabled] before any transport call.
  Never privateAuthUrl() => throw const FeatureDisabled(
    'private google drive auth endpoint is disabled on server',
  );

  /// Always throws [FeatureDisabled] before any transport call.
  Never privateDownload() => throw const FeatureDisabled(
    'private google drive download endpoint is disabled on server',
  );
}

/// Disabled SQL compatibility surface.
class SqlResource {
  /// Always throws [FeatureDisabled] before any transport call.
  Never query() =>
      throw const FeatureDisabled('sql query endpoint is disabled on server');
}