kcode-audio-speaker-review 0.1.0

Transport-neutral audio speaker review policy and classifier application
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# kcode-audio-speaker-review 0.1.0

Transport-neutral domain ownership for human review of audio speaker identities.
The library owns correction-packet types, exact chunk-confirmation validation,
idempotent classifier application and restoration, and the pure legacy-review
decisions shared by Audio Ingress and its Session History facade. It owns no
audio files, database connection, async runtime, provider call, HTTP behavior,
or final-transcript generation.

## Confirmation workflow

`validate_confirmation_coverage(packet, confirmation)` verifies that the
recording and chunk match, that every observation key is supplied exactly once,
and that known names contain 1 through 512 characters. It returns the existing
human-readable validation message on failure.

`apply_confirmation(classifier, packet, confirmation, legacy_keys)` validates
again, applies one unsigned chunk to `SpeechClassifier`, writes normalized
resolutions into the in-memory packet, and marks the packet `Confirmed` once all
chunks are signed. Known speakers with complete current feature rows are
trained. Unknown or featureless speakers are deleted idempotently. Keys in
`legacy_keys` are never sent to the current classifier. An already signed chunk
accepts only an exact retry. Partial classifier application is deleted in
reverse order if a later classifier operation fails.

`restore_training(classifier, packet, legacy_keys)` best-effort restores the
classifier to the packet's authoritative resolutions and returns every failure
message. The caller decides how to report those failures. Both classifier
operations are synchronous and must be invoked without holding another
capability's persistence lock.

`training_object_id(recording_id, chunk_index)` returns the deterministic
Audio Ingress classifier-object identity.

## Shared legacy policy

`legacy_review_disposition(recording_complete, confirmation_state,
has_ingress)` returns `Reprocess` for an unresolved finalized packet with no
accepted ingress, `Complete` for one with accepted ingress, and `None` for all
other states. `LegacyReviewDisposition` contains those two outcomes.

`confirmation_matches(packet, confirmation)` reports whether a signed chunk
already contains the complete exact resolution mapping. It performs no I/O.

## Public data

- `ParsedSpeaker { local_label, primary_language, feature_row }` and
  `ParsedChunk { clip_valid, clip_validity_reason, speakers }` hold normalized
  provider feature output.
- `CandidateMapping { full_name, score, runner_up_score }` holds read-only
  classifier evidence.
- `SpeakerResolution` is `Known { full_name }` or `Unknown`.
- `CorrectionObservation { local_label, speaker_ordinal, observation_key,
  candidate, resolution }` is one deterministic review row.
- `CorrectionChunk { chunk_index, chunk_count, audio_start_ms, audio_end_ms,
  raw_gemini_response, parsed, observations, signed_off }` is one chronological
  review interval.
- `CorrectionPacket { recording_id, user_id, sha256, original_filename,
  size_bytes, recorded_at, chunk_count, chunks, confirmation_state }` is the
  complete durable review document.
- `ConfirmationState` is `Unconfirmed`, legacy-decode-only
  `AutomaticallyTrained`, or `Confirmed`.
- `ObservationConfirmation { observation_key, resolution }` and
  `ChunkConfirmation { recording_id, chunk_index, observations }` are the exact
  human input.
- `FeatureRow` and `ObservationKey` are re-exported from
  `kcode-speaker-system` so packet serialization and established caller paths
  remain identical.

The classifier cohort constants are public and frozen:
`CLASSIFIER_PROVIDER`, `CLASSIFIER_MODEL`, `CLASSIFIER_PROMPT_VERSION`, and
`CLASSIFIER_SCHEMA_VERSION`.