polyvoice 0.6.0-alpha.6

Speaker diarization library for Rust — online and offline, ONNX-powered, ecosystem-agnostic
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

---
schema_version: 1
kind: module_contract
module: src/utils
level: subsystem
layer: utility
purpose: >
  Owns shared mathematical and segment utilities: cosine similarity,
  L2 normalization, mean vector, segment merging. Does NOT own any algorithm
  specific to a single module.
status: stable
owners:
  - polyvoice-core
workcell:
  type: leaf
  parent: ""
  children: []
  owns_paths:
    - src/utils/
  context_budget:
    max_files: 12
    max_source_lines: 1500
    max_contract_lines: 180
    max_readme_lines: 120
    max_todo_lines: 80
authority:
  write_policy: single_active_write_lease
  orchestrator: polyvoice-core
  read_agents: many_allowed
  migration_lease_required:
    - cross-workcell write
    - public surface migration
surface:
  - name: cosine_similarity
    kind: function
    visibility: public
    contract: >
      Computes cosine similarity between two f32 slices. Returns value in [-1, 1].
    proof:
      kind: unit-test
      target: src/utils::mod::tests
      command: cargo test --lib utils
  - name: l2_normalize
    kind: function
    visibility: public
    contract: >
      In-place L2 normalization of a vector.
    proof:
      kind: unit-test
      target: src/utils::mod::tests
      command: cargo test --lib utils
  - name: mean_vector
    kind: function
    visibility: public
    contract: >
      Computes element-wise mean of a vector of vectors.
    proof:
      kind: unit-test
      target: src/utils::mod::tests
      command: cargo test --lib utils
  - name: merge_segments
    kind: function
    visibility: public
    contract: >
      Merges adjacent segments with same speaker if gap <= max_gap_secs.
    proof:
      kind: unit-test
      target: src/utils::mod::tests
      command: cargo test --lib utils
dependencies:
  internal:
    - module: types
      scope: data-shape
      reason: Segment type.
  external: []
consumers:
  - path: src/ahc/mod.rs
    uses:
      - cosine_similarity
      - l2_normalize
  - path: src/cluster/mod.rs
    uses:
      - cosine_similarity
      - l2_normalize
  - path: src/spectral/mod.rs
    uses:
      - cosine_similarity
  - path: src/ecapa/mod.rs
    uses:
      - l2_normalize
  - path: src/onnx/mod.rs
    uses:
      - l2_normalize
  - path: src/lib.rs
    uses:
      - merge_segments
invariants:
  - id: cosine-range
    rule: cosine_similarity returns value in [-1.0, 1.0].
    proof:
      kind: unit-test
      target: src/utils::mod::tests
      command: cargo test --lib utils
  - id: l2-unit
    rule: After l2_normalize, vector norm is 1.0 (or 0.0 for zero vector).
    proof:
      kind: unit-test
      target: src/utils::mod::tests
      command: cargo test --lib utils
  - id: property-cosine-range
    rule: cosine_similarity of any two f32 vectors is in [-1.0, 1.0].
    proof:
      kind: unit-test
      target: tests/property_utils_test.rs::cosine_similarity_range
      command: cargo test --test property_utils_test
  - id: property-cosine-identical
    rule: cosine_similarity of identical non-zero vectors is 1.0.
    proof:
      kind: unit-test
      target: tests/property_utils_test.rs::cosine_similarity_identical_is_one
      command: cargo test --test property_utils_test
  - id: property-l2-unit
    rule: l2_normalize of any non-zero vector produces a unit vector.
    proof:
      kind: unit-test
      target: tests/property_utils_test.rs::l2_normalize_produces_unit_vector
      command: cargo test --test property_utils_test
verification:
  pre_change:
    - cargo test --lib utils
  full:
    - cargo test --lib utils
    - cargo clippy --all-targets --all-features -- -D warnings
agent_policy:
  allowed_mutations:
    - Adding new utility functions.
    - Performance optimizations.
  forbidden_mutations:
    - Changing existing function signatures without migration lease.
  escalation:
    - Changes to merge_segments semantics.
---

# src/utils

Shared mathematical and segment utilities.