tavus-cli 0.1.0__py3-none-any.whl

tavus_mcp/sdk/recipes/quickstart.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tavus_mcp.sdk.client.http import TavusClient
+
+
+async def quickstart(
+    client: TavusClient,
+    *,
+    system_prompt: str,
+    persona_name: str = "Agentic Tavus Persona",
+    replica_id: str | None = None,
+    conversation_name: str | None = None,
+) -> dict[str, Any]:
+    selected_replica_id = replica_id or await _first_stock_replica_id(client)
+    persona = await client.personas.create(
+        {
+            "persona_name": persona_name,
+            "system_prompt": system_prompt,
+            "default_replica_id": selected_replica_id,
+        }
+    )
+    persona_id = persona["persona_id"]
+    conversation = await client.conversations.create(
+        {
+            "persona_id": persona_id,
+            "replica_id": selected_replica_id,
+            "conversation_name": conversation_name or persona_name,
+        }
+    )
+    return {
+        "persona": persona,
+        "conversation": conversation,
+        "replica_id": selected_replica_id,
+    }
+
+
+async def _first_stock_replica_id(client: TavusClient) -> str:
+    replicas = await client.replicas.list(limit=25, replica_type="system")
+    data = replicas.get("data", replicas) if isinstance(replicas, dict) else replicas
+    if not data:
+        raise ValueError("No stock replicas were returned by the selected Tavus environment.")
+    first = data[0]
+    replica_id = first.get("replica_id") or first.get("replica_uuid") or first.get("id")
+    if not replica_id:
+        raise ValueError("Stock replica response did not include a replica id.")
+    return str(replica_id)

tavus_mcp/sdk/recipes/scaffold_embed.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from tavus_mcp.sdk.schemas.file_manifest import FileEntry, FileManifest
+
+EmbedTarget = Literal["iframe", "cvi-ui", "vanilla"]
+
+
+IFRAME_ALLOW = "camera; microphone; fullscreen; display-capture; autoplay"
+
+
+def scaffold_embed(
+    *,
+    conversation_url: str,
+    target: EmbedTarget = "iframe",
+    component_name: str = "TavusConversation",
+) -> FileManifest:
+    if target == "iframe":
+        return _iframe(conversation_url)
+    if target == "cvi-ui":
+        return _cvi_ui(conversation_url, component_name)
+    if target == "vanilla":
+        return _vanilla(conversation_url)
+    raise ValueError(f"Unsupported embed target: {target}")
+
+
+def _iframe(conversation_url: str) -> FileManifest:
+    return FileManifest(
+        files=[
+            FileEntry(
+                path="tavus-embed.html",
+                description="Standalone Tavus iframe embed.",
+                content=f"""<iframe
+  src="{conversation_url}"
+  allow="{IFRAME_ALLOW}"
+  allowfullscreen
+  style="width: 100%; height: 720px; border: 0;"
+></iframe>
+""",
+            )
+        ],
+        notes=["The iframe allow attribute includes display-capture for screen share support."],
+    )
+
+
+def _cvi_ui(conversation_url: str, component_name: str) -> FileManifest:
+    return FileManifest(
+        files=[
+            FileEntry(
+                path=f"src/components/{component_name}.tsx",
+                description=(
+                    "@tavus/cvi-ui React component. Install and initialize "
+                    "@tavus/cvi-ui first."
+                ),
+                content=f"""import {{ useCallback }} from 'react';
+
+const CONVERSATION_URL = {conversation_url!r};
+
+export function {component_name}() {{
+  const start = useCallback(() => {{
+    window.open(CONVERSATION_URL, '_blank', 'noopener,noreferrer');
+  }}, []);
+
+  return (
+    <button type="button" onClick={{start}}>
+      Start Tavus Conversation
+    </button>
+  );
+}}
+""",
+            )
+        ],
+        notes=[
+            "This starter preserves the mobile Safari user-gesture chain by joining from a click.",
+            (
+                "For a full in-app experience, run `npx @tavus/cvi-ui@latest init` "
+                "and wire the copied components."
+            ),
+        ],
+    )
+
+
+def _vanilla(conversation_url: str) -> FileManifest:
+    return FileManifest(
+        files=[
+            FileEntry(
+                path="tavus-vanilla.html",
+                description="Vanilla Daily iframe embed.",
+                content=f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Tavus Conversation</title>
+  <script crossorigin src="https://unpkg.com/@daily-co/daily-js"></script>
+</head>
+<body>
+  <button id="start">Start</button>
+  <div id="call" style="width: 100%; height: 720px;"></div>
+  <script>
+    const frame = window.DailyIframe.createFrame(document.getElementById('call'), {{
+      iframeStyle: {{ width: '100%', height: '100%', border: '0' }}
+    }});
+    document.getElementById('start').addEventListener('click', () => {{
+      frame.join({{ url: {conversation_url!r} }});
+    }});
+  </script>
+</body>
+</html>
+""",
+            )
+        ],
+        notes=["Join is bound to a click to preserve browser media permissions."],
+    )

tavus_mcp/sdk/recipes/templates.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from tavus_mcp.sdk.client.http import TavusClient
+
+PersonaTemplate = Literal["customer-support", "interviewer", "sales", "tutor", "dev-rel"]
+
+TEMPLATES: dict[str, str] = {
+    "customer-support": (
+        "You are a warm, concise customer support specialist. Resolve the user's issue, "
+        "ask focused follow-up questions when details are missing, and avoid overpromising."
+    ),
+    "interviewer": (
+        "You are a structured interviewer. Ask one question at a time, listen carefully, "
+        "probe for concrete examples, and keep the conversation professional."
+    ),
+    "sales": (
+        "You are a consultative sales assistant. Discover the user's needs, qualify fit, "
+        "explain value in practical terms, and never pressure the user."
+    ),
+    "tutor": (
+        "You are a patient tutor. Explain concepts step by step, check understanding, "
+        "adapt to the learner's pace, and use examples before abstractions."
+    ),
+    "dev-rel": (
+        "You are a developer relations guide. Help developers build successfully, give "
+        "precise technical answers, and include implementation tradeoffs when relevant."
+    ),
+}
+
+
+async def persona_from_template(
+    client: TavusClient,
+    *,
+    template: PersonaTemplate,
+    persona_name: str | None = None,
+    business_context: str | None = None,
+    default_replica_id: str | None = None,
+    layers: dict[str, Any] | None = None,
+) -> Any:
+    prompt = TEMPLATES[template]
+    if business_context:
+        prompt = f"{prompt}\n\nBusiness context:\n{business_context.strip()}"
+
+    body: dict[str, Any] = {
+        "persona_name": persona_name or _default_name(template),
+        "system_prompt": prompt,
+    }
+    if default_replica_id:
+        body["default_replica_id"] = default_replica_id
+    if layers:
+        body["layers"] = layers
+    return await client.personas.create(body)
+
+
+def _default_name(template: str) -> str:
+    return template.replace("-", " ").title()

tavus_mcp/sdk/recipes/tool_reuse.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+# Leaf path segment -> tool origin, for inline tool arrays on the persona body.
+_ARRAY_LEAF_ORIGIN = {
+    "visual_tools": "vision",
+    "perception_tools": "vision",
+    "audio_tools": "audio",
+}
+
+_ADVISORY_FIELDS = ("tool_id", "name", "origin", "description", "parameters", "delivery")
+
+
+def collect_inline_tools(ops: list[dict[str, Any]]) -> list[dict[str, str]]:
+    """Detect inline tool definitions written by JSON-Patch ops.
+
+    Returns ``[{"name", "origin"}, ...]`` for every inline tool the ops add or
+    replace. Handles array writes (``.../visual_tools``, ``.../audio_tools``,
+    ``.../perception_tools``, ``/layers/llm/tools``), single appends
+    (``.../-`` or ``.../<index>``), and object writes (``/layers``,
+    ``/layers/perception``, ``/layers/llm``).
+    """
+    found: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+
+    def add(origin: str, tool: Any) -> None:
+        if not isinstance(tool, dict):
+            return
+        fn = tool.get("function") if isinstance(tool.get("function"), dict) else tool
+        name = fn.get("name") if isinstance(fn, dict) else None
+        key = (origin, str(name))
+        if key in seen:
+            return
+        seen.add(key)
+        found.append({"name": str(name) if name else "", "origin": origin})
+
+    def add_many(origin: str, value: Any) -> None:
+        if isinstance(value, list):
+            for tool in value:
+                add(origin, tool)
+        elif isinstance(value, dict):
+            add(origin, value)
+
+    for op in ops:
+        if not isinstance(op, dict) or op.get("op") not in {"add", "replace"}:
+            continue
+        value = op.get("value")
+        segs = [s for s in str(op.get("path", "")).split("/") if s]
+        # Drop a trailing append marker / array index so the leaf is the field.
+        leaf_segs = [s for s in segs if not (s == "-" or s.isdigit())]
+        leaf = leaf_segs[-1] if leaf_segs else ""
+
+        if leaf in _ARRAY_LEAF_ORIGIN:
+            add_many(_ARRAY_LEAF_ORIGIN[leaf], value)
+        elif leaf == "tools" and "llm" in leaf_segs:
+            add_many("llm", value)
+        elif isinstance(value, dict):
+            _collect_from_object(leaf, value, add_many)
+
+    return found
+
+
+def _collect_from_object(
+    leaf: str, value: dict[str, Any], add_many: Callable[[str, Any], None]
+) -> None:
+    """Pull tool arrays out of an object-valued op (a perception layer, an llm
+    layer, or a whole ``/layers`` object)."""
+    perception = value if leaf == "perception" else value.get("perception")
+    if isinstance(perception, dict):
+        add_many("vision", perception.get("visual_tools"))
+        add_many("vision", perception.get("perception_tools"))
+        add_many("audio", perception.get("audio_tools"))
+
+    llm = value if leaf == "llm" else value.get("llm")
+    if isinstance(llm, dict):
+        add_many("llm", llm.get("tools"))
+
+
+def build_inline_deprecation_notice(inline: list[dict[str, str]]) -> dict[str, Any]:
+    """Advisory steering a persona patch that wrote inline tools toward the
+    first-class create + attach flow."""
+    return {
+        "inline_tools_written": inline,
+        "guidance": (
+            "Inline tools (layers.*.tools) are deprecated. Tools are first-class "
+            "objects now: create one with tavus_tool_create, then attach it with "
+            "tavus_persona_tools_attach (which also flips perception_model to "
+            "raven-1 for vision/audio tools). Check tavus_tool_list first so you "
+            "reuse an existing tool instead of duplicating it."
+        ),
+    }
+
+
+def build_library_match_advisory(
+    origin: str, name: str, saved_tools: list[dict[str, Any]]
+) -> dict[str, Any] | None:
+    """Surface saved tools of the same origin as a freshly created tool, so the
+    agent reuses instead of duplicating. Returns ``None`` when nothing of that
+    origin exists (no advisory noise)."""
+    same_origin = [
+        tool for tool in saved_tools if isinstance(tool, dict) and tool.get("origin") == origin
+    ]
+    if not same_origin:
+        return None
+
+    collision = next((tool for tool in same_origin if tool.get("name") == name), None)
+    return {
+        "new_tool": {"name": name, "origin": origin},
+        "name_collision_tool_id": collision.get("tool_id") if collision else None,
+        "matching_saved_tools": [_slim(tool) for tool in same_origin],
+        "guidance": (
+            f"Your account already has {len(same_origin)} saved {origin} tool(s) "
+            "(see matching_saved_tools). If one fits this need, do NOT duplicate it "
+            "— attach it with tavus_persona_tools_attach instead. If you keep this "
+            "new tool, tell the user which existing tool you saw and why its shape "
+            "(parameters / origin / delivery) does not fit."
+        ),
+    }
+
+
+def _slim(tool: dict[str, Any]) -> dict[str, Any]:
+    return {field: tool.get(field) for field in _ADVISORY_FIELDS if field in tool}

tavus_mcp/sdk/schemas/__init__.py

@@ -0,0 +1,16 @@
+from tavus_mcp.sdk.schemas.file_manifest import FileEntry, FileManifest
+from tavus_mcp.sdk.schemas.persona import (
+    JSONPatchOperation,
+    LayersPatchModel,
+    PersonaCreate,
+    PersonaPatchModel,
+)
+
+__all__ = [
+    "FileEntry",
+    "FileManifest",
+    "JSONPatchOperation",
+    "LayersPatchModel",
+    "PersonaCreate",
+    "PersonaPatchModel",
+]

tavus_mcp/sdk/schemas/file_manifest.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FileEntry(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    content: str
+    mode: Literal["create", "overwrite", "append"] = "create"
+    description: str | None = None
+
+
+class FileManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    files: list[FileEntry] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)

tavus_mcp/sdk/schemas/guardrail.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+GuardrailType = Literal["user", "system", "all"]
+GuardrailModality = Literal["verbal", "visual", "audio"]
+GuardrailListLegacy = Literal["true", "false"]
+GuardrailSort = Literal["ascending", "descending"]
+
+MAX_GUARDRAILS_NAME_LENGTH = 100
+MAX_GUARDRAIL_TAGS_PER_ITEM = 32
+
+_TAG_NAME_RE = re.compile(r"^[A-Za-z0-9_\- ]+$")
+
+
+class GuardrailCreate(BaseModel):
+    """Flat-list (new) guardrail shape — what `POST /v2/guardrails` accepts
+    when the payload has a top-level ``guardrail_name``. Legacy set creation
+    (``{name, data: [...]}``) is intentionally not exposed here; the user
+    explicitly removed sets in favor of flat guardrails."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    guardrail_name: str = Field(..., min_length=1)
+    guardrail_prompt: str = Field(..., min_length=1)
+    modality: GuardrailModality = "verbal"
+    callback_url: str = ""
+    tool_call: dict[str, Any] | None = None
+    app_message: bool = True
+    tags: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check_tags(self) -> GuardrailCreate:
+        if len(self.tags) > MAX_GUARDRAIL_TAGS_PER_ITEM:
+            raise ValueError(
+                f"guardrail can carry at most {MAX_GUARDRAIL_TAGS_PER_ITEM} tags"
+            )
+        for tag in self.tags:
+            if not isinstance(tag, str) or not tag:
+                raise ValueError("tags must be non-empty strings")
+        return self
+
+
+class GuardrailUpdate(BaseModel):
+    """Patch shape — every field optional. RQH's PATCH validator round-trips
+    the persisted dict, so persisted fields (uuid, owner_id, timestamps) are
+    accepted as no-ops; we just don't expose them as inputs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    guardrail_name: str | None = None
+    guardrail_prompt: str | None = None
+    modality: GuardrailModality | None = None
+    callback_url: str | None = None
+    tool_call: dict[str, Any] | None = None
+    app_message: bool | None = None
+    tags: list[str] | None = None
+
+    @model_validator(mode="after")
+    def _check_tags(self) -> GuardrailUpdate:
+        if self.tags is not None and len(self.tags) > MAX_GUARDRAIL_TAGS_PER_ITEM:
+            raise ValueError(
+                f"guardrail can carry at most {MAX_GUARDRAIL_TAGS_PER_ITEM} tags"
+            )
+        return self
+
+
+class GuardrailListParams(BaseModel):
+    """Query string for `GET /v2/guardrails`. Defaults mirror RQH so callers
+    that omit a param see what RQH would have defaulted them to."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    limit: int = 10
+    page: int = 1
+    name_or_uuid: str = ""
+    type: GuardrailType = "user"
+    sort: GuardrailSort = "ascending"
+    legacy: GuardrailListLegacy = "false"
+    tags: str | None = None
+    verbose: bool | None = None

tavus_mcp/sdk/schemas/objective.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+ObjectiveType = Literal["user", "system", "all"]
+ConfirmationMode = Literal["manual", "auto"]
+ObjectiveModality = Literal["verbal", "visual", "audio"]
+
+MAX_OBJECTIVE_NAME_LEN = 100
+MAX_OBJECTIVE_PROMPT_LEN = 10000
+MAX_OBJECTIVE_CALLBACK_URL_LEN = 2048
+MAX_OBJECTIVE_OUTPUT_VARIABLES = 50
+MAX_OBJECTIVES_NAME_LEN = 100
+MAX_OBJECTIVES_COUNT = 50
+
+_OBJECTIVE_NAME_RE = re.compile(r"^[a-zA-Z0-9_]+$")
+
+
+class ObjectiveItem(BaseModel):
+    """One step in an objective chain. Names are referenced by other items
+    via ``next_required_objective`` / ``next_conditional_objectives``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    objective_name: str
+    objective_prompt: str = Field(..., max_length=MAX_OBJECTIVE_PROMPT_LEN)
+    confirmation_mode: ConfirmationMode = "auto"
+    output_variables: list[str] = Field(default_factory=list)
+    modality: ObjectiveModality = "verbal"
+    next_conditional_objectives: dict[str, str] | None = None
+    next_required_objective: str | None = None
+    callback_url: str = ""
+    tool_call: dict[str, Any] | None = None
+
+    @model_validator(mode="after")
+    def _check(self) -> ObjectiveItem:
+        if not _OBJECTIVE_NAME_RE.match(self.objective_name):
+            raise ValueError(
+                "objective_name must contain only letters, numbers, and underscores"
+            )
+        if len(self.objective_name) > MAX_OBJECTIVE_NAME_LEN:
+            raise ValueError(
+                f"objective_name must be at most {MAX_OBJECTIVE_NAME_LEN} characters"
+            )
+        if len(self.callback_url) > MAX_OBJECTIVE_CALLBACK_URL_LEN:
+            raise ValueError(
+                f"callback_url must be at most {MAX_OBJECTIVE_CALLBACK_URL_LEN} characters"
+            )
+        if len(self.output_variables) > MAX_OBJECTIVE_OUTPUT_VARIABLES:
+            raise ValueError(
+                f"output_variables must have at most {MAX_OBJECTIVE_OUTPUT_VARIABLES} items"
+            )
+        if (
+            self.next_required_objective
+            and self.next_required_objective == self.objective_name
+        ):
+            raise ValueError(
+                f"objective '{self.objective_name}' cannot reference "
+                "itself via next_required_objective"
+            )
+        if (
+            self.next_conditional_objectives
+            and self.objective_name in self.next_conditional_objectives
+        ):
+            raise ValueError(
+                f"objective '{self.objective_name}' cannot reference "
+                "itself via next_conditional_objectives"
+            )
+        if self.next_required_objective and self.next_conditional_objectives:
+            raise ValueError(
+                "an objective may have either next_required_objective or "
+                "next_conditional_objectives, not both"
+            )
+        return self
+
+
+class ObjectivesCreate(BaseModel):
+    """Set-shape body for `POST /v2/objectives/`. Objectives are still
+    grouped into a named set (unlike guardrails, which went flat)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = ""
+    data: list[ObjectiveItem] = Field(..., min_length=1)
+    allow_loops: bool = False
+
+    @model_validator(mode="after")
+    def _check(self) -> ObjectivesCreate:
+        if len(self.name) > MAX_OBJECTIVES_NAME_LEN:
+            raise ValueError(
+                f"objectives set name must be at most {MAX_OBJECTIVES_NAME_LEN} characters"
+            )
+        if len(self.data) > MAX_OBJECTIVES_COUNT:
+            raise ValueError(
+                f"objectives list must have at most {MAX_OBJECTIVES_COUNT} items"
+            )
+        names = [item.objective_name for item in self.data]
+        if len(names) != len(set(names)):
+            duplicates = sorted({n for n in names if names.count(n) > 1})
+            raise ValueError(f"duplicate objective_name(s) in set: {duplicates}")
+        # Cross-item reference check — every referenced name must exist.
+        known = set(names)
+        for item in self.data:
+            if (
+                item.next_required_objective
+                and item.next_required_objective not in known
+            ):
+                raise ValueError(
+                    f"objective '{item.objective_name}' references unknown "
+                    f"next_required_objective '{item.next_required_objective}'"
+                )
+            for ref in (item.next_conditional_objectives or {}).keys():
+                if ref not in known:
+                    raise ValueError(
+                        f"objective '{item.objective_name}' references unknown "
+                        f"conditional outcome '{ref}'"
+                    )
+        return self
+
+
+class ObjectivesListParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    limit: int = 25
+    page: int = 1
+    type: ObjectiveType = "user"
+    sort: Literal["ascending", "descending"] = "ascending"
+    name_or_uuid: str | None = None