tavus-cli 0.1.0__py3-none-any.whl

tavus_mcp/sdk/env.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import os
+from enum import StrEnum
+from pathlib import Path
+
+from dotenv import load_dotenv
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, field_validator
+
+from tavus_mcp.sdk.errors import TavusConfigError
+
+
+class TavusEnvironment(StrEnum):
+    TEST = "TEST"
+    STG = "STG"
+    PROD = "PROD"
+
+
+DEFAULT_ENV = TavusEnvironment.PROD
+
+
+ENV_ALIASES = {
+    "TEST": TavusEnvironment.TEST,
+    "TEST_DB": TavusEnvironment.TEST,
+    "DEV": TavusEnvironment.TEST,
+    "LOCAL": TavusEnvironment.TEST,
+    "STG": TavusEnvironment.STG,
+    "STAGE": TavusEnvironment.STG,
+    "STAGING": TavusEnvironment.STG,
+    "PROD": TavusEnvironment.PROD,
+    "PRODUCTION": TavusEnvironment.PROD,
+}
+
+
+DEFAULT_PUBLIC_API_BASE_URLS = {
+    TavusEnvironment.TEST: "https://test.rqh.tavusapi.com/v2",
+    TavusEnvironment.STG: "https://stg.rqh.tavusapi.com/v2",
+    TavusEnvironment.PROD: "https://tavusapi.com/v2",
+}
+
+DEFAULT_PORTAL_API_BASE_URLS = {
+    TavusEnvironment.TEST: "https://test-api.tavus.io/api",
+    TavusEnvironment.STG: "https://stg-api.tavus.io/api",
+    TavusEnvironment.PROD: "https://prod-api.tavus.io/api",
+}
+
+DEFAULT_DEV_PORTAL_URLS = {
+    TavusEnvironment.TEST: "https://dev.platform.tavus.io",
+    TavusEnvironment.STG: "https://stage.platform.tavus.io",
+    TavusEnvironment.PROD: "https://platform.tavus.io",
+}
+
+
+class TavusConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    env: TavusEnvironment = DEFAULT_ENV
+    public_api_base_url: HttpUrl
+    portal_api_base_url: HttpUrl
+    dev_portal_url: HttpUrl
+    keyring_service: str = "tavus_mcp"
+    env_file: Path | None = Field(default=None)
+
+    @field_validator("public_api_base_url", "portal_api_base_url", "dev_portal_url")
+    @classmethod
+    def strip_trailing_slash(cls, value: HttpUrl) -> HttpUrl:
+        return HttpUrl(str(value).rstrip("/"))
+
+    @property
+    def keyring_username(self) -> str:
+        return self.env.value.lower()
+
+
+def _load_dotenv(cwd: Path | None) -> Path | None:
+    env_file = (cwd or Path.cwd()) / ".env"
+    if env_file.exists():
+        load_dotenv(env_file, override=False)
+        return env_file
+    return None
+
+
+def _env_name() -> TavusEnvironment:
+    raw = os.getenv("TAVUS_ENV", DEFAULT_ENV.value).strip().upper()
+    try:
+        return ENV_ALIASES[raw]
+    except KeyError as exc:
+        allowed = ", ".join(sorted(ENV_ALIASES))
+        raise TavusConfigError(
+            f"Unsupported TAVUS_ENV={raw!r}. Expected one of: {allowed}"
+        ) from exc
+
+
+def _configured_url(kind: str, env: TavusEnvironment) -> str:
+    generic = os.getenv(f"TAVUS_{kind}_API_BASE_URL")
+    if generic:
+        return generic
+
+    env_specific = os.getenv(f"TAVUS_{env.value}_{kind}_API_BASE_URL")
+    if env_specific:
+        return env_specific
+
+    defaults = DEFAULT_PUBLIC_API_BASE_URLS if kind == "PUBLIC" else DEFAULT_PORTAL_API_BASE_URLS
+    return defaults[env]
+
+
+def _configured_dev_portal_url(env: TavusEnvironment) -> str:
+    generic = os.getenv("TAVUS_DEV_PORTAL_URL")
+    if generic:
+        return generic
+    env_specific = os.getenv(f"TAVUS_{env.value}_DEV_PORTAL_URL")
+    if env_specific:
+        return env_specific
+    return DEFAULT_DEV_PORTAL_URLS[env]
+
+
+def load_config(*, cwd: Path | None = None) -> TavusConfig:
+    env_file = _load_dotenv(cwd)
+    env = _env_name()
+    return TavusConfig(
+        env=env,
+        public_api_base_url=_configured_url("PUBLIC", env),
+        portal_api_base_url=_configured_url("PORTAL", env),
+        dev_portal_url=_configured_dev_portal_url(env),
+        keyring_service=os.getenv("TAVUS_KEYRING_SERVICE", "tavus_mcp"),
+        env_file=env_file,
+    )

tavus_mcp/sdk/errors.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class TavusError(Exception):
+    """Base package error."""
+
+
+class TavusConfigError(TavusError):
+    """Invalid local configuration."""
+
+
+class TavusAuthError(TavusError):
+    """Missing or invalid auth credentials."""
+
+
+class TavusApiError(TavusError):
+    """HTTP API failure with structured context."""
+
+    def __init__(self, message: str, *, status_code: int | None = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class TavusPatchValidationError(TavusError):
+    """Invalid JSON Patch operation before it was sent to Tavus."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        path: str | None = None,
+        suggestions: list[str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.path = path
+        self.suggestions = suggestions or []
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "error": str(self),
+            "path": self.path,
+            "suggestions": self.suggestions,
+        }

tavus_mcp/sdk/patch.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import difflib
+from typing import Any, get_args, get_origin
+
+from pydantic import BaseModel
+
+from tavus_mcp.sdk.errors import TavusPatchValidationError
+from tavus_mcp.sdk.schemas.persona import JSONPatchOperation, PersonaPatchModel
+
+
+def allowed_patch_paths(model: type[BaseModel] = PersonaPatchModel) -> set[str]:
+    paths: set[str] = set()
+    _collect_model_paths(model, "", paths)
+    return paths
+
+
+def validate_patch_operations(ops: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    allowed = allowed_patch_paths()
+    validated: list[dict[str, Any]] = []
+
+    for raw in ops:
+        op = JSONPatchOperation.model_validate(raw).model_dump(by_alias=True, exclude_none=True)
+        path = str(op["path"])
+        _validate_path(path, allowed)
+        if op["op"] in {"move", "copy"} and "from" in op:
+            _validate_path(str(op["from"]), allowed)
+        validated.append(op)
+    return validated
+
+
+def _validate_path(path: str, allowed: set[str]) -> None:
+    if not path.startswith("/"):
+        raise TavusPatchValidationError("JSON Patch path must start with '/'.", path=path)
+    if path in allowed:
+        return
+
+    parts = [part for part in path.split("/") if part]
+    prefixes = ["/" + "/".join(parts[:i]) for i in range(1, len(parts) + 1)]
+    if any(prefix in allowed and _is_dynamic_child_allowed(prefix) for prefix in prefixes):
+        return
+
+    suggestions = difflib.get_close_matches(path, sorted(allowed), n=5)
+    raise TavusPatchValidationError(
+        f"Unsupported persona patch path: {path}",
+        path=path,
+        suggestions=suggestions,
+    )
+
+
+def _is_dynamic_child_allowed(prefix: str) -> bool:
+    return prefix.endswith(
+        (
+            "/tools",
+            "/headers",
+            "/extra_body",
+            "/default_query",
+            "/voice_settings",
+            "/visual_tools",
+            "/audio_tools",
+            "/perception_tools",
+            "/transport",
+            "/sts",
+        )
+    )
+
+
+def _collect_model_paths(model: type[BaseModel], base: str, paths: set[str]) -> None:
+    for name, field in model.model_fields.items():
+        path = f"{base}/{name}"
+        paths.add(path)
+        annotation = _unwrap_optional(field.annotation)
+        origin = get_origin(annotation)
+
+        if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+            _collect_model_paths(annotation, path, paths)
+        elif origin is list:
+            paths.add(f"{path}/-")
+            paths.add(f"{path}/0")
+        elif origin is dict:
+            paths.add(f"{path}/*")
+
+
+def _unwrap_optional(annotation: Any) -> Any:
+    origin = get_origin(annotation)
+    if origin in {type(None), None}:
+        return annotation
+    if origin in {__import__("types").UnionType, getattr(__import__("typing"), "Union", object)}:
+        args = [arg for arg in get_args(annotation) if arg is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return annotation

tavus_mcp/sdk/recipes/__init__.py

@@ -0,0 +1,6 @@
+from tavus_mcp.sdk.recipes.options import describe_persona_options
+from tavus_mcp.sdk.recipes.quickstart import quickstart
+from tavus_mcp.sdk.recipes.scaffold_embed import scaffold_embed
+from tavus_mcp.sdk.recipes.templates import persona_from_template
+
+__all__ = ["describe_persona_options", "persona_from_template", "quickstart", "scaffold_embed"]