Create app/main.py

app/main.py

@@ -0,0 +1,907 @@
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+from statistics import mean
+from typing import Any, Dict, List, Optional, Tuple
+
+import requests
+from fastapi import FastAPI, File, Form, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+APP_VERSION = "4.0.0"
+
+app = FastAPI(title="Japanese AI Interview API", version=APP_VERSION)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+HF_TOKEN = os.getenv("HF_TOKEN", "").strip()
+ASR_MODEL = os.getenv("ASR_MODEL", "openai/whisper-large-v3")
+CHAT_MODEL = os.getenv("CHAT_MODEL", "Qwen/Qwen2.5-7B-Instruct-1M")
+HF_ROUTER_URL = os.getenv("HF_ROUTER_URL", "https://router.huggingface.co/v1/chat/completions")
+HF_INFERENCE_BASE = os.getenv("HF_INFERENCE_BASE", "https://router.huggingface.co/hf-inference/models")
+MAX_QUESTION_LIMIT = int(os.getenv("MAX_QUESTION_LIMIT", "20"))
+LLM_TIMEOUT_SECONDS = int(os.getenv("LLM_TIMEOUT_SECONDS", "90"))
+ASR_TIMEOUT_SECONDS = int(os.getenv("ASR_TIMEOUT_SECONDS", "180"))
+
+ROLE_BANK_PATH = Path(__file__).resolve().parents[1] / "role_bank.json"
+ROLE_BANK: Dict[str, Any] = json.loads(ROLE_BANK_PATH.read_text(encoding="utf-8"))
+
+REPEAT_PROMPTS = [
+    "すみません、音が聞こえませんでした。マイクを確認して、もう一度お願いします。",
+    "声が小さいです。もう少し大きい声で、もう一度お願いします。",
+    "まだ音がうまく入りません。マイクを近づけて、もう一度お願いします。",
+]
+
+class StartRequest(BaseModel):
+    session_uuid: str
+    job_role: str = "construction"
+    question_count: int = 10
+
+
+@app.get("/")
+def root() -> Dict[str, Any]:
+    return {
+        "ok": True,
+        "service": "jp-role-interview",
+        "version": APP_VERSION,
+        "routes": ["/health", "/roles", "/start", "/answer"],
+    }
+
+
+@app.get("/health")
+def health() -> Dict[str, Any]:
+    return {
+        "ok": True,
+        "service": "jp-role-interview",
+        "version": APP_VERSION,
+        "hf_token_set": bool(HF_TOKEN),
+        "asr_model": ASR_MODEL,
+        "chat_model": CHAT_MODEL,
+        "role_count": len(ROLE_BANK),
+        "native_asr": False,
+        "uses_hf_serverless_asr": True,
+    }
+
+
+@app.get("/roles")
+def roles() -> Dict[str, Any]:
+    items = []
+    for key, role in ROLE_BANK.items():
+        items.append({
+            "role_key": key,
+            "english_name": role["english_name"],
+            "japanese_name": role["japanese_name"],
+            "question_count": role["question_count"],
+            "min_questions": role["min_questions"],
+            "max_questions": role["max_questions"],
+        })
+    return {"ok": True, "roles": items}
+
+
+@app.post("/start")
+def start_interview(payload: StartRequest) -> Dict[str, Any]:
+    role_key = payload.job_role if payload.job_role in ROLE_BANK else "construction"
+    role = ROLE_BANK[role_key]
+    question_count = max(role["min_questions"], min(payload.question_count, role["max_questions"], MAX_QUESTION_LIMIT))
+
+    opening_question = f"{role['intro_jp']} まず、お名前を教えてください。"
+    first_question = get_question_by_id(role, f"{role_key}_common_name_1")
+    if first_question:
+        opening_question = f"{role['intro_jp']} {first_question['jp']}"
+
+    memory = {
+        "session_uuid": payload.session_uuid,
+        "job_role": role_key,
+        "job_role_en": role["english_name"],
+        "job_role_jp": role["japanese_name"],
+        "question_count_target": question_count,
+        "candidate_name": None,
+        "country_name": None,
+        "age": None,
+        "reason_for_japan": None,
+        "occupation": None,
+        "japanese_level": None,
+        "experience_status": "unknown",
+        "answers_so_far": [],
+        "asked_question_ids": [first_question["id"]] if first_question else [],
+        "asked_themes": ["intro"],
+        "low_score_count": 0,
+        "no_sound_count": 0,
+        "repeat_count": 0,
+        "question_pool_size": role["question_count"],
+        "interview_status": "running",
+    }
+
+    return {
+        "ok": True,
+        "session_uuid": payload.session_uuid,
+        "job_role": role_key,
+        "question_no": 1,
+        "question_count": question_count,
+        "question_id": first_question["id"] if first_question else f"{role_key}_common_name_1",
+        "question_jp": opening_question,
+        "memory": memory,
+        "is_finished": False,
+        "speak_now": True,
+    }
+
+
+@app.post("/answer")
+async def answer_interview(
+    session_uuid: str = Form(...),
+    question_no: int = Form(...),
+    question_count: int = Form(10),
+    question_id: str = Form(""),
+    question_jp: str = Form(...),
+    memory_json: str = Form("{}"),
+    audio: UploadFile = File(...),
+) -> Dict[str, Any]:
+    memory = safe_json_loads(memory_json)
+    role_key = memory.get("job_role") or "construction"
+    role = ROLE_BANK.get(role_key, ROLE_BANK["construction"])
+    question_count = max(role["min_questions"], min(question_count, role["max_questions"], MAX_QUESTION_LIMIT))
+
+    audio_bytes = await audio.read()
+    transcript = ""
+    asr_error = None
+    if audio_bytes:
+        try:
+            transcript = transcribe_audio_with_hf(audio_bytes, audio.filename or "audio.webm")
+        except Exception as exc:
+            asr_error = str(exc)
+
+    if not transcript.strip():
+        memory["no_sound_count"] = int(memory.get("no_sound_count", 0)) + 1
+        memory["repeat_count"] = int(memory.get("repeat_count", 0)) + 1
+        repeat_idx = min(memory["no_sound_count"] - 1, len(REPEAT_PROMPTS) - 1)
+        repeat_prompt = REPEAT_PROMPTS[repeat_idx]
+        if memory["no_sound_count"] >= 2 and question_no >= role["min_questions"]:
+            result = build_final_result(memory, role, force_fail=True, summary_jp="音声が聞こえないため、面接を終了しました。")
+            return {
+                "ok": True,
+                "is_finished": True,
+                "session_uuid": session_uuid,
+                "question_no": question_no,
+                "question_count": question_count,
+                "transcript_jp": "",
+                "answer_score": 0,
+                "feedback_jp": repeat_prompt,
+                "memory": memory,
+                "llm_used": False,
+                "result": result,
+            }
+        return {
+            "ok": True,
+            "is_finished": False,
+            "needs_repeat": True,
+            "session_uuid": session_uuid,
+            "question_no": question_no,
+            "question_count": question_count,
+            "question_id": question_id,
+            "question_jp": question_jp,
+            "transcript_jp": "",
+            "answer_score": 0,
+            "feedback_jp": repeat_prompt,
+            "memory": memory,
+            "next_question_no": question_no,
+            "next_question_id": question_id,
+            "next_question_jp": question_jp,
+            "speak_now": True,
+            "asr_error": asr_error,
+            "llm_used": False,
+        }
+
+    memory["no_sound_count"] = 0
+
+    answer_turn = {
+        "question_no": question_no,
+        "question_id": question_id,
+        "question_jp": question_jp,
+        "answer_text_jp": transcript,
+    }
+    history = list(memory.get("answers_so_far", []))
+    history.append(answer_turn)
+
+    candidate_questions = select_candidate_questions(role, memory, transcript)
+    llm_used = False
+    evaluation: Dict[str, Any]
+    if HF_TOKEN:
+        try:
+            evaluation = run_llm_turn(
+                role=role,
+                question_no=question_no,
+                question_count=question_count,
+                question_id=question_id,
+                current_question=question_jp,
+                transcript=transcript,
+                memory=memory,
+                history=history,
+                candidate_questions=candidate_questions,
+            )
+            llm_used = True
+        except Exception as exc:
+            evaluation = fallback_turn_evaluation(role, memory, transcript, candidate_questions, error=str(exc))
+    else:
+        evaluation = fallback_turn_evaluation(role, memory, transcript, candidate_questions, error="HF_TOKEN is not set.")
+
+    profile_update = evaluation.get("profile_update", {})
+    merged_memory = merge_memory(memory, profile_update)
+    merged_memory["answers_so_far"] = history
+    merged_memory["asked_themes"] = merge_unique(memory.get("asked_themes", []), evaluation.get("asked_themes", []))
+    if evaluation.get("next_question_id"):
+        merged_memory["asked_question_ids"] = merge_unique(memory.get("asked_question_ids", []), [evaluation["next_question_id"]])
+
+    answer_score = clamp_int(evaluation.get("answer_score", heuristic_score(transcript, role)), 0, 10)
+    feedback_jp = clean_text(evaluation.get("feedback_jp")) or default_feedback(answer_score)
+
+    history[-1]["answer_score"] = answer_score
+    history[-1]["feedback_jp"] = feedback_jp
+    history[-1]["question_theme"] = evaluation.get("question_theme")
+    history[-1]["keywords_matched"] = keyword_matches(transcript, role["expected_keywords"])
+
+    merged_memory["experience_status"] = detect_experience_status(merged_memory, transcript)
+    merged_memory["low_score_count"] = int(memory.get("low_score_count", 0)) + (1 if answer_score <= 3 else 0)
+
+    should_finish = decide_finish(
+        role=role,
+        memory=merged_memory,
+        question_no=question_no,
+        question_count=question_count,
+        answer_score=answer_score,
+    )
+
+    if should_finish:
+        result = run_final_evaluation_if_possible(merged_memory, role, llm_used=llm_used)
+        return {
+            "ok": True,
+            "is_finished": True,
+            "session_uuid": session_uuid,
+            "question_no": question_no,
+            "question_count": question_count,
+            "transcript_jp": transcript,
+            "answer_score": answer_score,
+            "feedback_jp": feedback_jp,
+            "memory": merged_memory,
+            "llm_used": llm_used,
+            "result": result,
+        }
+
+    next_question_no = question_no + 1
+    next_question_id = clean_text(evaluation.get("next_question_id"))
+    next_question_jp = clean_text(evaluation.get("next_question_jp"))
+
+    if not next_question_id or not next_question_jp:
+        chosen = candidate_questions[0] if candidate_questions else choose_any_unused_question(role, merged_memory)
+        next_question_id = chosen["id"]
+        next_question_jp = chosen["jp"]
+
+    return {
+        "ok": True,
+        "is_finished": False,
+        "session_uuid": session_uuid,
+        "question_no": question_no,
+        "question_count": question_count,
+        "transcript_jp": transcript,
+        "answer_score": answer_score,
+        "feedback_jp": feedback_jp,
+        "memory": merged_memory,
+        "llm_used": llm_used,
+        "next_question_no": next_question_no,
+        "next_question_id": next_question_id,
+        "next_question_jp": next_question_jp,
+        "speak_now": True,
+    }
+
+
+def transcribe_audio_with_hf(audio_bytes: bytes, filename: str) -> str:
+    if not HF_TOKEN:
+        raise RuntimeError("HF_TOKEN is missing for ASR.")
+    url = f"{HF_INFERENCE_BASE}/{ASR_MODEL}"
+    headers = {
+        "Authorization": f"Bearer {HF_TOKEN}",
+        "Content-Type": guess_mime_type(filename),
+    }
+    response = requests.post(url, headers=headers, data=audio_bytes, timeout=ASR_TIMEOUT_SECONDS)
+    response.raise_for_status()
+    data = response.json()
+    if isinstance(data, dict):
+        text = data.get("text") or data.get("generated_text") or ""
+        return normalize_text(text)
+    if isinstance(data, list) and data:
+        # fallback for some provider formats
+        text = data[0].get("text", "") if isinstance(data[0], dict) else ""
+        return normalize_text(text)
+    return ""
+
+
+def guess_mime_type(filename: str) -> str:
+    name = (filename or "").lower()
+    if name.endswith(".wav"):
+        return "audio/wav"
+    if name.endswith(".mp3"):
+        return "audio/mpeg"
+    if name.endswith(".m4a"):
+        return "audio/mp4"
+    if name.endswith(".ogg"):
+        return "audio/ogg"
+    return "audio/webm"
+
+
+def run_llm_turn(
+    role: Dict[str, Any],
+    question_no: int,
+    question_count: int,
+    question_id: str,
+    current_question: str,
+    transcript: str,
+    memory: Dict[str, Any],
+    history: List[Dict[str, Any]],
+    candidate_questions: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    system_prompt = (
+        "You are a Japanese interviewer for working visa practice. "
+        "Use simple N4-level Japanese. "
+        "Ask ONE realistic interview question at a time. "
+        "Stay inside the selected job role. "
+        "If the answer is weak or unclear, you may ask a short repeat or clarification question. "
+        "If the candidate is failing badly and the minimum number of questions has been reached, you may end the interview early. "
+        "Return ONLY valid JSON."
+    )
+    payload = {
+        "role_key": role["role_key"],
+        "role_name_jp": role["japanese_name"],
+        "question_no": question_no,
+        "question_count_target": question_count,
+        "current_question_id": question_id,
+        "current_question_jp": current_question,
+        "candidate_answer_jp": transcript,
+        "memory": {
+            "candidate_name": memory.get("candidate_name"),
+            "country_name": memory.get("country_name"),
+            "age": memory.get("age"),
+            "reason_for_japan": memory.get("reason_for_japan"),
+            "occupation": memory.get("occupation"),
+            "japanese_level": memory.get("japanese_level"),
+            "experience_status": memory.get("experience_status"),
+            "low_score_count": memory.get("low_score_count", 0),
+            "asked_themes": memory.get("asked_themes", []),
+        },
+        "history_tail": history[-6:],
+        "candidate_questions": [
+            {
+                "id": q["id"],
+                "jp": q["jp"],
+                "theme": q["theme"],
+                "branch": q["branch"],
+                "stage": q["stage"],
+                "expected_keywords": q.get("expected_keywords", []),
+            }
+            for q in candidate_questions[:12]
+        ],
+        "schema": {
+            "answer_score": "integer 0-10",
+            "feedback_jp": "one short Japanese sentence",
+            "question_theme": "theme string",
+            "asked_themes": ["array"],
+            "profile_update": {
+                "candidate_name": "string or null",
+                "country_name": "string or null",
+                "age": "integer or null",
+                "reason_for_japan": "string or null",
+                "occupation": "string or null",
+                "japanese_level": "string or null",
+                "experience_status": "yes or no or unknown"
+            },
+            "continue_interview": "boolean",
+            "next_question_id": "question id from candidate_questions or empty when ending",
+            "next_question_jp": "question text from candidate_questions or empty when ending"
+        },
+        "rules": [
+            "Use only the provided candidate_questions for next_question_id.",
+            "Do not repeat a question unless clarification is needed.",
+            "Keep the question natural and interview-like.",
+            "Use the candidate name if known.",
+            "If question_no is already at target, continue_interview must be false."
+        ],
+    }
+    raw = call_hf_chat_json(system_prompt=system_prompt, user_payload=payload)
+    result = normalize_llm_turn_result(raw)
+    result["profile_update"] = merge_memory(
+        maybe_extract_basic_profile(memory, transcript, question_no),
+        result.get("profile_update", {}),
+    )
+    if question_no >= question_count:
+        result["continue_interview"] = False
+        result["next_question_id"] = ""
+        result["next_question_jp"] = ""
+    return result
+
+
+def normalize_llm_turn_result(raw: Dict[str, Any]) -> Dict[str, Any]:
+    profile = raw.get("profile_update", {}) if isinstance(raw.get("profile_update"), dict) else {}
+    asked_themes = raw.get("asked_themes", [])
+    if not isinstance(asked_themes, list):
+        asked_themes = []
+    return {
+        "answer_score": clamp_int(raw.get("answer_score", 6), 0, 10),
+        "feedback_jp": clean_text(raw.get("feedback_jp")),
+        "question_theme": clean_text(raw.get("question_theme")) or None,
+        "asked_themes": [clean_text(x) for x in asked_themes if clean_text(x)],
+        "profile_update": {
+            "candidate_name": normalize_optional_text(profile.get("candidate_name")),
+            "country_name": normalize_optional_text(profile.get("country_name")),
+            "age": normalize_optional_int(profile.get("age")),
+            "reason_for_japan": normalize_optional_text(profile.get("reason_for_japan")),
+            "occupation": normalize_optional_text(profile.get("occupation")),
+            "japanese_level": normalize_optional_text(profile.get("japanese_level")),
+            "experience_status": normalize_optional_text(profile.get("experience_status")),
+        },
+        "continue_interview": bool(raw.get("continue_interview", True)),
+        "next_question_id": clean_text(raw.get("next_question_id")),
+        "next_question_jp": clean_text(raw.get("next_question_jp")),
+    }
+
+
+def call_hf_chat_json(system_prompt: str, user_payload: Dict[str, Any]) -> Dict[str, Any]:
+    if not HF_TOKEN:
+        raise RuntimeError("HF_TOKEN is missing.")
+    body = {
+        "model": CHAT_MODEL,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": json.dumps(user_payload, ensure_ascii=False)},
+        ],
+        "temperature": 0.35,
+        "max_tokens": 900,
+        "response_format": {"type": "json_object"},
+    }
+    response = requests.post(
+        HF_ROUTER_URL,
+        headers={
+            "Authorization": f"Bearer {HF_TOKEN}",
+            "Content-Type": "application/json",
+        },
+        json=body,
+        timeout=LLM_TIMEOUT_SECONDS,
+    )
+    response.raise_for_status()
+    data = response.json()
+    content = data.get("choices", [{}])[0].get("message", {}).get("content", "")
+    if not content:
+        raise RuntimeError("HF router returned empty content.")
+    parsed = json.loads(content)
+    if not isinstance(parsed, dict):
+        raise RuntimeError("HF router did not return a JSON object.")
+    return parsed
+
+
+def select_candidate_questions(role: Dict[str, Any], memory: Dict[str, Any], transcript: str) -> List[Dict[str, Any]]:
+    questions = role["questions"]
+    asked_ids = set(memory.get("asked_question_ids", []))
+    asked_themes = set(memory.get("asked_themes", []))
+    experience_status = detect_experience_status(memory, transcript)
+    priority: List[Tuple[int, Dict[str, Any]]] = []
+
+    for q in questions:
+        if q["id"] in asked_ids or q["stage"] == "closing":
+            continue
+        score = 0
+        theme = q["theme"]
+        stage = q["stage"]
+        branch = q["branch"]
+
+        if stage == "screening":
+            score += 30
+        if stage == "role":
+            score += 20
+        if stage == "followup":
+            score += 10
+
+        if theme not in asked_themes:
+            score += 15
+        else:
+            score -= 6
+
+        if branch == "yes_exp" and experience_status == "yes":
+            score += 18
+        elif branch == "no_exp" and experience_status == "no":
+            score += 18
+        elif branch in {"yes_exp", "no_exp"} and experience_status == "unknown":
+            score -= 10
+
+        if theme == "experience" and experience_status == "unknown":
+            score += 14
+
+        if theme in {"intro", "motivation", "language"} and len(memory.get("answers_so_far", [])) < 4:
+            score += 18
+
+        if theme in {"safety", "teamwork", "reliability"} and len(memory.get("answers_so_far", [])) >= 4:
+            score += 10
+
+        if keyword_matches(transcript, q.get("expected_keywords", [])):
+            score += 4
+
+        priority.append((score, q))
+
+    priority.sort(key=lambda x: x[0], reverse=True)
+    picked = [q for _, q in priority[:12]]
+    if not picked:
+        chosen = choose_any_unused_question(role, memory)
+        return [chosen] if chosen else []
+    return picked
+
+
+def fallback_turn_evaluation(
+    role: Dict[str, Any],
+    memory: Dict[str, Any],
+    transcript: str,
+    candidate_questions: List[Dict[str, Any]],
+    error: str,
+) -> Dict[str, Any]:
+    profile_update = maybe_extract_basic_profile(memory, transcript, len(memory.get("answers_so_far", [])))
+    if "experience_status" not in profile_update:
+        profile_update["experience_status"] = detect_experience_status(memory, transcript)
+
+    score = heuristic_score(transcript, role)
+    next_q = candidate_questions[0] if candidate_questions else choose_any_unused_question(role, memory)
+    continue_interview = True
+    if int(memory.get("low_score_count", 0)) >= 2 and len(memory.get("answers_so_far", [])) >= role["min_questions"]:
+        continue_interview = False
+
+    return {
+        "answer_score": score,
+        "feedback_jp": default_feedback(score),
+        "profile_update": profile_update,
+        "continue_interview": continue_interview,
+        "next_question_id": next_q["id"] if next_q else "",
+        "next_question_jp": next_q["jp"] if next_q else "",
+        "question_theme": next_q["theme"] if next_q else "",
+        "asked_themes": [next_q["theme"]] if next_q else [],
+        "debug_error": error,
+    }
+
+
+def decide_finish(role: Dict[str, Any], memory: Dict[str, Any], question_no: int, question_count: int, answer_score: int) -> bool:
+    if question_no >= question_count:
+        return True
+    if int(memory.get("no_sound_count", 0)) >= 2 and question_no >= role["min_questions"]:
+        return True
+    if int(memory.get("low_score_count", 0)) >= 3 and question_no >= role["min_questions"]:
+        return True
+    return False
+
+
+def run_final_evaluation_if_possible(merged_memory: Dict[str, Any], role: Dict[str, Any], llm_used: bool) -> Dict[str, Any]:
+    if llm_used and HF_TOKEN:
+        try:
+            return run_llm_final_evaluation(merged_memory, role)
+        except Exception:
+            pass
+    return build_final_result(merged_memory, role, force_fail=False)
+
+
+def run_llm_final_evaluation(merged_memory: Dict[str, Any], role: Dict[str, Any]) -> Dict[str, Any]:
+    history = merged_memory.get("answers_so_far", [])
+    system_prompt = (
+        "You are a Japanese interview evaluator for N4-level job interview practice. "
+        "Review the interview fairly. "
+        "Return ONLY valid JSON. "
+        "Use short Japanese only for summary_jp and closing_message_jp."
+    )
+    payload = {
+        "role_key": role["role_key"],
+        "role_name_jp": role["japanese_name"],
+        "profile_memory": {
+            "candidate_name": merged_memory.get("candidate_name"),
+            "country_name": merged_memory.get("country_name"),
+            "age": merged_memory.get("age"),
+            "reason_for_japan": merged_memory.get("reason_for_japan"),
+            "occupation": merged_memory.get("occupation"),
+            "japanese_level": merged_memory.get("japanese_level"),
+            "experience_status": merged_memory.get("experience_status"),
+        },
+        "history": history,
+        "schema": {
+            "summary_jp": "short Japanese summary",
+            "overall_score": "integer 0-100",
+            "scores": {
+                "fluency": "1-10",
+                "grammar": "1-10",
+                "confidence": "1-10",
+                "relevance": "1-10",
+                "role_fit": "1-10"
+            },
+            "pass_fail": "PASS or FAIL",
+            "strengths": ["short strings"],
+            "weaknesses": ["short strings"],
+            "tips": ["short strings"],
+            "closing_message_jp": "thank you message in Japanese"
+        },
+    }
+    raw = call_hf_chat_json(system_prompt=system_prompt, user_payload=payload)
+    raw_scores = raw.get("scores", {}) if isinstance(raw.get("scores"), dict) else {}
+    return {
+        "candidate_name": merged_memory.get("candidate_name"),
+        "country_name": merged_memory.get("country_name"),
+        "age": merged_memory.get("age"),
+        "job_role": merged_memory.get("job_role"),
+        "job_role_jp": merged_memory.get("job_role_jp"),
+        "summary_jp": clean_text(raw.get("summary_jp")) or "面接が完了しました。",
+        "total_questions": len(history),
+        "overall_score": clamp_int(raw.get("overall_score", 65), 0, 100),
+        "scores": {
+            "fluency": clamp_int(raw_scores.get("fluency", 6), 1, 10),
+            "grammar": clamp_int(raw_scores.get("grammar", 6), 1, 10),
+            "confidence": clamp_int(raw_scores.get("confidence", 6), 1, 10),
+            "relevance": clamp_int(raw_scores.get("relevance", 6), 1, 10),
+            "role_fit": clamp_int(raw_scores.get("role_fit", 6), 1, 10),
+        },
+        "pass_fail": "PASS" if str(raw.get("pass_fail", "PASS")).upper() == "PASS" else "FAIL",
+        "strengths": ensure_string_list(raw.get("strengths")),
+        "weaknesses": ensure_string_list(raw.get("weaknesses")),
+        "tips": ensure_string_list(raw.get("tips")),
+        "closing_message_jp": clean_text(raw.get("closing_message_jp")) or random_closing(role),
+        "answers": history,
+    }
+
+
+def build_final_result(merged_memory: Dict[str, Any], role: Dict[str, Any], force_fail: bool = False, summary_jp: str = "") -> Dict[str, Any]:
+    history = merged_memory.get("answers_so_far", [])
+    scores = [int(item.get("answer_score", 0)) for item in history] or [0]
+    avg_10 = round(mean(scores), 1)
+    overall_score = clamp_int(avg_10 * 10, 0, 100)
+    if force_fail:
+        overall_score = min(overall_score, 39)
+    pass_fail = "PASS" if overall_score >= 60 and not force_fail else "FAIL"
+
+    strengths: List[str] = []
+    weaknesses: List[str] = []
+    tips: List[str] = []
+
+    if merged_memory.get("candidate_name"):
+        strengths.append("Basic self introduction was understood.")
+    else:
+        weaknesses.append("Name was not clearly understood.")
+
+    if merged_memory.get("experience_status") == "yes":
+        strengths.append("Candidate shared job-related experience.")
+    elif merged_memory.get("experience_status") == "no":
+        weaknesses.append("No direct experience was explained clearly.")
+
+    if overall_score >= 70:
+        strengths.append("Answers were mostly clear and relevant.")
+    else:
+        weaknesses.append("Several answers were short or unclear.")
+
+    tips.extend([
+        "Use one or two extra sentences in each answer.",
+        "Use polite endings like です and ます.",
+        "Answer slowly and clearly.",
+    ])
+
+    return {
+        "candidate_name": merged_memory.get("candidate_name"),
+        "country_name": merged_memory.get("country_name"),
+        "age": merged_memory.get("age"),
+        "job_role": merged_memory.get("job_role"),
+        "job_role_jp": merged_memory.get("job_role_jp"),
+        "summary_jp": summary_jp or "面接が完了しました。おつかれさまでした。",
+        "total_questions": len(history),
+        "overall_score": overall_score,
+        "scores": {
+            "fluency": clamp_int(round(avg_10), 1, 10),
+            "grammar": clamp_int(round(avg_10 - 1), 1, 10),
+            "confidence": clamp_int(round(avg_10), 1, 10),
+            "relevance": clamp_int(round(avg_10 + 1), 1, 10),
+            "role_fit": clamp_int(round(avg_10), 1, 10),
+        },
+        "pass_fail": pass_fail,
+        "strengths": strengths,
+        "weaknesses": weaknesses,
+        "tips": tips,
+        "closing_message_jp": random_closing(role),
+        "answers": history,
+    }
+
+
+def random_closing(role: Dict[str, Any]) -> str:
+    for q in role["questions"]:
+        if q["stage"] == "closing":
+            return q["jp"]
+    return f"本日の{role['japanese_name']}の面接練習はここまでです。ご参加ありがとうございました。"
+
+
+def choose_any_unused_question(role: Dict[str, Any], memory: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    asked_ids = set(memory.get("asked_question_ids", []))
+    for q in role["questions"]:
+        if q["id"] not in asked_ids and q["stage"] != "closing":
+            return q
+    return None
+
+
+def get_question_by_id(role: Dict[str, Any], question_id: str) -> Optional[Dict[str, Any]]:
+    for q in role["questions"]:
+        if q["id"] == question_id:
+            return q
+    return None
+
+
+def normalize_text(text: str) -> str:
+    return re.sub(r"\s+", " ", (text or "")).strip()
+
+
+def clean_text(value: Any) -> str:
+    return normalize_text(str(value or ""))
+
+
+def normalize_optional_text(value: Any) -> Optional[str]:
+    value = clean_text(value)
+    return value or None
+
+
+def normalize_optional_int(value: Any) -> Optional[int]:
+    try:
+        if value in (None, ""):
+            return None
+        return int(value)
+    except Exception:
+        return None
+
+
+def merge_unique(old_values: List[Any], new_values: List[Any]) -> List[Any]:
+    result = list(old_values or [])
+    for item in new_values or []:
+        if item not in result:
+            result.append(item)
+    return result
+
+
+def safe_json_loads(value: str) -> Dict[str, Any]:
+    try:
+        parsed = json.loads(value or "{}")
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        return {}
+
+
+def clamp_int(value: Any, low: int, high: int) -> int:
+    try:
+        return max(low, min(high, int(round(float(value)))))
+    except Exception:
+        return low
+
+
+def merge_memory(memory: Dict[str, Any], memory_update: Dict[str, Any]) -> Dict[str, Any]:
+    merged = dict(memory or {})
+    for key, value in (memory_update or {}).items():
+        if value not in (None, "", [], {}):
+            merged[key] = value
+    return merged
+
+
+def maybe_extract_basic_profile(memory: Dict[str, Any], transcript: str, question_no: int) -> Dict[str, Any]:
+    update: Dict[str, Any] = {}
+    text = transcript.strip()
+
+    if not memory.get("candidate_name"):
+        name = extract_name(text)
+        if question_no <= 2 and name:
+            update["candidate_name"] = name
+
+    if not memory.get("country_name"):
+        country = extract_country(text)
+        if country:
+            update["country_name"] = country
+
+    if not memory.get("age"):
+        age = extract_age(text)
+        if age:
+            update["age"] = age
+
+    if not memory.get("reason_for_japan") and any(x in text for x in ["日本", "働きたい", "行きたい", "勉強"]):
+        update["reason_for_japan"] = text[:80]
+
+    if not memory.get("occupation") and any(x in text for x in ["仕事", "働いて", "学生", "勉強"]):
+        update["occupation"] = text[:80]
+
+    if not memory.get("japanese_level") and any(x in text for x in ["日本語", "勉強", "年", "ヶ月", "少し"]):
+        update["japanese_level"] = text[:80]
+
+    update["experience_status"] = detect_experience_status(memory, text)
+    return update
+
+
+def detect_experience_status(memory: Dict[str, Any], text: str) -> str:
+    current = str(memory.get("experience_status", "unknown"))
+    low = (text or "").strip()
+    yes_markers = ["あります", "しました", "働いたことがあります", "経験があります", "やったことがあります"]
+    no_markers = ["ありません", "ないです", "したことがありません", "経験がありません", "ない"]
+    if any(x in low for x in yes_markers):
+        return "yes"
+    if any(x in low for x in no_markers):
+        return "no"
+    return current if current in {"yes", "no"} else "unknown"
+
+
+def extract_name(text: str) -> Optional[str]:
+    value = text.replace("私は", "").replace("わたしは", "").replace("ぼくは", "")
+    value = value.replace("です", "").replace("と申します", "").replace("といいます", "").strip(" 。")
+    if not value or len(value) > 30:
+        return None
+    return value
+
+
+def extract_country(text: str) -> Optional[str]:
+    known = ["ネパール", "日本", "インド", "バングラデシュ", "スリランカ", "ベトナム", "中国", "ミャンマー", "フィリピン", "インドネシア"]
+    for item in known:
+        if item in text:
+            return item
+    match = re.search(r"(.+?)から来ました", text)
+    if match:
+        return match.group(1).strip(" 。")
+    return None
+
+
+def extract_age(text: str) -> Optional[int]:
+    match = re.search(r"(\d{1,2})", text)
+    if match:
+        return int(match.group(1))
+    return None
+
+
+def keyword_matches(text: str, keywords: List[str]) -> List[str]:
+    hits = []
+    for kw in keywords:
+        if kw and kw in text:
+            hits.append(kw)
+    return hits
+
+
+def heuristic_score(transcript: str, role: Dict[str, Any]) -> int:
+    text = transcript.strip()
+    if not text:
+        return 0
+    score = 3
+    if len(text) >= 6:
+        score += 1
+    if len(text) >= 12:
+        score += 1
+    if "です" in text or "ます" in text:
+        score += 1
+    hits = len(keyword_matches(text, role["expected_keywords"]))
+    if hits >= 1:
+        score += 1
+    if hits >= 2:
+        score += 1
+    if len(text) >= 25:
+        score += 1
+    return min(score, 10)
+
+
+def default_feedback(score: int) -> str:
+    if score >= 8:
+        return "とても良いです。自然に答えられています。"
+    if score >= 6:
+        return "良いです。もう少し長く、ていねいに話すともっと良くなります。"
+    if score >= 4:
+        return "意味は伝わりますが、少し短いです。完全な文で話してみましょう。"
+    return "短すぎるか、内容が分かりにくいです。もう少し詳しく話してください。"
+
+
+def ensure_string_list(value: Any) -> List[str]:
+    if not isinstance(value, list):
+        return []
+    result = []
+    for item in value:
+        text = clean_text(item)
+        if text:
+            result.append(text)
+    return result