tavus-cli 0.1.0__py3-none-any.whl

tavus_mcp/sdk/schemas/persona.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+PipelineMode = Literal["full", "speech-to-speech", "echo"]
+
+
+class LLMLayerPatchModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    tools: list[dict[str, Any]] | None = None
+    headers: dict[str, Any] | None = None
+    extra_body: dict[str, Any] | None = None
+    default_query: dict[str, Any] | None = None
+    base_url: str | None = None
+    api_key: str | None = None
+    model: str | None = None
+    disable_vision: bool | None = None
+    speculative_inference: bool | None = None
+    enable_llm_proxy: bool | None = None
+    model_name: str | None = None
+    is_custom: bool | None = None
+    endpoint: str | None = None
+
+
+class TTSLayerPatchModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    voice_settings: dict[str, Any] | None = None
+    external_voice_id: str | None = None
+    tts_engine: str | None = None
+    api_key: str | None = None
+    playht_user_id: str | None = None
+    tts_emotion_control: bool | None = None
+    tts_model_name: str | None = None
+    pronunciation_dictionary_id: str | None = None
+
+
+class STTLayerPatchModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    stt_engine: str | None = None
+    participant_pause_sensitivity: str | None = None
+    participant_interrupt_sensitivity: str | None = None
+    smart_turn_detection: bool | None = None
+    hotwords: str | None = None
+
+
+class PerceptionLayerPatchModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    perception_model: str | None = None
+    visual_tools: list[dict[str, Any]] | None = None
+    visual_awareness_queries: list[str] | None = None
+    visual_tool_prompt: str | None = None
+    audio_tools: list[dict[str, Any]] | None = None
+    audio_awareness_queries: list[str] | None = None
+    audio_tool_prompt: str | None = None
+    perception_analysis_queries: list[str] | None = None
+    perception_tools: list[dict[str, Any]] | None = None
+    ambient_awareness_queries: list[str] | None = None
+    perception_tool_prompt: str | None = None
+    tool_prompt: str | None = None
+
+
+class ConversationalFlowLayerPatchModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    turn_detection_model: str | None = None
+    turn_taking_patience: str | None = None
+    turn_commitment: str | None = None
+    replica_interruptibility: str | None = None
+    active_listening: str | None = None
+    voice_isolation: str | None = None
+    noise_cancellation: str | None = None
+    wake_phrase: str | None = None
+    idle_engagement: str | None = None
+
+
+class CapabilitiesLayerPatchModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    mcp_enabled: bool | None = None
+    search_enabled: bool | None = None
+    activity_log_enabled: bool | None = None
+    search_results_prompt_injection_prevention_enabled: bool | None = None
+
+
+class KnowledgeBaseLayerPatchModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    rag_score_threshold: float | None = None
+    rag_n_chunks: int | None = None
+    rag_surrounding_chunk_radius: int | None = None
+    enable_rag_observability_app_messages: bool | None = None
+    use_procedure_goalchain: bool | None = None
+
+
+class LayersPatchModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    llm: LLMLayerPatchModel | None = None
+    tts: TTSLayerPatchModel | None = None
+    stt: STTLayerPatchModel | None = None
+    sts: dict[str, Any] | None = None
+    transport: dict[str, Any] | None = None
+    perception: PerceptionLayerPatchModel | None = None
+    conversational_flow: ConversationalFlowLayerPatchModel | None = None
+    capabilities: CapabilitiesLayerPatchModel | None = None
+    knowledge_base: KnowledgeBaseLayerPatchModel | None = None
+
+
+class PersonaCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    system_prompt: str | None = None
+    greeting: str | None = None
+    pipeline_mode: PipelineMode = "full"
+    context: str | None = None
+    persona_name: str | None = None
+    layers: LayersPatchModel | None = None
+    memories: list[str] | None = None
+    default_replica_id: str | None = None
+    objectives_id: str | None = None
+    guardrails_id: str | None = None
+    guardrail_ids: list[str] | None = None
+    guardrail_tags: list[str] | None = None
+    document_ids: list[str] | None = None
+    document_tags: list[str] | None = None
+    is_template: bool | None = None
+
+    @model_validator(mode="after")
+    def validate_pipeline_mode(self) -> PersonaCreate:
+        if self.pipeline_mode == "full" and not self.system_prompt:
+            raise ValueError("system_prompt is required for pipeline_mode='full'")
+        if self.pipeline_mode in {"speech-to-speech", "echo"}:
+            if self.system_prompt:
+                raise ValueError(
+                    f"system_prompt is not allowed for pipeline_mode={self.pipeline_mode!r}"
+                )
+            if self.context:
+                raise ValueError(f"context is not allowed for pipeline_mode={self.pipeline_mode!r}")
+        return self
+
+
+class PersonaPatchModel(PersonaCreate):
+    model_config = ConfigDict(extra="forbid")
+
+    uuid: str | None = None
+    owner_id: int | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+    session_id: str | None = None
+    is_draft: bool | None = None
+    source_template_id: str | None = None
+    registration_id: int | None = None
+    persona_settings_id: int | None = None
+
+    @model_validator(mode="after")
+    def validate_pipeline_mode(self) -> PersonaPatchModel:
+        if self.pipeline_mode == "full" and self.system_prompt == "":
+            raise ValueError("system_prompt cannot be empty for pipeline_mode='full'")
+        return self
+
+
+class JSONPatchOperation(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    op: Literal["add", "remove", "replace", "move", "copy", "test"]
+    path: str
+    value: Any = None
+    from_: str | None = Field(default=None, alias="from")

tavus_mcp/sdk/schemas/pronunciation.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+PronunciationType = Literal["alias", "ipa"]
+
+MAX_RULES_PER_DICTIONARY = 10000
+MAX_TEXT_LEN = 200
+MAX_PRONUNCIATION_LEN = 500
+MAX_NAME_LEN = 255
+
+
+class PronunciationRule(BaseModel):
+    """One substitution rule. ``type="alias"`` swaps ``text`` for the literal
+    ``pronunciation`` string before TTS; ``type="ipa"`` interprets
+    ``pronunciation`` as IPA and uses the SSML phoneme tag."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    text: str = Field(..., min_length=1, max_length=MAX_TEXT_LEN)
+    pronunciation: str = Field(..., min_length=1, max_length=MAX_PRONUNCIATION_LEN)
+    type: PronunciationType
+    alphabet: Literal["ipa"] | None = None
+    case_sensitive: bool = False
+    word_boundaries: bool = True
+
+    @model_validator(mode="after")
+    def _set_default_alphabet(self) -> PronunciationRule:
+        if self.type == "ipa" and self.alphabet is None:
+            self.alphabet = "ipa"
+        return self
+
+
+class PronunciationDictionaryCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., min_length=1, max_length=MAX_NAME_LEN)
+    rules: list[PronunciationRule] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check_rules(self) -> PronunciationDictionaryCreate:
+        if len(self.rules) > MAX_RULES_PER_DICTIONARY:
+            raise ValueError(
+                f"dictionary can hold at most {MAX_RULES_PER_DICTIONARY} rules"
+            )
+        texts = [r.text for r in self.rules]
+        if len(texts) != len(set(texts)):
+            duplicates = sorted({t for t in texts if texts.count(t) > 1})
+            raise ValueError(f"duplicate 'text' entries are not allowed: {duplicates}")
+        return self
+
+
+class PronunciationDictionaryUpdate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str | None = Field(default=None, max_length=MAX_NAME_LEN)
+    rules: list[PronunciationRule] | None = None
+
+    @model_validator(mode="after")
+    def _check_rules(self) -> PronunciationDictionaryUpdate:
+        if self.rules is None:
+            return self
+        if len(self.rules) > MAX_RULES_PER_DICTIONARY:
+            raise ValueError(
+                f"dictionary can hold at most {MAX_RULES_PER_DICTIONARY} rules"
+            )
+        texts = [r.text for r in self.rules]
+        if len(texts) != len(set(texts)):
+            duplicates = sorted({t for t in texts if texts.count(t) > 1})
+            raise ValueError(f"duplicate 'text' entries are not allowed: {duplicates}")
+        return self

tavus_mcp/sdk/schemas/tool.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+MAX_TOOL_SIZE = 10000
+MAX_PERSONA_TOOLS = 50
+
+TOOL_AUTH_SCRUB_PLACEHOLDER = "*" * 8
+_TOOL_NAME_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]{0,63}$")
+_PLACEHOLDER_RE = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)\}")
+_BODYLESS_METHODS = {"GET", "HEAD", "DELETE"}
+_RESERVED_PARAMETER_PREFIX = "tavus_"
+
+Origin = Literal["llm", "vision", "audio"]
+OnCall = Literal["generate_filler", "static_filler", "silent", "passthrough"]
+OnResolve = Literal[
+    "generate_response", "response_in_result", "add_to_context", "fire_and_forget"
+]
+HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
+ApiKeyLocation = Literal["header", "query"]
+ToolListType = Literal["user", "system", "all"]
+
+
+class AuthNone(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    type: Literal["none"] = "none"
+
+
+class AuthBearer(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    type: Literal["bearer"] = "bearer"
+    token: str = Field(..., min_length=1)
+
+
+class AuthBasic(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    type: Literal["basic"] = "basic"
+    username: str = Field(..., min_length=1)
+    password: str = Field(..., min_length=1)
+
+
+class AuthApiKey(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    type: Literal["api_key"] = "api_key"
+    name: str = Field(..., min_length=1)
+    value: str = Field(..., min_length=1)
+    location: ApiKeyLocation = "header"
+
+
+class AuthHmac(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    type: Literal["hmac"] = "hmac"
+    secret: str = Field(..., min_length=1)
+
+
+class AuthOAuth2(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    type: Literal["oauth2_client_credentials"] = "oauth2_client_credentials"
+    token_url: str = Field(..., min_length=1)
+    client_id: str = Field(..., min_length=1)
+    client_secret: str = Field(..., min_length=1)
+    scope: str | None = None
+
+    @model_validator(mode="after")
+    def _check_token_url(self) -> AuthOAuth2:
+        if not self.token_url.lower().startswith("https://"):
+            raise ValueError("auth.token_url must be https://")
+        return self
+
+
+ToolAuth = AuthNone | AuthBearer | AuthBasic | AuthApiKey | AuthHmac | AuthOAuth2
+
+_AUTH_SECRET_FIELD = {
+    "bearer": "token",
+    "basic": "password",
+    "api_key": "value",
+    "hmac": "secret",
+    "oauth2_client_credentials": "client_secret",
+}
+
+
+class ApiDelivery(BaseModel):
+    """HTTP-tool delivery channel. RQH calls the third-party endpoint at
+    ``url`` when the tool fires; placeholders (``{ident}``) in url/body/query
+    are substituted from the LLM-supplied arguments declared in
+    ``parameters.properties``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    url: str = Field(..., min_length=1)
+    method: HttpMethod = "POST"
+    timeout: float = 10.0
+    headers: dict[str, str] | None = None
+    auth: ToolAuth | None = Field(default=None, discriminator="type")
+    body_template: dict[str, Any] | None = None
+    query_params: dict[str, str] | None = None
+    content_type: str | None = None
+
+    @model_validator(mode="after")
+    def _check(self) -> ApiDelivery:
+        if not self.url.lower().startswith("https://"):
+            raise ValueError("delivery.api.url must be https://")
+        if not (0 < self.timeout <= 60):
+            raise ValueError(
+                "delivery.api.timeout must be a number in (0, 60] seconds (default 10)"
+            )
+        if self.body_template is not None and self.method in _BODYLESS_METHODS:
+            raise ValueError(
+                f"method {self.method} does not send a request body; "
+                "remove body_template or change method to POST/PUT/PATCH"
+            )
+        # Round-trip footgun: PATCHing a payload that still contains the
+        # scrubbed-secret placeholder from a prior GET silently re-encrypts
+        # asterisks. Reject so the caller has to omit the field instead.
+        if isinstance(self.auth, (AuthBearer, AuthBasic, AuthApiKey, AuthHmac, AuthOAuth2)):
+            field = _AUTH_SECRET_FIELD[self.auth.type]
+            value = getattr(self.auth, field, None)
+            if value == TOOL_AUTH_SCRUB_PLACEHOLDER:
+                raise ValueError(
+                    f"delivery.api.auth.{field} looks like the scrub placeholder "
+                    "echoed from a GET response; omit it to keep the existing secret"
+                )
+        # HMAC mode sends a fixed Tavus-envelope body to a static URL — any
+        # body_template/query_params/url placeholders are silently ignored.
+        if isinstance(self.auth, AuthHmac):
+            conflicts: list[str] = []
+            if self.body_template:
+                conflicts.append("body_template")
+            if self.query_params:
+                conflicts.append("query_params")
+            if _PLACEHOLDER_RE.search(self.url):
+                conflicts.append("url placeholders")
+            if conflicts:
+                raise ValueError(
+                    f"auth.type=hmac ignores {conflicts}; remove these fields or switch auth type"
+                )
+        return self
+
+
+class ToolDelivery(BaseModel):
+    """How a tool fires. Exactly one channel must be enabled:
+    ``app_message=True`` (delivered over the Daily data channel) OR
+    ``api`` set (delivered over HTTPS to a third-party endpoint)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    app_message: bool | None = None
+    api: ApiDelivery | None = None
+
+    @model_validator(mode="after")
+    def _exactly_one_channel(self) -> ToolDelivery:
+        has_app = self.app_message is True
+        has_api = self.api is not None
+        if has_app and has_api:
+            raise ValueError(
+                "delivery must enable exactly one channel: set delivery.app_message=true "
+                "OR include delivery.api, not both"
+            )
+        if not has_app and not has_api:
+            raise ValueError(
+                "delivery must enable a channel: set delivery.app_message=true "
+                "or include delivery.api"
+            )
+        return self
+
+
+class ToolCreate(BaseModel):
+    """Body for `POST /v2/tools`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    description: str = Field(..., min_length=1)
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    delivery: ToolDelivery = Field(default_factory=lambda: ToolDelivery(app_message=True))
+    origin: Origin = "llm"
+    on_call: OnCall | None = None
+    on_resolve: OnResolve | None = "fire_and_forget"
+    static_filler: str | None = None
+    tags: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check(self) -> ToolCreate:
+        _validate_tool_name(self.name)
+        _validate_tool_size(self.description, self.parameters)
+        _validate_parameter_names(self.parameters)
+        _validate_placeholders(self.delivery, self.parameters)
+        _validate_origin_fields(
+            self.origin, self.on_call, self.on_resolve, self.static_filler
+        )
+        return self
+
+
+class ToolUpdate(BaseModel):
+    """Body for `PATCH /v2/tools/{tool_id}`. Every field optional; provided
+    fields replace the current value. Omit a field to leave it unchanged."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str | None = None
+    description: str | None = None
+    parameters: dict[str, Any] | None = None
+    delivery: ToolDelivery | None = None
+    origin: Origin | None = None
+    on_call: OnCall | None = None
+    on_resolve: OnResolve | None = None
+    tags: list[str] | None = None
+    static_filler: str | None = None
+
+    @model_validator(mode="after")
+    def _check(self) -> ToolUpdate:
+        if self.name is not None:
+            _validate_tool_name(self.name)
+        if self.description is not None and self.parameters is not None:
+            _validate_tool_size(self.description, self.parameters)
+        if self.parameters is not None:
+            _validate_parameter_names(self.parameters)
+        if self.delivery is not None:
+            _validate_placeholders(self.delivery, self.parameters or {})
+        return self
+
+
+class AttachToolsBody(BaseModel):
+    """Body for `POST /v2/personas/{id}/tools/` — attach by tool_id list."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    tool_ids: list[str] = Field(..., min_length=1)
+
+    @model_validator(mode="after")
+    def _check(self) -> AttachToolsBody:
+        if len(self.tool_ids) > MAX_PERSONA_TOOLS:
+            raise ValueError(
+                f"cannot attach more than {MAX_PERSONA_TOOLS} tools at once"
+            )
+        for tid in self.tool_ids:
+            if not isinstance(tid, str) or not tid:
+                raise ValueError("tool_ids must be non-empty strings")
+        return self
+
+
+class ToolListParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    limit: int = 25
+    page: int = 1
+    type: ToolListType = "user"
+    sort: Literal["ascending", "descending"] = "ascending"
+    name_or_uuid: str | None = None
+
+
+def _validate_tool_name(name: str) -> None:
+    if not _TOOL_NAME_RE.match(name):
+        raise ValueError(
+            "name must start with a letter or underscore and contain only "
+            "letters, digits, and underscores (max 64 chars)"
+        )
+
+
+def _validate_tool_size(description: str, parameters: dict[str, Any]) -> None:
+    total = len(description or "") + len(json.dumps(parameters or {}, sort_keys=True))
+    if total > MAX_TOOL_SIZE:
+        raise ValueError(
+            f"tool spec is too large: description + parameters serialize to "
+            f"{total} characters, limit is {MAX_TOOL_SIZE}"
+        )
+
+
+def _validate_parameter_names(parameters: dict[str, Any]) -> None:
+    properties = parameters.get("properties") if isinstance(parameters, dict) else None
+    if not isinstance(properties, dict):
+        return
+    offending = sorted(
+        name
+        for name in properties
+        if isinstance(name, str) and name.startswith(_RESERVED_PARAMETER_PREFIX)
+    )
+    if offending:
+        raise ValueError(
+            f"parameter names starting with '{_RESERVED_PARAMETER_PREFIX}' are "
+            f"reserved for Tavus system placeholders: {offending}"
+        )
+
+
+def _validate_placeholders(
+    delivery: ToolDelivery, parameters: dict[str, Any]
+) -> None:
+    if delivery.api is None:
+        return
+    found: set[str] = set()
+    found |= set(_PLACEHOLDER_RE.findall(delivery.api.url))
+    if delivery.api.body_template is not None:
+        found |= _placeholders_in_object(delivery.api.body_template)
+    if delivery.api.query_params is not None:
+        found |= _placeholders_in_object(delivery.api.query_params)
+    found = {n for n in found if not n.startswith(_RESERVED_PARAMETER_PREFIX)}
+    declared: set[str] = set()
+    properties = parameters.get("properties") if isinstance(parameters, dict) else None
+    if isinstance(properties, dict):
+        declared = {k for k in properties if isinstance(k, str)}
+    missing = sorted(found - declared)
+    if missing:
+        raise ValueError(
+            f"delivery.api references placeholder(s) {missing} not declared in "
+            f"parameters.properties (declared: {sorted(declared)})"
+        )
+
+
+def _placeholders_in_object(obj: Any) -> set[str]:
+    if isinstance(obj, str):
+        return set(_PLACEHOLDER_RE.findall(obj))
+    if isinstance(obj, dict):
+        out: set[str] = set()
+        for v in obj.values():
+            out |= _placeholders_in_object(v)
+        return out
+    if isinstance(obj, list):
+        out = set()
+        for v in obj:
+            out |= _placeholders_in_object(v)
+        return out
+    return set()
+
+
+def _validate_origin_fields(
+    origin: Origin,
+    on_call: OnCall | None,
+    on_resolve: OnResolve | None,
+    static_filler: str | None,
+) -> None:
+    if origin == "llm":
+        if on_call == "static_filler" and not static_filler:
+            raise ValueError(
+                "static_filler is required when on_call='static_filler'"
+            )
+        return
+    # vision / audio = perception tools, fire-and-forget by design
+    if on_call is not None:
+        raise ValueError(f"on_call must be null for {origin} tools")
+    if on_resolve not in (None, "fire_and_forget"):
+        raise ValueError(
+            f"on_resolve must be 'fire_and_forget' for {origin} tools"
+        )
+    if static_filler is not None:
+        raise ValueError(f"static_filler must be null for {origin} tools")