nardial 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,305 @@
1
+ import json
2
+ import wave
3
+ from os import environ
4
+ import re
5
+
6
+
7
+ import numpy as np
8
+ from sic_framework.core.message_python2 import AudioRequest
9
+ from sic_framework.devices import Nao, Pepper
10
+ from sic_framework.devices.common_naoqi.naoqi_motion import NaoqiAnimationRequest
11
+ from sic_framework.devices.common_naoqi.naoqi_motion_recorder import NaoqiMotionRecording, PlayRecording
12
+ from sic_framework.devices.device import SICDeviceManager
13
+ from sic_framework.services.google_tts.google_tts import Text2Speech, Text2SpeechConf, GetSpeechRequest, SpeechResult
14
+ from sic_framework.devices.common_desktop.desktop_speakers import SpeakersConf
15
+ from sic_framework.services.llm.openai_gpt import GPT
16
+ from sic_framework.services.llm import GPTConf, GPTRequest
17
+ from dotenv import load_dotenv
18
+
19
+ from sic_framework.devices.desktop import Desktop
20
+ from sic_framework.services.dialogflow.dialogflow import (
21
+ Dialogflow,
22
+ DialogflowConf,
23
+ GetIntentRequest,
24
+ )
25
+
26
+
27
+ class ConversationAgent:
28
+ def __init__(self, device_manager: SICDeviceManager, google_keyfile_path, sample_rate_dialogflow_hertz=44100, dialogflow_language="en",
29
+ google_tts_voice_name="en-US-Standard-C", google_tts_voice_gender="FEMALE", default_speaking_rate=1.0,
30
+ openai_key_path=None):
31
+
32
+ if openai_key_path:
33
+ load_dotenv(openai_key_path)
34
+
35
+ # Setup GPT client
36
+ conf = GPTConf(openai_key=environ["OPENAI_API_KEY"])
37
+ self.gpt = GPT(conf=conf)
38
+ print("OpenAI GPT4 Ready")
39
+
40
+ # Setup TTS
41
+ self.google_tts_voice_name = google_tts_voice_name
42
+ self.google_tts_voice_gender = google_tts_voice_gender
43
+ self.tts = Text2Speech(conf=Text2SpeechConf(keyfile_json=json.load(open(google_keyfile_path)),
44
+ speaking_rate=default_speaking_rate))
45
+ init_reply = self.tts.request(GetSpeechRequest(text="I am initializing",
46
+ voice_name=self.google_tts_voice_name,
47
+ ssml_gender=self.google_tts_voice_gender))
48
+ self.tts_sample_rate = init_reply.sample_rate
49
+ print("Google TTS ready")
50
+
51
+ # Setup Device Manager
52
+ if isinstance(device_manager, Pepper) or isinstance(device_manager, Nao):
53
+ self.device = device_manager
54
+ self.speaker = device_manager.speaker
55
+ elif isinstance(device_manager, Desktop):
56
+ self.device = Desktop(speakers_conf=SpeakersConf(sample_rate=self.tts_sample_rate))
57
+ self.speaker = self.device.speakers
58
+ else:
59
+ raise ValueError(f"DeviceManager {device_manager} is currently not supported")
60
+ self.mic = self.device.mic
61
+ print("Device connected")
62
+
63
+ # Set up Dialogflow
64
+ dialogflow_conf = DialogflowConf(keyfile_json=json.load(open(google_keyfile_path)),
65
+ sample_rate_hertz=sample_rate_dialogflow_hertz, language=dialogflow_language)
66
+ self.dialogflow = Dialogflow(ip="localhost", conf=dialogflow_conf, input_source=self.mic)
67
+ # flag to signal when the app should listen (i.e. transmit to dialogflow)
68
+ self.request_id = np.random.randint(10000)
69
+ print("Dialogflow Ready")
70
+
71
+ def say(self, text, speaking_rate=1.0):
72
+ print('Saying', text)
73
+ reply = self.tts.request(GetSpeechRequest(text=text,
74
+ voice_name=self.google_tts_voice_name,
75
+ ssml_gender=self.google_tts_voice_gender,
76
+ speaking_rate=speaking_rate))
77
+ print(f'Speech generated with sample rate: {reply.sample_rate}')
78
+ self.speaker.request(AudioRequest(reply.waveform, reply.sample_rate))
79
+ print('Sent to device speaker')
80
+
81
+ def play_audio(self, audio_file):
82
+ with wave.open(audio_file, 'rb') as wf:
83
+ # Get parameters
84
+ sample_width = wf.getsampwidth()
85
+ framerate = wf.getframerate()
86
+ n_frames = wf.getnframes()
87
+
88
+ # Ensure format is 16-bit (2 bytes per sample)
89
+ if sample_width != 2:
90
+ raise ValueError("WAV file is not 16-bit audio. Sample width = {} bytes.".format(sample_width))
91
+
92
+ audio = wf.readframes(n_frames)
93
+ self.speaker.request(AudioRequest(audio, framerate))
94
+
95
+ def play_motion_sequence(self, motion_sequence_file):
96
+ if isinstance(self.device, Desktop):
97
+ return
98
+ try:
99
+ recording = NaoqiMotionRecording.load(motion_sequence_file)
100
+ self.device.motion_record.request(PlayRecording(recording))
101
+ except Exception as e:
102
+ print(f"Exception: {e}")
103
+
104
+ def play_animation(self, animation_name):
105
+ if isinstance(self.device, Desktop):
106
+ return
107
+ try:
108
+ self.device.motion.request(NaoqiAnimationRequest(animation_name), block=True)
109
+ except Exception as e:
110
+ print(f"Failed to play animation: {animation_name}", e)
111
+
112
+ def ask_yesno(self, question, max_attempts=2):
113
+ attempts = 0
114
+ while attempts < max_attempts:
115
+ # ask question
116
+ tts_reply = self.tts.request(GetSpeechRequest(text=question,
117
+ voice_name=self.google_tts_voice_name,
118
+ ssml_gender=self.google_tts_voice_gender))
119
+ self.speaker.request(AudioRequest(tts_reply.waveform, tts_reply.sample_rate))
120
+
121
+ # listen for answer
122
+ # TODO: Wrap this listening logic in reusable `listen()` function(s).
123
+ reply = self.dialogflow.request(GetIntentRequest(self.request_id, {'answer_yesno': 1}))
124
+
125
+ print("The detected intent:", reply.intent)
126
+
127
+ # return answer
128
+ if reply.intent:
129
+ if "yesno_yes" in reply.intent:
130
+ return "yes"
131
+ elif "yesno_no" in reply.intent:
132
+ return "no"
133
+ elif "yesno_dontknow" in reply.intent:
134
+ return "dontknow"
135
+ attempts += 1
136
+ return None
137
+
138
+ def ask_entity(self, question, context, target_intent, target_entity, max_attempts=2):
139
+ attempts = 0
140
+
141
+ while attempts < max_attempts:
142
+ # ask question
143
+ tts_reply = self.tts.request(GetSpeechRequest(text=question,
144
+ voice_name=self.google_tts_voice_name,
145
+ ssml_gender=self.google_tts_voice_gender))
146
+ self.speaker.request(AudioRequest(tts_reply.waveform, tts_reply.sample_rate))
147
+
148
+ # listen for answer
149
+ # TODO: Wrap this listening logic in reusable `listen()` function(s).
150
+ reply = self.dialogflow.request(GetIntentRequest(self.request_id, context))
151
+
152
+ print("The detected intent:", reply.intent)
153
+
154
+ # Return entity
155
+ if reply.intent:
156
+ if target_intent in reply.intent:
157
+ if reply.response.query_result.parameters and target_entity in reply.response.query_result.parameters:
158
+ return reply.response.query_result.parameters[target_entity]
159
+ attempts += 1
160
+ return None
161
+
162
+ def ask_open(self, question, max_attempts=2):
163
+ attempts = 0
164
+
165
+ while attempts < max_attempts:
166
+ # ask question
167
+ tts_reply = self.tts.request(GetSpeechRequest(text=question,
168
+ voice_name=self.google_tts_voice_name,
169
+ ssml_gender=self.google_tts_voice_gender))
170
+ self.speaker.request(AudioRequest(tts_reply.waveform, tts_reply.sample_rate))
171
+
172
+ # listen for answer
173
+ # TODO: Wrap this listening logic in reusable `listen()` function(s).
174
+ reply = self.dialogflow.request(GetIntentRequest(self.request_id))
175
+
176
+ print("The detected intent:", reply.intent)
177
+
178
+ # Return entity
179
+ if reply.response.query_result.query_text:
180
+ return reply.response.query_result.query_text
181
+ attempts += 1
182
+ return None
183
+
184
+ def ask_options(self, question, options, max_attempts=2):
185
+ """
186
+ Ask a multiple-choice question and return the chosen option as a string.
187
+ Uses ask_open under the hood and matches the answer to one of the options.
188
+ """
189
+ attempts = 0
190
+ options_lower = [opt.lower() for opt in options]
191
+ while attempts < max_attempts:
192
+ answer = self.ask_open(question)
193
+ if answer:
194
+ answer_lower = answer.lower()
195
+ for opt in options_lower:
196
+ if opt in answer_lower:
197
+ return opt
198
+ attempts += 1
199
+ return None
200
+
201
+ def extract_topics_with_gpt(self, raw_topics):
202
+ """Condense raw topics (often full sentences) into 1-2 single-word, lowercase keywords.
203
+
204
+ Returns a de-duplicated list preserving order. Falls back to a simple local heuristic
205
+ if the GPT response can't be parsed.
206
+ """
207
+ def _heuristic(lines):
208
+ if not lines:
209
+ return []
210
+ stop = {
211
+ "the","a","an","and","or","but","if","then","than","that","this","these","those",
212
+ "i","you","he","she","it","we","they","me","my","mine","your","yours","his","her","its","our","ours","their","theirs",
213
+ "to","in","on","at","from","for","with","about","as","of","is","are","was","were","be","been","am","do","does","did",
214
+ "yes","no","maybe","okay","ok","yeah","yep","nope","uh","um","favorite","favourite","because","thing","things","think"
215
+ }
216
+ out, seen = [], set()
217
+ for t in lines:
218
+ words = re.findall(r"[A-Za-z]+", str(t).lower())
219
+ picked = [w for w in words if len(w) > 2 and w not in stop]
220
+ if not picked and words:
221
+ picked = [words[0]]
222
+ # take up to 2 keywords per input line
223
+ for w in picked[:2]:
224
+ if w not in seen:
225
+ out.append(w); seen.add(w)
226
+ return out
227
+
228
+ raw_topics = [str(x) for x in (raw_topics or []) if str(x).strip()]
229
+ if not raw_topics:
230
+ return []
231
+ try:
232
+ prompt = (
233
+ "You will receive a JSON array of phrases. For each item, extract 1-2 concise English keywords "
234
+ "(single words, lowercase). Avoid function words; these are the topics of interest of the user; prefer specific nouns (e.g., 'oak', 'garden', 'dogs', 'elephants'). "
235
+ "Return ONLY a JSON array of unique keywords (strings), no explanations.\n"
236
+ f"INPUT: {json.dumps(raw_topics, ensure_ascii=False)}\nOUTPUT:"
237
+ )
238
+ resp = self.gpt.request(GPTRequest(prompt))
239
+ text = (resp.response or "").strip()
240
+ data = json.loads(text)
241
+ if not isinstance(data, list):
242
+ raise ValueError("GPT did not return a JSON list")
243
+ out, seen = [], set()
244
+ for item in data:
245
+ if not isinstance(item, str):
246
+ continue
247
+ w = re.sub(r"[^A-Za-z]+", "", item.lower())
248
+ if len(w) > 2 and w not in seen:
249
+ out.append(w); seen.add(w)
250
+ return out or _heuristic(raw_topics)
251
+ except Exception:
252
+ return _heuristic(raw_topics)
253
+
254
+ def personalize(self, robot_input: str, user_age: int | str, user_input: str, language: str = "en") -> str:
255
+ """
256
+ Generate a short, supportive, age-aware follow-up line based on the robot's last question and the user's reply.
257
+
258
+ Inputs:
259
+ - robot_input: what the robot just asked/said
260
+ - user_age: age of the child (int or string)
261
+ - user_input: user's reply as captured
262
+ - language: only English ('en') is used; parameter kept for compatibility
263
+
264
+ Returns one sentence (<= 25 words). Falls back to a simple template on failure.
265
+ """
266
+ try:
267
+ age_txt = str(user_age).strip()
268
+ # Always use English prompt for consistency
269
+ system_preamble = (
270
+ f"You are a social robot talking to a child aged {age_txt}. "
271
+ "The child is in the hospital. Your goal is to be warm, positive, and brief. "
272
+ "Use simple words, be encouraging, and you may ask one short follow-up question. "
273
+ "Respond in exactly one sentence (max 25 words)."
274
+ )
275
+ prompt = (
276
+ f"Context: {system_preamble}\n"
277
+ f"Robot asked/said: {robot_input}\n"
278
+ f"Child replied: \"{user_input}\"\n"
279
+ "Now generate an appropriate one-sentence response."
280
+ )
281
+
282
+ resp = self.gpt.request(GPTRequest(prompt))
283
+ text = (resp.response or "").strip()
284
+ # Trim surrounding quotes/newlines if present
285
+ text = re.sub(r'^[\s\"\']+|[\s\"\']+$', "", text)
286
+ # Ensure it ends with a period/question mark for TTS prosody
287
+ if text and text[-1] not in ".!?":
288
+ text += "."
289
+ # Keep it reasonably short
290
+ words = text.split()
291
+ if len(words) > 28:
292
+ text = " ".join(words[:28]) + "…"
293
+ return text or "Thanks for sharing. Would you like to tell me a bit more?"
294
+ except Exception:
295
+ return "Thanks for sharing. Would you like to tell me a bit more?"
296
+
297
+ def ask_llm(self, user_prompt, context_messages, system_prompt):
298
+ try:
299
+ return self.gpt.request(GPTRequest(prompt=user_prompt, context_messages=context_messages, system_message=system_prompt))
300
+ except Exception as e:
301
+ print(f"Exception: {e}")
302
+ return None
303
+
304
+ def greet(self):
305
+ self.say("Hello, I am your companion robot")
@@ -0,0 +1,295 @@
1
+ from pathlib import Path
2
+ from typing import Any, Dict, List, Optional, Union
3
+ from datetime import datetime
4
+ import os
5
+ import json
6
+ import re
7
+
8
+
9
+ class Session:
10
+ def __init__(self, session_id: str, participant_id: Optional[str] = None, run_id: Optional[str] = None,
11
+ metadata: Optional[Dict[str, Any]] = None, started_at: Optional[str] = None, ended_at: Optional[str] = None,
12
+ events: Optional[List[Dict[str, Any]]] = None, dialog_ids: Optional[List[str]] = None,
13
+ summary: Optional[Dict[str, Any]] = None) -> None:
14
+ self.session_id = session_id
15
+ self.participant_id = participant_id
16
+ self.run_id = run_id
17
+ self.metadata = metadata or {}
18
+ self.started_at = started_at or datetime.utcnow().isoformat()
19
+ self.ended_at = ended_at
20
+ self.events: List[Dict[str, Any]] = events or []
21
+ self.dialog_ids: List[str] = dialog_ids or []
22
+ self.summary: Dict[str, Any] = summary or {}
23
+
24
+
25
+ class ConversationState:
26
+ """
27
+ Minimal conversation history manager with per-participant transcripts:
28
+ - continuity: completed_dialogs, user_model, topics_of_interest
29
+ - per-session history: events (your session_history), metadata
30
+ - session-level dialog_ids: ordered, unique IDs used in the session
31
+ - per-participant transcript files under participants/{participant_id}.json
32
+ """
33
+
34
+ def __init__(
35
+ self,
36
+ path: Optional[str] = None,
37
+ base_dir: Optional[str] = None,
38
+ overwrite_with_participant_info: bool = False
39
+ ) -> None:
40
+ # Determine base directory
41
+ self.base_dir = Path(base_dir) if base_dir else Path.cwd()
42
+
43
+ # Default file location inside the caller's project
44
+ self.path = Path(path) if path else self.base_dir / "conversation_state.json"
45
+ self.path.parent.mkdir(parents=True, exist_ok=True)
46
+
47
+ # continuity
48
+ self.completed_dialogs: List[str] = []
49
+ self.user_model: Dict[str, Any] = {}
50
+ self.topics_of_interest: List[str] = []
51
+
52
+ # all sessions (append-only)
53
+ self.sessions: List[Session] = []
54
+
55
+ # participants folder inside caller's project
56
+ self.participants_dir = self.base_dir / "participants"
57
+ self.participants_dir.mkdir(parents=True, exist_ok=True)
58
+
59
+ self.load()
60
+
61
+ self.participant_id = None
62
+ if overwrite_with_participant_info:
63
+ self.overwrite_with_participant_info()
64
+
65
+ def overwrite_with_participant_info(self) -> None:
66
+ self.participant_id = os.environ.get("PARTICIPANT_ID") or None
67
+ if not self.participant_id:
68
+ return
69
+
70
+ print(f"[INFO] Using participant_id={self.participant_id}")
71
+ pid_completed, pid_topics = self.load_participant_continuity(participant_id=self.participant_id)
72
+
73
+ # For a new participant (no file), this will be empty -> fresh run
74
+ self.completed_dialogs = pid_completed or set()
75
+ self.topics_of_interest = pid_topics or []
76
+ self.user_model = {}
77
+
78
+ print(
79
+ f"[DEBUG] Loaded participant continuity: completed={sorted(list(self.completed_dialogs))}, "
80
+ f"topics={self.topics_of_interest}")
81
+
82
+ def load_participant_continuity(self, participant_id: str):
83
+ try:
84
+ safe_id = self._sanitize_participant_id(participant_id)
85
+ path = self.participants_dir / f"{safe_id}.json"
86
+
87
+ if not path.exists():
88
+ return set(), []
89
+
90
+ with open(path, "r", encoding="utf-8") as f:
91
+ data = json.load(f) or {}
92
+
93
+ summary = data.get("summary") or {}
94
+ completed = set(summary.get("dialog_ids_seen") or [])
95
+ topics = list(summary.get("topics_of_interest") or [])
96
+
97
+ return completed, topics
98
+ except Exception:
99
+ return set(), []
100
+
101
+ def load(self) -> None:
102
+ if not self.path.exists():
103
+ self._initialize_empty_state()
104
+ return
105
+
106
+ try:
107
+ with open(self.path, "r", encoding="utf-8") as f:
108
+ data = json.load(f) or {}
109
+ except Exception:
110
+ # corrupted file fallback
111
+ self._initialize_empty_state()
112
+ return
113
+
114
+ self.completed_dialogs = data.get("completed_dialogs", [])
115
+ self.user_model = data.get("user_model", {})
116
+ self.topics_of_interest = data.get("topics_of_interest", [])
117
+ self.sessions = [Session(**s) for s in data.get("sessions", [])]
118
+
119
+ def _initialize_empty_state(self) -> None:
120
+ self.completed_dialogs = []
121
+ self.user_model = {}
122
+ self.topics_of_interest = []
123
+ self.sessions = []
124
+
125
+ self.save() # create file immediately
126
+
127
+ def save(self) -> None:
128
+ data = {
129
+ "completed_dialogs": self.completed_dialogs,
130
+ "user_model": self.user_model,
131
+ "topics_of_interest": self.topics_of_interest,
132
+ "sessions": [s.__dict__ for s in self.sessions],
133
+ }
134
+ self._atomic_write_json(self.path, data)
135
+
136
+ # ---------- per-session ----------
137
+ def start_session(self, metadata: Optional[Dict[str, Any]] = None, *, participant_id: Optional[str] = None, run_id: Optional[str] = None) -> str:
138
+ sid = f"sess_{len(self.sessions) + 1:04d}"
139
+ session = Session(session_id=sid, participant_id=participant_id, run_id=run_id, metadata=metadata)
140
+ self.sessions.append(session)
141
+ return sid
142
+
143
+ def add_events(self, session_id: str, events: List[Dict[str, Any]]) -> None:
144
+ sess = self._get_session(session_id)
145
+ sess.events.extend(list(events or []))
146
+
147
+ def add_dialog_id(self, session_id: str, dialog_id: str) -> None:
148
+ """Use this if you want to record dialog IDs during the run."""
149
+ sess = self._get_session(session_id)
150
+ if sess.dialog_ids is None:
151
+ sess.dialog_ids = []
152
+ if dialog_id not in sess.dialog_ids:
153
+ sess.dialog_ids.append(dialog_id)
154
+
155
+ def end_session(self,
156
+ session_id: str,
157
+ completed_ids: Optional[Union[List[str], set]] = None,
158
+ user_model: Optional[Dict[str, Any]] = None,
159
+ topics_of_interest: Optional[List[str]] = None,
160
+ extra_summary: Optional[Dict[str, Any]] = None) -> None:
161
+ """Finalize a session, merge continuity, and derive dialog_ids if needed."""
162
+ sess = self._get_session(session_id)
163
+ sess.ended_at = datetime.utcnow().isoformat()
164
+ sess.summary = {
165
+ "user_model": user_model or {},
166
+ "topics_of_interest": topics_of_interest or [],
167
+ **(extra_summary or {})
168
+ }
169
+
170
+ # If caller didn't pass completed_ids, derive dialog_ids once from events
171
+ if not completed_ids and not sess.dialog_ids:
172
+ self._derive_dialog_ids_from_events(sess)
173
+
174
+ # Continuity merges
175
+ if completed_ids:
176
+ self._merge_completed(completed_ids)
177
+ elif sess.dialog_ids:
178
+ self._merge_completed(sess.dialog_ids)
179
+ if user_model:
180
+ self.user_model.update(user_model)
181
+ if topics_of_interest:
182
+ self._merge_interests(topics_of_interest)
183
+
184
+ # Write/update per-participant transcript if participant_id present
185
+ pid = sess.participant_id
186
+ if pid:
187
+ self.save_participant_transcript(pid)
188
+
189
+ # ---------- helpers ----------
190
+ def _get_session(self, session_id: str) -> Session:
191
+ for s in self.sessions:
192
+ if s.session_id == session_id:
193
+ return s
194
+ raise KeyError(f"Session {session_id} not found")
195
+
196
+ def _merge_completed(self, completed_ids: Union[List[str], set]) -> None:
197
+ prev = set(self.completed_dialogs)
198
+ self.completed_dialogs = list(prev.union(set(completed_ids)))
199
+
200
+ def _merge_interests(self, topics: List[str]) -> None:
201
+ seen = {str(x).strip().lower() for x in self.topics_of_interest}
202
+ for t in topics or []:
203
+ k = str(t).strip().lower()
204
+ if k and k not in seen:
205
+ self.topics_of_interest.append(t)
206
+ seen.add(k)
207
+
208
+ @staticmethod
209
+ def _derive_dialog_ids_from_events(sess: Session) -> None:
210
+ """Build ordered unique dialog_ids from system events in the session history."""
211
+ ids: List[str] = []
212
+ seen = set()
213
+ for ev in sess.events or []:
214
+ if ev.get("type") in {"dialog_start", "dialog_end"}:
215
+ did = ev.get("dialog_id")
216
+ if isinstance(did, str):
217
+ k = did.strip()
218
+ if k and k not in seen:
219
+ ids.append(k)
220
+ seen.add(k)
221
+ if ids:
222
+ sess.dialog_ids = ids
223
+
224
+ # ---------- per-participant transcripts ----------
225
+ def save_participant_transcript(self, participant_id: str) -> None:
226
+ safe_id = self._sanitize_participant_id(participant_id)
227
+ path = Path(self.participants_dir) / f"{safe_id}.json"
228
+
229
+ sessions = [s for s in self.sessions if s.participant_id == participant_id]
230
+
231
+ payload = {
232
+ "participant_id": participant_id,
233
+ "sessions": [s.__dict__ for s in sessions],
234
+ "summary": {
235
+ "total_sessions": len(sessions),
236
+ "dialog_ids_seen": self._collect_dialog_ids(sessions),
237
+ "topics_of_interest": self._collect_topics_from_summaries(sessions),
238
+ "last_updated": datetime.utcnow().isoformat(),
239
+ },
240
+ }
241
+
242
+ self._atomic_write_json(path, payload)
243
+
244
+ @staticmethod
245
+ def _sanitize_participant_id(participant_id: str) -> str:
246
+ s = str(participant_id).strip()
247
+ s = re.sub(r"\s+", "_", s)
248
+ s = re.sub(r"[^A-Za-z0-9._-]", "_", s)
249
+ reserved = {"CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9"}
250
+ if s.upper() in reserved:
251
+ s = f"_{s}"
252
+ return s or "participant"
253
+
254
+ @staticmethod
255
+ def _collect_dialog_ids(sessions: List[Session]) -> List[str]:
256
+ seen, ids = set(), []
257
+ for s in sessions:
258
+ for did in s.dialog_ids or []:
259
+ k = str(did).strip()
260
+ if k and k not in seen:
261
+ ids.append(k)
262
+ seen.add(k)
263
+ return ids
264
+
265
+ @staticmethod
266
+ def _collect_topics_from_summaries(sessions: List[Session]) -> List[str]:
267
+ seen, topics = set(), []
268
+ for s in sessions:
269
+ for t in (s.summary or {}).get("topics_of_interest") or []:
270
+ if isinstance(t, str):
271
+ k = t.strip().lower()
272
+ if k and k not in seen:
273
+ topics.append(t)
274
+ seen.add(k)
275
+ return topics
276
+
277
+ # ---------- safe write ----------
278
+ @staticmethod
279
+ def _atomic_write_json(path: Union[str, Path], data: Dict[str, Any]) -> None:
280
+ path = Path(path)
281
+ path.parent.mkdir(parents=True, exist_ok=True)
282
+
283
+ tmp_path = path.with_suffix(path.suffix + ".tmp")
284
+
285
+ def _serialize(obj):
286
+ if isinstance(obj, Session):
287
+ return obj.__dict__
288
+ if isinstance(obj, datetime):
289
+ return obj.isoformat()
290
+ raise TypeError(f"Type not serializable: {type(obj)}")
291
+
292
+ with open(tmp_path, "w", encoding="utf-8") as f:
293
+ json.dump(data, f, indent=2, ensure_ascii=False, default=_serialize)
294
+
295
+ os.replace(tmp_path, path)