fluffychat/.github/instructions/token-info-feedback-v2.instructions.md

applyTo
lib/pangea/token_info_feedback/**, lib/**

Token Info Feedback — v2 Migration (Client)

Migrate the token info feedback flow to use the v2 endpoint and v2 phonetic transcription types. This is a client-side companion to the choreo instructions at 2-step-choreographer/.github/instructions/token-info-feedback-pt-v2.instructions.md.

Context

Token info feedback lets users flag incorrect token data (POS, language, phonetics, lemma). The server evaluates the feedback via LLM, conditionally calls sub-handlers, and returns updated fields. The client applies the updates to local caches and optionally edits the Matrix message.

Why migrate: The phonetics field currently sends a plain String and receives a PhoneticTranscriptionResponse (v1 nested types). The v2 endpoint expects PTRequest + PTResponse and returns PTResponse (flat v2 types). This aligns token feedback with the broader PT v2 migration.

Staleness detection: The server compares the client-sent phonetics against its CMS cache. If they differ and the LLM didn't request changes, the server returns the CMS version as updatedPhonetics so the client refreshes its local cache. This means updatedPhonetics may be non-null even when the user's feedback didn't trigger phonetic changes.

---

1. Endpoint URL

v1: {choreoEndpoint}/token/feedback v2: {choreoEndpoint}/token/feedback_v2

Update PApiUrls.tokenFeedback (or add a new constant) in urls.dart.

---

2. Request Changes

Replace phonetics with ptRequest + ptResponse

v1: phonetics: String — a rendered transcription like "hái", extracted by PhoneticTranscriptionBuilder.transcription (the first token's phoneticL1Transcription.content).

v2: Two new fields replace phonetics:

• ptRequest: PTRequest? — the PT request used to fetch phonetics (surface, langCode, userL1, userL2). The server passes this directly to pt_v2_handler.get() when feedback triggers a phonetics re-evaluation.
• ptResponse: PTResponse? — the cached PT response containing List<Pronunciation>. The server uses ptResponse.pronunciations for the evaluation prompt and staleness detection.

This means TokenInfoFeedbackRequestData drops phonetics: String and adds ptRequest: PTRequest? + ptResponse: PTResponse?.

What feeds into ptRequest / ptResponse

The data flows through this chain:

1. PhoneticTranscriptionBuilder resolves a PhoneticTranscriptionResponse (v1) → extracts a String.
2. TokenFeedbackButton receives the string via onFlagTokenInfo(lemmaInfo, transcript).
3. Call sites (reading_assistance_content.dart, analytics_details_popup.dart) put the string into TokenInfoFeedbackRequestData(phonetics: transcript).

After v2 migration, this chain must change:

1. PhoneticTranscriptionBuilder resolves a v2 response → exposes both the PTRequest it used and the PTResponse it received.
2. TokenFeedbackButton callback signature changes: Function(LemmaInfoResponse, PTRequest, PTResponse).
3. Call sites pass both objects into the updated request data: TokenInfoFeedbackRequestData(ptRequest: ptReq, ptResponse: ptRes).

toJson() serialization

v1:

{ "phonetics": "hái" }

v2:

{
  "pt_request": {
    "surface": "还",
    "lang_code": "zh",
    "user_l1": "en",
    "user_l2": "zh"
  },
  "pt_response": {
    "pronunciations": [
      { "transcription": "hái", "ipa": "xaɪ̌", "ud_conditions": "Pos=ADV" },
      { "transcription": "huán", "ipa": "xwaň", "ud_conditions": "Pos=VERB" }
    ]
  }
}

All other request fields (userId, roomId, fullText, detectedLanguage, tokens, selectedToken, lemmaInfo, wordCardL1) are unchanged.

---

3. Response Changes

updatedPhonetics field

v1: PhoneticTranscriptionResponse? — deeply nested v1 types with phoneticTranscriptionResult.phoneticTranscription[0].phoneticL1Transcription.content.

v2: The v2 response type (e.g., PhoneticTranscriptionV2Response with pronunciations: List<Pronunciation>). Deserialized via the v2 model's fromJson().

New behavior: updatedPhonetics may be non-null in two cases:

1. The LLM evaluated user feedback and generated new phonetics (same as v1).
2. The server detected that the client's cached phonetics are stale compared to CMS. In this case, the server returns the current CMS version so the client can refresh.

Either way, the client should apply the update to its local cache (see §4).

All other response fields (userFriendlyMessage, updatedToken, updatedLemmaInfo, updatedLanguage) are unchanged.

---

4. Cache Side-Effects in _submitFeedback

The dialog applies server updates to local caches. The phonetic cache write must change:

v1 (current)

Future<void> _updatePhoneticTranscription(
  PhoneticTranscriptionResponse response,
) async {
  final req = PhoneticTranscriptionRequest(
    arc: LanguageArc(l1: ..., l2: ...),
    content: response.content,
  );
  await PhoneticTranscriptionRepo.set(req, response);
}

This constructs a v1 PhoneticTranscriptionRequest to use as the cache key, then writes the v1 response.

v2 (target)

Construct the v2 cache key (surface + lang_code + user_l1) and write the v2 response to the v2 PT cache. The exact implementation depends on how the PT v2 repo's set() method is designed during the broader PT migration. The key pieces are:

• Cache key inputs: surface = the token's surface text, langCode = this.langCode (from the dialog), userL1 = requestData.wordCardL1.
• Response type: The v2 response containing List<Pronunciation>.
• Cache target: The v2 PT cache (not the v1 phonetic_transcription_storage).

---

5. Files to Modify

File	Change
token_info_feedback_request.dart	Drop phonetics: String. Add ptRequest: PTRequest? + ptResponse: PTResponse?. Update toJson(), ==, hashCode.
token_info_feedback_response.dart	updatedPhonetics: PhoneticTranscriptionResponse? → v2 response type. Update fromJson(), toJson(), ==, hashCode. Remove v1 PhoneticTranscriptionResponse import.
token_info_feedback_dialog.dart	Update _updatePhoneticTranscription to use v2 cache key/types. Remove v1 PhoneticTranscriptionRequest, PhoneticTranscriptionResponse, LanguageArc, PLanguageStore imports.
token_info_feedback_repo.dart	Update URL to PApiUrls.tokenFeedbackV2 (or equivalent).
token_feedback_button.dart (outside this folder)	Change callback from (LemmaInfoResponse, String) to (LemmaInfoResponse, PTRequest, PTResponse). Update how the PT objects are extracted from the builder.
Call sites (outside this folder)	reading_assistance_content.dart, analytics_details_popup.dart — update onFlagTokenInfo to pass PTRequest + PTResponse into TokenInfoFeedbackRequestData.
urls.dart (outside this folder)	Add tokenFeedbackV2 URL constant.

---

6. Dependency on PT v2 Migration

This migration depends on the core PT v2 models existing on the client:

• Pronunciation model (with transcription, ipa, ud_conditions)
• V2 response model (with pronunciations: List<Pronunciation>)
• V2 repo with a set() method that accepts the v2 cache key

These are created as part of the main PT v2 migration (see phonetic-transcription-v2-design.instructions.md §3). Implement the core PT v2 models first, then update token info feedback.

---

7. Checklist

• Replace phonetics field with ptRequest + ptResponse in request model
• Update updatedPhonetics field type in response model
• Update _updatePhoneticTranscription cache write in dialog
• Update TokenFeedbackButton callback signature to (LemmaInfoResponse, PTRequest, PTResponse)
• Update call sites to pass PTRequest + PTResponse
• Update URL to v2 endpoint
• Remove all v1 PT type imports from token_info_feedback files