Crate videre_api 

Facade over videre’s faces-labeling operations. Plain functions over an open rusqlite::Connection, returning serde types and a shared Error. Transport-agnostic on purpose: the axum --faces server is the in-repo caller, but nothing here depends on it.

Structs

ClusterData

One unassigned cluster (green section in the labeling UI).

ClusterDetail

Cluster detail: every face in one unassigned cluster.

ClusterFaceData

One face row on a cluster detail page.

FaceLearningEventProof

One journal entry plus read-time proof facts. source_available says whether every referenced face still exists; incompatible says whether the entry can no longer feed training. Both are computed at read time and never rewrite the historical row.

FaceLearningStatus

Learning status for the gallery background worker.

FaceLookup

The single-row query face_image_bytes needs before it can do any image work, split out so a caller holding a shared/locked Connection (the axum server serializes every request on one Mutex<Connection>) can release that lock immediately after this cheap lookup, instead of holding it for the entire decode/crop/resize/encode/cache-write below, which otherwise fully serializes every thumbnail request behind the lock, turning a many-thousand-singleton library into one thumbnail at a time.

FacesData

Top-level payload for the labeling page.

LearningAcknowledgement

Durable learning work committed with a visible people mutation.

LibraryStats

OriginalLookup

The single-row query original_image_bytes needs before any image I/O. See FaceLookup for why this split matters for concurrency.

PersonData

One labeled person: their confirmed faces plus a representative face id (the primary, or lowest id) used as the card thumbnail.

PersonDetail

Person detail: every confirmed face for one person.

PersonFaceData

One face row on a person detail page. is_primary marks the current default photo (the person’s thumbnail on the labeling page).

PipelineRunStatus

QuestionAnswerOutcome

Result of answering one identity question: the new delivery state and, for Yes and No, the durable learning work the answer committed.

SingletonData

One unclustered, unassigned face (orange section).

TeachingContext

Versioned model context attached to evidence captured by a Gallery action.

TrainedProfileSummary

The stored outcome of one background training run.

Enums

Error

Errors returned by videre-api operations. Each consumer maps these to its own convention (axum -> StatusCode, other embedders -> their own error type).

Functions

answer_question_with_learning

Answer one pending identity question. Yes confirms the subject cluster as the target person and teaches one positive membership; No teaches one negative membership without labeling; Skip only changes delivery state. Every answer revalidates subject, target, active profile, and evidence revision inside the transaction. Drift supersedes the stale question and returns Conflict without writing a label or teaching event.

assign

Assign faces to an existing/new person: sets person_label + confirmed. Rejects an empty label after sanitizing.

assign_with_learning

cluster_detail

Every face in one unassigned cluster (for the cluster detail page).

delete_person

delete_person_with_learning

dissolve_cluster

Ungroup a bad cluster: its faces become unassigned singletons (not deleted).

dissolve_cluster_with_learning

face_bytes_from_lookup

The expensive part of face_image_bytes: cache check, decode/crop/encode, write-through. Takes no Connection, so it can run without holding the shared DB lock.

face_image_bytes

JPEG bytes for a single aligned face thumbnail (140px), reading the disk cache first and converting from the source image (HEIC via QuickLook) on a miss, writing through to the cache. Returns Error::NotFound if the face id is unknown or the crop cannot be produced. Synchronous: callers that need async should run this on a blocking thread.

face_learning_event

face_learning_events

Learning events, newest first. Payloads carry scalar feature snapshots and provenance ids only; embeddings never leave the library.

face_learning_status

Learning state plus pending question volume for the status resource.

face_lookup

The cheap part of face_image_bytes: just the DB row. No image I/O.

faces_list

People / unassigned clusters / singletons for the labeling page.

library_stats

load_training_snapshot

Load the immutable training inputs for the learning worker’s snapshot.

make_face_thumb

Load, crop, and orientation-correct a face thumbnail.

mime_for_ext

new_person

Create a person from faces. Same effect as assign; kept as a distinct operation because callers treat “new person” and “assign to existing” as separate user intents.

new_person_with_learning

original_bytes_from_lookup

The expensive part of original_image_bytes: read/convert/cache. Takes no Connection, so it can run without holding the shared DB lock.

original_image_bytes

Bytes for the full original image behind a face (raw for common formats, QuickLook-converted JPEG for HEIC, with the HEIC result cached). Returns the MIME type alongside the bytes. Error::NotFound if the id is unknown or the file cannot be read/converted. Synchronous.

original_lookup

The cheap part of original_image_bytes: just the DB row. No image I/O.

pending_identity_questions

Pending identity questions for the gallery page, bounded and in priority order. Selection never mutates anything.

persist_trained_profile

Persist a trained candidate: insert, promote through the shipped gates, and return the profile identity and verdict. The profile row keeps the promotion outcome either way.

person_detail

Every confirmed face for one person, primary first and flagged.

pipeline_status

refresh_identity_questions

Refresh the pending question page from the active profile. Runs outside request handling; safe to call whenever training promotes a profile.

remove_face

Reset one face to fully unassigned (cluster, label, confirmed, primary).

remove_face_with_learning

sanitize_person_label

The display form of a person’s name.

search_person

Image paths for confirmed faces of a person (prefix match), for the person-name autocomplete. Delegates to the existing core search.

set_full_name

Reset every face of a person back to unassigned. Deliberately does NOT touch cluster_id, so a face rejoins its cluster’s unassigned group rather than scattering to singletons. Change only what a person is shown as, never their identity.

set_primary

Mark one face as the person’s primary (their labeling-page thumbnail), clearing any previous primary in the same transaction so exactly one remains. The target update is guarded by person_label so it can’t steal a face from another person.

Type Aliases

Result