← Docs hub

Speaker Identity A2A Implementation Roadmap

이 문서는 화자 분리/인식 PoC를 제품 경로와 Cloud A2A Task Manager에 연결하기 위한 구현 로드맵이다.

앞선 문서들이 “현재 구조 분석”과 “확장 설계”라면, 이 문서는 후속 개발자가 실제 작업을 티켓으로 나눌 때 사용할 실행 순서다.

1. 구현 원칙

2. 구현 티켓 분해

SPK-07은 단순 문서 작업이 아니라 제품 architecture 결정이다. Voice ID를 계정/얼굴 ID에 직접 붙이는 방식과 Person Profile link 방식은 이후 DB, 앱 UI, 개인정보 동의, Cloud payload가 모두 달라진다.

3. 온디바이스 구현 상세

3.1 SPK-01: SpeakerContext DTO

권장 Kotlin 모델:

data class SpeakerContext(
    val contractVersion: String = "speaker-context-v1",
    val speakerId: String = "",
    val displayName: String = "",
    val speakerConfidence: Float = 0f,
    val speakerState: SpeakerState = SpeakerState.UNKNOWN,
    val speakerCount: Int = 0,
    val overlapRatio: Float = 0f,
    val unknownRatio: Float = 0f,
    val maxScore: Float = 0f,
    val safetyGate: SpeakerSafetyGate = SpeakerSafetyGate.REPROMPT,
    val personalizationAllowed: Boolean = false,
    val authorityLevel: String = "unknown",
    val source: String = "ondevice_sherpa_poc"
)

권장 상태:

identified
unknown
ambiguous
multi_speaker
overlap
far_speech
disabled

주의:

• displayName은 UI/TTS 용도이고, Cloud 정책의 primary key는 speakerId여야 한다.
• 초기 단계에서는 speakerId를 등록 폴더명 기반으로 만들 수 있지만, 제품화 단계에서는 stable id와 삭제 정책이 필요하다.
• contractVersion은 Cloud 정규화에서 필수 확인해야 한다.

3.2 SPK-02: PoC 결과 변환 Adapter

현재 근거:

ForegroundService.kt
- speakerEnrollmentBufferLock
- pendingSpeakerPrefix
- lastIdentifiedSpeakerName
- idAcceptThreshold = 0.50f
- extensionFeatures.enableSpeakerStability = true

SpeakerIdentificationEngine.kt
- registerSpeakerFromWavPath()
- identifyFromSamples()
- identifyFromSegment()
- searchEmbeddingWithScoreRaw()

DiarizationEngine.kt
- diarize(samples)
- DiarizationSegment(startSec, endSec, speakerId)

SpeakerStabilityFeature.kt
- sessionBoostScore = 0.04f
- recentBoostScore = 0.02f
- sessionDecayMs = 20_000L

변환 규칙:

3.3 SPK-03: Cloud Request 삽입

삽입 위치는 Cloud LLM request를 구성하는 경로다.

원칙:

• 기존 recognized_text, asr_confidence, audio_locale, memory_context, device_context를 유지한다.
• voice_context.speaker_context를 새 field로 추가한다.
• log에는 raw audio, embedding, WAV path를 남기지 않는다.

요청 예시:

{
  "recognized_text": "거실 청정하고 10분 뒤에 돌아와",
  "voice_context": {
    "recognized_text": "거실 청정하고 10분 뒤에 돌아와",
    "asr_confidence": 0.94,
    "audio_locale": "ko-KR",
    "speaker_context": {
      "contract_version": "speaker-context-v1",
      "speaker_id": "spk_001",
      "display_name": "아빠",
      "speaker_confidence": 0.72,
      "speaker_state": "identified",
      "speaker_count": 1,
      "overlap_ratio": 0.0,
      "unknown_ratio": 0.0,
      "max_score": 0.72,
      "safety_gate": "pass",
      "personalization_allowed": true,
      "authority_level": "normal",
      "source": "ondevice_sherpa_poc"
    }
  }
}

4. Cloud A2A 구현 상세

4.1 SPK-04: normalize_voice_context() 확장

현재 근거:

gemini/a2a/runtime/session_state.py
normalize_voice_context()

현재 기본화:

recognized_text
asr_confidence
audio_locale
slot_state
handoff_chain
replan_reason
selected_flow_id
owner_selection

추가 권장:

def _normalize_speaker_context(value):
    speaker = value if isinstance(value, dict) else {}
    return {
        "contract_version": str(speaker.get("contract_version") or "speaker-context-v1"),
        "speaker_id": str(speaker.get("speaker_id") or ""),
        "display_name": str(speaker.get("display_name") or ""),
        "speaker_confidence": _safe_float(speaker.get("speaker_confidence"), 0.0),
        "speaker_state": _allowed_state(speaker.get("speaker_state")),
        "speaker_count": _safe_int(speaker.get("speaker_count"), 0),
        "overlap_ratio": _safe_float(speaker.get("overlap_ratio"), 0.0),
        "unknown_ratio": _safe_float(speaker.get("unknown_ratio"), 0.0),
        "max_score": _safe_float(speaker.get("max_score"), 0.0),
        "safety_gate": _allowed_gate(speaker.get("safety_gate")),
        "personalization_allowed": bool(speaker.get("personalization_allowed", False)),
        "authority_level": str(speaker.get("authority_level") or "unknown"),
        "source": str(speaker.get("source") or "unknown"),
    }

Cloud는 값이 없으면 unknown으로 낮춰야 한다. 값이 없다고 제품 경로를 실패시키면 기존 기능 회귀가 생긴다.

Identity 확장 필드는 아래 기본값으로 정규화한다.

4.2 SPK-05: Speaker-scoped Memory

현재 근거:

gemini/a2a/runtime/memory_context.py
normalize_memory_context()
build_memory_update()

추가 권장:

{
  "write_candidates": {
    "short_term_pair": {
      "speaker_id": "spk_001",
      "speaker_state": "identified",
      "write_policy": "speaker_scoped",
      "user_text": "...",
      "assistant_text": "...",
      "route_family": "ODL",
      "workflow_id": "wf_001"
    },
    "profile_candidates": []
  }
}

정책:

4.3 SPK-06: TaskManager Side-effect Gate

현재 근거:

gemini/a2a/runtime/task_manager.py
build_device_task_requests()
execute_task_plan()

적용 위치:

• device task request를 만들기 전 speaker safety를 확인한다.
• side-effect가 큰 기능은 safety_gate=pass가 아니면 confirmation_required 또는 blocked로 낮춘다.
• active workflow가 있을 때 workflow_owner_speaker_id와 현재 speaker_id가 다르면 takeover 정책을 적용한다.

정책 예시:

5. 권장 구현 순서

Phase 1: On-device DTO와 adapter만 추가
Phase 2: Cloud request에 speaker_context 추가, Cloud는 무시해도 기존 기능 유지
Phase 3: Cloud normalize_voice_context에서 speaker_context 정규화
Phase 4: memory_update에 speaker scope 추가, unknown no-write 적용
Phase 5: TaskManager side-effect gate 적용
Phase 6: Person Profile / Identity Link 설계 반영
Phase 7: 실기기 E2E evidence 수집
Phase 8: threshold tuning과 privacy/delete 정책 확정

이 순서를 지키는 이유는 rollback 위험을 줄이기 위해서다. Cloud가 speaker_context를 아직 사용하지 않더라도 payload에 추가하는 것은 additive change다. 반대로 TaskManager gate를 먼저 넣으면 기존 기능 실행이 막히는 회귀가 생길 수 있다.

6. 테스트 매트릭스

7. 릴리즈 게이트

8. 후속 의사결정

아래 항목은 구현 전에 소유자 합의가 필요하다.