tavus-cli 0.1.0__py3-none-any.whl

tavus_mcp/sdk/recipes/build_and_verify.py

@@ -0,0 +1,618 @@
+"""Persona build + verify loop.
+
+Drives the conversational builder end-to-end:
+``chat → creator answers → fan-out artifact updates → publish → select/attach
+replica → CVI text-mode smoke test → LLM-judged verdict``. The builder
+chat, artifact writers, replica selector, probe generator, and judge all
+run on RQH, so end users don't need to bring their own LLM credentials.
+
+The recipe is HTTP-only — it speaks to RQH ``/v2/builder/*``,
+``/v2/persona-builder/*``, and the usual ``/v2/*`` resources, all authenticated
+by the user's ``x-api-key`` like the rest of the SDK.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from tavus_mcp.sdk.client.http import TavusClient
+
+BUILDER_SECTIONS = ("personality", "greeting", "objectives", "guardrails")
+BUILDER_TARGETS = ("persona_name", *BUILDER_SECTIONS)
+PERSONA_BUILDER_LLM_TIMEOUT_S = 120.0
+CVI_SMOKE_TURN_TIMEOUT_S = 60.0
+AnswerProvider = Callable[[dict[str, Any], int, list[dict[str, Any]]], str | None]
+BuildProgress = Callable[[dict[str, Any], int, list[dict[str, Any]]], None]
+
+
+async def build_and_verify(
+    client: TavusClient,
+    *,
+    replica_id: str | None = None,
+    prompt: str | None = None,
+    goal: str | None = None,
+    name: str | None = None,
+    model: str = "claude-sonnet-4-6",
+    inner_model: str | None = None,
+    max_rounds: int = 4,
+    max_turns: int | None = None,
+    answers: Sequence[str] | None = None,
+    answer_provider: AnswerProvider | None = None,
+    on_builder_reply: BuildProgress | None = None,
+    probes: list[str] | None = None,
+    auto_refine: bool = False,
+    max_refine_rounds: int = 3,
+) -> dict[str, Any]:
+    """Drive an end-to-end persona build + CVI text-mode smoke test.
+
+    All LLM work runs on RQH; no client-side LLM credentials are required.
+    Returns ``{builder_id, persona_id, persona_url, replica_id, system_prompt,
+    persona_spec, build_transcript, probes, smoke_transcript, verdict,
+    validated, refine_rounds_used}``.
+    """
+    creator_prompt = _coerce_prompt(prompt, goal)
+    if max_turns is not None:
+        max_rounds = max_turns
+    max_rounds = max(1, max_rounds)
+    session_name = name or _derive_persona_name(creator_prompt)
+
+    if replica_id:
+        await _ensure_replica_exists(client, replica_id)
+
+    session = await client.builders.create({"name": session_name, "model": model})
+    builder_id = str(session["builder_id"])
+    persona_id = str(session["persona_id"])
+
+    build_transcript: list[dict[str, Any]] = []
+    await _run_build_loop(
+        client=client,
+        builder_id=builder_id,
+        prompt=creator_prompt,
+        inner_model=inner_model,
+        max_rounds=max_rounds,
+        answers=answers,
+        answer_provider=answer_provider,
+        on_builder_reply=on_builder_reply,
+        transcript=build_transcript,
+    )
+
+    await client.builders.publish(builder_id)
+    replica_selection: dict[str, Any] | None = None
+    if replica_id:
+        await client.personas.patch(
+            persona_id,
+            [{"op": "replace", "path": "/default_replica_id", "value": replica_id}],
+        )
+    else:
+        replica_selection = await _select_default_replica(client, persona_id, inner_model)
+        replica_id = str(replica_selection.get("replica_id") or "").strip()
+
+    spec = await _assemble_spec(client, persona_id)
+    chosen_probes = (
+        list(probes) if probes else await _generate_probes(client, spec, inner_model)
+    )
+    smoke_transcript = await _run_smoke_test(client, persona_id, chosen_probes)
+    verdict = await _judge_transcript(client, spec, smoke_transcript, inner_model)
+
+    refine_rounds_used = 0
+    while (
+        auto_refine
+        and verdict.get("overall") != "pass"
+        and refine_rounds_used < max_refine_rounds
+    ):
+        gap_message = (
+            "The last CVI smoke test flagged these gaps. Tighten the persona to address "
+            f"them:\n{_summarize_gaps(verdict)}"
+        )
+        await _run_build_loop(
+            client=client,
+            builder_id=builder_id,
+            prompt=gap_message,
+            inner_model=inner_model,
+            max_rounds=max(3, max_rounds // 2),
+            answers=None,
+            answer_provider=None,
+            on_builder_reply=None,
+            transcript=build_transcript,
+        )
+        await client.builders.publish(builder_id)
+        await _prepend_validation_directive(client, persona_id, verdict)
+        spec = await _assemble_spec(client, persona_id)
+        smoke_transcript = await _run_smoke_test(client, persona_id, chosen_probes)
+        verdict = await _judge_transcript(client, spec, smoke_transcript, inner_model)
+        refine_rounds_used += 1
+
+    return {
+        "builder_id": builder_id,
+        "persona_id": persona_id,
+        "persona_name": spec.get("persona_name"),
+        "persona_url": _persona_url(client, persona_id),
+        "system_prompt": spec.get("system_prompt"),
+        "replica_id": replica_id or spec.get("default_replica_id"),
+        "replica_selection": replica_selection,
+        "persona_spec": spec,
+        "build_transcript": build_transcript,
+        "probes": chosen_probes,
+        "smoke_transcript": smoke_transcript,
+        "verdict": verdict,
+        "validated": verdict.get("overall") == "pass",
+        "refine_rounds_used": refine_rounds_used,
+    }
+
+
+def _coerce_prompt(prompt: str | None, goal: str | None) -> str:
+    value = prompt if prompt is not None else goal
+    if not value or not value.strip():
+        raise ValueError("prompt is required")
+    return value.strip()
+
+
+def _derive_persona_name(prompt: str) -> str:
+    """Mirror creator-studio's seeded persona name for the initial row."""
+    import re
+
+    cleaned = re.sub(r"^\s*(an?|the)\s+", "", prompt, flags=re.IGNORECASE)
+    cleaned = re.sub(r"[.!?,;:].*$", "", cleaned).strip()
+    if not cleaned:
+        return "Untitled persona"
+    words = " ".join(cleaned.split()[:4])
+    return words[:1].upper() + words[1:]
+
+
+def _persona_url(client: TavusClient, persona_id: str) -> str:
+    base = str(client.config.dev_portal_url).rstrip("/")
+    return f"{base}/dev/personas/update?persona_id={persona_id}"
+
+
+async def _ensure_replica_exists(client: TavusClient, replica_id: str) -> None:
+    try:
+        await client.replicas.get(replica_id)
+    except Exception as exc:
+        from tavus_mcp.sdk.errors import TavusError
+
+        raise TavusError(
+            f"Replica {replica_id!r} not found in this Tavus environment: {exc}"
+        ) from exc
+
+
+async def _select_default_replica(
+    client: TavusClient, persona_id: str, inner_model: str | None
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"persona_id": persona_id}
+    if inner_model:
+        body["model"] = inner_model
+    selection = await client.request(
+        "POST",
+        "/persona-builder/select-replica",
+        json=body,
+        timeout=PERSONA_BUILDER_LLM_TIMEOUT_S,
+    )
+    replica_id = selection.get("replica_id") if isinstance(selection, dict) else None
+    if not replica_id:
+        from tavus_mcp.sdk.errors import TavusError
+
+        raise TavusError("RQH did not return a default replica selection.")
+    return selection
+
+
+async def _run_build_loop(
+    *,
+    client: TavusClient,
+    builder_id: str,
+    prompt: str,
+    inner_model: str | None,
+    max_rounds: int,
+    answers: Sequence[str] | None,
+    answer_provider: AnswerProvider | None,
+    on_builder_reply: BuildProgress | None,
+    transcript: list[dict[str, Any]],
+) -> None:
+    next_message = prompt
+    answer_index = 0
+    answers_used = 0
+    builder_turns = 0
+    initial_fanout_done = False
+    human_driven = answer_provider is not None or answers is not None
+    max_builder_turns = max_rounds + 1 if human_driven else max_rounds
+    while next_message and builder_turns < max_builder_turns:
+        if not next_message:
+            break
+        latest_creator_message = next_message
+        transcript.append({"role": "user", "text": next_message})
+        reply = await client.builders.chat(builder_id, next_message)
+        builder_turns += 1
+        transcript.append(
+            {
+                "role": "assistant",
+                "text": reply.get("text", ""),
+                "targets": list(reply.get("targets") or []),
+                "draft_ready": bool(reply.get("draft_ready", False)),
+                "suggestions": list(reply.get("suggestions") or []),
+            }
+        )
+        if on_builder_reply is not None:
+            on_builder_reply(reply, min(builder_turns, max_rounds), transcript)
+
+        if reply.get("draft_ready"):
+            sections = _sections_for_ready_reply(reply, initial_fanout_done)
+            if sections:
+                await _apply_builder_sections(
+                    client, builder_id, sections, latest_creator_message
+                )
+                transcript.append(
+                    {
+                        "role": "system",
+                        "text": (
+                            "applied "
+                            + ", ".join(sections)
+                            + f": {latest_creator_message}"
+                        ),
+                    }
+                )
+                initial_fanout_done = True
+
+        if _looks_like_preview_closer(reply):
+            break
+
+        if human_driven:
+            if answers_used >= max_rounds:
+                break
+            if answer_provider is not None:
+                next_message = (
+                    answer_provider(reply, min(builder_turns, max_rounds), transcript)
+                    or ""
+                )
+            else:
+                if answers is None or answer_index >= len(answers):
+                    break
+                next_message = str(answers[answer_index]).strip()
+                answer_index += 1
+            if next_message:
+                answers_used += 1
+            continue
+
+        if reply.get("draft_ready"):
+            break
+
+        decision = await _decide_next(
+            client=client,
+            prompt=prompt,
+            transcript=transcript,
+            latest=reply,
+            inner_model=inner_model,
+        )
+        applied_targets = await _apply_decision_target_updates(
+            client, builder_id, decision, transcript
+        )
+        done = bool(decision.get("action") == "done")
+        if done and not initial_fanout_done and not applied_targets:
+            await _apply_fallback_target_updates(client, builder_id, prompt, transcript)
+            initial_fanout_done = True
+        if done:
+            break
+        next_message = decision.get("next_message") or ""
+
+    if not initial_fanout_done:
+        await _apply_fallback_target_updates(client, builder_id, prompt, transcript)
+
+
+def _sections_for_ready_reply(
+    reply: dict[str, Any], initial_fanout_done: bool
+) -> list[str]:
+    if not initial_fanout_done:
+        return list(BUILDER_SECTIONS)
+    raw_targets = reply.get("targets")
+    if not isinstance(raw_targets, list) or not raw_targets:
+        return list(BUILDER_SECTIONS)
+    sections = [target for target in raw_targets if target in BUILDER_SECTIONS]
+    return list(dict.fromkeys(sections))
+
+
+def _looks_like_preview_closer(reply: dict[str, Any]) -> bool:
+    text = str(reply.get("text") or "").strip().lower()
+    if not text:
+        return False
+    if "preview" not in text:
+        return False
+    return "?" not in text
+
+
+async def _apply_builder_sections(
+    client: TavusClient, builder_id: str, sections: Sequence[str], message: str
+) -> None:
+    for section in sections:
+        if section == "personality":
+            await client.builders.update_personality(
+                builder_id, message, persona_name=True, system_prompt=True
+            )
+        elif section == "greeting":
+            await client.builders.update_greeting(builder_id, message)
+        elif section == "objectives":
+            await client.builders.update_objectives(builder_id, message)
+        elif section == "guardrails":
+            await client.builders.update_guardrails(builder_id, message)
+
+
+async def _apply_decision_target_updates(
+    client: TavusClient,
+    builder_id: str,
+    decision: dict[str, Any],
+    transcript: list[dict[str, Any]],
+) -> set[str]:
+    applied_targets: set[str] = set()
+    for update in _iter_target_updates(decision.get("target_updates")):
+        target = update.get("target")
+        message = update.get("message") or ""
+        if target not in BUILDER_TARGETS or not message:
+            continue
+        await _apply_target_update(client, builder_id, target, message)
+        applied_targets.add(target)
+        transcript.append({"role": "system", "text": f"applied {target}: {message}"})
+    return applied_targets
+
+
+async def _apply_fallback_target_updates(
+    client: TavusClient,
+    builder_id: str,
+    prompt: str,
+    transcript: list[dict[str, Any]],
+) -> None:
+    for target, message in _fallback_target_updates(prompt):
+        await _apply_target_update(client, builder_id, target, message)
+        transcript.append({"role": "system", "text": f"applied {target}: {message}"})
+
+
+def _iter_target_updates(raw: Any) -> list[dict[str, Any]]:
+    if isinstance(raw, dict):
+        raw = [raw]
+    if not isinstance(raw, list):
+        return []
+    return [item for item in raw if isinstance(item, dict)]
+
+
+def _fallback_target_updates(goal: str) -> list[tuple[str, str]]:
+    base = (
+        "The builder marked the draft ready without applying any structured "
+        "persona updates. Use this creator goal to produce the missing "
+        f"configuration:\n\n{goal}"
+    )
+    return [
+        (
+            "persona_name",
+            f"{base}\n\nCreate a short, specific persona title. Use title case. "
+            "Do not use placeholder names.",
+        ),
+        (
+            "personality",
+            f"{base}\n\nCreate a complete, detailed system prompt with role, audience, "
+            "conversation style, workflow, boundaries, and success behavior.",
+        ),
+        (
+            "objectives",
+            f"{base}\n\nCreate concise objectives that capture what the persona should "
+            "drive the conversation toward.",
+        ),
+        (
+            "guardrails",
+            f"{base}\n\nCreate concise guardrails for anything the persona must avoid "
+            "or safely redirect.",
+        ),
+    ]
+
+
+async def _apply_target_update(
+    client: TavusClient, builder_id: str, target: str, message: str
+) -> None:
+    if target == "persona_name":
+        await client.builders.update_personality(builder_id, message, persona_name=True)
+    elif target == "personality":
+        await client.builders.update_personality(
+            builder_id, message, persona_name=True, system_prompt=True
+        )
+    elif target == "greeting":
+        await client.builders.update_greeting(builder_id, message)
+    elif target == "objectives":
+        await client.builders.update_objectives(builder_id, message)
+    elif target == "guardrails":
+        await client.builders.update_guardrails(builder_id, message)
+
+
+async def _decide_next(
+    *,
+    client: TavusClient,
+    prompt: str,
+    transcript: list[dict[str, Any]],
+    latest: dict[str, Any],
+    inner_model: str | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "goal": prompt,
+        "transcript": transcript,
+        "latest_reply": latest,
+    }
+    if inner_model:
+        body["model"] = inner_model
+    return await client.request(
+        "POST",
+        "/persona-builder/llm/decide-next-action",
+        json=body,
+        timeout=PERSONA_BUILDER_LLM_TIMEOUT_S,
+    )
+
+
+async def _generate_probes(
+    client: TavusClient, spec: dict[str, Any], inner_model: str | None
+) -> list[str]:
+    body: dict[str, Any] = {"persona_spec": spec}
+    if inner_model:
+        body["model"] = inner_model
+    response = await client.request(
+        "POST",
+        "/persona-builder/llm/generate-probes",
+        json=body,
+        timeout=PERSONA_BUILDER_LLM_TIMEOUT_S,
+    )
+    probes = [
+        str(p) for p in (response.get("probes") or []) if isinstance(p, str) and p.strip()
+    ]
+    if not probes:
+        return ["Tell me about yourself.", "What can you help me with?"]
+    return probes
+
+
+async def _judge_transcript(
+    client: TavusClient,
+    spec: dict[str, Any],
+    smoke_transcript: list[dict[str, Any]],
+    inner_model: str | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "persona_spec": spec,
+        "smoke_transcript": smoke_transcript,
+    }
+    if inner_model:
+        body["model"] = inner_model
+    verdict = await client.request(
+        "POST",
+        "/persona-builder/llm/judge-transcript",
+        json=body,
+        timeout=PERSONA_BUILDER_LLM_TIMEOUT_S,
+    )
+    if not isinstance(verdict, dict) or "overall" not in verdict:
+        return {
+            "objectives": [],
+            "guardrails": [],
+            "knowledge_base": {"used": False, "evidence": "no verdict returned"},
+            "tools": [],
+            "overall": "partial",
+            "summary": "Judge did not return a structured verdict.",
+        }
+    return verdict
+
+
+async def _assemble_spec(client: TavusClient, persona_id: str) -> dict[str, Any]:
+    persona = await client.personas.get(persona_id, include_settings="true")
+    if not isinstance(persona, dict):
+        return {"persona_id": persona_id, "raw": persona}
+    spec: dict[str, Any] = {
+        "persona_id": persona_id,
+        "persona_name": persona.get("persona_name"),
+        "system_prompt": persona.get("system_prompt"),
+        "greeting": persona.get("greeting"),
+        "default_replica_id": persona.get("default_replica_id"),
+    }
+    objectives_id = persona.get("objectives_id")
+    guardrails_id = persona.get("guardrails_id")
+    document_ids = list(persona.get("document_ids") or [])
+    layers = persona.get("layers") or {}
+    llm_layer = layers.get("llm") if isinstance(layers, dict) else {}
+    tools_field: list[Any] = []
+    if isinstance(llm_layer, dict):
+        tools_field = list(llm_layer.get("tools") or [])
+
+    spec["objectives"] = await _safe_get(client.objectives, objectives_id)
+    spec["guardrails"] = await _safe_get(client.guardrails, guardrails_id)
+    documents: list[Any] = []
+    for did in document_ids:
+        doc = await _safe_get(client.documents, did)
+        if doc is not None:
+            documents.append(doc)
+    spec["documents"] = documents
+    spec["tools"] = tools_field
+    return spec
+
+
+async def _safe_get(resource: Any, resource_id: str | None) -> Any:
+    if not resource_id:
+        return None
+    try:
+        return await resource.get(resource_id)
+    except Exception:
+        return None
+
+
+async def _run_smoke_test(
+    client: TavusClient, persona_id: str, probes: list[str]
+) -> list[dict[str, Any]]:
+    convo = await client.conversations.create({"persona_id": persona_id, "chat": True})
+    cid = str(convo.get("conversation_id") if isinstance(convo, dict) else convo)
+    transcript: list[dict[str, Any]] = []
+    try:
+        for probe in probes:
+            transcript.append({"role": "user", "text": probe})
+            try:
+                reply = await client.conversations.chat_turn(
+                    cid, probe, timeout_s=CVI_SMOKE_TURN_TIMEOUT_S
+                )
+                transcript.append({"role": "assistant", "text": reply})
+            except TimeoutError as exc:
+                transcript.append(
+                    {"role": "assistant", "text": "", "error": f"timeout: {exc}"}
+                )
+    finally:
+        try:
+            await client.conversations.end(cid)
+        except Exception:
+            pass
+    return transcript
+
+
+def _summarize_gaps(verdict: dict[str, Any]) -> str:
+    parts: list[str] = []
+    for obj in verdict.get("objectives") or []:
+        if not obj.get("satisfied"):
+            parts.append(
+                f"Objective '{obj.get('name')}' not satisfied: {obj.get('evidence')}"
+            )
+    for gr in verdict.get("guardrails") or []:
+        if not gr.get("held"):
+            parts.append(f"Guardrail '{gr.get('name')}' did not hold: {gr.get('evidence')}")
+    kb = verdict.get("knowledge_base") or {}
+    if kb and not kb.get("used", True):
+        parts.append(f"Knowledge base not used: {kb.get('evidence')}")
+    for tool in verdict.get("tools") or []:
+        if not tool.get("invoked"):
+            parts.append(f"Tool '{tool.get('name')}' not invoked: {tool.get('evidence')}")
+    if not parts:
+        parts.append(verdict.get("summary") or "Partial coverage; tighten the persona.")
+    return "\n".join(f"- {part}" for part in parts)
+
+
+async def _prepend_validation_directive(
+    client: TavusClient, persona_id: str, verdict: dict[str, Any]
+) -> None:
+    spec = await _assemble_spec(client, persona_id)
+    prompt = str(spec.get("system_prompt") or "").strip()
+    directive = _validation_directive(verdict)
+    if not prompt or directive in prompt:
+        return
+    await client.personas.patch(
+        persona_id,
+        [{"op": "replace", "path": "/system_prompt", "value": f"{directive}\n\n{prompt}"}],
+    )
+
+
+def _validation_directive(verdict: dict[str, Any]) -> str:
+    corrections = [
+        "- You are the published persona, not the persona builder. Never ask the user "
+        "what persona to create.",
+        "- If required information is missing, ask for it instead of giving generic "
+        "advice or jumping ahead.",
+    ]
+    for obj in verdict.get("objectives") or []:
+        if not obj.get("satisfied"):
+            name = obj.get("name") or "unnamed_objective"
+            corrections.append(f"- Satisfy objective `{name}` before attempting later objectives.")
+    for guardrail in verdict.get("guardrails") or []:
+        if not guardrail.get("held"):
+            name = guardrail.get("name") or "unnamed_guardrail"
+            corrections.append(f"- Treat guardrail `{name}` as mandatory in every response.")
+
+    return (
+        "## Critical Runtime Corrections\n\n"
+        "These rules override any conflicting guidance. Before every response, "
+        "check the persona objectives and guardrails. If required information is "
+        "missing, ask for it instead of giving generic advice or jumping ahead.\n"
+        + "\n".join(corrections)
+    )

tavus_mcp/sdk/recipes/options.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from tavus_mcp.sdk.client.http import TavusClient
+from tavus_mcp.sdk.patch import allowed_patch_paths
+from tavus_mcp.sdk.schemas.persona import PersonaPatchModel
+
+
+async def describe_persona_options(client: TavusClient, persona_id: str) -> dict[str, Any]:
+    (
+        persona,
+        replicas,
+        voices,
+        guardrails,
+        objectives,
+        documents,
+        tools,
+        pronunciation_dictionaries,
+        attached_tools,
+    ) = await asyncio.gather(
+        client.personas.get(persona_id, verbose="true", include_settings="true"),
+        client.replicas.list(limit=100, replica_type="system"),
+        client.voices.list(limit=100),
+        client.guardrails.list(limit=100),
+        client.objectives.list(limit=100),
+        client.documents.list(limit=100),
+        client.tools.list(limit=100),
+        client.pronunciation_dictionaries.list(limit=100),
+        client.personas.list_tools(persona_id),
+    )
+    return {
+        "persona": persona,
+        # First-class tools already attached to this persona.
+        "persona_attached_tools": _data(attached_tools),
+        "available": {
+            "replicas": _data(replicas),
+            "voices": _data(voices),
+            "guardrails": _data(guardrails),
+            "objectives": _data(objectives),
+            "documents": _data(documents),
+            # Grouped by trigger origin so vision/audio tools aren't mislabeled
+            # as llm — attach with tavus_persona_tools_attach.
+            "tools": _group_tools_by_origin(_data(tools)),
+            "pronunciation_dictionaries": _data(pronunciation_dictionaries),
+        },
+        "schemas": {
+            "persona_patch_model": PersonaPatchModel.model_json_schema(),
+            "patchable_paths": sorted(allowed_patch_paths()),
+        },
+    }
+
+
+def _data(value: Any) -> Any:
+    if isinstance(value, dict) and "data" in value:
+        return value["data"]
+    return value
+
+
+def _group_tools_by_origin(tools: Any) -> dict[str, list[Any]]:
+    grouped: dict[str, list[Any]] = {"llm": [], "vision": [], "audio": []}
+    if isinstance(tools, list):
+        for tool in tools:
+            origin = tool.get("origin", "llm") if isinstance(tool, dict) else "llm"
+            grouped.setdefault(origin, []).append(tool)
+    return grouped