annie.parsers.participants

Parser and resolver for the protagonist participant file.

A protagonist file maps each video to the track index that is its active / monitored protagonist. Classically this is a two-column CSV — uuid,track_id — but Annie is dataset-agnostic: the key column (the video id) and the value column (the track id) are chosen when the source is added, defaulting to uuid / track_id. A track_id of -1 means “no active track”.

Annie keeps human judgement separate from heuristic output. The user selects the source file; Annie never writes to it. Manual corrections go to its _manual sibling (..._heuristic.csv → ..._heuristic_manual.csv), an upsert keyed by the video id, written with the same two columns. Resolution order is manual ▸ source ▸ -1.

Functions

manual_path_for(→ pathlib.Path)

Return the manual-correction sibling path for a source file.

load_participants(→ dict[str, int])

Load a protagonist CSV into a video_id -> track_id mapping.

resolved_mapping(→ dict[str, int])

Return the merged video_id -> track_id mapping (manual overrides source).

resolve_active_track(→ int)

Resolve the active track id for a video using manual ▸ source ▸ -1.

set_active_track(→ pathlib.Path)

Upsert a manual protagonist correction for uuid.

export_resolved(→ pathlib.Path)

Write the resolved (manual ▸ source) mapping to a standalone CSV.

Module Contents

annie.parsers.participants.manual_path_for(source_file: str | pathlib.Path) → pathlib.Path[source]

Return the manual-correction sibling path for a source file.

/x/participant_face_track_heuristic.csv → /x/participant_face_track_heuristic_manual.csv.

Parameters:

source_file – Path to the pristine protagonist source CSV.

Returns:

The path where manual corrections are written.

annie.parsers.participants.load_participants(path: str | pathlib.Path, key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → dict[str, int][source]

Load a protagonist CSV into a video_id -> track_id mapping.

A missing file resolves to an empty mapping (treated as “no corrections / no source yet”) rather than raising, so resolution degrades cleanly. Rows whose track-id value is blank or non-integer are skipped. Always reads the file afresh: it backs read-modify-write updates (see set_active_track()).

Parameters:

  • path – Path to the protagonist CSV.

  • key_column – The column holding the video id.

  • value_column – The column holding the track index.

Returns:

Mapping from video id to its active track index (may be -1). Empty if the file does not exist.

annie.parsers.participants.resolved_mapping(source_file: str | pathlib.Path, key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → dict[str, int][source]

Return the merged video_id -> track_id mapping (manual overrides source).

Parameters:

  • source_file – Path to the protagonist source CSV.

  • key_column – The column holding the video id.

  • value_column – The column holding the track index.

Returns:

The source mapping with manual corrections layered on top.

annie.parsers.participants.resolve_active_track(uuid: str, source_file: str | pathlib.Path, key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → int[source]

Resolve the active track id for a video using manual ▸ source ▸ -1.

Parameters:

  • uuid – The video id to look up.

  • source_file – Path to the protagonist source CSV.

  • key_column – The column holding the video id.

  • value_column – The column holding the track index.

Returns:

The resolved active track index, or -1 when none applies.

annie.parsers.participants.set_active_track(uuid: str, track_id: int, source_file: str | pathlib.Path, key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → pathlib.Path[source]

Upsert a manual protagonist correction for uuid.

Writes to the _manual sibling of the source file only (the source file is never touched). The write is an upsert keyed by the video id — re-correcting a video overwrites its previous manual row rather than appending.

Parameters:

  • uuid – The video id being corrected.

  • track_id – The newly chosen active track index.

  • source_file – Path to the protagonist source CSV (defines where the _manual sibling lives).

  • key_column – The column holding the video id.

  • value_column – The column holding the track index.

Returns:

The path to the manual-correction file that was written.

annie.parsers.participants.export_resolved(source_file: str | pathlib.Path, out_path: str | pathlib.Path, key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → pathlib.Path[source]

Write the resolved (manual ▸ source) mapping to a standalone CSV.

This is the export of the corrected protagonist datasource: the heuristic rows with every manual correction applied, in one self-contained file.

Parameters:

  • source_file – Path to the protagonist source CSV.

  • out_path – Destination CSV path.

  • key_column – The column holding the video id.

  • value_column – The column holding the track index.

Returns:

The path written.