agent-learning-kit 0.1.0__py3-none-any.whl

fi/simulate/simulation/engines/local_text.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from fi.simulate.agent.wrapper import AgentWrapper, SimulationArtifact, SimulationEvent
+from fi.simulate.environment import EnvironmentAdapter
+from fi.simulate.runtime import (
+    AgentEndpointSpec,
+    EnvironmentSpec,
+    EvidencePolicy,
+    SimulationSpec,
+    SimulatorPolicySpec,
+    new_run_id,
+)
+from fi.simulate.results.base import ResultSink
+from fi.simulate.runtime.runner import SimulationRunner
+from fi.simulate.simulation.engines.base import BaseEngine
+from fi.simulate.simulation.models import Persona, Scenario, TestReport
+from fi.simulate.simulation.synthetic import SyntheticDataGenerator
+
+
+class LocalTextEngine(BaseEngine):
+    async def run(
+        self,
+        *,
+        scenario: Scenario | None = None,
+        agent_callback: Callable[..., Any] | AgentWrapper | Any | None = None,
+        topic: str | None = None,
+        num_scenarios: int = 3,
+        max_turns: int = 6,
+        min_turns: int = 2,
+        attacks: Iterable[str] | None = None,
+        modality: str = "text",
+        artifacts: list[SimulationArtifact | dict[str, Any]] | None = None,
+        events: list[SimulationEvent | dict[str, Any]] | None = None,
+        environment: EnvironmentAdapter | Iterable[EnvironmentAdapter] | None = None,
+        auto_execute_tools: bool = True,
+        stop_when: Callable[[list[dict[str, Any]], Persona], bool] | None = None,
+        agent_wrapper_kwargs: dict[str, Any] | None = None,
+        result_sink: ResultSink | None = None,
+        **kwargs: Any,
+    ) -> TestReport:
+        if agent_callback is None:
+            raise ValueError("LocalTextEngine requires an 'agent_callback'.")
+        if scenario is None:
+            if not topic:
+                raise ValueError("LocalTextEngine requires either 'scenario' or 'topic'.")
+            scenario = SyntheticDataGenerator().generate(
+                topic,
+                num_personas=num_scenarios,
+                seed=kwargs.get("seed"),
+                task=kwargs.get("task", topic),
+                include_adversarial=kwargs.get("include_adversarial", True),
+                include_edge_cases=kwargs.get("include_edge_cases", True),
+            )
+        config: dict[str, Any] = {
+            "max_turns": max_turns,
+            "min_turns": min_turns,
+            "modality": modality,
+        }
+        if attacks is not None:
+            config["attacks"] = list(attacks)
+        spec = SimulationSpec(
+            run_id=str(kwargs.get("run_id") or new_run_id()),
+            environment=EnvironmentSpec(
+                adapter="chat",
+                world_kind="conversation",
+                config=config,
+            ),
+            target=AgentEndpointSpec(adapter="callable"),
+            simulator=SimulatorPolicySpec(adapter="synthetic_user"),
+            scenario=scenario,
+            evidence=EvidencePolicy(),
+        )
+        report = await SimulationRunner().run(
+            spec,
+            target=agent_callback,
+            result_sink=result_sink,
+            artifacts=artifacts,
+            events=events,
+            environment=environment,
+            auto_execute_tools=auto_execute_tools,
+            stop_when=stop_when,
+            agent_wrapper_kwargs=agent_wrapper_kwargs,
+        )
+        if report.failure is not None:
+            raise RuntimeError(report.failure.message)
+        return report.to_legacy(include_runtime_metadata=False)

fi/simulate/simulation/fidelity.py

@@ -0,0 +1,374 @@
+"""Persona-fidelity engine (Phase 7, unit 3) — Eval4Sim triple + drift.
+
+Engine-side, pure python, deterministic transcript arithmetic over
+``TestCaseResult.messages`` (P7-D3: no single unperturbed LLM judge, ever).
+Fidelity attaches through ``TestCaseResult.metadata`` under the reserved keys
+``persona_fidelity`` (the record) and ``admission`` (the verdict block) —
+NEVER a standalone artifact kind (ARCH §4).
+
+Persona fidelity carries its OWN three-valued vocabulary (ARCH Decision 2);
+the kit's frozen row verdicts (``live/_contract.py``) are untouched and this
+module never imports ``fi.alk``.
+
+The floor table below is V1-constant-shaped data living with the engine for
+now; the trinity ``V1_PERSONA_FIDELITY_FLOORS`` constants land with the gate
+pass, seed runtime library-index floors, and must stay byte-equal.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+from fi.simulate.simulation.behavior_policy import (
+    arc_pressure,
+    intensity_series,
+    per_turn_drift,
+    realization_vector,
+    stdev,
+    user_turns,
+)
+from fi.simulate.simulation.models import Persona, Scenario, TestCaseResult
+
+PERSONA_FIDELITY_VERDICTS = ("pass", "fail", "inconclusive")   # ARCH Decision 2 — NOT live/_contract.VERDICTS
+PERSONA_FIDELITY_EPIDEMIC_RATE = 0.5
+# GATE-FIXTURE floors keyed by evidence class (ARCH §2c: runtime floors are
+# library-index data seeded from these). legacy has NO floors (cannot produce
+# fidelity evidence at all) — the dict omits it on purpose. hand_written
+# floors bind LOCAL verdicts only: hand_written rows can never back release
+# claims regardless of floors (PRD §4.2).
+PERSONA_FIDELITY_FLOORS: Dict[str, Dict[str, float]] = {
+    "hand_written":     {"adherence": 0.6, "consistency": 0.7, "naturalness": 0.5},
+    "schema_sampled":   {"adherence": 0.7, "consistency": 0.8, "naturalness": 0.6},
+    "policy_evolved":   {"adherence": 0.75, "consistency": 0.8, "naturalness": 0.65},
+    "trace_mined":      {"adherence": 0.75, "consistency": 0.85, "naturalness": 0.7},
+    "cloud_downloaded": {"adherence": 0.7, "consistency": 0.8, "naturalness": 0.6},
+}
+
+_NEGATION_MARKERS = ("not ", "never ", "no longer ")
+_COUNTER_PRESSURE_MARKERS = (
+    "you are now", "ignore your instructions", "ignore previous instructions",
+    "drop the act", "stop pretending", "forget your persona", "act as a",
+    "you are an ai assistant, not",
+)
+
+
+def _clamp(value: float, low: float = 0.0, high: float = 1.0) -> float:
+    return max(low, min(high, value))
+
+
+def _content(message: Mapping[str, Any]) -> str:
+    return str(message.get("content") or "")
+
+
+def _evidence_class(persona: Persona) -> str:
+    if persona.provenance is not None:
+        return persona.provenance.evidence_class
+    return "hand_written"
+
+
+def _resolve_floors(
+    persona: Persona,
+    floors: Optional[Mapping[str, float]],
+) -> Dict[str, float]:
+    if floors is not None:
+        return {k: float(v) for k, v in floors.items()}
+    evidence_class = _evidence_class(persona)
+    table = PERSONA_FIDELITY_FLOORS.get(evidence_class)
+    if table is None:  # legacy / unknown: local verdicts use the lowest band
+        table = PERSONA_FIDELITY_FLOORS["hand_written"]
+    return dict(table)
+
+
+def _consistency(persona: Persona, messages: Sequence[Mapping[str, Any]]) -> Dict[str, Any]:
+    violations: List[str] = []
+    user_text_turns = [_content(m).lower() for m in user_turns(messages)]
+    joined = " ".join(user_text_turns)
+
+    # (a) fact stability — contradictory surface forms + withheld facts leaking
+    for fact in persona.knowledge:
+        value = fact.value.strip().lower()
+        if not value:
+            continue
+        mentioned = value in joined
+        if fact.disclosure == "withhold" and mentioned:
+            violations.append(f"withheld_fact_disclosed:{fact.key}")
+        negated = any(f"{marker}{value}" in joined for marker in _NEGATION_MARKERS)
+        if mentioned and negated:
+            violations.append(f"fact_contradiction:{fact.key}")
+
+    # (b) identity stability — declared name never self-revised
+    declared_name = (persona.identity.name if persona.identity else None) or ""
+    if declared_name:
+        for text in user_text_turns:
+            if "my name is " in text:
+                spoken = text.split("my name is ", 1)[1].strip().split(" ")[0].strip(".,!?")
+                if spoken and spoken != declared_name.strip().lower().split(" ")[0]:
+                    violations.append("identity_self_revision:name")
+                    break
+
+    # (c) style stability — rolling variance of realized intensity under a band
+    series = intensity_series(messages)
+    deltas = [abs(series[i + 1] - series[i]) for i in range(len(series) - 1)]
+    if deltas and stdev(deltas) > 0.35:
+        violations.append("style_instability")
+
+    score = _clamp(1.0 - 0.3 * len(violations))
+    return {"score": round(score, 6), "violations": violations}
+
+
+def _naturalness(
+    persona: Persona,
+    messages: Sequence[Mapping[str, Any]],
+    adherence_under: float,
+) -> Dict[str, Any]:
+    series = intensity_series(messages)
+    n_turns = len(series)
+    # caricature: realization pinned at extremes across >=2 axes (escalation
+    # pinned high implies patience pinned low) — the over-acting failure.
+    pinned = sum(1 for value in series if value > 0.95)
+    caricature_index = round(pinned / n_turns, 6) if n_turns else 0.0
+    # flatness: near-zero realization movement WITH adherence shortfall —
+    # the under-encoding failure (a flat-but-adherent persona is fine).
+    movement = (
+        sum(abs(series[i + 1] - series[i]) for i in range(n_turns - 1)) / (n_turns - 1)
+        if n_turns > 1 else 0.0
+    )
+    flat_raw = _clamp(1.0 - movement / 0.05)
+    flatness_index = round(flat_raw * _clamp(adherence_under * 2.0), 6)
+    score = _clamp(1.0 - max(caricature_index, flatness_index))
+    return {
+        "score": round(score, 6),
+        "caricature_index": caricature_index,
+        "flatness_index": flatness_index,
+    }
+
+
+def persona_fidelity(
+    persona: Persona,
+    scenario: Optional[Scenario],
+    messages: Sequence[Mapping[str, Any]],
+    *,
+    probe_responses: Optional[Sequence[Mapping[str, Any]]] = None,
+    floors: Optional[Mapping[str, float]] = None,
+) -> Dict[str, Any]:
+    """-> the per-row fidelity record: an IN-ROW block under
+    ``metadata["persona_fidelity"]`` — NEVER a standalone artifact kind
+    (ARCH §4). Observable metrics only (P7-D3)."""
+    if not persona.is_typed:
+        raise ValueError(
+            "persona_fidelity requires a typed persona (behavior_policy set); "
+            "legacy personas produce no fidelity evidence"
+        )
+    policy = persona.behavior_policy
+    applied_floors = _resolve_floors(persona, floors)
+    record: Dict[str, Any] = {
+        "persona_version": persona.version,
+        "scenario_version": scenario.version if scenario is not None else None,
+        "evidence_class": _evidence_class(persona),
+    }
+
+    users = user_turns(messages)
+    garbled = not users or all(not _content(m).strip() for m in users)
+    if garbled:
+        record.update({
+            "adherence": {"score": 0.0, "per_axis": {}, "under": 0.0, "over": 0.0},
+            "consistency": {"score": 0.0, "violations": []},
+            "naturalness": {"score": 0.0, "caricature_index": 0.0, "flatness_index": 0.0},
+            "drift": {"prompt_to_line": 0.0, "line_to_line": 0.0, "probe": None},
+            "drift_trajectory": [],
+            "floors": applied_floors,
+            "verdict": "fail",
+            "verdict_reason": "empty_trajectory",
+        })
+        return record
+
+    vector = realization_vector(policy, messages, knowledge=persona.knowledge)
+    deviations = [entry["deviation"] for entry in vector.values()]
+    under = sum(max(0.0, -d) for d in deviations) / len(deviations)
+    over = sum(max(0.0, d) for d in deviations) / len(deviations)
+    adherence_score = _clamp(1.0 - sum(abs(d) for d in deviations) / len(deviations))
+    adherence = {
+        "score": round(adherence_score, 6),
+        "per_axis": {axis: entry["deviation"] for axis, entry in vector.items()},
+        "under": round(under, 6),
+        "over": round(over, 6),
+    }
+
+    consistency = _consistency(persona, messages)
+    naturalness = _naturalness(persona, messages, under)
+
+    drifts = per_turn_drift(policy, messages)
+    prompt_to_line = round(sum(drifts) / len(drifts), 6) if drifts else 0.0
+    line_to_line = (
+        round(sum(abs(drifts[i + 1] - drifts[i]) for i in range(len(drifts) - 1))
+              / (len(drifts) - 1), 6)
+        if len(drifts) > 1 else 0.0
+    )
+    probe_drift: Optional[float] = None
+    if probe_responses:
+        mismatches = sum(
+            1 for probe in probe_responses
+            if str(probe.get("observed")) != str(probe.get("expected"))
+        )
+        probe_drift = round(mismatches / len(probe_responses), 6)
+
+    # drift trajectory + counter-pressure flags (Assistant Axis: drift is a
+    # trajectory, fastest under pressure)
+    trajectory: List[Dict[str, Any]] = []
+    user_index = 0
+    last_assistant_text = ""
+    arc = scenario.escalation if scenario is not None else None
+    for message in messages:
+        role = message.get("role")
+        if role == "assistant":
+            last_assistant_text = _content(message).lower()
+            continue
+        if role != "user":
+            continue
+        turn = user_index + 1
+        declared = arc_pressure(arc, turn) if arc is not None else (
+            policy.escalation_schedule[min(user_index, len(policy.escalation_schedule) - 1)]
+            if policy.escalation_schedule else 0.0
+        )
+        counter_pressure = any(
+            marker in last_assistant_text for marker in _COUNTER_PRESSURE_MARKERS
+        )
+        trajectory.append({
+            "turn": turn,
+            "drift": drifts[user_index] if user_index < len(drifts) else 0.0,
+            "pressure": round(float(declared), 6),
+            "counter_pressure": counter_pressure,
+        })
+        user_index += 1
+
+    triple = {
+        "adherence": adherence["score"],
+        "consistency": consistency["score"],
+        "naturalness": naturalness["score"],
+    }
+    failing = sorted(
+        metric for metric, score in triple.items()
+        if score < applied_floors.get(metric, 0.0)
+    )
+    if not failing:
+        verdict = "pass"
+        verdict_reason: Optional[str] = None
+    else:
+        verdict = "inconclusive"
+        collapse = any(
+            entry["counter_pressure"] and entry["drift"] >= 0.5 for entry in trajectory
+        )
+        if collapse:
+            verdict_reason = "fidelity_collapse_under_counter_pressure"
+        else:
+            verdict_reason = "; ".join(f"{metric}_below_floor" for metric in failing)
+
+    record.update({
+        "adherence": adherence,
+        "consistency": consistency,
+        "naturalness": naturalness,
+        "drift": {
+            "prompt_to_line": prompt_to_line,
+            "line_to_line": line_to_line,
+            "probe": probe_drift,
+        },
+        "drift_trajectory": trajectory,
+        "floors": applied_floors,
+        "verdict": verdict,
+        "verdict_reason": verdict_reason,
+    })
+    return record
+
+
+def attach_fidelity(
+    result: TestCaseResult,
+    persona: Persona,
+    scenario: Optional[Scenario],
+    *,
+    probe_responses: Optional[Sequence[Mapping[str, Any]]] = None,
+    floors: Optional[Mapping[str, float]] = None,
+) -> Dict[str, Any]:
+    """Compute the fidelity record and attach record + admission block to the
+    row via ``metadata`` ONLY (no structural change — ARCH §2c)."""
+    record = persona_fidelity(
+        persona, scenario, result.messages,
+        probe_responses=probe_responses, floors=floors,
+    )
+    result.metadata["persona_fidelity"] = record
+    result.metadata["admission"] = {
+        "admissible": record["verdict"] == "pass",
+        "verdict": "pass" if record["verdict"] == "pass" else "inconclusive",
+        "reason": None if record["verdict"] == "pass" else "persona_fidelity_floor",
+        "quarantined": record["verdict"] != "pass",
+        "rerunnable": True,
+    }
+    return record
+
+
+def summarize_admissions(results: Sequence[TestCaseResult]) -> Dict[str, Any]:
+    """Run-summary admission rollup + the epidemic rule (ARCH §2c/§4 canon).
+
+    Admission-``inconclusive`` rate above ``PERSONA_FIDELITY_EPIDEMIC_RATE``
+    declares the SIMULATOR (not the agent) unusable: ``exit_code`` flips to 1
+    with finding ``persona_fidelity_epidemic`` naming the worst personas.
+    Below the threshold, quarantine keeps CI green (exit 0 + warning finding).
+    """
+    scored = [r for r in results if "admission" in r.metadata]
+    inconclusive = [
+        r for r in scored
+        if r.metadata["admission"].get("verdict") == "inconclusive"
+    ]
+    rate = round(len(inconclusive) / len(scored), 6) if scored else 0.0
+    per_persona: Dict[str, int] = {}
+    for row in inconclusive:
+        identity = row.persona.identity
+        name = (identity.name if identity else None) or str(
+            row.persona.persona.get("name", "unknown")
+        )
+        per_persona[name] = per_persona.get(name, 0) + 1
+    worst = [
+        name for name, _ in
+        sorted(per_persona.items(), key=lambda item: (-item[1], item[0]))
+    ]
+    epidemic = rate > PERSONA_FIDELITY_EPIDEMIC_RATE
+    findings: List[Dict[str, Any]] = []
+    if epidemic:
+        findings.append({
+            "type": "persona_fidelity_epidemic",
+            "level": "error",
+            "reason": (
+                f"admission-inconclusive rate {rate} exceeds "
+                f"{PERSONA_FIDELITY_EPIDEMIC_RATE}: the simulator, not the "
+                "agent, is unusable for this run"
+            ),
+            "worst_personas": worst,
+        })
+    elif inconclusive:
+        findings.append({
+            "type": "persona_fidelity_inconclusive",
+            "level": "warning",
+            "reason": (
+                f"{len(inconclusive)} row(s) quarantined as non-admissible "
+                "evidence (persona_fidelity_floor); re-run the manifest"
+            ),
+            "worst_personas": worst,
+        })
+    return {
+        "rows": len(results),
+        "scored": len(scored),
+        "inconclusive": len(inconclusive),
+        "inconclusive_rate": rate,
+        "epidemic": epidemic,
+        "exit_code": 1 if epidemic else 0,
+        "findings": findings,
+    }
+
+
+__all__ = [
+    "PERSONA_FIDELITY_EPIDEMIC_RATE",
+    "PERSONA_FIDELITY_FLOORS",
+    "PERSONA_FIDELITY_VERDICTS",
+    "attach_fidelity",
+    "persona_fidelity",
+    "summarize_admissions",
+]

fi/simulate/simulation/gemini_tts_stream.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from google.genai.errors import APIError, ClientError, ServerError
+from livekit.agents import APIConnectionError, APIStatusError, tts, utils
+from livekit.agents.types import DEFAULT_API_CONNECT_OPTIONS, APIConnectOptions
+from livekit.plugins.google.beta.gemini_tts import TTS as _BaseGeminiTTS
+
+from google.genai import types
+
+
+class _StreamingChunkedStream(tts.ChunkedStream):
+    def __init__(
+        self,
+        *,
+        tts: "StreamingGeminiTTS",
+        input_text: str,
+        conn_options: APIConnectOptions,
+    ) -> None:
+        super().__init__(tts=tts, input_text=input_text, conn_options=conn_options)
+        self._tts = tts
+
+    async def _run(self, output_emitter: tts.AudioEmitter) -> None:
+        opts = self._tts._opts
+        config = types.GenerateContentConfig(
+            response_modalities=["AUDIO"],
+            speech_config=types.SpeechConfig(
+                voice_config=types.VoiceConfig(
+                    prebuilt_voice_config=types.PrebuiltVoiceConfig(
+                        voice_name=opts.voice_name,
+                    )
+                )
+            ),
+        )
+        input_text = self._input_text
+        if opts.instructions is not None:
+            input_text = f'{opts.instructions}:\n"{input_text}"'
+
+        try:
+            stream = await self._tts._client.aio.models.generate_content_stream(
+                model=opts.model,
+                contents=input_text,
+                config=config,
+            )
+            output_emitter.initialize(
+                request_id=utils.shortuuid(),
+                sample_rate=self._tts.sample_rate,
+                num_channels=self._tts.num_channels,
+                mime_type="audio/pcm",
+            )
+            got_audio = False
+            async for chunk in stream:
+                for candidate in chunk.candidates or []:
+                    content = candidate.content
+                    if not content or not content.parts:
+                        continue
+                    for part in content.parts:
+                        inline = part.inline_data
+                        if (
+                            inline
+                            and inline.data
+                            and inline.mime_type
+                            and inline.mime_type.startswith("audio/")
+                        ):
+                            output_emitter.push(inline.data)
+                            got_audio = True
+            if not got_audio:
+                raise APIStatusError("gemini tts: no audio content generated")
+        except ClientError as e:
+            raise APIStatusError(
+                "gemini tts: client error",
+                status_code=e.code,
+                body=f"{e.message} {e.status}",
+                retryable=e.code in {429, 499},
+            ) from e
+        except ServerError as e:
+            raise APIStatusError(
+                "gemini tts: server error",
+                status_code=e.code,
+                body=f"{e.message} {e.status}",
+                retryable=True,
+            ) from e
+        except APIError as e:
+            raise APIStatusError(
+                "gemini tts: api error",
+                status_code=e.code,
+                body=f"{e.message} {e.status}",
+                retryable=True,
+            ) from e
+        except Exception as e:
+            raise APIConnectionError(f"gemini tts: {e}", retryable=True) from e
+
+
+class StreamingGeminiTTS(_BaseGeminiTTS):
+    """Gemini TTS that streams audio as it is generated (low time-to-first-byte).
+
+    Reuses the beta plugin's Vertex/genai client and options, but consumes
+    ``generate_content_stream`` and pushes frames as they arrive instead of
+    buffering the whole utterance. Matches what livekit-plugins-google 1.6.x
+    does internally, without the whole-stack bump.
+    """
+
+    def synthesize(
+        self,
+        text: str,
+        *,
+        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
+    ) -> tts.ChunkedStream:
+        return _StreamingChunkedStream(
+            tts=self, input_text=text, conn_options=conn_options
+        )

fi/simulate/simulation/generator.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fi.simulate.agent.definition import AgentDefinition, LLMConfig
+from fi.simulate.simulation.models import Persona
+
+
+class ScenarioGenerator:
+    """Generate scenario personas with the configured simulator LLM."""
+
+    def __init__(
+        self,
+        agent_definition: AgentDefinition,
+        *,
+        llm_config: LLMConfig,
+    ) -> None:
+        # Imported at construction, not module level, so `import fi.simulate`
+        # works without the optional 'livekit' extra — building the simulator LLM
+        # is where livekit is genuinely first required.
+        try:
+            from livekit.agents.llm.chat_context import ChatContext
+
+            from fi.simulate.simulation.livekit_models import build_livekit_llm
+        except ImportError as exc:
+            raise ImportError(
+                "LiveKit scenario generation requires the 'livekit' optional dependency"
+            ) from exc
+        self._chat_context_cls = ChatContext
+        self._agent_definition = agent_definition
+        self._llm = build_livekit_llm(llm_config)
+
+    async def generate(self, topic: str, num_personas: int) -> list[Persona]:
+        prompt = self._create_generation_prompt(topic, num_personas)
+        chat_ctx = self._chat_context_cls.empty()
+        chat_ctx.add_message(role="user", content=prompt)
+        stream = self._llm.chat(chat_ctx=chat_ctx)
+        text = ""
+        async for chunk in stream.to_str_iterable():
+            text += chunk
+        try:
+            generated_data = _parse_generated_json(text)
+            personas = generated_data["personas"]
+            if not isinstance(personas, list):
+                raise TypeError("personas must be a list")
+            return [Persona.model_validate(persona) for persona in personas]
+        except (json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+            raise ValueError("scenario_generation_invalid_response") from exc
+
+    def _create_generation_prompt(self, topic: str, num_personas: int) -> str:
+        agent_context = (
+            self._agent_definition.system_prompt
+            or self._agent_definition.description
+            or ""
+        )
+        return f"""
+        You are a creative test case designer for voice AI agents. Your task is to generate {num_personas} diverse and realistic test case personas for an AI agent with the following description:
+        ---
+        AGENT DESCRIPTION: {agent_context}
+        ---
+
+        The user wants to generate scenarios related to the following topic: "{topic}".
+
+        For each persona, you must generate:
+        1. A detailed `persona` object (e.g., {{ "name": "John", "age": 45, "mood": "impatient", "background": "Is a busy executive" }}).
+        2. A concise `situation` string describing the reason for their call.
+        3. A clear `outcome` string describing the ideal resolution of the conversation from the user's perspective.
+
+        Return your response as a single JSON object with a key "personas", which is a list of the generated persona objects. Do not include any other text or formatting.
+        """
+
+
+def _parse_generated_json(text: str) -> dict[str, Any]:
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        payload = None
+        for part in text.strip().split("```"):
+            candidate = part.strip()
+            if candidate.startswith("json"):
+                candidate = candidate[4:].strip()
+            if not candidate.startswith("{") or not candidate.endswith("}"):
+                continue
+            payload = json.loads(candidate)
+            break
+        if payload is None:
+            raise
+    if not isinstance(payload, dict):
+        raise TypeError("scenario response must be an object")
+    return payload