voplica.types.ai.dataset

The protobuf package voplica.types.ai.dataset: 0 services, 48 messages and 14 enums, defined in voplica/types/ai/dataset/dataset.proto, voplica/types/ai/dataset/dataset_generation.proto, voplica/types/ai/dataset/dataset_item_captioning_workflow.proto, voplica/types/ai/dataset/dataset_preparation.proto, voplica/types/ai/dataset/dataset_subject.proto.

Messages

Dataset

A source Dataset is a mutable, user-owned collection of same-type source assets (images, videos, or audio). It only describes which raw assets belong to the dataset. Preparation outputs (recipes, preparations, prepared items with their files and captions, snapshots) are tracked separately - see voplica/types/ai/dataset/dataset_preparation.proto.

Field	Number	Type	Label	Description
id	1	string
name	2	string
created_at	3	uint64
last_file_added_at	4	uint64		Timestamp when the last source asset was attached to the dataset.
default_preview	5	voplica.types.file.AssetFileVariantGroups	optional	Note: file_variant_groups are returned only if requested explicitly.
owner_id	6	string
visibility	7	voplica.types.base.VisibilityType
best_for_category	8	voplica.types.ai.common.SubjectCategory		Indicates the best model category the dataset could be used for.
likeness_category	9	voplica.types.base.LikenessCategory		If the dataset is of a likeness of a real person or copyright non-free content then the permission should be granted explicitly.
mpa_rating	10	voplica.types.base.MPARating		MPA rating of the content in the dataset or previews.
download_allowed	11	bool
asset_type	12	voplica.types.base.AssetType
assets_count	20	uint64		How many source assets are attached to the dataset.
likes_count	21	uint64		Unique likes count.
used_count	22	uint64		How many times the dataset was used in model trainings (sum across all training jobs that referenced this dataset, regardless of who triggered the training).
views_count	23	uint64		Engagement metrics (read-only, updated by the platform). Renamed from checks_count/views_count – see the checks->views/views->engagement terminology rename.
engagement_count	24	uint64

DatasetMetadata

Owner-only metadata for a source dataset. Preparation lifecycle hints live here so they are not exposed publicly on the listed Dataset payload.

Field	Number	Type	Label	Description
description	1	string
has_source_changes_since_latest_preparation	2	bool		Coarse hint for the owner: true when source dataset membership changed after the most recent owner-triggered preparation run completed. Exact readiness still depends on a recipe-specific preparation plan (see PlanDatasetPreparation).
default_preview_manual_selected	3	bool		Manually set default preview asset. If false - the default preview uses the latest asset selection strategy.
current_dataset_preparation_job_status	4	voplica.types.base.JobStatus		Status of the most recent dataset preparation run triggered for this source dataset by the owner. For non-owner-triggered preparation runs, consult the run record directly (see GetDatasetPreparationRun).
current_dataset_preparation_workflow_execution_id	5	string	optional	Workflow execution id for the current or most recent owner-triggered preparation run.
current_dataset_preparation_message	6	string	optional	If the last owner-triggered dataset preparation failed, this carries the error message.
revenue_share	7	bool		Whether the dataset is eligible for revenue sharing.
latest_preparation_id	8	string	optional	Preparation most recently written by an owner-triggered preparation run, if any. UI hint only; enumerate all preparations via ListDatasetPreparations(source_dataset_id). Immutable training snapshots are frozen from preparations at training time, not tracked here.
visible_preparations_count	9	uint64		How many preparations exist for this dataset that the owner can see. Not exposed on the public Dataset payload.
current_dataset_preparation_run_id	10	string	optional	Run id of the current/most recent owner-triggered preparation.
revenue_share_blocked	11	bool	optional	Admin-set kill switch: blocks revenue-share eligibility regardless of the owner’s revenue_share flag. Owner/admin view only.
revenue_share_eligibility	12	voplica.types.ai.model.RevenueShareEligibility		Computed eligibility (and, when ineligible, why). Owner/admin view only.

DatasetGenerationParams

Tuning for one dataset generation run. Frozen onto the run at trigger time and forwarded to the worker verbatim - the worker never re-resolves them.

Field	Number	Type	Label	Description
image_count	1	uint32		How many images the run should produce in total (across all selected looks). The shot matrix is capped to this count. 0 is invalid and treated as absent (the service applies its default) - never a truthiness check.
size_class	2	DatasetGenerationSizeClass		Output size class. UNSPECIFIED = MEDIUM (~1 MP). The worker maps the class to dimensions.
refine	3	bool	optional	The skin-texture refine pass after each generated image. DEFAULT IS TRUE, which is not the proto3 bool default: absent means true, and only an explicit false disables it - read it with a presence check.
edit_model_variant_id	4	string	optional	Explicit edit-model variant id. Absent = the default edit model family (QWEN_IMAGE_EDIT_2511). An explicit variant wins.
cover_emotions	5	bool		Coverage toggles. When true, the deterministic shot matrix additionally varies the axis; when false the axis is held at its neutral value. Both widen the matrix, so a fixed image_count spreads across more combinations rather than producing more images.
cover_environments	6	bool

DatasetGenerationRun

Process-lineage record for one dataset generation run: “this execution rendered THESE looks of THIS character into THAT dataset”. One run == one workflow execution == one engine idempotency key (the run id is a 26-char ULID and passes through toEngineIdempotencyKey untouched).

Field	Number	Type	Label	Description
id	1	string
dataset_id	2	string		The IMAGE_ASSET dataset the generated images are attached to. Always populated - for an inline-new-dataset request the service creates the dataset BEFORE the run row, so a run never exists without its target.
character_id	3	string		The character whose identity every shot is conditioned on.
look_ids	4	string	repeated
owner_id	5	string		User who triggered the run, pays for it, and owns every file/asset it produces.
params	6	DatasetGenerationParams		Frozen tuning for this run.
state	7	voplica.types.base.JobStatus		Lifecycle state. PENDING at creation, RUNNING once the workflow reports started, then COMPLETED/FAILED/CANCELLED. The Workflow Engine wins over worker-reported terminal status (the worker’s message and counts are still persisted).
workflow_execution_id	8	string	optional
root_workflow_execution_id	9	string		Root workflow execution that triggered this run - the wrapper execution the user is billed for. Populated at trigger time.
requested_images_count	10	uint32		How many images the run intends to produce (the planned shot count after capping by params.image_count).
generated_images_count	11	uint32
failed_images_count	12	uint32		Shots that failed. Per-shot failures are isolated - one failed shot never fails the run; an all-failed run terminates FAILED.
face_confidence_avg	13	float	optional	Face-confidence aggregates over the images that carried a score (scored after refine, against the look’s FACE_CLOSEUP baseline). Absent while no image has been scored. A low score never fails or retries a run: it is a quality signal to read before training.
face_confidence_min	14	float	optional
created_at	15	uint64		Epoch milliseconds.
started_at	16	uint64	optional	When the workflow actually began executing. Absent while PENDING.
completed_at	17	uint64	optional	When the run reached a terminal state. Absent until then.
message	18	string	optional	Terminal detail (failure reason, cancellation note, all-failed summary).

DatasetItemCaptioningScope

Which items to caption.

Field	Number	Type	Label	Description
target_keys	1	string	repeated
categories	2	voplica.types.ai.common.SubjectCategory	repeated
subject_ids	3	string	repeated
source_asset_ids	4	string	repeated
only_missing	5	bool		true (default expectation): caption only items MISSING one of the requested formats. false: also regenerate existing AUTO_GENERATED captions of those formats (USER_* are never touched either way).

AudioDatasetPreparationRecipe

Field	Number	Type	Label	Description
sample_rate	1	uint32
channels_count	2	uint32
segment_length_ms	3	uint64
normalize_loudness	4	bool
remove_silence	5	bool

BackgroundCrop

Field	Number	Type	Label	Description
preferred_centric_position_selection_prompt	1	string	optional	Optional prompt to bias what to keep when cropping (for example “face” for full-body character preparation).

DatasetCaptionGenerationConfig

Auto-generation tuning for item captions. The captioner reads, per item: the item’s TRAINING_SAMPLE crop, the WHOLE source image (context), the membership row’s auto_caption_hint, the target’s category, and - when the item belongs to a subject - the subject’s name/description.

Field	Number	Type	Label	Description
class_word	1	string	optional	Optional class word hint fed to the captioner (e.g. “man”, “dog”, “car”). It becomes part of the generated text as descriptive content; it is NOT a training-time trigger word.
prepend_text	2	string	optional	Optional fixed prefix/suffix wrapped around the generated text.
append_text	3	string	optional
conflict_strategy	4	voplica.types.ai.common.CaptioningConflictStrategy
target_model_families	5	voplica.types.ai.common.ModelFamily	repeated	Model families this caption style targets (informational hint for picking a captioner).
generation_params	20	google.protobuf.Struct		Free-form generation parameters consumed by the captioning worker (model name, task token, max tokens, temperature, …).

DatasetPreparation

The mutable container of prepared items for one (source_dataset, recipe). Find-or-created by PrepareDataset (or at training start for recipe selections).

Field	Number	Type	Label	Description
id	1	string
source_dataset_id	2	string
recipe_id	3	string	optional	Recipe this preparation materializes (persistent id when available; always carries the fingerprint). Unique key: (source_dataset_id, recipe_fingerprint).
recipe_fingerprint	4	string
asset_type	5	voplica.types.base.AssetType
owner_id	6	string
name	13	string	optional	Optional user-assigned display name (“Anna — face+body v2”). Pure display metadata: mutable via UpdateDatasetPreparationConfig, settable at PrepareDataset time, and NEVER part of any fingerprint or reuse key. UIs list preparations as name (id) and fall back to the recipe name / fingerprint when unnamed.
created_at	7	uint64		Seconds since epoch.
updated_at	8	uint64
version	9	uint64		The ONLY change signal, bumped on: item file add/override/reset, caption upsert/delete/generate, exclude/unexclude, and subject reassignment touching this preparation’s items. Config changes below do NOT bump it (they alter future planned work, not frozen content).
embedded_recipe	10	DatasetPreparationRecipe	optional	Full recipe payload for AD-HOC recipes (no recipe_id), persisted so auto-preparation can still resolve the recipe later. Populated in responses only when GetDatasetPreparationRequest.include_full_recipe = true.
subject_scope	11	DatasetPreparationSubjectScope		MUTABLE, dataset-local configuration. NOT part of any fingerprint.
captioning	12	DatasetPreparationCaptioningConfig
items_count	20	uint64
prepared_assets_count	21	uint64		Distinct source assets having at least one item.
excluded_items_count	22	uint64

DatasetPreparationCaptioningConfig

Field	Number	Type	Label	Description
formats	1	DatasetCaptionFormat	repeated	Formats auto-generated for every item (e.g. [TAGS, NATURAL_LANGUAGE]). Missing formats count as caption WORK in plans/runs. EMPTY disables auto-captioning (typical for STYLE - items then train caption-less with trigger words only). Independent of the targets’ subject_mode: whole-image BACKGROUND/PLACE items are captioned like any crop (the “crop” is the whole-image variant).
generation_config	2	DatasetCaptionGenerationConfig

DatasetPreparationPlan

Readiness answer for “what do the selected source assets still need before training?”. Computed against the dataset’s DatasetPreparation for the recipe (which may not exist yet - then everything is missing).

Field	Number	Type	Label	Description
source_dataset_id	1	string
reuse_policy	2	DatasetPreparationReusePolicy
recipe_fingerprint	3	string
preparation_id	4	string	optional	The preparation the plan was computed against. Empty when none exists yet.
preparation_version	5	uint64
items	6	DatasetPreparationPlanItem	repeated	Per-asset readiness. For very large selections the service MAY truncate this list (the counts below always cover the FULL selection); items_truncated = true signals that.
items_truncated	7	bool
items_to_prepare_count	8	uint64		Per-asset action counts (v2-compatible semantics).
items_to_reuse_count	9	uint64
items_to_skip_count	10	uint64
items_to_fail_count	11	uint64
expected_items_count	12	uint64		Item-granular work counts (what the run would actually produce / cost).
files_to_generate_count	13	uint64
captions_to_generate_count	14	uint64
assets_requiring_instance_discovery_count	15	uint64

DatasetPreparationPlanItem

Field	Number	Type	Label	Description
source_asset_id	1	string
source_file_id	2	string
source_item_fingerprint	3	string
action	4	DatasetPreparationPlanAction
requires_instance_discovery	5	bool		True when the asset has no subject-instance analysis yet and the recipe has PER_SUBJECT_INSTANCE targets: the run will discover + auto-assign instances first, then derive the concrete expected items. expected_items is then a lower bound (whole-image targets only).
expected_items	6	ExpectedPreparedItem	repeated	Exactly what is missing for this asset. Empty for action=REUSE_PREPARED_ITEM.
message	7	string	optional

DatasetPreparationRecipe

Field	Number	Type	Label	Description
id	1	string		Optional persistent recipe id. Ad-hoc recipes leave this empty and use recipe_fingerprint as identity.
name	2	string		Display name for persistent recipes. Empty for ad-hoc recipes.
owner_id	3	string		Owner of the persistent recipe row. Empty for ad-hoc recipes.
visibility	4	voplica.types.base.VisibilityType		Visibility of the persistent recipe. Ignored for ad-hoc recipes.
created_at	5	uint64
description	6	string	optional
asset_type	10	voplica.types.base.AssetType		Source asset type this recipe operates on. Must match the source dataset.
target_model_families	12	voplica.types.ai.common.ModelFamily	repeated	NOTE: there is deliberately NO recipe-level category. Category is a per-TARGET property (ImageDatasetPreparationTarget.category): one recipe routinely carries a face target (CHARACTER_FACE) and a full-body target (CHARACTER_GENERIC) side by side. Hints which model families this recipe was designed for. Informational; the recipe can still be selected for any compatible training.
required_file_kinds	14	PreparedFileKind	repeated	File kinds every item must carry. Items missing any required kind count as missing work in plans/runs (subject to reuse policy). Caption WORK is configured separately on the preparation (DatasetPreparationCaptioningConfig), not on the recipe - recipes stay caption-free so tuning the captioner never rotates recipe_fingerprint.
image	20	ImageDatasetPreparationRecipe	oneof media_recipe
video	21	VideoDatasetPreparationRecipe	oneof media_recipe
audio	22	AudioDatasetPreparationRecipe	oneof media_recipe
model_3d	23	Model3DDatasetPreparationRecipe	oneof media_recipe
recipe_fingerprint	30	string
implementation_version	31	string		Version of preparation code/models. Must be included in recipe_fingerprint. Bump when worker outputs change for the same recipe payload.
metadata	32	google.protobuf.Struct		Free-form metadata. Only entries that affect preparation outputs should be included here; otherwise document-only metadata belongs in description or external storage.

DatasetPreparationRun

Process-lineage record for one dataset preparation run: “this execution considered THESE frozen source inputs and produced/reused items in the dataset’s DatasetPreparation”. The run owns everything process-shaped: the frozen work items (paged via ListDatasetPreparationRunItems), progress counts, and terminal status. DatasetPreparationSnapshots are deliberately NOT tied to runs - they are instant freezes of the preparation, and one version may have been filled by many runs.

Field	Number	Type	Label	Description
id	1	string
preparation_id	2	string		The mutable preparation this run writes into.
source_dataset_id	3	string
recipe_fingerprint	4	string		Denormalized from the preparation for filtering.
owner_id	5	string		User who triggered the run (and pays for it).
workflow_execution_id	6	string	optional	The workflow execution that runs the preparation: for a standalone preparation run, the root execution; for one started by a combined prepare-and-train run, the child execution (the parent is in root_workflow_execution_id). Empty until the execution is launched.
root_workflow_execution_id	7	string		Root workflow execution that triggered this run. Equals workflow_execution_id for standalone runs; the combined parent for prepare-and-train children. Always populated when the run is created (before any workflow starts).
status	8	voplica.types.base.JobStatus
started_at	9	uint64		Seconds since epoch.
completed_at	10	uint64	optional
message	11	string	optional
reuse_policy	12	DatasetPreparationReusePolicy		Snapshot of the reuse policy used for this run.
source_snapshot_fingerprint	13	string		Fingerprint + size of the run’s frozen source snapshot. The item list is paged via ListDatasetPreparationRunItems (never embedded).
source_items_count	14	uint64
prepared_items_count	15	uint64
reused_items_count	16	uint64
skipped_items_count	17	uint64
failed_items_count	18	uint64
files_generated_count	19	uint64		Item-granular outcome counts.
captions_generated_count	20	uint64

DatasetPreparationRunItem

One frozen work item of a preparation run: the source item the run considered plus its planned action and exactly which files/captions were missing at plan time. Persisted at PrepareDataset time and paged via ListDatasetPreparationRunItems. Authoritative for the worker - it MUST NOT re-query dataset membership.

Field	Number	Type	Label	Description
preparation_run_id	1	string
source_item	2	DatasetPreparationSourceItemSnapshot
planned_action	3	DatasetPreparationPlanAction
requires_instance_discovery	4	bool
expected_items	5	ExpectedPreparedItem	repeated
message	6	string	optional

DatasetPreparationSnapshot

An immutable, instant, lifecycle-free SNAPSHOT of a DatasetPreparation at a version - the frozen training data a run consumed. Find-or-created by (preparation_id, version): reused when that version is already frozen, otherwise the current NON-EXCLUDED items (files + captions + subject labels) are frozen in one operation. Born complete; never changes. Preparation PROGRESS lives on DatasetPreparationRun, never here.

Field	Number	Type	Label	Description
id	1	string
preparation_id	2	string		The preparation and the version this snapshot froze.
version	3	uint64
source_dataset_id	4	string
recipe_id	5	string	optional
recipe_fingerprint	6	string
embedded_recipe	7	DatasetPreparationRecipe	optional	Gated by DatasetPreparationSnapshotFetchingOptions.include_full_recipe.
recipe_summary	8	DatasetPreparationSnapshotRecipeSummary
content_fingerprint	9	string		Content identity over the frozen items: hash{preparation_id, version, items sorted by (source_asset_id, subject_instance_id|“”, target_key) -> {item_fingerprint, subject_id|“”, captions: sorted format -> sha256(text)}}. Covers visuals AND captions AND subject labels - the three things training consumes. Non-unique verify hint.
created_at	10	uint64		Seconds since epoch.
items_count	11	uint64
prepared_assets_count	12	uint64
subjects_count	13	uint64		Distinct subject identities frozen into the items.
file_kinds_present	14	PreparedFileKind	repeated	Capability summary so training resolution can fail fast (e.g. “no MASK files”, “no TAGS captions”) without paging items.
caption_formats_present	15	DatasetCaptionFormat	repeated
owner_id	16	string		Owner of the preparation at freeze time. Visibility for other users follows the source dataset visibility plus the dataset’s download_allowed flag.

DatasetPreparationSnapshotFetchingOptions

Field	Number	Type	Label	Description
include_full_recipe	1	bool		When true, the snapshot response also includes the full DatasetPreparationRecipe (resolved either from the persistent recipe row or from the stored ad-hoc payload). Frozen items are never embedded - page them via ListDatasetPreparationSnapshotItems.

DatasetPreparationSnapshotItem

One frozen item of a snapshot - a faithful copy of a PreparedItem (files + captions nested), so ONE paged read streams complete (image, caption[, mask]) tuples.

Field	Number	Type	Label	Description
id	1	string
preparation_snapshot_id	2	string
prepared_item_id	3	string		Lineage to the live item this row froze.
source_asset_id	4	string
subject_instance_id	5	string	optional
subject_id	6	string	optional	The identity assignment AT FREEZE TIME (the filter target of training selections).
target_key	7	string
category	8	voplica.types.ai.common.SubjectCategory
files	9	PreparedItemFile	repeated
captions	10	PreparedItemCaption	repeated
item_fingerprint	11	string
resolution	12	voplica.types.image.ImageSize	optional
aspect_ratio	13	voplica.types.image.AspectRatioType	optional

DatasetPreparationSnapshotRecipeSummary

Summary of the recipe used by a snapshot, for cheap list rendering.

Field	Number	Type	Label	Description
recipe_id	1	string	optional
recipe_fingerprint	2	string
implementation_version	3	string
asset_type	4	voplica.types.base.AssetType
target_categories	5	voplica.types.ai.common.SubjectCategory	repeated	Categories of the recipe’s targets (e.g. [CHARACTER_GENERIC, CHARACTER_FACE]).
required_file_kinds	6	PreparedFileKind	repeated
recipe_name	7	string		Recipe display name when a persistent recipe was used. Empty otherwise.

DatasetPreparationSourceItemSnapshot

Frozen snapshot of one source asset captured at the start of a preparation run. The snapshot is what the worker actually consumes - the source dataset itself is mutable.

Field	Number	Type	Label	Description
source_asset_id	1	string
source_file_id	2	string
source_file_fingerprint	3	string		Stable hash of the source file bytes or source file version.
source_item_fingerprint	4	string

DatasetPreparationSourceSnapshot

Frozen snapshot of the source-dataset membership one preparation run operated on. Owned by a DatasetPreparationRun (process lineage: “what inputs did this run consider”); it is NOT part of a DatasetPreparationSnapshot, whose identity is its frozen items. Callers use source_snapshot_fingerprint to detect dataset drift between planning and preparing.

Field	Number	Type	Label	Description
source_dataset_id	1	string
captured_at	2	uint64
last_asset_added_at	3	uint64
assets_count	4	uint64
source_snapshot_fingerprint	5	string		Stable hash over the sorted source_item_fingerprints in items. Lookup-only - services verify canonical item-list equality on hash match.
items	6	DatasetPreparationSourceItemSnapshot	repeated	Full snapshot of the selected source items. For very large snapshots, services may omit items from list/get responses and expose membership via dedicated RPCs.

DatasetPreparationSubjectScope

Field	Number	Type	Label	Description
mode	1	DatasetSubjectScopeMode
subject_ids	2	string	repeated	For LISTED_SUBJECTS.
max_instances_per_asset_per_target	3	uint32		Cost guard for crowd photos. 0 = unlimited.
fast_path_mode	4	DatasetFastPathMode		Fast-path override (applies only while mode is unset/empty - a curated scope always wins). UNSPECIFIED = AUTO.

ExpectedPreparedItem

One expected-but-missing training example (readiness unit inside plan/run items).

Field	Number	Type	Label	Description
subject_instance_id	1	string	optional	Empty for WHOLE_IMAGE targets and for assets whose instances are not discovered yet.
target_key	2	string
missing_file_kinds	3	PreparedFileKind	repeated	Visual work still needed for this item.
missing_caption_formats	4	DatasetCaptionFormat	repeated	Caption work still needed (per DatasetPreparationCaptioningConfig.formats).

ImageBackgroundNormalization

Field	Number	Type	Label	Description
masked_background_generation	1	MaskedBackgroundGeneration	oneof strategy
similar_background_extension	2	SimilarBackgroundExtension	oneof strategy
random_color_extension	3	RandomColorBackgroundExtension	oneof strategy
background_crop	4	BackgroundCrop	oneof strategy

ImageDatasetPreparationRecipe

Image-specific recipe. targets defines the prepared image variants the recipe must produce, for example “full_body_1024_square” and “face_1024_square”.

Field	Number	Type	Label	Description
targets	1	ImageDatasetPreparationTarget	repeated
background_normalization	3	ImageBackgroundNormalization
generate_masks	4	bool		When true, produce mask artifacts (kind=MASK) for every target.
generate_alpha_images	5	bool		When true, produce alpha artifacts (kind=ALPHA) for every target.
preserve_analysis_metadata	6	bool		When true, persist analysis metadata files (kind=ANALYSIS_METADATA).

ImageDatasetPreparationTarget

Field	Number	Type	Label	Description
key	1	string		Stable target key, for example “full_body_1024_square” or “face_1024_square” - authored by the RECIPE CREATOR as a name for this output variant (a named output port); must be unique within one recipe. Workers stamp it onto every PreparedItem produced from this target; item filters and ModelTrainingDataset.target_keys reference it (the precision filter beside the semantic categories filter).
resolution	2	voplica.types.image.ImageSize
aspect_ratio	3	voplica.types.image.AspectRatioType	optional
crop_policy	4	ImageDatasetCropPolicy
preferred_focus_prompt	5	string	optional	Optional natural-language hint used to bias the crop (for example “face” or, for WHOLE_IMAGE targets, what to keep when cropping to the aspect ratio).
min_subject_side_pixels	6	uint32		When > 0, a subject instance smaller than this (pixels, either dimension of the framed region) is skipped for THIS target only - e.g. a higher threshold for a full-body target and a lower one for a face target. 0 means no size threshold.
category	7	voplica.types.ai.common.SubjectCategory		What KIND of training example this target produces (CHARACTER_FACE for a face crop, CHARACTER_GENERIC for a full-body crop, OBJECT, STYLE, …). REQUIRED; the structural face-vs-body discriminator that training selections filter by. Fingerprint-affecting.
subject_mode	8	ImageTargetSubjectMode		Whole-image vs per-subject-instance expansion. Fingerprint-affecting.
framing	9	ImageSubjectFraming		PER_SUBJECT targets only: which region drives the crop. Fingerprint-affecting.
min_instance_quality	10	float		PER_SUBJECT targets only: skip instances whose quality_score is below this (0 = no threshold). Drops tiny/blurry background faces before any GPU work.

MaskedBackgroundGeneration

Field	Number	Type	Label	Description
keep_masked_area_coefficient	1	double		1.0 keeps the masked area exactly. Lower values let the worker blend masked pixels into the regenerated background.
preferred_background_variations_count	2	uint32		0 means “implementation-defined default” (typically Min(365, dataset_assets_count)).

Model3DDatasetPreparationRecipe

3D-asset preparation. Placeholder shape - extend with actual normalization fields when the first 3D training worker lands. Behavior-affecting fields contribute to recipe_fingerprint; display-only fields go into the parent recipe’s metadata.

Field	Number	Type	Label	Description
target_polygon_count	1	uint32		Target polygon count after decimation. 0 means no decimation.
target_texture_resolution	2	uint32		Target texture resolution in pixels (longest side). 0 means keep source resolution.
canonical_format	3	string	optional	Re-export to a canonical format (for example “glb”, “obj”, “fbx”). Empty preserves the source format.
normalize_scale_and_origin	4	bool		When true, normalize the mesh into a unit-sized bounding box centered at the origin.
subject_selection_prompt	5	string	optional	Optional captioning prompt for renders used by multimodal text encoders.

PreparedItem

One training example. Natural key: (preparation_id, source_asset_id, subject_instance_id|“”, target_key).

Field	Number	Type	Label	Description
id	1	string
preparation_id	2	string
source_dataset_id	3	string
source_asset_id	4	string
subject_instance_id	5	string	optional	The detected subject instance this item crops (see voplica/types/ai/dataset/dataset_subject.proto). EMPTY for WHOLE_IMAGE targets.
subject_id	6	string	optional	Denormalized CURRENT identity assignment of that instance. Curation rewrites it (and bumps the preparation version - subject labels are frozen snapshot content). Empty for whole-image items and unassigned instances.
target_key	7	string
category	8	voplica.types.ai.common.SubjectCategory		Denormalized from the recipe target - the structural face-vs-body-vs-style discriminator training selections filter by.
files	9	PreparedItemFile	repeated	At most one per kind.
captions	10	PreparedItemCaption	repeated	At most one per format.
excluded	11	bool		Curation: excluded items are omitted from future snapshots (and from training).
excluded_reason	12	string	optional
resolution	13	voplica.types.image.ImageSize	optional
aspect_ratio	14	voplica.types.image.AspectRatioType	optional
item_fingerprint	15	string
created_at	16	uint64		Seconds since epoch.
updated_at	17	uint64
metadata	20	google.protobuf.Struct
captioning_context	21	PreparedItemCaptioningContext	optional	Populated only when requested via PreparedItemFetchingOptions.include_captioning_context.

PreparedItemCaption

One caption of a prepared item (at most ONE per format - service-enforced). The text never contains trigger words - those are applied per training selection at load time.

Field	Number	Type	Label	Description
format	1	DatasetCaptionFormat
text	2	string
provenance	3	DatasetContentProvenance
updated_at	4	uint64		Seconds since epoch. Together with provenance, lets a UI surface cross-format staleness (the user edited NATURAL_LANGUAGE; TAGS is still AUTO from an older pass).

PreparedItemCaptioningContext

Captioning context assembled on demand (fetching option), so the captioning worker can read everything it needs in the same paged stream as the items.

Field	Number	Type	Label	Description
source_file	1	voplica.types.file.FileInfo	optional	The WHOLE source image (context for describing the crop).
auto_caption_hint	2	string	optional	The membership row’s auto_caption_hint (“John, a 30yo man with brown hair”).
subject_name	3	string	optional	The assigned subject’s name/description, when any (“Anna”; “gold bracelet with an emerald stone”).
subject_description	4	string	optional

PreparedItemFetchingOptions

File hydration + context assembly for prepared items and frozen snapshot items.

Field	Number	Type	Label	Description
files_retriever	1	voplica.types.file.FilesRetriever	optional	When set, item file FileInfos are hydrated with their variants.
include_captioning_context	2	bool		When true, PreparedItem.captioning_context is populated (source file + hint + subject name/description) - the captioning worker’s one-stream read.

PreparedItemFile

One file of a prepared item (at most ONE per kind - service-enforced).

Field	Number	Type	Label	Description
kind	1	PreparedFileKind
file	2	voplica.types.file.FileInfo
provenance	3	DatasetContentProvenance
prepared_file_fingerprint	4	string
updated_at	5	uint64		Seconds since epoch.

RandomColorBackgroundExtension

No fields.

SimilarBackgroundExtension

No fields.

VideoDatasetPreparationRecipe

Video-specific recipe. Like images, targets defines the named prepared clip variants the recipe must produce, so prepared video artifacts are addressable by target_key (training selections and artifact reads filter by target exactly as for images).

Field	Number	Type	Label	Description
targets	1	VideoDatasetPreparationTarget	repeated
extract_audio	2	bool		When true, each produced clip additionally carries its extracted audio segment as an AUDIO_TRACK companion file (time-aligned with the clip). The clip’s own muxed audio is preserved regardless - audio-capable trainers (LTX do_audio) read it from the clip.
subject_selection_prompt	3	string	optional
preserve_analysis_metadata	4	bool

VideoDatasetPreparationTarget

Field	Number	Type	Label	Description
key	1	string		Stable target key, for example “clip_720p_24fps_5s” - authored by the recipe creator, unique within one recipe, stamped onto produced items, referenced by selection filters (see the image target’s key comment).
resolution	2	voplica.types.image.ImageSize
frame_rate	3	uint32
clip_length_ms	4	uint64
category	5	voplica.types.ai.common.SubjectCategory		What KIND of training example this target produces (mirrors the image target field; PreparedItem.category is denormalized from it). REQUIRED; fingerprint-affecting.
subject_mode	6	ImageTargetSubjectMode		Whole-clip vs per-subject-instance expansion. PER_SUBJECT_INSTANCE expands over the asset’s in-scope subject instances’ video_track locators: the produced clip windows are intersected with the track’s [start_ms, end_ms] and cropped to a smoothed window that follows the tracked subject. Fingerprint-affecting.
framing	7	ImageSubjectFraming		PER_SUBJECT targets only: which region drives the tracked crop window - the subject box or the track’s keyframe face region (CHARACTER subjects). Fingerprint-affecting.
min_subject_side_pixels	8	uint32		When > 0, a subject instance whose framed region (at the track keyframe) is smaller than this in pixels (either dimension) is skipped for THIS target only. 0 = no threshold. Mirrors the image target field.
min_instance_quality	9	float		PER_SUBJECT targets only: skip instances whose quality_score is below this (0 = no threshold). Mirrors the image target field.

AudioSubjectSegment

Where a subject occurs inside an AUDIO asset: one contiguous segment (e.g. one diarized speaker turn; the embedding is then a speaker embedding).

Field	Number	Type	Label	Description
start_ms	1	uint64
end_ms	2	uint64
channel	3	uint32	optional	Channel index for multi-channel sources. 0-based; unset = mixed/mono.

DatasetSubject

One dataset-level identity.

Field	Number	Type	Label	Description
id	1	string
source_dataset_id	2	string
owner_id	3	string
name	4	string		Auto: “Subject 1”, “Subject 2”; user renames (“Anna”, “Emerald bracelet”).
description	5	string	optional
category	6	voplica.types.ai.common.SubjectCategory		What kind of subject this is. LOCALIZABLE categories only (CHARACTER_GENERIC, OBJECT, VEHICLE, CLOTHES, …) - never whole-image categories, never CHARACTER_FACE (a face is a target FRAMING of a CHARACTER subject, not a subject kind).
origin	7	DatasetSubjectOrigin
references	8	DatasetSubjectReference	repeated	User-provided exemplars (see DatasetSubjectReference). Optional for clustered person subjects; the defining input for object subjects.
embedding_model_version	10	string
instances_count	12	uint64
assets_count	13	uint64		Distinct source assets containing at least one assigned instance.
created_at	14	uint64		Seconds since epoch.
updated_at	15	uint64
short_preview	16	DatasetSubjectShortPreview	optional	Subject preview (converted Asset) + which source is currently selected as the avatar (a member instance’s detected crop or one of the subject’s reference files). Populated on List/Get ONLY when a previews_retriever is supplied. Mirrors the GenModel.default_model_variant ShortPreview pattern so subjects list WITH their preview in one query.

DatasetSubjectDiscoveryPolicy

Field	Number	Type	Label	Description
recluster_only	1	bool		Skip per-asset analysis; re-run only the clustering activity over stored instances.
min_quality	2	float		Instances below this quality are left UNASSIGNED by clustering. 0 = worker default.
cluster_distance_threshold	3	float		Embedding-distance threshold for cluster membership / centroid matching. 0 = worker default.
preserve_user_assignments	4	bool		Default true: USER_ASSIGNED / USER_REJECTED instances are never moved, and clusters are seeded from user-confirmed members.

DatasetSubjectDiscoveryRun

Process-lineage record for one subject-discovery execution: per-asset analysis fan-out followed by a single clustering activity. Frozen inputs + outcome counts live here.

Field	Number	Type	Label	Description
id	1	string
source_dataset_id	2	string
owner_id	3	string
workflow_execution_id	4	string	optional
root_workflow_execution_id	5	string
status	6	voplica.types.base.JobStatus
started_at	7	uint64		Seconds since epoch.
completed_at	8	uint64	optional
message	9	string	optional
policy	10	DatasetSubjectDiscoveryPolicy
source_snapshot_fingerprint	11	string		Frozen source membership summary (items paged via ListDatasetSubjectDiscoveryRunItems).
source_items_count	12	uint64
analyzed_items_count	13	uint64		Outcome counts, finalized at terminal state.
reused_items_count	14	uint64
failed_items_count	15	uint64
instances_count	16	uint64
subjects_count	17	uint64		Clusters produced or updated by the clustering activity.

DatasetSubjectDiscoveryRunItem

One frozen work item of a discovery run (paged; authoritative for the worker - it MUST NOT re-query dataset membership).

Field	Number	Type	Label	Description
discovery_run_id	1	string
source_item	2	DatasetPreparationSourceItemSnapshot
planned_action	3	DatasetSubjectDiscoveryPlanAction
message	4	string	optional

DatasetSubjectInstance

One detected subject instance in one source asset. Written by workers, curated by the user.

Field	Number	Type	Label	Description
id	1	string
source_dataset_id	2	string
source_asset_id	3	string
source_file_id	4	string
source_item_fingerprint	5	string		Drift guard: the source item identity this detection was computed on.
instance_index	6	uint32
instance_fingerprint	7	string
analysis_implementation_version	8	string
category	9	voplica.types.ai.common.SubjectCategory		What kind of instance this is (mirrors the subject’s category once assigned; persons are CHARACTER_GENERIC, objects OBJECT, etc.).
image_region	10	ImageSubjectRegion	oneof locator
video_track	11	VideoSubjectTrack	oneof locator
audio_segment	12	AudioSubjectSegment	oneof locator
model_3d_region	13	Model3DSubjectRegion	oneof locator
mask_file	14	voplica.types.file.FileInfo	optional	Representative instance mask, when the detector produced one (images: segmentation mask; video: keyframe mask). Drives MASK artifacts.
detection_confidence	15	float
quality_score	16	float	optional	Usability for recognition/matching (persons: face quality). Unset when not applicable.
embedding_model_version	18	string
subject_id	20	string	optional	Current identity assignment. Empty while UNASSIGNED/USER_REJECTED.
assignment_state	21	SubjectAssignmentState
assignment_confidence	22	float	optional	Populated for AUTO_ASSIGNED (cluster / centroid / reference match confidence).
created_at	23	uint64		Seconds since epoch.
updated_at	24	uint64
preview	25	voplica.types.file.AssetFileVariantGroups	optional	The instance’s preview: the detected crop (face/object crop; video keyframe; audio snippet) CONVERTED to an Asset (multiple formats/resolutions). ALWAYS the detected crop for an instance. Populated on List/Get ONLY when a previews_retriever is supplied; the Asset’s asset_readiness reflects conversion progress.
preview_source	26	voplica.types.file.FileInfo	optional

DatasetSubjectReference

A user-provided exemplar of a subject: a reference image (or crop) plus an optional textual description. References drive matching: for persons they pin WHICH detected face is the user’s character (dominant-identity disambiguation in group shots); for objects they are the input to reference-guided detection (“find THIS bracelet in every image”).

Field	Number	Type	Label	Description
image	1	voplica.types.file.FileInfo
description	2	string	optional	e.g. “gold bracelet with an emerald stone” - helps open-vocabulary detection and captioning.

DatasetSubjectShortPreview

Field	Number	Type	Label	Description
default_preview	1	voplica.types.file.AssetFileVariantGroups	optional
default_preview_source	4	voplica.types.file.FileInfo	optional	Interim fallback while default_preview converts (async): the files-SIGNED crop of the cover instance, so the subject avatar shows instantly and upgrades once the Asset is ready. Set only for an instance cover (reference covers are rendered from the reference file in the UI).
instance_id	2	string	oneof preview_source
reference_id	3	string	oneof preview_source

ImageSubjectRegion

Where a subject occurs inside an IMAGE asset.

Field	Number	Type	Label	Description
bbox	1	voplica.types.image.BoundingBox
face_bbox	2	voplica.types.image.BoundingBox	optional	Persons only: the face region (drives FACE-framed targets).

Model3DSubjectRegion

Where a subject occurs inside a 3D asset. Placeholder shape (like the 3D recipe) - extend when the first 3D worker lands.

Field	Number	Type	Label	Description
object_path	1	string		Node / submesh path inside the asset (format-specific, e.g. glTF node path).

VideoSubjectTrack

Where a subject occurs inside a VIDEO asset: one contiguous TRACK of the same subject. The same person re-appearing after a long absence may be a second track (second instance)

• assign both to the same DatasetSubject.

Field	Number	Type	Label	Description
start_ms	1	uint64
end_ms	2	uint64
keyframe_ms	3	uint64		Representative frame of the track (drives previews, embeddings, and FACE framing).
keyframe_bbox	4	voplica.types.image.BoundingBox
keyframe_face_bbox	5	voplica.types.image.BoundingBox	optional

Enums

DatasetGenerationSizeClass

Name	Number	Description
DATASET_GENERATION_SIZE_CLASS_UNSPECIFIED	0	Absent/unset. Treated as MEDIUM (~1 MP), the FE default class.
DATASET_GENERATION_SIZE_CLASS_SMALL	1	~0.25 megapixels.
DATASET_GENERATION_SIZE_CLASS_MEDIUM	2	~1 megapixel. The default class.
DATASET_GENERATION_SIZE_CLASS_LARGE	3	~2 megapixels.
DATASET_GENERATION_SIZE_CLASS_EXTRA_LARGE	4	~4 megapixels.

DatasetCaptionFormat

Caption text format. Trainers pick the format compatible with the text encoder(s) of the trained model family (SDXL -> TAGS; FLUX/SD3 -> NATURAL_LANGUAGE). Captions live ON prepared items, one per format (see PreparedItemCaption).

Name	Number	Description
DATASET_CAPTION_FORMAT_UNSPECIFIED	0
DATASET_CAPTION_FORMAT_TAGS	1	Short comma-separated tags, commonly used by SD1/SDXL training recipes.
DATASET_CAPTION_FORMAT_NATURAL_LANGUAGE	2	Natural-language description, commonly used by FLUX, SD3, video, and multimodal recipes.
DATASET_CAPTION_FORMAT_TRANSCRIPT	3	Verbatim transcript for audio/video recipes.
DATASET_CAPTION_FORMAT_CUSTOM	100	Custom format defined by the worker, with details in DatasetCaptionGenerationConfig.generation_params.

DatasetContentProvenance

Who produced a piece of dataset content (a prepared file or a caption).

Name	Number	Description
DATASET_CONTENT_PROVENANCE_UNSPECIFIED	0
DATASET_CONTENT_PROVENANCE_AUTO_GENERATED	1	Produced by a worker (preparation or captioning).
DATASET_CONTENT_PROVENANCE_USER_AUTHORED	2	Supplied by the user for a slot no worker had filled (own crop, own mask, own caption).
DATASET_CONTENT_PROVENANCE_USER_EDITED	3	Auto-generated, then replaced/edited by the user. Re-generation must not overwrite these unless explicitly forced.

DatasetFastPathMode

Name	Number	Description
DATASET_FAST_PATH_MODE_UNSPECIFIED	0	Same as AUTO.
DATASET_FAST_PATH_MODE_AUTO	1	Default: auto-scope only when the dataset has exactly ONE identity with assigned instances (dominant) OR exactly one reference-defined (USER_CREATED with references) subject; otherwise fail with FAILED_PRECONDITION (“curate subjects first”).
DATASET_FAST_PATH_MODE_FORCE	2	Force the fast path regardless of how many identities exist: auto-scope to ALL identities with assigned instances (equivalent to ALL_ASSIGNED_SUBJECTS).
DATASET_FAST_PATH_MODE_DISABLED	3	Never auto-scope: an uncurated PER_SUBJECT recipe always fails with FAILED_PRECONDITION until the user sets a subject scope.

DatasetPreparationPlanAction

Action proposed by PlanDatasetPreparation for one selected source asset.

Name	Number	Description
DATASET_PREPARATION_PLAN_ACTION_UNSPECIFIED	0
DATASET_PREPARATION_PLAN_ACTION_REUSE_PREPARED_ITEM	1	Every expected artifact for this source asset already exists in the prepared set; no work is needed.
DATASET_PREPARATION_PLAN_ACTION_PREPARE_ITEM	2	The source asset is missing at least one expected file or caption (expected_items lists exactly which) and requires preparation work.
DATASET_PREPARATION_PLAN_ACTION_SKIP_ITEM	3	The source asset should not be prepared, for example because no target subject was detected during planning. message carries the reason.
DATASET_PREPARATION_PLAN_ACTION_FAIL_ITEM	4	The request should fail before starting any work, for example because the reuse policy is FAIL_IF_ANY_ITEM_MISSING and this source asset is missing an expected artifact. message carries the reason.

DatasetPreparationReusePolicy

Defines how a preparation run treats artifacts that already exist in the dataset’s DatasetPreparation for the selected source assets.

No-work short-circuit: when the prepared set already contains every expected artifact for every selected source asset, the REUSE_PREPARED_WHEN_COMPATIBLE and FAIL_IF_ANY_ITEM_MISSING policies complete without starting any workflow. REPROCESS_ALL_ITEMS intentionally skips this short-circuit and regenerates everything.

Name	Number	Description
DATASET_PREPARATION_REUSE_POLICY_UNSPECIFIED	0
DATASET_PREPARATION_REUSE_POLICY_REUSE_PREPARED_WHEN_COMPATIBLE	1	Default policy: prepare only the missing artifacts; keep every existing artifact in the set untouched (including USER_EDITED/USER_AUTHORED overrides).
DATASET_PREPARATION_REUSE_POLICY_REPROCESS_ALL_ITEMS	2	Regenerate every expected artifact for the selected source assets, replacing existing AUTO_GENERATED entries (user-authored/edited overrides are preserved). Use this when the worker implementation or models changed in a way that cannot be expressed by implementation_version alone.
DATASET_PREPARATION_REUSE_POLICY_FAIL_IF_ANY_ITEM_MISSING	3	Do not start work if any selected source asset is missing any expected artifact. Use this to validate a dataset’s readiness (for example before training) without paying for any new preparation.

DatasetSubjectScopeMode

Which subject instances PER_SUBJECT_INSTANCE targets expand over. Dataset-local configuration on the preparation (NOT the recipe - recipes are shareable across datasets and their fingerprint must stay dataset-agnostic).

Name	Number	Description
DATASET_SUBJECT_SCOPE_MODE_UNSPECIFIED	0
DATASET_SUBJECT_SCOPE_MODE_LISTED_SUBJECTS	1	Default: only instances assigned to subject_ids. Nothing is cropped until the user (or the fast path / a reference-defined subject) put identities in scope - UNASSIGNED and USER_REJECTED instances are never prepared.
DATASET_SUBJECT_SCOPE_MODE_ALL_ASSIGNED_SUBJECTS	2	Instances assigned to ANY subject identity (never UNASSIGNED/REJECTED ones).

ImageDatasetCropPolicy

Crop policy used by image preparation when fitting a source image into a target.

Name	Number	Description
IMAGE_DATASET_CROP_POLICY_UNSPECIFIED	0
IMAGE_DATASET_CROP_POLICY_PRESERVE_SUBJECT_EXTEND_BACKGROUND	1	Keep the selected subject fully visible and extend background generatively if needed.
IMAGE_DATASET_CROP_POLICY_PRESERVE_SUBJECT_PAD_BACKGROUND	2	Keep the selected subject fully visible and pad with plain or generated background.
IMAGE_DATASET_CROP_POLICY_CROP_BACKGROUND_ONLY	3	Allow background-only cropping and avoid subject cropping where possible.
IMAGE_DATASET_CROP_POLICY_ALLOW_SUBJECT_CROP	4	Allow subject cropping, for example for face-only crops.

ImageSubjectFraming

What region of a subject instance drives the crop of a PER_SUBJECT target.

Name	Number	Description
IMAGE_SUBJECT_FRAMING_UNSPECIFIED	0
IMAGE_SUBJECT_FRAMING_SUBJECT	1	The instance’s bbox/mask (person body, object). The default.
IMAGE_SUBJECT_FRAMING_FACE	2	The instance’s face region (CHARACTER subjects only). Video analog: the track’s keyframe face region (VideoSubjectTrack.keyframe_face_bbox) drives the tracked crop window of PER_SUBJECT video targets.

ImageTargetSubjectMode

How a target expands over the image’s subject instances.

Name	Number	Description
IMAGE_TARGET_SUBJECT_MODE_UNSPECIFIED	0
IMAGE_TARGET_SUBJECT_MODE_WHOLE_IMAGE	1	ONE item per source asset; no subject dimension. For whole-image categories (STYLE, BACKGROUND, PLACE, …) and plain full-image training. Recipes whose targets are ALL whole-image need no analysis and no subject layer at all (the ANALYSIS-FREE lane). Captioning is an INDEPENDENT axis (DatasetPreparationCaptioningConfig.formats): BACKGROUND / PLACE / GENERIC items are routinely auto-captioned; STYLE typically is not.
IMAGE_TARGET_SUBJECT_MODE_PER_SUBJECT_INSTANCE	2	One item PER IN-SCOPE SUBJECT INSTANCE (a group photo yields one item per selected person). WHICH instances are in scope is dataset-level configuration (DatasetPreparation.subject_scope) - the recipe stays dataset-agnostic and shareable.

PreparedFileKind

Name	Number	Description
PREPARED_FILE_KIND_UNSPECIFIED	0
PREPARED_FILE_KIND_TRAINING_SAMPLE	1	Primary prepared training sample: image, video clip, or audio segment, depending on the source asset type. Trainers consume one or more samples per item.
PREPARED_FILE_KIND_MASK	2	Binary or grayscale mask aligned with a training sample. Filesystem-oriented trainers (e.g. ai-toolkit) consume these directly as their mask inputs.
PREPARED_FILE_KIND_ALPHA	3	Alpha image (separate file or RGBA variant of a training sample). NOTE: current trainers read transparency from the training sample’s OWN alpha channel and take no separate alpha input - this kind exists for compositing/preview pipelines and future trainers; training materialization MAY ignore it.
PREPARED_FILE_KIND_ANALYSIS_METADATA	4	Machine-readable analysis metadata used to reproduce or refine preparation. Captions are NOT a file kind - they are first-class item state (PreparedItemCaption, one per text format). Sidecar caption .txt files, when a filesystem-oriented trainer needs them, are generated at training-materialization time from the item’s caption of the selected caption_format + trigger words.
PREPARED_FILE_KIND_AUDIO_TRACK	5	Companion audio segment extracted from a video training sample (VideoDatasetPreparationRecipe.extract_audio), time-aligned with the item’s clip. Needed as its own kind because an item carries at most ONE file per kind and the clip already occupies TRAINING_SAMPLE. Audio-capable video trainers (e.g. LTX do_audio) read the MUXED track inside the clip itself; this extracted companion exists for audio-only reuse and inspection.

DatasetSubjectDiscoveryPlanAction

Name	Number	Description
DATASET_SUBJECT_DISCOVERY_PLAN_ACTION_UNSPECIFIED	0
DATASET_SUBJECT_DISCOVERY_PLAN_ACTION_ANALYZE	1	Analyze the asset (no instances known yet, or re-analysis forced).
DATASET_SUBJECT_DISCOVERY_PLAN_ACTION_REUSE_INSTANCES	2	Instances already exist for the asset’s current source_item_fingerprint - reuse them.
DATASET_SUBJECT_DISCOVERY_PLAN_ACTION_SKIP	3	Skip (e.g. unsupported media).

DatasetSubjectOrigin

Name	Number	Description
DATASET_SUBJECT_ORIGIN_UNSPECIFIED	0
DATASET_SUBJECT_ORIGIN_AUTO_CLUSTERED	1	Created by the clustering activity of a subject-discovery run (“Subject N”).
DATASET_SUBJECT_ORIGIN_USER_CREATED	2	Created by the user (typically with reference exemplars).

SubjectAssignmentState

How an instance is currently tied to an identity.

Name	Number	Description
SUBJECT_ASSIGNMENT_STATE_UNSPECIFIED	0
SUBJECT_ASSIGNMENT_STATE_UNASSIGNED	1	Detected, not part of any identity yet. Never prepared by PER_SUBJECT targets.
SUBJECT_ASSIGNMENT_STATE_AUTO_ASSIGNED	2	Assigned by clustering or centroid/reference matching. Clustering may move it later.
SUBJECT_ASSIGNMENT_STATE_USER_ASSIGNED	3	Placed by the user. Clustering NEVER moves it; re-runs seed clusters from these.
SUBJECT_ASSIGNMENT_STATE_USER_REJECTED	4	Marked “not a real subject” by the user (reflection, poster, false positive). Never assigned, never prepared.