tavus-cli 0.1.0__py3-none-any.whl

tavus_mcp/sdk/__init__.py

@@ -0,0 +1,6 @@
+"""Shared Tavus SDK internals used by the CLI and MCP server."""
+
+from tavus_mcp.sdk.client.http import TavusClient
+from tavus_mcp.sdk.env import TavusConfig, TavusEnvironment, load_config
+
+__all__ = ["TavusClient", "TavusConfig", "TavusEnvironment", "load_config"]

tavus_mcp/sdk/auth/__init__.py

@@ -0,0 +1 @@
+"""Auth helpers."""

tavus_mcp/sdk/auth/keyring_store.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import keyring
+
+from tavus_mcp.sdk.env import TavusConfig
+
+
+def get_api_key(config: TavusConfig) -> str | None:
+    return keyring.get_password(config.keyring_service, config.keyring_username)
+
+
+def set_api_key(config: TavusConfig, api_key: str) -> None:
+    keyring.set_password(config.keyring_service, config.keyring_username, api_key)
+
+
+def delete_api_key(config: TavusConfig) -> None:
+    try:
+        keyring.delete_password(config.keyring_service, config.keyring_username)
+    except keyring.errors.PasswordDeleteError:
+        return

tavus_mcp/sdk/auth/oauth.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import socket
+import threading
+import time
+import webbrowser
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from secrets import token_urlsafe
+from socketserver import BaseServer
+from typing import Any
+from urllib.parse import urlencode
+
+from tavus_mcp.sdk.auth import keyring_store
+from tavus_mcp.sdk.env import TavusConfig
+from tavus_mcp.sdk.errors import TavusAuthError
+
+
+@dataclass(frozen=True)
+class LoginResult:
+    api_key: str
+    email: str | None = None
+
+
+@dataclass
+class _Captured:
+    api_key: str | None = None
+    email: str | None = None
+    error: str | None = None
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+def _handler(state: str, captured: _Captured) -> type[BaseHTTPRequestHandler]:
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, format: str, *args: Any) -> None:
+            return
+
+        def _cors_headers(self) -> None:
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Methods", "POST, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type")
+
+        def do_OPTIONS(self) -> None:
+            self.send_response(204)
+            self._cors_headers()
+            self.end_headers()
+
+        def do_POST(self) -> None:
+            if self.path.rstrip("/") != "/callback":
+                self.send_error(404)
+                return
+            length = int(self.headers.get("Content-Length", "0"))
+            try:
+                payload = json.loads(self.rfile.read(length).decode("utf-8"))
+            except Exception:
+                self.send_error(400, "Invalid JSON")
+                return
+            if payload.get("state") != state:
+                captured.error = "Invalid state"
+                self.send_error(400, captured.error)
+                return
+            api_key = payload.get("api_key")
+            if not isinstance(api_key, str) or not api_key:
+                captured.error = "Missing api_key"
+                self.send_error(400, captured.error)
+                return
+            captured.api_key = api_key
+            email = payload.get("email")
+            if isinstance(email, str):
+                captured.email = email
+            self.send_response(204)
+            self._cors_headers()
+            self.end_headers()
+            threading.Thread(target=self.server.shutdown, daemon=True).start()
+
+    return Handler
+
+
+def _shutdown(server: BaseServer) -> None:
+    try:
+        server.shutdown()
+    except Exception:
+        return
+
+
+def _authorize_url(config: TavusConfig, *, callback: str, state: str, key_name: str) -> str:
+    query = urlencode({"callback": callback, "state": state, "name": key_name})
+    return f"{str(config.dev_portal_url).rstrip('/')}/dev/cli-authorize?{query}"
+
+
+def _run_login_flow(
+    config: TavusConfig, *, key_name: str, timeout_seconds: int = 300
+) -> _Captured:
+    state = token_urlsafe(32)
+    port = _free_port()
+    captured = _Captured()
+    server = ThreadingHTTPServer(("127.0.0.1", port), _handler(state, captured))
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    callback = f"http://127.0.0.1:{port}/callback"
+    url = _authorize_url(config, callback=callback, state=state, key_name=key_name)
+    webbrowser.open(url, new=1)
+
+    deadline = time.monotonic() + timeout_seconds
+    try:
+        while time.monotonic() < deadline and not captured.api_key and not captured.error:
+            time.sleep(0.1)
+        if captured.error:
+            raise TavusAuthError(captured.error)
+        if not captured.api_key:
+            raise TavusAuthError(
+                "Timed out waiting for the dev-portal to send the API key."
+            )
+        return captured
+    finally:
+        _shutdown(server)
+        thread.join(timeout=2)
+
+
+async def login_with_browser(config: TavusConfig, *, key_name: str) -> LoginResult:
+    captured = await asyncio.to_thread(_run_login_flow, config, key_name=key_name)
+    assert captured.api_key is not None
+    keyring_store.set_api_key(config, captured.api_key)
+    return LoginResult(api_key=captured.api_key, email=captured.email)

tavus_mcp/sdk/auth/session.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from tavus_mcp.sdk.auth import keyring_store
+from tavus_mcp.sdk.env import TavusConfig
+from tavus_mcp.sdk.errors import TavusAuthError
+
+
+@dataclass(frozen=True)
+class TavusSession:
+    api_key: str
+    source: str
+
+
+def _env_api_key(config: TavusConfig) -> tuple[str, str] | None:
+    generic = os.getenv("TAVUS_API_KEY")
+    if generic:
+        return generic, "env:TAVUS_API_KEY"
+
+    env_specific_name = f"TAVUS_{config.env.value}_API_KEY"
+    env_specific = os.getenv(env_specific_name)
+    if env_specific:
+        return env_specific, f"env:{env_specific_name}"
+    return None
+
+
+def get_session(config: TavusConfig, *, required: bool = True) -> TavusSession | None:
+    if env_key := _env_api_key(config):
+        api_key, source = env_key
+        return TavusSession(api_key=api_key, source=source)
+
+    stored = keyring_store.get_api_key(config)
+    if stored:
+        return TavusSession(
+            api_key=stored,
+            source=f"keyring:{config.keyring_service}/{config.keyring_username}",
+        )
+
+    if required:
+        raise TavusAuthError(
+            f"No Tavus API key found for {config.env.value}. Run `tavus auth login` "
+            "or set TAVUS_API_KEY/TAVUS_<ENV>_API_KEY."
+        )
+    return None

tavus_mcp/sdk/client/__init__.py

@@ -0,0 +1,3 @@
+from tavus_mcp.sdk.client.http import TavusClient
+
+__all__ = ["TavusClient"]

tavus_mcp/sdk/client/http.py

@@ -0,0 +1,451 @@
+from __future__ import annotations
+
+import asyncio
+import json as _json
+from typing import Any, Self
+
+import httpx
+
+from tavus_mcp.sdk.auth.session import TavusSession, get_session
+from tavus_mcp.sdk.env import TavusConfig, load_config
+from tavus_mcp.sdk.errors import TavusApiError
+from tavus_mcp.sdk.patch import validate_patch_operations
+from tavus_mcp.sdk.schemas.guardrail import GuardrailCreate, GuardrailUpdate
+from tavus_mcp.sdk.schemas.objective import ObjectivesCreate
+from tavus_mcp.sdk.schemas.persona import JSONPatchOperation, PersonaCreate
+from tavus_mcp.sdk.schemas.pronunciation import (
+    PronunciationDictionaryCreate,
+    PronunciationDictionaryUpdate,
+)
+from tavus_mcp.sdk.schemas.tool import AttachToolsBody, ToolCreate, ToolUpdate
+
+BREAK_MARKER = "[BREAK]"
+STOP_MARKER = "[STOP]"
+BUILDER_LLM_TIMEOUT_S = 120.0
+
+
+class TavusClient:
+    def __init__(
+        self,
+        config: TavusConfig,
+        session: TavusSession,
+        *,
+        timeout: float = 30,
+        retry: bool = False,
+    ) -> None:
+        self.config = config
+        self.session = session
+        self.retry = retry
+        headers = {"x-api-key": session.api_key, "Content-Type": "application/json"}
+        self._client = httpx.AsyncClient(
+            base_url=str(config.public_api_base_url),
+            timeout=timeout,
+            headers=headers,
+        )
+        self._portal_client = httpx.AsyncClient(
+            base_url=str(config.portal_api_base_url),
+            timeout=timeout,
+            headers=headers,
+        )
+        self.personas = PersonaResource(self)
+        self.replicas = Resource(self, "replicas")
+        self.conversations = ConversationResource(self)
+        self.guardrails = GuardrailResource(self)
+        self.objectives = ObjectiveResource(self)
+        self.documents = Resource(self, "documents")
+        self.voices = Resource(self, "voices")
+        self.tools = ToolResource(self)
+        self.pronunciation_dictionaries = PronunciationDictionaryResource(self)
+        self.builders = BuilderResource(self)
+
+    @classmethod
+    def from_env(cls, *, required: bool = True, timeout: float = 30, retry: bool = False) -> Self:
+        config = load_config()
+        session = get_session(config, required=required)
+        if session is None:
+            raise RuntimeError("Session was unexpectedly missing.")
+        return cls(config, session, timeout=timeout, retry=retry)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+        await self._portal_client.aclose()
+
+    async def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        return await self._do_request(self._client, method, path, **kwargs)
+
+    async def portal_request(self, method: str, path: str, **kwargs: Any) -> Any:
+        return await self._do_request(self._portal_client, method, path, **kwargs)
+
+    async def _do_request(
+        self, client: httpx.AsyncClient, method: str, path: str, **kwargs: Any
+    ) -> Any:
+        response = await client.request(method, path, **kwargs)
+        if response.is_error:
+            try:
+                body: Any = response.json()
+            except ValueError:
+                body = response.text
+            raise TavusApiError(
+                f"Tavus API {method.upper()} {path} failed with {response.status_code}",
+                status_code=response.status_code,
+                body=body,
+            )
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+
+class Resource:
+    def __init__(self, client: TavusClient, name: str) -> None:
+        self.client = client
+        self.name = name.strip("/")
+
+    async def list(self, **params: Any) -> Any:
+        return await self.client.request("GET", f"/{self.name}", params=_clean(params))
+
+    async def get(self, resource_id: str, **params: Any) -> Any:
+        return await self.client.request(
+            "GET",
+            f"/{self.name}/{resource_id}",
+            params=_clean(params),
+        )
+
+    async def create(self, payload: dict[str, Any]) -> Any:
+        return await self.client.request("POST", f"/{self.name}", json=payload)
+
+    async def patch(self, resource_id: str, payload: Any) -> Any:
+        return await self.client.request("PATCH", f"/{self.name}/{resource_id}", json=payload)
+
+    async def delete(self, resource_id: str) -> Any:
+        return await self.client.request("DELETE", f"/{self.name}/{resource_id}")
+
+
+class PersonaResource(Resource):
+    def __init__(self, client: TavusClient) -> None:
+        super().__init__(client, "personas")
+
+    async def create(self, payload: dict[str, Any]) -> Any:
+        validated = PersonaCreate.model_validate(payload).model_dump(exclude_none=True)
+        return await super().create(validated)
+
+    async def patch(self, resource_id: str, payload: list[dict[str, Any]]) -> Any:
+        validated = validate_patch_operations(payload)
+        return await super().patch(resource_id, validated)
+
+    async def list_tools(self, persona_id: str) -> Any:
+        return await self.client.request("GET", f"/personas/{persona_id}/tools/")
+
+    async def attach_tools(self, persona_id: str, tool_ids: list[str]) -> Any:
+        body = AttachToolsBody(tool_ids=tool_ids).model_dump()
+        return await self.client.request(
+            "POST", f"/personas/{persona_id}/tools/", json=body
+        )
+
+    async def detach_tool(self, persona_id: str, tool_id: str) -> Any:
+        return await self.client.request(
+            "DELETE", f"/personas/{persona_id}/tools/{tool_id}"
+        )
+
+
+class GuardrailResource(Resource):
+    """Flat-list guardrails (no more sets). Adds `validate` and `tags` to the
+    base CRUD surface."""
+
+    def __init__(self, client: TavusClient) -> None:
+        super().__init__(client, "guardrails")
+
+    async def create(self, payload: dict[str, Any]) -> Any:
+        validated = GuardrailCreate.model_validate(payload).model_dump(exclude_none=True)
+        return await self.client.request("POST", "/guardrails/", json=validated)
+
+    async def patch(self, resource_id: str, payload: dict[str, Any]) -> Any:
+        validated = GuardrailUpdate.model_validate(payload).model_dump(exclude_none=True)
+        return await self.client.request(
+            "PATCH", f"/guardrails/{resource_id}", json=validated
+        )
+
+    async def validate(self, payload: dict[str, Any]) -> Any:
+        """`POST /v2/guardrails/validate` — checks a legacy set-shape payload
+        without persisting. Useful before bulk-importing."""
+        return await self.client.request("POST", "/guardrails/validate", json=payload)
+
+    async def tags(self, **params: Any) -> Any:
+        """`GET /v2/guardrails/tags` — KB-shaped `{tags, total_count}`."""
+        return await self.client.request(
+            "GET", "/guardrails/tags", params=_clean(params)
+        )
+
+
+class ObjectiveResource(Resource):
+    """Objective *sets* — still set-based (unlike guardrails). Each set
+    bundles ordered/conditional steps and lives at a single ``objectives_id``
+    that personas reference. PATCH takes JSON Patch ops against the set
+    document (matches the `PATCH /v2/objectives/{id}` server contract)."""
+
+    def __init__(self, client: TavusClient) -> None:
+        super().__init__(client, "objectives")
+
+    async def create(self, payload: dict[str, Any]) -> Any:
+        validated = ObjectivesCreate.model_validate(payload).model_dump(exclude_none=True)
+        return await self.client.request("POST", "/objectives/", json=validated)
+
+    async def patch(self, resource_id: str, payload: list[dict[str, Any]]) -> Any:
+        ops = [
+            JSONPatchOperation.model_validate(item).model_dump(
+                by_alias=True, exclude_none=True
+            )
+            for item in payload
+        ]
+        return await self.client.request(
+            "PATCH", f"/objectives/{resource_id}", json=ops
+        )
+
+    async def validate(self, payload: dict[str, Any]) -> Any:
+        """`POST /v2/objectives/validate` — check a set-shape payload
+        (cycles, single-root, references) without persisting."""
+        validated = ObjectivesCreate.model_validate(payload).model_dump(exclude_none=True)
+        return await self.client.request("POST", "/objectives/validate", json=validated)
+
+
+class ToolResource(Resource):
+    """Tools resource with the new HTTP-delivery surface area."""
+
+    def __init__(self, client: TavusClient) -> None:
+        super().__init__(client, "tools")
+
+    async def create(self, payload: dict[str, Any]) -> Any:
+        validated = ToolCreate.model_validate(payload).model_dump(exclude_none=True)
+        return await super().create(validated)
+
+    async def patch(self, resource_id: str, payload: dict[str, Any]) -> Any:
+        validated = ToolUpdate.model_validate(payload).model_dump(exclude_none=True)
+        return await super().patch(resource_id, validated)
+
+
+class PronunciationDictionaryResource(Resource):
+    """`/v2/pronunciation-dictionaries/*` — substitution maps that personas
+    reference via ``layers.tts.pronunciation_dictionary_id``."""
+
+    def __init__(self, client: TavusClient) -> None:
+        super().__init__(client, "pronunciation-dictionaries")
+
+    async def create(self, payload: dict[str, Any]) -> Any:
+        validated = PronunciationDictionaryCreate.model_validate(payload).model_dump(
+            exclude_none=True
+        )
+        return await self.client.request(
+            "POST", "/pronunciation-dictionaries/", json=validated
+        )
+
+    async def patch(self, resource_id: str, payload: dict[str, Any]) -> Any:
+        validated = PronunciationDictionaryUpdate.model_validate(payload).model_dump(
+            exclude_none=True
+        )
+        return await self.client.request(
+            "PATCH", f"/pronunciation-dictionaries/{resource_id}", json=validated
+        )
+
+
+class ConversationResource(Resource):
+    def __init__(self, client: TavusClient) -> None:
+        super().__init__(client, "conversations")
+
+    async def end(self, conversation_id: str) -> Any:
+        return await self.client.request("POST", f"/conversations/{conversation_id}/end")
+
+    async def respond_send(
+        self, conversation_id: str, text: str, *, timeout_s: float | None = None
+    ) -> Any:
+        payload: dict[str, Any] = {"text": text}
+        kwargs: dict[str, Any] = {"json": payload}
+        if timeout_s is not None:
+            payload["timeout_s"] = timeout_s
+            kwargs["timeout"] = max(30.0, timeout_s + 20.0)
+        return await self.client.request(
+            "POST",
+            f"/conversations/{conversation_id}/respond",
+            **kwargs,
+        )
+
+    async def respond_poll(self, conversation_id: str) -> Any:
+        return await self.client.request("GET", f"/conversations/{conversation_id}/respond")
+
+    async def chat_turn(
+        self,
+        conversation_id: str,
+        text: str,
+        *,
+        timeout_s: float = 20.0,
+        poll_s: float = 0.4,
+    ) -> str:
+        sent = await self.respond_send(conversation_id, text, timeout_s=timeout_s)
+        if isinstance(sent, dict) and sent.get("status") == "ready":
+            return sent.get("text", "")
+        loop = asyncio.get_event_loop()
+        deadline = loop.time() + timeout_s
+        while loop.time() < deadline:
+            reply = await self.respond_poll(conversation_id)
+            if isinstance(reply, dict) and reply.get("status") == "ready":
+                return reply.get("text", "")
+            await asyncio.sleep(poll_s)
+        raise TimeoutError(
+            f"No reply within {timeout_s}s for conversation {conversation_id}"
+        )
+
+
+class BuilderResource:
+    """Builder endpoints. Hits RQH /v2/builder/... directly with x-api-key."""
+
+    def __init__(self, client: TavusClient) -> None:
+        self.client = client
+
+    async def create(self, payload: dict[str, Any]) -> Any:
+        return await self.client.request("POST", "/builder", json=payload)
+
+    async def list(self, **params: Any) -> Any:
+        return await self.client.request("GET", "/builder", params=_clean(params))
+
+    async def get(self, builder_id: str) -> Any:
+        return await self.client.request("GET", f"/builder/{builder_id}")
+
+    async def delete(self, builder_id: str) -> Any:
+        return await self.client.request("DELETE", f"/builder/{builder_id}")
+
+    async def chat_history(self, builder_id: str, limit: int = 50) -> Any:
+        return await self.client.request(
+            "GET", f"/builder/{builder_id}/chat", params={"limit": limit}
+        )
+
+    async def append_messages(
+        self, builder_id: str, messages: list[dict[str, str]]
+    ) -> Any:
+        return await self.client.request(
+            "POST", f"/builder/{builder_id}/append-messages", json={"messages": messages}
+        )
+
+    async def update_objectives(self, builder_id: str, message: str) -> Any:
+        return await self.client.request(
+            "POST",
+            f"/builder/{builder_id}/update-objectives",
+            json={"message": message},
+            timeout=BUILDER_LLM_TIMEOUT_S,
+        )
+
+    async def update_guardrails(self, builder_id: str, message: str) -> Any:
+        return await self.client.request(
+            "POST",
+            f"/builder/{builder_id}/update-guardrails",
+            json={"message": message},
+            timeout=BUILDER_LLM_TIMEOUT_S,
+        )
+
+    async def update_greeting(self, builder_id: str, message: str) -> Any:
+        return await self.client.request(
+            "POST",
+            f"/builder/{builder_id}/update-greeting",
+            json={"message": message},
+            timeout=BUILDER_LLM_TIMEOUT_S,
+        )
+
+    async def update_personality(
+        self,
+        builder_id: str,
+        message: str,
+        *,
+        persona_name: bool = False,
+        system_prompt: bool = False,
+    ) -> Any:
+        return await self.client.request(
+            "POST",
+            f"/builder/{builder_id}/update-personality",
+            json={
+                "message": message,
+                "persona_name": persona_name,
+                "system_prompt": system_prompt,
+            },
+            timeout=BUILDER_LLM_TIMEOUT_S,
+        )
+
+    async def publish(self, builder_id: str) -> Any:
+        return await self.client.request(
+            "POST", f"/builder/{builder_id}/publish"
+        )
+
+    async def chat(self, builder_id: str, message: str) -> dict[str, Any]:
+        """Send a chat turn. Drains the streamed body (text + `[BREAK]` +
+        trailing JSON) into one structured response: ``{text, suggestions,
+        draft_ready, targets}``.
+        """
+        async with self.client._client.stream(
+            "POST",
+            f"/builder/{builder_id}/chat",
+            json={"message": message},
+            timeout=BUILDER_LLM_TIMEOUT_S,
+        ) as response:
+            if response.is_error:
+                body_bytes = await response.aread()
+                try:
+                    body: Any = _json.loads(body_bytes)
+                except ValueError:
+                    body = body_bytes.decode("utf-8", errors="replace")
+                raise TavusApiError(
+                    f"Tavus API POST /builder/{builder_id}/chat failed with {response.status_code}",
+                    status_code=response.status_code,
+                    body=body,
+                )
+            chunks: list[str] = []
+            async for chunk in response.aiter_text():
+                chunks.append(chunk)
+        return _parse_builder_chat_stream("".join(chunks))
+
+
+def _parse_builder_chat_stream(body: str) -> dict[str, Any]:
+    """Drain the builder chat stream into ``{text, suggestions,
+    draft_ready, targets}``.
+
+    Wire format (concatenated chunks):
+        <text chunks>...[STOP]<json>[BREAK]
+
+    The text frame ends at ``[STOP]``. The JSON payload sits between
+    ``[STOP]`` and the trailing ``[BREAK]``. Either marker may be
+    absent — a turn that fails before reaching autocomplete arrives
+    without ``[BREAK]``; a turn that emits no streamed text arrives
+    without ``[STOP]``.
+    """
+    text_part, stop_sep, after_stop = body.partition(STOP_MARKER)
+    if stop_sep:
+        json_segment = after_stop
+    else:
+        # No [STOP] — try to recover JSON before [BREAK] from the tail.
+        json_segment = ""
+        if BREAK_MARKER in text_part:
+            text_part, _, json_segment = text_part.rpartition(BREAK_MARKER)
+    json_segment, _, _ = json_segment.partition(BREAK_MARKER)
+    text_part = text_part.strip()
+    data: dict[str, Any] = {}
+    if json_segment.strip():
+        try:
+            parsed = _json.loads(json_segment.strip())
+            if isinstance(parsed, dict):
+                data = parsed
+        except ValueError:
+            pass
+    return {
+        "text": text_part,
+        "suggestions": list(data.get("suggestions", []) or []),
+        "draft_ready": bool(data.get("draft_ready", False)),
+        "targets": list(data.get("targets", []) or []),
+    }
+
+
+def _clean(params: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in params.items() if value is not None}