typecast-python 0.3.6__tar.gz → 0.3.8__tar.gz

{typecast_python-0.3.6 → typecast_python-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.3.6
+Version: 0.3.8
 Summary: Official Typecast Python SDK - Convert text to lifelike speech using AI-powered voices
 Project-URL: Homepage, https://typecast.ai
 Project-URL: Documentation, https://typecast.ai/docs/overview

{typecast_python-0.3.6 → typecast_python-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "typecast-python"
-version = "0.3.6"
+version = "0.3.8"
 description = "Official Typecast Python SDK - Convert text to lifelike speech using AI-powered voices"
 authors = [
     {name = "Neosapience", email = "help@typecast.ai"}
@@ -98,6 +98,9 @@ dev = [
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
+markers = [
+    "e2e: end-to-end tests against the real Typecast API (require credentials)",
+]
 filterwarnings = [
     "ignore::DeprecationWarning",
 ]

{typecast_python-0.3.6 → typecast_python-0.3.8}/src/typecast/__init__.py

@@ -19,6 +19,7 @@ from .models import (
     OutputStream,
     PlanTier,
     Prompt,
+    RecommendedVoice,
     SubscriptionResponse,
     TTSRequest,
     TTSRequestStream,
@@ -48,6 +49,7 @@ __all__ = [
     "OutputStream",
     "PlanTier",
     "Prompt",
+    "RecommendedVoice",
     "SubscriptionResponse",
     "TTSRequest",
     "TTSRequestStream",

typecast_python-0.3.8/src/typecast/_user_agent.py

@@ -0,0 +1,70 @@
+import platform
+import sys
+from importlib import metadata
+
+import aiohttp
+import requests
+
+from . import conf
+
+
+def _package_version(package_name: str) -> str:
+    try:
+        return metadata.version(package_name)
+    except metadata.PackageNotFoundError:
+        return "dev"
+
+
+def _os_name() -> str:
+    system = platform.system().lower()
+    if system == "darwin":
+        return "macos"
+    if system.startswith("windows"):
+        return "windows"
+    return system or "unknown"
+
+
+def _arch_name() -> str:
+    machine = platform.machine().lower()
+    if machine in {"x86_64", "amd64"}:
+        return "x64"
+    if machine in {"aarch64", "arm64"}:
+        return "arm64"
+    return machine or "unknown"
+
+
+def build_user_agent(
+    *,
+    mode: str,
+    http_library: str,
+    host: str,
+    transport: str = "rest",
+) -> str:
+    sdk_version = _package_version("typecast-python")
+    base = "default" if conf.is_default_host(host) else "custom"
+    return (
+        f"typecast-python/{sdk_version} "
+        f"Python/{sys.version_info.major}.{sys.version_info.minor} "
+        f"{platform.python_implementation()}/{platform.python_version()} "
+        f"{http_library} "
+        f"(mode={mode}; base={base}; transport={transport}; "
+        f"os={_os_name()}; arch={_arch_name()}; sdk_env=python; platform=server)"
+    )
+
+
+def requests_user_agent(host: str, transport: str = "rest") -> str:
+    return build_user_agent(
+        mode="sync",
+        http_library=f"requests/{requests.__version__}",
+        host=host,
+        transport=transport,
+    )
+
+
+def aiohttp_user_agent(host: str, transport: str = "rest") -> str:
+    return build_user_agent(
+        mode="async",
+        http_library=f"aiohttp/{aiohttp.__version__}",
+        host=host,
+        transport=transport,
+    )

{typecast_python-0.3.6 → typecast_python-0.3.8}/src/typecast/async_client.py

@@ -11,6 +11,7 @@ from ._voice_clone import (
     validate_clone_inputs,
     validate_custom_voice_id,
 )
+from ._user_agent import aiohttp_user_agent
 from .client import _guess_audio_mime
 from .client import _output_with_inferred_format
 from .client import _validate_output_path
@@ -28,6 +29,7 @@ from .models import (
     CustomVoice,
     LanguageCode,
     Output,
+    RecommendedVoice,
     SubscriptionResponse,
     TTSModel,
     TTSPrompt,
@@ -61,34 +63,48 @@ class AsyncTypecast:
         ...         f.write(response.audio_data)
     """
 
-    def __init__(self, host: Optional[str] = None, api_key: Optional[str] = None):
+    def __init__(
+        self,
+        host: Optional[str] = None,
+        api_key: Optional[str] = None,
+        session: Optional[aiohttp.ClientSession] = None,
+    ):
         """Initialize the async Typecast client.
 
         Args:
             host: API host URL. Defaults to TYPECAST_API_HOST env var
                 or 'https://api.typecast.ai'.
             api_key: API key for authentication. Defaults to TYPECAST_API_KEY env var.
+            session: Optional externally-managed aiohttp.ClientSession. When provided,
+                __aenter__ will not create a new session and __aexit__ will not close it
+                (the caller owns its lifecycle). Auth headers (`X-API-KEY`, `User-Agent`)
+                are attached per-request via `_request_headers()`.
 
         Raises:
-            ValueError: If no API key is provided and TYPECAST_API_KEY is not set.
+            ValueError: If no API key is provided and TYPECAST_API_KEY is not set
+                for the default host.
         """
         self.host = conf.get_host(host)
         self.api_key = conf.get_api_key(api_key)
         if not self.api_key and conf.is_default_host(self.host):
             raise ValueError("API key is required for the default Typecast API host")
-        self.session: Optional[aiohttp.ClientSession] = None
+        self._owns_session = session is None
+        self.session: Optional[aiohttp.ClientSession] = session
 
     async def __aenter__(self):
-        # Auth header at session scope; per-request Content-Type is set by aiohttp
-        # (json= auto-sets application/json, data=FormData() auto-sets multipart).
-        headers = {}
-        if self.api_key:
-            headers["X-API-KEY"] = self.api_key
-        self.session = aiohttp.ClientSession(headers=headers)
+        # When an external session is injected, do not create a new one.
+        # Per-request auth headers are attached via _request_headers() on each call.
+        if self.session is None:
+            headers = {"User-Agent": aiohttp_user_agent(self.host)}
+            if self.api_key:
+                headers["X-API-KEY"] = self.api_key
+            self.session = aiohttp.ClientSession(headers=headers)
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        if self.session:
+        # Only close sessions we created. External sessions are caller-owned;
+        # leave the reference intact so the client can be re-entered.
+        if self.session and self._owns_session:
             await self.session.close()
 
     def _handle_error(self, status_code: int, response_text: str):
@@ -113,6 +129,20 @@ class AsyncTypecast:
                 status_code=status_code,
             )
 
+    def _request_headers(self) -> Optional[dict]:
+        """Headers to attach to each individual request.
+
+        For owned sessions, auth is set at session scope, so return None and let
+        aiohttp use the session headers. For external sessions, the session has
+        no auth headers, so we attach X-API-KEY and User-Agent per-request.
+        """
+        if self._owns_session:
+            return None
+        headers = {"User-Agent": aiohttp_user_agent(self.host)}
+        if self.api_key:
+            headers["X-API-KEY"] = self.api_key
+        return headers
+
     async def text_to_speech(self, request: TTSRequest) -> TTSResponse:
         """Convert text to speech asynchronously.
 
@@ -134,7 +164,9 @@ class AsyncTypecast:
             raise TypecastError("Client session not initialized. Use async with.")
         endpoint = "/v1/text-to-speech"
         async with self.session.post(
-            f"{self.host}{endpoint}", json=request.model_dump(exclude_none=True)
+            f"{self.host}{endpoint}",
+            json=request.model_dump(exclude_none=True),
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 error_text = await response.text()
@@ -203,7 +235,11 @@ class AsyncTypecast:
             NotFoundError, UnprocessableEntityError, RateLimitError,
             InternalServerError, TypecastError: depending on response status.
         """
-        if not isinstance(chunk_size, int) or isinstance(chunk_size, bool) or chunk_size < 1:
+        if (
+            not isinstance(chunk_size, int)
+            or isinstance(chunk_size, bool)
+            or chunk_size < 1
+        ):
             raise ValueError("chunk_size must be a positive integer")
         if not self.session:
             raise TypecastError("Client session not initialized. Use async with.")
@@ -213,6 +249,7 @@ class AsyncTypecast:
             f"{self.host}{endpoint}",
             json=request.model_dump(exclude_none=True),
             timeout=stream_timeout,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 error_text = await response.text()
@@ -256,6 +293,7 @@ class AsyncTypecast:
             f"{self.host}{endpoint}",
             json=request.model_dump(exclude_none=True),
             params=params,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 text = await response.text()
@@ -305,6 +343,7 @@ class AsyncTypecast:
             f"{self.host}/v1/voices/clone",
             data=form,
             timeout=timeout,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 text = await response.text()
@@ -329,6 +368,7 @@ class AsyncTypecast:
         async with self.session.delete(
             f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
             timeout=timeout,
+            headers=self._request_headers(),
         ) as response:
             if response.status not in (200, 204):
                 text = await response.text()
@@ -355,7 +395,9 @@ class AsyncTypecast:
             params["model"] = model
 
         async with self.session.get(
-            f"{self.host}{endpoint}", params=params
+            f"{self.host}{endpoint}",
+            params=params,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 error_text = await response.text()
@@ -383,7 +425,9 @@ class AsyncTypecast:
             raise TypecastError("Client session not initialized. Use async with.")
         endpoint = f"/v1/voices/{voice_id}"
 
-        async with self.session.get(f"{self.host}{endpoint}") as response:
+        async with self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        ) as response:
             if response.status != 200:
                 error_text = await response.text()
                 self._handle_error(response.status, error_text)
@@ -420,7 +464,9 @@ class AsyncTypecast:
                 params[key] = getattr(value, "value", value)
 
         async with self.session.get(
-            f"{self.host}{endpoint}", params=params
+            f"{self.host}{endpoint}",
+            params=params,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 error_text = await response.text()
@@ -447,7 +493,9 @@ class AsyncTypecast:
         if not self.session:
             raise TypecastError("Client session not initialized. Use async with.")
         endpoint = "/v1/users/me/subscription"
-        async with self.session.get(f"{self.host}{endpoint}") as response:
+        async with self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        ) as response:
             if response.status != 200:
                 error_text = await response.text()
                 self._handle_error(response.status, error_text)
@@ -470,10 +518,37 @@ class AsyncTypecast:
             raise TypecastError("Client session not initialized. Use async with.")
         endpoint = f"/v2/voices/{voice_id}"
 
-        async with self.session.get(f"{self.host}{endpoint}") as response:
+        async with self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        ) as response:
             if response.status != 200:
                 error_text = await response.text()
                 self._handle_error(response.status, error_text)
 
             data = await response.json()
             return VoiceV2Response.model_validate(data)
+
+    async def recommend_voices(
+        self, query: str, count: int = 5
+    ) -> list[RecommendedVoice]:
+        """Recommend voices from a text description.
+
+        Recommendation results only include ``voice_id``, ``voice_name``, and
+        ``score``. Use ``voice_v2`` or ``voices_v2`` to fetch detailed metadata
+        for returned voice IDs.
+        """
+        if count < 1 or count > 10:
+            raise ValueError("count must be between 1 and 10")
+        if not self.session:
+            raise TypecastError("Client session not initialized. Use async with.")
+
+        async with self.session.get(
+            f"{self.host}/v1/voices/recommendations",
+            params={"query": query, "count": count},
+        ) as response:
+            if response.status != 200:
+                error_text = await response.text()
+                self._handle_error(response.status, error_text)
+
+            data = await response.json()
+            return [RecommendedVoice.model_validate(item) for item in data]

{typecast_python-0.3.6 → typecast_python-0.3.8}/src/typecast/client.py

@@ -10,6 +10,7 @@ from ._voice_clone import (
     validate_clone_inputs,
     validate_custom_voice_id,
 )
+from ._user_agent import requests_user_agent
 from .composer import SpeechComposer
 from .exceptions import (
     BadRequestError,
@@ -25,6 +26,7 @@ from .models import (
     CustomVoice,
     LanguageCode,
     Output,
+    RecommendedVoice,
     SubscriptionResponse,
     TTSModel,
     TTSPrompt,
@@ -95,13 +97,22 @@ class Typecast:
         ...     f.write(response.audio_data)
     """
 
-    def __init__(self, host: Optional[str] = None, api_key: Optional[str] = None):
+    def __init__(
+        self,
+        host: Optional[str] = None,
+        api_key: Optional[str] = None,
+        session: Optional[requests.Session] = None,
+    ):
         """Initialize the Typecast client.
 
         Args:
             host: API host URL. Defaults to TYPECAST_API_HOST env var
                 or 'https://api.typecast.ai'.
             api_key: API key for authentication. Defaults to TYPECAST_API_KEY env var.
+            session: Optional externally-managed requests.Session. When provided,
+                the client will not create a new session nor close it; auth headers
+                (`X-API-KEY`, `User-Agent`) are attached per-request via
+                `_request_headers()`.
 
         Raises:
             ValueError: If no API key is provided and TYPECAST_API_KEY is not set.
@@ -110,11 +121,18 @@ class Typecast:
         self.api_key = conf.get_api_key(api_key)
         if not self.api_key and conf.is_default_host(self.host):
             raise ValueError("API key is required for the default Typecast API host")
-        self.session = requests.Session()
-        headers = {"Content-Type": "application/json"}
-        if self.api_key:
-            headers["X-API-KEY"] = self.api_key
-        self.session.headers.update(headers)
+        self._owns_session = session is None
+        if session is not None:
+            self.session = session
+        else:
+            self.session = requests.Session()
+            headers = {
+                "Content-Type": "application/json",
+                "User-Agent": requests_user_agent(self.host),
+            }
+            if self.api_key:
+                headers["X-API-KEY"] = self.api_key
+            self.session.headers.update(headers)
 
     def _handle_error(self, status_code: int, response_text: str):
         """Handle HTTP error responses with specific exception types."""
@@ -138,6 +156,20 @@ class Typecast:
                 status_code=status_code,
             )
 
+    def _request_headers(self) -> Optional[dict]:
+        """Headers to attach to each individual request.
+
+        For owned sessions, auth is set at session scope, so return None and let
+        requests use the session headers. For external sessions, the session has
+        no auth headers, so we attach X-API-KEY and User-Agent per-request.
+        """
+        if self._owns_session:
+            return None
+        headers = {"User-Agent": requests_user_agent(self.host)}
+        if self.api_key:
+            headers["X-API-KEY"] = self.api_key
+        return headers
+
     def text_to_speech(self, request: TTSRequest) -> TTSResponse:
         """Convert text to speech.
 
@@ -156,7 +188,9 @@ class Typecast:
         """
         endpoint = "/v1/text-to-speech"
         response = self.session.post(
-            f"{self.host}{endpoint}", json=request.model_dump(exclude_none=True)
+            f"{self.host}{endpoint}",
+            json=request.model_dump(exclude_none=True),
+            headers=self._request_headers(),
         )
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -236,7 +270,11 @@ class Typecast:
             NotFoundError, UnprocessableEntityError, RateLimitError,
             InternalServerError, TypecastError: depending on response status.
         """
-        if not isinstance(chunk_size, int) or isinstance(chunk_size, bool) or chunk_size < 1:
+        if (
+            not isinstance(chunk_size, int)
+            or isinstance(chunk_size, bool)
+            or chunk_size < 1
+        ):
             raise ValueError("chunk_size must be a positive integer")
         endpoint = "/v1/text-to-speech/stream"
         response = self.session.post(
@@ -244,6 +282,7 @@ class Typecast:
             json=request.model_dump(exclude_none=True),
             stream=True,
             timeout=(10, 300),
+            headers=self._request_headers(),
         )
         if response.status_code != 200:
             error_text = response.text
@@ -291,6 +330,7 @@ class Typecast:
             json=request.model_dump(exclude_none=True),
             params=params,
             timeout=(10, 300),
+            headers=self._request_headers(),
         )
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -327,12 +367,19 @@ class Typecast:
         }
         data = {"name": name, "model": model_str}
         # Remove the session-level Content-Type so requests can set the
-        # correct multipart/form-data boundary for this request.
+        # correct multipart/form-data boundary for this request. For external
+        # sessions, also attach the per-request auth headers (X-API-KEY,
+        # User-Agent); _request_headers() returns None for owned sessions, so
+        # owned-session behavior is unchanged.
+        headers = {"Content-Type": None}
+        per_request = self._request_headers()
+        if per_request:
+            headers.update(per_request)
         response = self.session.post(
             f"{self.host}/v1/voices/clone",
             files=files,
             data=data,
-            headers={"Content-Type": None},
+            headers=headers,
             timeout=(10, 300),
         )
         if response.status_code != 200:
@@ -353,6 +400,7 @@ class Typecast:
         response = self.session.delete(
             f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
             timeout=(10, 60),
+            headers=self._request_headers(),
         )
         if response.status_code not in (200, 204):
             self._handle_error(response.status_code, response.text)
@@ -375,7 +423,9 @@ class Typecast:
         if model:
             params["model"] = model
 
-        response = self.session.get(f"{self.host}{endpoint}", params=params)
+        response = self.session.get(
+            f"{self.host}{endpoint}", params=params, headers=self._request_headers()
+        )
 
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -398,7 +448,9 @@ class Typecast:
             This method is deprecated. Use voices_v2() for enhanced metadata.
         """
         endpoint = f"/v1/voices/{voice_id}"
-        response = self.session.get(f"{self.host}{endpoint}")
+        response = self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        )
 
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -432,7 +484,9 @@ class Typecast:
             for key, value in filter_dict.items():
                 params[key] = getattr(value, "value", value)
 
-        response = self.session.get(f"{self.host}{endpoint}", params=params)
+        response = self.session.get(
+            f"{self.host}{endpoint}", params=params, headers=self._request_headers()
+        )
 
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -454,7 +508,9 @@ class Typecast:
             InternalServerError: On server-side failures.
         """
         endpoint = "/v1/users/me/subscription"
-        response = self.session.get(f"{self.host}{endpoint}")
+        response = self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        )
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
         return SubscriptionResponse.model_validate(response.json())
@@ -472,9 +528,33 @@ class Typecast:
             NotFoundError: If the voice ID does not exist.
         """
         endpoint = f"/v2/voices/{voice_id}"
-        response = self.session.get(f"{self.host}{endpoint}")
+        response = self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        )
 
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
 
         return VoiceV2Response.model_validate(response.json())
+
+    def recommend_voices(self, query: str, count: int = 5) -> list[RecommendedVoice]:
+        """Recommend voices from a text description.
+
+        Recommendation results only include ``voice_id``, ``voice_name``, and
+        ``score``. Use ``voice_v2`` or ``voices_v2`` to fetch detailed metadata
+        for returned voice IDs.
+
+        Args:
+            query: Text description of the desired voice.
+            count: Number of recommendations to return, from 1 to 10. Defaults to 5.
+        """
+        if count < 1 or count > 10:
+            raise ValueError("count must be between 1 and 10")
+
+        response = self.session.get(
+            f"{self.host}/v1/voices/recommendations",
+            params={"query": query, "count": count},
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return [RecommendedVoice.model_validate(item) for item in response.json()]

{typecast_python-0.3.6 → typecast_python-0.3.8}/src/typecast/models/__init__.py

@@ -23,6 +23,7 @@ from .voices import (
     CustomVoice,
     GenderEnum,
     ModelInfo,
+    RecommendedVoice,
     UseCaseEnum,
     VoicesResponse,
     VoicesV2Filter,
@@ -46,6 +47,7 @@ __all__ = [
     "PlanTier",
     "Prompt",
     "PresetPrompt",
+    "RecommendedVoice",
     "SmartPrompt",
     "SubscriptionResponse",
     "TTSModel",

{typecast_python-0.3.6 → typecast_python-0.3.8}/src/typecast/models/voices.py

@@ -68,6 +68,19 @@ class VoiceV2Response(BaseModel):
     use_cases: Optional[list[str]] = None
 
 
+class RecommendedVoice(BaseModel):
+    """Recommended voice result.
+
+    Recommendation results only include the matched voice ID, voice name, and
+    similarity score. Use ``voice_v2`` or ``voices_v2`` to fetch detailed voice
+    metadata for a returned ``voice_id``.
+    """
+
+    voice_id: str
+    voice_name: str
+    score: float
+
+
 class VoicesV2Filter(BaseModel):
     """Filter options for V2 voices endpoint"""