speechcortex-sdk 0.1.0__tar.gz → 0.1.dev2__tar.gz

{speechcortex_sdk-0.1.0/speechcortex_sdk.egg-info → speechcortex_sdk-0.1.dev2}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: speechcortex-sdk
-Version: 0.1.0
+Version: 0.1.dev2
 Summary: The official Python SDK for SpeechCortex ASR platform.
-Home-page: https://github.com/skanda-observeai/zeus-sdk-py
+Home-page: https://github.com/speechcortex/speechcortex-sdk
 Author: SpeechCortex Team
 Author-email: SpeechCortex Team <team@speechcortex.com>
 License: MIT
-Project-URL: Homepage, https://github.com/skanda-observeai/zeus-sdk-py
-Project-URL: Bug Tracker, https://github.com/skanda-observeai/zeus-sdk-py/issues
-Project-URL: Source Code, https://github.com/skanda-observeai/zeus-sdk-py
-Project-URL: Documentation, https://github.com/skanda-observeai/zeus-sdk-py#readme
+Project-URL: Homepage, https://github.com/speechcortex/speechcortex-sdk
+Project-URL: Bug Tracker, https://github.com/speechcortex/speechcortex-sdk/issues
+Project-URL: Source Code, https://github.com/speechcortex/speechcortex-sdk
+Project-URL: Documentation, https://github.com/speechcortex/speechcortex-sdk#readme
 Keywords: speechcortex,asr,speech-to-text,speech recognition
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -35,7 +35,7 @@ Dynamic: requires-python
 
 # SpeechCortex Python SDK
 
-[![CI](https://github.com/skanda-observeai/zeus-sdk-py/actions/workflows/ci.yml/badge.svg)](https://github.com/skanda-observeai/zeus-sdk-py/actions/workflows/ci.yml)
+[![CI](https://github.com/speechcortex/speechcortex-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/speechcortex/speechcortex-sdk/actions/workflows/ci.yml)
 [![PyPI version](https://badge.fury.io/py/speechcortex-sdk.svg)](https://badge.fury.io/py/speechcortex-sdk)
 [![Python Versions](https://img.shields.io/pypi/pyversions/speechcortex-sdk.svg)](https://pypi.org/project/speechcortex-sdk/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -57,7 +57,7 @@ Official Python SDK for SpeechCortex ASR (Automatic Speech Recognition) platform
 ## Installation
 
 ```bash
-pip install "git+https://github.com/skanda-observeai/zeus-sdk-py.git@package_init"
+pip install "git+https://github.com/speechcortex/speechcortex-sdk.git@package_init"
 ```
 
 ```bash

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/README.md

@@ -1,6 +1,6 @@
 # SpeechCortex Python SDK
 
-[![CI](https://github.com/skanda-observeai/zeus-sdk-py/actions/workflows/ci.yml/badge.svg)](https://github.com/skanda-observeai/zeus-sdk-py/actions/workflows/ci.yml)
+[![CI](https://github.com/speechcortex/speechcortex-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/speechcortex/speechcortex-sdk/actions/workflows/ci.yml)
 [![PyPI version](https://badge.fury.io/py/speechcortex-sdk.svg)](https://badge.fury.io/py/speechcortex-sdk)
 [![Python Versions](https://img.shields.io/pypi/pyversions/speechcortex-sdk.svg)](https://pypi.org/project/speechcortex-sdk/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -22,7 +22,7 @@ Official Python SDK for SpeechCortex ASR (Automatic Speech Recognition) platform
 ## Installation
 
 ```bash
-pip install "git+https://github.com/skanda-observeai/zeus-sdk-py.git@package_init"
+pip install "git+https://github.com/speechcortex/speechcortex-sdk.git@package_init"
 ```
 
 ```bash

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "speechcortex-sdk"
-version = "0.1.0"
+version = "0.1.dev2"
 description = "The official Python SDK for SpeechCortex ASR platform."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -36,17 +36,17 @@ dependencies = [
 ]
 
 [project.urls]
-"Homepage" = "https://github.com/skanda-observeai/zeus-sdk-py"
-"Bug Tracker" = "https://github.com/skanda-observeai/zeus-sdk-py/issues"
-"Source Code" = "https://github.com/skanda-observeai/zeus-sdk-py"
-"Documentation" = "https://github.com/skanda-observeai/zeus-sdk-py#readme"
+"Homepage" = "https://github.com/speechcortex/speechcortex-sdk"
+"Bug Tracker" = "https://github.com/speechcortex/speechcortex-sdk/issues"
+"Source Code" = "https://github.com/speechcortex/speechcortex-sdk"
+"Documentation" = "https://github.com/speechcortex/speechcortex-sdk#readme"
 
 ######
 # poetry configuration (optional)
 ######
 [tool.poetry]
 name = "speechcortex-sdk"
-version = "0.1.0"
+version = "0.1.dev2"
 description = "The official Python SDK for SpeechCortex ASR platform."
 authors = ["SpeechCortex Team <team@speechcortex.com>"]
 license = "MIT"

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/requirements.txt

@@ -6,3 +6,5 @@ aiohttp>=3.9.1
 aiofiles>=23.2.1
 aenum>=3.1.0
 deprecation>=2.1.0
+requests>=2.31.0
+urllib3>=2.0.0

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/setup.py

@@ -15,14 +15,14 @@ DESCRIPTION = "The official Python SDK for SpeechCortex ASR platform."
 
 setup(
     name="speechcortex-sdk",
-    version="0.1.0",
+    version="0.1.dev2",
     author="SpeechCortex Team",
     author_email="team@speechcortex.com",
-    url="https://github.com/skanda-observeai/zeus-sdk-py",
+    url="https://github.com/speechcortex/speechcortex-sdk",
     project_urls={
-        "Bug Tracker": "https://github.com/skanda-observeai/zeus-sdk-py/issues",
-        "Source Code": "https://github.com/skanda-observeai/zeus-sdk-py",
-        "Documentation": "https://github.com/skanda-observeai/zeus-sdk-py#readme",
+        "Bug Tracker": "https://github.com/speechcortex/speechcortex-sdk/issues",
+        "Source Code": "https://github.com/speechcortex/speechcortex-sdk",
+        "Documentation": "https://github.com/speechcortex/speechcortex-sdk#readme",
     },
     description=DESCRIPTION,
     long_description=LONG_DESCRIPTION,

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/speechcortex/__init__.py

@@ -8,7 +8,7 @@ SpeechCortex Python SDK
 Official Python SDK for SpeechCortex ASR (Automatic Speech Recognition) platform.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.dev2"
 
 # Core client
 from .client import SpeechCortexClient, SpeechCortex, TranscribeRouter
@@ -46,6 +46,18 @@ from .clients.transcribe import (
     Alternative,
     Channel,
     Word,
+    # Batch transcription
+    BatchClient,
+    BatchOptions,
+    TranscriptionConfig,
+    JobDetails,
+    TranscriptionResult,
+    TranscriptionStatus,
+    BatchError,
+    JobNotFoundError,
+    JobFailedError,
+    TranscriptionNotReadyError,
+    BatchTimeoutError,
 )
 
 # Audio utilities
@@ -105,6 +117,18 @@ __all__ = [
     "Alternative",
     "Channel",
     "Word",
+    # Batch transcription
+    "BatchClient",
+    "BatchOptions",
+    "TranscriptionConfig",
+    "JobDetails",
+    "TranscriptionResult",
+    "TranscriptionStatus",
+    "BatchError",
+    "JobNotFoundError",
+    "JobFailedError",
+    "TranscriptionNotReadyError",
+    "BatchTimeoutError",
     # Audio
     "Microphone",
     "SpeechCortexMicrophoneError",

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/speechcortex/client.py

@@ -6,7 +6,7 @@ from typing import Optional
 
 from .options import SpeechCortexClientOptions
 from .errors import SpeechCortexError, SpeechCortexApiKeyError
-from .clients.transcribe import RealtimeClient
+from .clients.transcribe import RealtimeClient, BatchClient
 
 
 class TranscribeRouter:
@@ -15,6 +15,7 @@ class TranscribeRouter:
     def __init__(self, config: SpeechCortexClientOptions):
         self._config = config
         self._realtime_client: Optional[RealtimeClient] = None
+        self._batch_client: Optional[BatchClient] = None
 
     def realtime(self) -> RealtimeClient:
         """
@@ -26,6 +27,17 @@ class TranscribeRouter:
         if self._realtime_client is None:
             self._realtime_client = RealtimeClient(self._config)
         return self._realtime_client
+    
+    def batch(self) -> BatchClient:
+        """
+        Get a batch/post-call transcription client.
+        
+        Returns:
+            BatchClient instance for batch transcription
+        """
+        if self._batch_client is None:
+            self._batch_client = BatchClient(self._config)
+        return self._batch_client
 
 
 class _LegacyWebsocket:
@@ -95,7 +107,14 @@ class SpeechCortexClient:
         Access transcription services.
         
         Returns:
-            TranscribeRouter for accessing real-time and batch transcription
+            TranscribeRouter for accessing real-time and batch transcription.
+            
+        Example:
+            >>> # Real-time transcription
+            >>> client.transcribe.realtime()
+            >>> 
+            >>> # Batch/post-call transcription
+            >>> client.transcribe.batch()
         """
         if self._transcribe is None:
             self._transcribe = TranscribeRouter(self._config)

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/speechcortex/clients/transcribe/__init__.py

@@ -19,6 +19,19 @@ from .realtime import (
     Channel,
     Word,
 )
+from .batch import (
+    BatchClient,
+    BatchOptions,
+    TranscriptionConfig,
+    JobDetails,
+    TranscriptionResult,
+    TranscriptionStatus,
+    BatchError,
+    JobNotFoundError,
+    JobFailedError,
+    TranscriptionNotReadyError,
+    BatchTimeoutError,
+)
 
 __all__ = [
     "LiveTranscriptionEvents",
@@ -36,4 +49,16 @@ __all__ = [
     "Alternative",
     "Channel",
     "Word",
+    # Batch transcription
+    "BatchClient",
+    "BatchOptions",
+    "TranscriptionConfig",
+    "JobDetails",
+    "TranscriptionResult",
+    "TranscriptionStatus",
+    "BatchError",
+    "JobNotFoundError",
+    "JobFailedError",
+    "TranscriptionNotReadyError",
+    "BatchTimeoutError",
 ]

speechcortex_sdk-0.1.dev2/speechcortex/clients/transcribe/batch/__init__.py

@@ -0,0 +1,32 @@
+# Copyright 2024 SpeechCortex SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+from .client import BatchClient
+from .options import BatchOptions, TranscriptionConfig
+from .response import (
+    JobDetails,
+    TranscriptionResult,
+    TranscriptionStatus,
+)
+from .exceptions import (
+    BatchError,
+    JobNotFoundError,
+    JobFailedError,
+    TranscriptionNotReadyError,
+    BatchTimeoutError,
+)
+
+__all__ = [
+    "BatchClient",
+    "BatchOptions",
+    "TranscriptionConfig",
+    "JobDetails",
+    "TranscriptionResult",
+    "TranscriptionStatus",
+    "BatchError",
+    "JobNotFoundError",
+    "JobFailedError",
+    "TranscriptionNotReadyError",
+    "BatchTimeoutError",
+]

speechcortex_sdk-0.1.dev2/speechcortex/clients/transcribe/batch/client.py

@@ -0,0 +1,564 @@
+# Copyright 2024 SpeechCortex SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+"""
+Async batch transcription client for SpeechCortex SDK.
+
+This client provides a pure async interface for post-call/batch transcription,
+allowing users to submit audio files or presigned URLs, poll for status, and
+retrieve transcription results using aiohttp.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any, BinaryIO, Dict, Optional, Union
+from uuid import UUID
+
+import aiohttp
+import aiofiles
+
+from ....options import SpeechCortexClientOptions
+from ....errors import SpeechCortexError, SpeechCortexApiKeyError
+from .options import BatchOptions, TranscriptionConfig
+from .response import JobDetails, TranscriptionResult, TranscriptionStatus
+from .exceptions import (
+    BatchError,
+    JobNotFoundError,
+    JobFailedError,
+    TranscriptionNotReadyError,
+    BatchTimeoutError,
+)
+
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+class BatchClient:
+    """
+    Async client for SpeechCortex batch/post-call transcription.
+
+    This client provides a pure async interface for submitting transcription jobs,
+    polling for status, and retrieving results. It uses aiohttp for non-blocking
+    HTTP communication.
+
+    Supports async context manager for automatic resource cleanup.
+
+    Example:
+        >>> from speechcortex import SpeechCortexClient
+        >>>
+        >>> client = SpeechCortexClient(api_key="your_key")
+        >>> batch = client.transcribe.batch()
+        >>>
+        >>> async with batch:
+        ...     job = await batch.submit_job(
+        ...         presigned_url="https://example.com/audio.mp3",
+        ...         language="en-US"
+        ...     )
+        ...     result = await batch.wait_for_completion(job.job_id)
+        ...     print(result.transcription)
+    """
+
+    def __init__(self, config: SpeechCortexClientOptions) -> None:
+        """
+        Initialize the batch transcription client.
+
+        Args:
+            config: SpeechCortexClientOptions containing API key, URL, etc.
+
+        Raises:
+            SpeechCortexError: If config is None.
+            SpeechCortexApiKeyError: If API key is missing.
+        """
+        if config is None:
+            raise SpeechCortexError("Config is required")
+
+        if not config.api_key:
+            raise SpeechCortexApiKeyError("API key is required for batch transcription")
+
+        self._config = config
+        self._api_key = config.api_key
+
+        # Derive the REST base URL from the config URL
+        # Config URL may be wss:// for realtime; we need https:// for REST
+        raw_url = config.url.rstrip("/")
+        if raw_url.startswith("wss://"):
+            raw_url = raw_url.replace("wss://", "https://", 1)
+        elif raw_url.startswith("ws://"):
+            raw_url = raw_url.replace("ws://", "http://", 1)
+        self._base_url = raw_url
+
+        # Batch API path
+        self._batch_path = config.batch_path
+
+        # Session is lazily created
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._closed = False
+
+        logger.debug(
+            "BatchClient initialized (base_url=%s, batch_path=%s)",
+            self._base_url,
+            self._batch_path,
+        )
+
+    # ------------------------------------------------------------------
+    # Async context manager
+    # ------------------------------------------------------------------
+    async def __aenter__(self) -> BatchClient:
+        """Async context manager entry."""
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit with automatic cleanup."""
+        await self.close()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    async def submit_job(
+        self,
+        presigned_url: Optional[str] = None,
+        audio_file: Optional[Union[str, Path, BinaryIO, bytes]] = None,
+        config: Optional[TranscriptionConfig] = None,
+        **kwargs: Any,
+    ) -> JobDetails:
+        """
+        Submit a transcription job.
+
+        Either presigned_url or audio_file must be provided, but not both.
+
+        Args:
+            presigned_url: Presigned URL to audio file (S3, etc.)
+            audio_file: Audio file path, file-like object, or bytes.
+            config: TranscriptionConfig with transcription parameters.
+            **kwargs: Additional transcription parameters (language, model, etc.)
+
+        Returns:
+            JobDetails object with job_id and initial status.
+
+        Raises:
+            BatchError: If job submission fails.
+            SpeechCortexApiKeyError: If API key is invalid.
+            ValueError: If neither or both of presigned_url / audio_file are provided.
+        """
+        if presigned_url and audio_file:
+            raise ValueError("Cannot specify both presigned_url and audio_file")
+        if not presigned_url and not audio_file:
+            raise ValueError("Must provide either presigned_url or audio_file")
+
+        # Build transcription config
+        if config is None:
+            config = TranscriptionConfig()
+
+        # Override config with kwargs
+        for key, value in kwargs.items():
+            if hasattr(config, key):
+                setattr(config, key, value)
+
+        query_params = config.to_query_params()
+
+        try:
+            if presigned_url:
+                return await self._submit_presigned_url(presigned_url, query_params)
+            else:
+                return await self._submit_file_upload(audio_file, query_params)  # type: ignore[arg-type]
+        except SpeechCortexApiKeyError:
+            raise
+        except BatchError:
+            raise
+        except Exception as e:
+            raise BatchError(f"Failed to submit job: {e}") from e
+
+    async def get_status(self, job_id: Union[str, UUID]) -> TranscriptionStatus:
+        """
+        Get the current status of a transcription job.
+
+        Args:
+            job_id: Job identifier (UUID string or UUID object).
+
+        Returns:
+            TranscriptionStatus object with current status.
+
+        Raises:
+            JobNotFoundError: If job is not found.
+            BatchError: If request fails.
+        """
+        job_id_str = str(job_id)
+        url = f"{self._base_url}{self._batch_path}/status/{job_id_str}"
+
+        logger.debug("Getting status for job: %s", job_id_str)
+
+        try:
+            data = await self._request("GET", url)
+            return TranscriptionStatus.from_dict(data)
+        except JobNotFoundError:
+            raise
+        except Exception as e:
+            raise BatchError(f"Failed to get status: {e}") from e
+
+    async def get_transcription(self, job_id: Union[str, UUID]) -> TranscriptionResult:
+        """
+        Get the transcription result for a completed job.
+
+        Args:
+            job_id: Job identifier (UUID string or UUID object).
+
+        Returns:
+            TranscriptionResult object with transcription data.
+
+        Raises:
+            JobNotFoundError: If job is not found.
+            TranscriptionNotReadyError: If job is not completed yet.
+            JobFailedError: If job failed.
+            BatchError: If request fails.
+        """
+        job_id_str = str(job_id)
+        url = f"{self._base_url}{self._batch_path}/get_transcription/{job_id_str}"
+
+        logger.debug("Getting transcription for job: %s", job_id_str)
+
+        try:
+            data = await self._request("GET", url, allow_202=True)
+
+            # 202 means job is not ready yet (handled via status code in _request)
+            if data.get("_status_code") == 202:
+                status = data.get("status", "unknown")
+                raise TranscriptionNotReadyError(job_id_str, status)
+
+            # Check if job failed
+            if data.get("status", "").upper() == "FAILED":
+                error_msg = data.get("message", "Transcription failed")
+                raise JobFailedError(job_id_str, error_msg)
+
+            return TranscriptionResult.from_dict(data)
+
+        except (JobNotFoundError, TranscriptionNotReadyError, JobFailedError):
+            raise
+        except BatchError:
+            raise
+        except Exception as e:
+            raise BatchError(f"Failed to get transcription: {e}") from e
+
+    async def wait_for_completion(
+        self,
+        job_id: Union[str, UUID],
+        options: Optional[BatchOptions] = None,
+        **kwargs: Any,
+    ) -> TranscriptionResult:
+        """
+        Wait for a job to complete and return the result.
+
+        This method polls the job status at regular intervals until the job
+        completes or fails. Uses asyncio.wait_for for timeout handling.
+
+        Args:
+            job_id: Job identifier (UUID string or UUID object).
+            options: BatchOptions with polling configuration.
+            **kwargs: Additional options (polling_interval, timeout).
+
+        Returns:
+            TranscriptionResult object with transcription data.
+
+        Raises:
+            BatchTimeoutError: If job doesn't complete within timeout.
+            JobFailedError: If job fails.
+            BatchError: If request fails.
+        """
+        if options is None:
+            options = BatchOptions()
+
+        polling_interval = kwargs.get("polling_interval", options.polling_interval)
+        timeout = kwargs.get("timeout", options.timeout)
+        job_id_str = str(job_id)
+
+        logger.info(
+            "Waiting for job completion: %s (polling_interval=%.1fs, timeout=%s)",
+            job_id_str,
+            polling_interval,
+            timeout or "none",
+        )
+
+        try:
+            await asyncio.wait_for(
+                self._poll_job_status(job_id_str, polling_interval),
+                timeout=timeout,
+            )
+            return await self.get_transcription(job_id_str)
+
+        except asyncio.TimeoutError:
+            raise BatchTimeoutError(job_id_str, timeout) from None
+
+    async def transcribe(
+        self,
+        presigned_url: Optional[str] = None,
+        audio_file: Optional[Union[str, Path, BinaryIO, bytes]] = None,
+        config: Optional[TranscriptionConfig] = None,
+        options: Optional[BatchOptions] = None,
+        **kwargs: Any,
+    ) -> TranscriptionResult:
+        """
+        Convenience method: submit job and wait for completion.
+
+        Combines submit_job() and wait_for_completion() in a single call.
+
+        Args:
+            presigned_url: Presigned URL to audio file.
+            audio_file: Audio file path, file-like object, or bytes.
+            config: TranscriptionConfig with transcription parameters.
+            options: BatchOptions with polling configuration.
+            **kwargs: Additional parameters (language, model, polling_interval, timeout, etc.)
+
+        Returns:
+            TranscriptionResult object with transcription data.
+
+        Raises:
+            BatchError: If any step fails.
+        """
+        # Extract polling options from kwargs
+        polling_kwargs: Dict[str, Any] = {}
+        for key in ("polling_interval", "timeout"):
+            if key in kwargs:
+                polling_kwargs[key] = kwargs.pop(key)
+
+        # Submit job
+        job = await self.submit_job(
+            presigned_url=presigned_url,
+            audio_file=audio_file,
+            config=config,
+            **kwargs,
+        )
+
+        logger.debug("Waiting for job completion (job_id=%s)", job.job_id)
+
+        # Wait for completion
+        result = await self.wait_for_completion(
+            job.job_id,
+            options=options,
+            **polling_kwargs,
+        )
+
+        logger.info("Transcription completed successfully (job_id=%s)", job.job_id)
+        return result
+
+    async def close(self) -> None:
+        """
+        Close the HTTP session and cleanup resources.
+
+        Safe to call multiple times.
+        """
+        if self._session and not self._closed:
+            try:
+                await self._session.close()
+            except Exception:
+                pass  # best-effort cleanup
+            finally:
+                self._session = None
+                self._closed = True
+                logger.debug("BatchClient session closed")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    async def _ensure_session(self) -> None:
+        """Create aiohttp session lazily."""
+        if self._session is None and not self._closed:
+            timeout = aiohttp.ClientTimeout(total=300.0, connect=30.0)
+            self._session = aiohttp.ClientSession(timeout=timeout)
+            logger.debug("aiohttp session created")
+
+    def _get_headers(self) -> Dict[str, str]:
+        """Build common request headers."""
+        return {
+            "X-API-Key": self._api_key,
+            "User-Agent": (
+                f"speechcortex-sdk python/{sys.version_info.major}.{sys.version_info.minor}"
+            ),
+        }
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+        form_data: Optional[aiohttp.FormData] = None,
+        allow_202: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Send an HTTP request and return JSON response.
+
+        Args:
+            method: HTTP method (GET, POST).
+            url: Full URL.
+            params: Query parameters.
+            json_data: JSON body.
+            form_data: Multipart form data.
+            allow_202: If True, return 202 responses with _status_code marker.
+
+        Returns:
+            JSON response as dict.
+
+        Raises:
+            SpeechCortexApiKeyError: On 401.
+            JobNotFoundError: On 404.
+            BatchError: On other errors.
+        """
+        await self._ensure_session()
+        assert self._session is not None
+
+        headers = self._get_headers()
+
+        kwargs: Dict[str, Any] = {"headers": headers, "params": params}
+        if json_data is not None:
+            kwargs["json"] = json_data
+        if form_data is not None:
+            # Don't set Content-Type for multipart — aiohttp handles it
+            kwargs["data"] = form_data
+
+        logger.debug("HTTP %s %s", method, url)
+
+        try:
+            async with self._session.request(method, url, **kwargs) as response:
+                if response.status == 401:
+                    raise SpeechCortexApiKeyError("Invalid API key")
+
+                if response.status == 404:
+                    raise JobNotFoundError("unknown", "Resource not found")
+
+                if response.status == 202 and allow_202:
+                    data = await response.json()
+                    data["_status_code"] = 202
+                    return data
+
+                if response.status >= 400:
+                    error_text = await response.text()
+                    logger.error("HTTP %d: %s", response.status, error_text)
+                    raise BatchError(f"HTTP {response.status}: {error_text}")
+
+                return await response.json()
+
+        except (SpeechCortexApiKeyError, JobNotFoundError, BatchError):
+            raise
+        except aiohttp.ClientError as e:
+            raise BatchError(f"Request failed: {e}") from e
+        except asyncio.TimeoutError:
+            raise BatchError(f"Request timeout: {method} {url}") from None
+        except Exception as e:
+            raise BatchError(f"Unexpected error: {e}") from e
+
+    async def _submit_presigned_url(
+        self, presigned_url: str, query_params: Dict[str, Any]
+    ) -> JobDetails:
+        """Submit job with presigned URL."""
+        url = f"{self._base_url}{self._batch_path}/transcribe"
+
+        logger.debug("Submitting job with presigned URL: %s", url)
+
+        data = await self._request(
+            "POST",
+            url,
+            params=query_params,
+            json_data={"presigned_url": presigned_url},
+        )
+
+        if "job_id" not in data:
+            error_msg = data.get("message", "No job_id in response")
+            raise BatchError(f"Job submission failed: {error_msg}")
+
+        logger.info("Job submitted successfully: %s", data.get("job_id"))
+        return JobDetails.from_dict(data)
+
+    async def _submit_file_upload(
+        self,
+        audio_file: Union[str, Path, BinaryIO, bytes],
+        query_params: Dict[str, Any],
+    ) -> JobDetails:
+        """Submit job with file upload."""
+        url = f"{self._base_url}{self._batch_path}/transcribe/upload"
+
+        logger.debug("Submitting job with file upload: %s", url)
+
+        form = aiohttp.FormData()
+
+        if isinstance(audio_file, (str, Path)):
+            file_path = Path(audio_file)
+            if not file_path.exists():
+                raise FileNotFoundError(f"Audio file not found: {audio_file}")
+
+            async with aiofiles.open(file_path, "rb") as f:
+                file_content = await f.read()
+            form.add_field(
+                "audio_file",
+                file_content,
+                filename=file_path.name,
+                content_type="audio/mpeg",
+            )
+        elif isinstance(audio_file, bytes):
+            form.add_field(
+                "audio_file",
+                audio_file,
+                filename="audio.mp3",
+                content_type="audio/mpeg",
+            )
+        else:
+            # File-like object
+            content = audio_file.read()
+            filename = getattr(audio_file, "name", "audio.mp3")
+            if hasattr(filename, "split"):
+                filename = os.path.basename(filename)
+            form.add_field(
+                "audio_file",
+                content,
+                filename=filename,
+                content_type="audio/mpeg",
+            )
+
+        data = await self._request(
+            "POST",
+            url,
+            params=query_params,
+            form_data=form,
+        )
+
+        if "job_id" not in data:
+            error_msg = data.get("message", "No job_id in response")
+            raise BatchError(f"Job submission failed: {error_msg}")
+
+        logger.info("Job submitted successfully: %s", data.get("job_id"))
+        return JobDetails.from_dict(data)
+
+    async def _poll_job_status(self, job_id: str, polling_interval: float) -> None:
+        """Poll job status until completion or failure."""
+        logger.debug(
+            "Starting status polling for job_id=%s (interval=%.1fs)",
+            job_id,
+            polling_interval,
+        )
+        poll_count = 0
+
+        while True:
+            poll_count += 1
+            status = await self.get_status(job_id)
+            status_upper = status.status.upper()
+
+            logger.debug(
+                "Job %s status: %s (poll #%d)", job_id, status_upper, poll_count
+            )
+
+            if status_upper == "COMPLETED":
+                logger.info("Job completed (job_id=%s, polls=%d)", job_id, poll_count)
+                return
+
+            if status_upper == "FAILED":
+                error_msg = status.error_message or "Job failed"
+                raise JobFailedError(job_id, error_msg)
+
+            await asyncio.sleep(polling_interval)

speechcortex_sdk-0.1.dev2/speechcortex/clients/transcribe/batch/exceptions.py

@@ -0,0 +1,59 @@
+# Copyright 2024 SpeechCortex SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+"""
+Batch transcription specific exceptions.
+"""
+
+from ....errors import SpeechCortexError, SpeechCortexApiError, SpeechCortexTimeoutError
+
+
+class BatchError(SpeechCortexError):
+    """
+    Base exception for all batch transcription errors.
+    """
+    pass
+
+
+class JobNotFoundError(BatchError):
+    """
+    Exception raised when a transcription job is not found.
+    """
+    def __init__(self, job_id: str, message: str = None):
+        msg = message or f"Job not found: {job_id}"
+        super().__init__(msg)
+        self.job_id = job_id
+
+
+class JobFailedError(BatchError):
+    """
+    Exception raised when a transcription job fails.
+    """
+    def __init__(self, job_id: str, error_message: str = None):
+        msg = error_message or f"Job {job_id} failed"
+        super().__init__(msg)
+        self.job_id = job_id
+        self.error_message = error_message
+
+
+class TranscriptionNotReadyError(BatchError):
+    """
+    Exception raised when attempting to get transcription result before job is completed.
+    """
+    def __init__(self, job_id: str, status: str):
+        msg = f"Transcription not ready for job {job_id}. Current status: {status}"
+        super().__init__(msg)
+        self.job_id = job_id
+        self.status = status
+
+
+class BatchTimeoutError(SpeechCortexTimeoutError):
+    """
+    Exception raised when waiting for job completion times out.
+    """
+    def __init__(self, job_id: str, timeout: float):
+        msg = f"Job {job_id} did not complete within {timeout} seconds"
+        super().__init__(msg)
+        self.job_id = job_id
+        self.timeout = timeout

speechcortex_sdk-0.1.dev2/speechcortex/clients/transcribe/batch/options.py

@@ -0,0 +1,88 @@
+# Copyright 2024 SpeechCortex SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+"""
+Configuration options for batch transcription.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, Union
+import os
+
+
+@dataclass
+class TranscriptionConfig:
+    """
+    Configuration for transcription parameters.
+    
+    Attributes:
+        language: Language code (e.g., "en-US", "ENGLISH")
+        model: Transcription model to use (default: "batch-zeus")
+        diarize: Enable speaker diarization (default: False)
+        punctuate: Enable punctuation (default: True)
+        smart_format: Enable smart formatting (default: True)
+        channel: Number of audio channels (default: 2)
+        pci: PCI compliance flag (default: False)
+        extra_params: Additional parameters as dict or JSON string
+    """
+    language: str = "en-US"
+    model: str = "batch-zeus"
+    diarize: bool = False
+    punctuate: bool = False
+    smart_format: bool = False
+    channel: int = 2
+    pci: bool = False
+    extra_params: Optional[Union[Dict[str, Any], str]] = None
+    
+    def to_query_params(self) -> Dict[str, Any]:
+        """Convert config to query parameters for API request."""
+        params = {
+            "language": self.language,
+            "model": self.model,
+            "diarize": str(self.diarize).lower(),
+            "punctuate": str(self.punctuate).lower(),
+            "smart_format": str(self.smart_format).lower(),
+            "channel": str(self.channel),
+            "pci": str(self.pci).lower(),
+        }
+        
+        # Handle extra_params
+        if self.extra_params:
+            if isinstance(self.extra_params, str):
+                import json
+                try:
+                    extra = json.loads(self.extra_params)
+                    if isinstance(extra, dict):
+                        params.update(extra)
+                except json.JSONDecodeError:
+                    pass
+            elif isinstance(self.extra_params, dict):
+                params.update(self.extra_params)
+        
+        return params
+
+
+@dataclass
+class BatchOptions:
+    """
+    Options for batch transcription operations.
+    
+    Attributes:
+        polling_interval: Time in seconds between status checks (default: 3.0)
+        timeout: Maximum time in seconds to wait for completion (default: None, no timeout)
+        batch_path: API path for batch transcription endpoints (default: "/api/v1/transcription")
+    """
+    polling_interval: float = 3.0
+    timeout: Optional[float] = None
+    batch_path: str = field(default_factory=lambda: os.getenv(
+        "SPEECHCORTEX_BATCH_PATH", 
+        "/api/v1/transcription"
+    ))
+    
+    def __post_init__(self):
+        """Validate options after initialization."""
+        if self.polling_interval <= 0:
+            raise ValueError("polling_interval must be greater than 0")
+        if self.timeout is not None and self.timeout <= 0:
+            raise ValueError("timeout must be greater than 0")

speechcortex_sdk-0.1.dev2/speechcortex/clients/transcribe/batch/response.py

@@ -0,0 +1,149 @@
+# Copyright 2024 SpeechCortex SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+"""
+Response models for batch transcription.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional, Dict, Any
+from uuid import UUID
+
+
+@dataclass
+class JobDetails:
+    """
+    Details about a transcription job.
+    
+    Attributes:
+        job_id: Unique job identifier
+        status: Current job status (pending, downloading, uploading, queued, processing, completed, failed)
+        created_at: Job creation timestamp
+        updated_at: Last update timestamp (optional)
+        error_message: Error message if job failed (optional)
+    """
+    job_id: UUID
+    status: str
+    created_at: datetime
+    updated_at: Optional[datetime] = None
+    error_message: Optional[str] = None
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "JobDetails":
+        """Create JobDetails from API response dictionary."""
+        # Handle both UUID string and UUID object
+        job_id = data.get("job_id")
+        if isinstance(job_id, str):
+            job_id = UUID(job_id)
+        elif not isinstance(job_id, UUID):
+            raise ValueError(f"Invalid job_id format: {job_id}")
+        
+        # Parse timestamps
+        created_at = data.get("created_at")
+        if isinstance(created_at, str):
+            # Handle ISO format with or without timezone
+            created_at = created_at.replace("Z", "+00:00")
+            created_at = datetime.fromisoformat(created_at)
+        elif not isinstance(created_at, datetime):
+            created_at = datetime.now()
+        
+        updated_at = data.get("updated_at")
+        if updated_at:
+            if isinstance(updated_at, str):
+                updated_at = updated_at.replace("Z", "+00:00")
+                updated_at = datetime.fromisoformat(updated_at)
+            elif not isinstance(updated_at, datetime):
+                updated_at = None
+        
+        return cls(
+            job_id=job_id,
+            status=data.get("status", "pending"),
+            created_at=created_at,
+            updated_at=updated_at,
+            error_message=data.get("error_message"),
+        )
+
+
+@dataclass
+class TranscriptionStatus:
+    """
+    Status information for a transcription job.
+    
+    Attributes:
+        job_id: Unique job identifier
+        status: Current job status
+        created_at: Job creation timestamp
+        updated_at: Last update timestamp (optional)
+        error_message: Error message if job failed (optional)
+    """
+    job_id: UUID
+    status: str
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    error_message: Optional[str] = None
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TranscriptionStatus":
+        """Create TranscriptionStatus from API response dictionary."""
+        job_id = data.get("job_id")
+        if isinstance(job_id, str):
+            job_id = UUID(job_id)
+        elif not isinstance(job_id, UUID):
+            raise ValueError(f"Invalid job_id format: {job_id}")
+        
+        created_at = None
+        if data.get("created_at"):
+            created_at_str = data["created_at"]
+            if isinstance(created_at_str, str):
+                created_at_str = created_at_str.replace("Z", "+00:00")
+                created_at = datetime.fromisoformat(created_at_str)
+        
+        updated_at = None
+        if data.get("updated_at"):
+            updated_at_str = data["updated_at"]
+            if isinstance(updated_at_str, str):
+                updated_at_str = updated_at_str.replace("Z", "+00:00")
+                updated_at = datetime.fromisoformat(updated_at_str)
+        
+        return cls(
+            job_id=job_id,
+            status=data.get("status", "pending"),
+            created_at=created_at,
+            updated_at=updated_at,
+            error_message=data.get("error_message"),
+        )
+
+
+@dataclass
+class TranscriptionResult:
+    """
+    Transcription result for a completed job.
+    
+    Attributes:
+        job_id: Unique job identifier
+        status: Job status
+        transcription: Transcription data (dict) - only present if completed
+        message: Status message
+    """
+    job_id: UUID
+    status: str
+    transcription: Optional[Dict[str, Any]] = None
+    message: Optional[str] = None
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TranscriptionResult":
+        """Create TranscriptionResult from API response dictionary."""
+        job_id = data.get("job_id")
+        if isinstance(job_id, str):
+            job_id = UUID(job_id)
+        elif not isinstance(job_id, UUID):
+            raise ValueError(f"Invalid job_id format: {job_id}")
+        
+        return cls(
+            job_id=job_id,
+            status=data.get("status", "pending"),
+            transcription=data.get("transcription"),
+            message=data.get("message"),
+        )

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/speechcortex/options.py

@@ -15,7 +15,7 @@ from .errors import SpeechCortexApiKeyError
 try:
     from . import __version__
 except ImportError:
-    __version__ = "0.1.0"
+    __version__ = "0.1.1"
 
 
 class SpeechCortexClientOptions:  # pylint: disable=too-many-instance-attributes
@@ -44,6 +44,7 @@ class SpeechCortexClientOptions:  # pylint: disable=too-many-instance-attributes
         headers: Optional[Dict] = None,
         options: Optional[Dict] = None,
         realtime_path: str = "/transcribe/realtime",
+        batch_path: str = "/api/v1/transcription",
     ):
         self._logger = verboselogs.VerboseLogger(__name__)
         self._logger.addHandler(logging.StreamHandler())
@@ -114,6 +115,7 @@ class SpeechCortexClientOptions:  # pylint: disable=too-many-instance-attributes
                     break
 
         self.options = options
+        self.batch_path = batch_path
 
         # Normalize realtime path (ensure starts with '/'; strip trailing '?')
         if realtime_path is None or realtime_path == "":

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2/speechcortex_sdk.egg-info}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: speechcortex-sdk
-Version: 0.1.0
+Version: 0.1.dev2
 Summary: The official Python SDK for SpeechCortex ASR platform.
-Home-page: https://github.com/skanda-observeai/zeus-sdk-py
+Home-page: https://github.com/speechcortex/speechcortex-sdk
 Author: SpeechCortex Team
 Author-email: SpeechCortex Team <team@speechcortex.com>
 License: MIT
-Project-URL: Homepage, https://github.com/skanda-observeai/zeus-sdk-py
-Project-URL: Bug Tracker, https://github.com/skanda-observeai/zeus-sdk-py/issues
-Project-URL: Source Code, https://github.com/skanda-observeai/zeus-sdk-py
-Project-URL: Documentation, https://github.com/skanda-observeai/zeus-sdk-py#readme
+Project-URL: Homepage, https://github.com/speechcortex/speechcortex-sdk
+Project-URL: Bug Tracker, https://github.com/speechcortex/speechcortex-sdk/issues
+Project-URL: Source Code, https://github.com/speechcortex/speechcortex-sdk
+Project-URL: Documentation, https://github.com/speechcortex/speechcortex-sdk#readme
 Keywords: speechcortex,asr,speech-to-text,speech recognition
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -35,7 +35,7 @@ Dynamic: requires-python
 
 # SpeechCortex Python SDK
 
-[![CI](https://github.com/skanda-observeai/zeus-sdk-py/actions/workflows/ci.yml/badge.svg)](https://github.com/skanda-observeai/zeus-sdk-py/actions/workflows/ci.yml)
+[![CI](https://github.com/speechcortex/speechcortex-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/speechcortex/speechcortex-sdk/actions/workflows/ci.yml)
 [![PyPI version](https://badge.fury.io/py/speechcortex-sdk.svg)](https://badge.fury.io/py/speechcortex-sdk)
 [![Python Versions](https://img.shields.io/pypi/pyversions/speechcortex-sdk.svg)](https://pypi.org/project/speechcortex-sdk/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -57,7 +57,7 @@ Official Python SDK for SpeechCortex ASR (Automatic Speech Recognition) platform
 ## Installation
 
 ```bash
-pip install "git+https://github.com/skanda-observeai/zeus-sdk-py.git@package_init"
+pip install "git+https://github.com/speechcortex/speechcortex-sdk.git@package_init"
 ```
 
 ```bash

{speechcortex_sdk-0.1.0 → speechcortex_sdk-0.1.dev2}/speechcortex_sdk.egg-info/SOURCES.txt

@@ -17,6 +17,11 @@ speechcortex/audio/microphone/microphone.py
 speechcortex/clients/__init__.py
 speechcortex/clients/transcribe/__init__.py
 speechcortex/clients/transcribe/enums.py
+speechcortex/clients/transcribe/batch/__init__.py
+speechcortex/clients/transcribe/batch/client.py
+speechcortex/clients/transcribe/batch/exceptions.py
+speechcortex/clients/transcribe/batch/options.py
+speechcortex/clients/transcribe/batch/response.py
 speechcortex/clients/transcribe/realtime/__init__.py
 speechcortex/clients/transcribe/realtime/client.py
 speechcortex/clients/transcribe/realtime/options.py