Skip to content

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

13.3 KB
Raw Blame
import 'api_key_provider.dart';
import 'backend_auth.dart';
import 'client.dart';
import 'collection_uploads.dart';
import 'config.dart';
import 'content_scope.dart';
import 'http.dart';
import 'models.dart';
import 'transport.dart';
import 'upload.dart';
import 'utils.dart';

/// Preferred entry point for project, collection, and stream scoped clients.
abstract final class VModal {
  /// Acquires a scoped VModal token through the host's authenticated backend.
  /// Readiness requires authoritative identity and grant confirmation.
  static Future<BackendConnection> connectWithBackend({
    required String expectedAppUserId,
    required String expectedProjectId,
    required Future<ScopedTokenEnvelope> Function() loadToken,
    Uri? baseUri,
    Duration timeout = const Duration(seconds: 30),
    int maxRetries = 1,
    Duration refreshLeeway = const Duration(seconds: 60),
    ScopedTokenEnvelope? initialToken,
    DateTime Function()? clock,
    DelayStrategy? delay,
    VmodalTransport Function(SdkConfig)? transportFactory,
    SignedUploadTransport Function(SdkConfig)? signedUploadTransportFactory,
  }) => BackendConnection.connect(
    expectedAppUserId: expectedAppUserId,
    expectedProjectId: expectedProjectId,
    loadToken: loadToken,
    baseUri: baseUri,
    timeout: timeout,
    maxRetries: maxRetries,
    refreshLeeway: refreshLeeway,
    initialToken: initialToken,
    clock: clock,
    delay: delay,
    transportFactory: transportFactory,
    signedUploadTransportFactory: signedUploadTransportFactory,
  );

  /// Creates one owned project client without performing network I/O.
  static VModalProject configure({
    required String projectId,
    required ApiKeyProvider apiKeyProvider,
    Uri? baseUri,
    Duration timeout = const Duration(seconds: 30),
    String mode = 'gateway',
    int maxRetries = 1,
  }) {
    final project = ContentScope.project(projectId);
    final config = SdkConfig(
      baseUrl: baseUri?.toString(),
      timeout: timeout,
      mode: mode,
      maxRetries: maxRetries,
      apiKeyProvider: apiKeyProvider,
    );
    return VModalProject._(project, VmodalClient(config: config));
  }

  /// Creates a project and transfers ownership of [client] to it.
  ///
  /// After this call, close the returned project instead of closing [client]
  /// separately.
  static VModalProject fromClient({
    required String projectId,
    required VmodalClient client,
  }) => VModalProject._(ContentScope.project(projectId), client);
}

/// Immutable client for one developer-owned project.
final class VModalProject {
  VModalProject._(this.projectId, this._client);

  /// Normalized public project identifier.
  final String projectId;
  final VmodalClient _client;
  bool _closed = false;

  /// Creates an immutable collection and stream scope without network I/O.
  VModalScope scope({
    required String collectionName,
    required String streamName,
  }) => VModalScope._(
    ContentScope.create(projectId, collectionName, streamName),
    _client,
  );

  /// Lists decoded logical collection names owned by this project.
  ///
  /// Backend order and the first occurrence of duplicates are preserved.
  Future<List<String>> listCollections({
    String? mode,
    CancellationToken? cancellation,
  }) async {
    final response = await _client.collections.listGroups(
      mode: mode,
      cancellation: cancellation,
    );
    final found = <String>{};
    for (final item in response.data) {
      final name = ContentScope.decodeCollection(projectId, item.groupName);
      if (name != null) found.add(name);
    }
    return found.toList(growable: false);
  }

  /// Closes the owned low-level client. Repeated calls have no effect.
  Future<void> close() async {
    if (_closed) return;
    _closed = true;
    await _client.close();
  }
}

/// Immutable operations for one project, collection, and stream.
final class VModalScope {
  VModalScope._(this._scope, this._client)
    : projectId = _scope.projectId,
      collectionName = _scope.collectionName,
      streamName = _scope.streamName;

  final ContentScope _scope;
  final VmodalClient _client;

  /// Normalized public project identifier.
  final String projectId;

  /// Normalized logical collection name.
  final String collectionName;

  /// Normalized stream name.
  final String streamName;

  /// Starts a signed upload using this scope.
  UploadTask<VideoUploadResponse> upload(
    UploadSource source, {
    ScopedUploadOptions options = const ScopedUploadOptions(),
  }) => _client.collections.videoUpload(
    source,
    collectionName: _scope.backendCollectionName,
    subCollectionName: streamName,
    mode: options.mode,
    modality: options.modality,
    ttl: options.ttl,
    options: options.uploadOptions,
  );

  /// Uploads JSON Lines metadata using this scope.
  Future<MetadataParquetUploadResponse> uploadMetadata(
    VmodalFilePart part, {
    ScopedMetadataOptions options = const ScopedMetadataOptions(),
    CancellationToken? cancellation,
  }) => _client.collections.uploadMetadataJsonl(
    part,
    mode: options.mode,
    groupName: _scope.backendCollectionName,
    streamName: streamName,
    writeMode: options.writeMode,
    allowOverlap: options.allowOverlap,
    cancellation: cancellation,
  );

  /// Searches only this collection and stream.
  Future<SearchResponse> search(
    String query, {
    ScopedSearchOptions options = const ScopedSearchOptions(),
    CancellationToken? cancellation,
  }) => _client.searches.searchVideo(
    SearchRequest(
      queryText: query,
      queryMetadata: options.queryMetadata,
      queryMetadataText: options.queryMetadataText,
      imageQuery: options.imageQuery,
      mode: options.mode,
      groupName: _scope.backendCollectionName,
      streamName: streamName,
      searchSources: options.searchSources,
      searchCombineMode: options.searchCombineMode,
      startDate: options.startDate,
      endDate: options.endDate,
      offset: options.offset,
      limit: options.limit,
      textEmbScoreMin: options.textEmbScoreMin,
      imageEmbScoreMin: options.imageEmbScoreMin,
      versionLancedb: options.versionLancedb,
    ),
    cancellation: cancellation,
  );

  /// Associates existing asset identifiers with this collection and stream.
  Future<CollectionAddAssetsResponse> addAssets(
    String collectionId,
    List<String> assetIds, {
    ScopedAddAssetsOptions options = const ScopedAddAssetsOptions(),
    CancellationToken? cancellation,
  }) => _client.collections.addAssets(
    collectionId: collectionId,
    assetIds: assetIds,
    mode: options.mode,
    groupName: _scope.backendCollectionName,
    streamName: streamName,
    cancellation: cancellation,
  );

  /// Updates one asset in this collection and stream.
  Future<CollectionDescriptionUpdateResponse> updateAsset(
    String filename, {
    required ScopedAssetChanges changes,
    CancellationToken? cancellation,
  }) {
    final clean = strRequired(filename, 'filename');
    final mode = strRequired(changes.mode, 'mode');
    return _client.collections.updateDescription(
      groupName: _scope.backendCollectionName,
      mode: mode,
      streamName: streamName,
      filenameSanitized: clean,
      description: changes.description,
      tag: changes.tags,
      cancellation: cancellation,
    );
  }

  /// Creates an index job for this collection and stream.
  Future<IndexationSubmitResponse> createIndex({
    ScopedCreateIndexOptions options = const ScopedCreateIndexOptions(),
    CancellationToken? cancellation,
  }) => _client.indexes.createIndex(
    IndexationSubmitRequest(
      mode: options.mode,
      groupName: _scope.backendCollectionName,
      streamName: streamName,
      indexType: options.indexType,
      modality: options.modality,
      insertMode: options.insertMode,
      createIndex: options.createIndex,
      version: options.version,
      startDate: options.startDate,
      endDate: options.endDate,
      embeddingModel: options.embeddingModel,
      reProcess: options.reProcess,
      dryRun: options.dryRun,
    ),
    cancellation: cancellation,
  );

  /// Lists index jobs filtered to this collection.
  Future<IndexationJobsListResponse> listIndexJobs({
    ScopedIndexJobsOptions options = const ScopedIndexJobsOptions(),
    CancellationToken? cancellation,
  }) => _client.indexes.jobsList(
    status: options.status,
    mode: options.mode,
    groupName: _scope.backendCollectionName,
    limit: options.limit,
    cancellation: cancellation,
  );

  /// Reads one index job without organization overrides.
  Future<IndexationStatusResponse> indexStatus(
    String jobId, {
    CancellationToken? cancellation,
  }) => _client.indexes.indexStatus(jobId, cancellation: cancellation);

  /// Deletes one index version from this collection.
  Future<IndexationDeleteResponse> deleteIndex(
    String version, {
    ScopedDeleteIndexOptions options = const ScopedDeleteIndexOptions(),
    CancellationToken? cancellation,
  }) => _client.indexes.deleteIndex(
    IndexationDeleteRequest(
      mode: options.mode,
      groupName: _scope.backendCollectionName,
      version: version,
      modality: options.modality,
      dryRun: options.dryRun,
      confirm: options.confirm,
    ),
    cancellation: cancellation,
  );

  /// Deletes the complete logical collection, including all streams.
  Future<DeleteCollectionResponse> deleteCollection({
    ScopedDeleteCollectionOptions options =
        const ScopedDeleteCollectionOptions(),
    CancellationToken? cancellation,
  }) => _client.collections.delete(
    groupName: _scope.backendCollectionName,
    mode: options.mode,
    scope: options.scope,
    dryRun: options.dryRun,
    confirm: options.confirm,
    cancellation: cancellation,
  );
}

/// Signed-upload behavior without organization fields.
final class ScopedUploadOptions {
  const ScopedUploadOptions({
    this.mode = 'vid_file',
    this.modality = 'vid_raw',
    this.ttl = 12600,
    this.uploadOptions = const VideoUploadOptions(),
  });

  final String mode;
  final String modality;
  final int ttl;
  final VideoUploadOptions uploadOptions;
}

/// Metadata-upload behavior without organization fields.
final class ScopedMetadataOptions {
  const ScopedMetadataOptions({
    this.mode = 'img_file',
    this.writeMode = 'append',
    this.allowOverlap = false,
  });

  final String mode;
  final String writeMode;
  final bool allowOverlap;
}

/// Search behavior without organization fields.
final class ScopedSearchOptions {
  const ScopedSearchOptions({
    this.queryMetadata,
    this.queryMetadataText,
    this.imageQuery,
    this.mode = 'vid_file',
    this.searchSources = const <String>['image'],
    this.searchCombineMode = 'union',
    this.startDate,
    this.endDate,
    this.offset = 0,
    this.limit = 50,
    this.textEmbScoreMin = 0.90,
    this.imageEmbScoreMin = 1.5,
    this.versionLancedb,
  });

  /// Legacy structured metadata query kept for source compatibility.
  @Deprecated('Use queryMetadataText for the current CCTV string contract.')
  final Map<String, Object?>? queryMetadata;

  /// CCTV metadata text serialized as the `query_metadata` string.
  final String? queryMetadataText;
  final String? imageQuery;
  final String mode;
  final List<String> searchSources;
  final String searchCombineMode;
  final String? startDate;
  final String? endDate;
  final int offset;
  final int limit;
  final double textEmbScoreMin;
  final double imageEmbScoreMin;
  final int? versionLancedb;
}

/// Add-assets behavior without organization fields.
final class ScopedAddAssetsOptions {
  const ScopedAddAssetsOptions({this.mode = 'vid_file'});

  final String mode;
}

/// Asset changes for the selected scope.
final class ScopedAssetChanges {
  const ScopedAssetChanges({
    this.mode = 'vid_file',
    this.description,
    this.tags,
  });

  final String mode;
  final String? description;
  final List<String>? tags;
}

/// Index-creation behavior without organization fields.
final class ScopedCreateIndexOptions {
  const ScopedCreateIndexOptions({
    this.mode = 'vid_file',
    this.indexType,
    this.modality,
    this.insertMode = 'append',
    this.createIndex = true,
    this.version = 'new_version',
    this.startDate,
    this.endDate,
    this.embeddingModel,
    this.reProcess = false,
    this.dryRun = false,
  });

  final String mode;
  final String? indexType;
  final String? modality;
  final String insertMode;
  final bool createIndex;
  final String version;
  final String? startDate;
  final String? endDate;
  final String? embeddingModel;
  final bool reProcess;
  final bool dryRun;
}

/// Index-job filters without organization fields.
final class ScopedIndexJobsOptions {
  const ScopedIndexJobsOptions({this.status, this.mode, this.limit = 200});

  final String? status;
  final String? mode;
  final int limit;
}

/// Index-deletion behavior without organization fields.
final class ScopedDeleteIndexOptions {
  const ScopedDeleteIndexOptions({
    this.mode = 'vid_file',
    this.modality,
    this.dryRun = false,
    this.confirm = false,
  });

  final String mode;
  final String? modality;
  final bool dryRun;
  final bool confirm;
}

/// Collection-deletion behavior without organization fields.
final class ScopedDeleteCollectionOptions {
  const ScopedDeleteCollectionOptions({
    this.mode = 'vid_file',
    this.scope = 'all',
    this.dryRun = false,
    this.confirm = false,
  });

  final String mode;
  final String scope;
  final bool dryRun;
  final bool confirm;
}