omniai-kit 1.0.0__py3-none-any.whl

omniai/client.py

@@ -0,0 +1,316 @@
+"""OmniAI Python Client SDK.
+
+Provides synchronous and asynchronous clients with nested resource namespaces
+and top-level convenience methods for chat, streaming, background tasks, and LiveKit sessions.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import (
+    Any,
+    AsyncGenerator,
+    Dict,
+    Generator,
+    List,
+    Mapping,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+)
+import httpx
+
+from omniai._base import AsyncBaseClient, BaseClient
+from omniai._constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    SUPPORTED_PROVIDERS,
+)
+from omniai.resources.chat import AsyncChatResource, ChatResource
+from omniai.resources.livekit import AsyncLiveKitResource, LiveKitResource
+from omniai.resources.models import AsyncModelsResource, ModelsResource
+from omniai.resources.tasks import AsyncTasksResource, TasksResource
+from omniai.types.livekit import LiveSessionInfo
+from omniai.types.models import ModelInfo, ModelList
+from omniai.types.tasks import AsyncTaskJob, TaskJob
+
+logger = logging.getLogger("omniai.client")
+
+T = TypeVar("T")
+
+
+class OmniaiClient(BaseClient):
+    """
+    Synchronous client for OmniAI.
+
+    Usage:
+        >>> from omniai import OmniaiClient
+        >>> client = OmniaiClient()
+        >>> response = client.chat(model="gemini:gemini-2.5-flash", prompt="Hello!")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ):
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            headers=headers,
+            http_client=http_client,
+        )
+        self.chat = ChatResource(self)
+        self.models = ModelsResource(self)
+        self.tasks = TasksResource(self)
+        self.livekit = LiveKitResource(self)
+
+    def chat(
+        self,
+        model: str,
+        prompt: Optional[str] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+        response_model: Optional[Type[T]] = None,
+        tools: Optional[List[Any]] = None,
+        output_format: Optional[Union[str, Dict[str, Any]]] = None,
+        system_instruction: Optional[str] = None,
+        temperature: float = 0.1,
+        max_tokens: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> Union[str, T]:
+        """Convenience method to execute a chat completion."""
+        return self.chat.completions.create(
+            model=model,
+            prompt=prompt,
+            messages=messages,
+            response_model=response_model,
+            tools=tools,
+            output_format=output_format,
+            system_instruction=system_instruction,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            timeout=timeout,
+        )
+
+    def stream(
+        self,
+        model: str,
+        prompt: Optional[str] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+        system_instruction: Optional[str] = None,
+        temperature: float = 0.1,
+        max_tokens: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> Generator[str, None, None]:
+        """Convenience method to stream a chat completion chunk-by-chunk."""
+        return self.chat.completions.stream(
+            model=model,
+            prompt=prompt,
+            messages=messages,
+            system_instruction=system_instruction,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            timeout=timeout,
+        )
+
+    def submit_task(
+        self,
+        model: str,
+        prompt: Optional[str] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+        response_model: Optional[Type[T]] = None,
+        tools: Optional[List[Any]] = None,
+        output_format: Optional[Union[str, Dict[str, Any]]] = None,
+        system_instruction: Optional[str] = None,
+        temperature: float = 0.1,
+        max_tokens: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> TaskJob[T]:
+        """Submits a background task to the OmniAI Celery queue."""
+        return self.tasks.submit(
+            model=model,
+            prompt=prompt,
+            messages=messages,
+            response_model=response_model,
+            tools=tools,
+            output_format=output_format,
+            system_instruction=system_instruction,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            timeout=timeout,
+        )
+
+    def create_live_session(
+        self,
+        model: str = "gemini:gemini-2.5-flash",
+        voice: str = "Aoede",
+        video_input: bool = False,
+        timeout: Optional[float] = None,
+    ) -> LiveSessionInfo:
+        """Requests room and participant credentials for a LiveKit WebRTC session."""
+        return self.livekit.create_session(
+            model=model,
+            voice=voice,
+            video_input=video_input,
+            timeout=timeout,
+        )
+
+    def list_models(self, timeout: Optional[float] = None) -> ModelList:
+        """Lists available AI models."""
+        return self.models.list(timeout=timeout)
+
+
+class AsyncOmniaiClient(AsyncBaseClient):
+    """
+    Asynchronous client for OmniAI.
+
+    Usage:
+        >>> import asyncio
+        >>> from omniai import AsyncOmniaiClient
+        >>> async def main():
+        ...     async with AsyncOmniaiClient() as client:
+        ...         res = await client.chat(model="gemini:gemini-2.5-flash", prompt="Hello!")
+        ...         print(res)
+        >>> asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ):
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            headers=headers,
+            http_client=http_client,
+        )
+        self.chat = AsyncChatResource(self)
+        self.models = AsyncModelsResource(self)
+        self.tasks = AsyncTasksResource(self)
+        self.livekit = AsyncLiveKitResource(self)
+
+    async def chat(
+        self,
+        model: str,
+        prompt: Optional[str] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+        response_model: Optional[Type[T]] = None,
+        tools: Optional[List[Any]] = None,
+        output_format: Optional[Union[str, Dict[str, Any]]] = None,
+        system_instruction: Optional[str] = None,
+        temperature: float = 0.1,
+        max_tokens: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> Union[str, T]:
+        """Convenience method to execute an async chat completion."""
+        return await self.chat.completions.create(
+            model=model,
+            prompt=prompt,
+            messages=messages,
+            response_model=response_model,
+            tools=tools,
+            output_format=output_format,
+            system_instruction=system_instruction,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            timeout=timeout,
+        )
+
+    async def stream(
+        self,
+        model: str,
+        prompt: Optional[str] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+        system_instruction: Optional[str] = None,
+        temperature: float = 0.1,
+        max_tokens: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> AsyncGenerator[str, None]:
+        """Convenience method to stream an async chat completion chunk-by-chunk."""
+        async for chunk in self.chat.completions.stream(
+            model=model,
+            prompt=prompt,
+            messages=messages,
+            system_instruction=system_instruction,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            timeout=timeout,
+        ):
+            yield chunk
+
+    async def submit_task(
+        self,
+        model: str,
+        prompt: Optional[str] = None,
+        messages: Optional[List[Dict[str, str]]] = None,
+        response_model: Optional[Type[T]] = None,
+        tools: Optional[List[Any]] = None,
+        output_format: Optional[Union[str, Dict[str, Any]]] = None,
+        system_instruction: Optional[str] = None,
+        temperature: float = 0.1,
+        max_tokens: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> AsyncTaskJob[T]:
+        """Submits an async background task to the OmniAI Celery queue."""
+        return await self.tasks.submit(
+            model=model,
+            prompt=prompt,
+            messages=messages,
+            response_model=response_model,
+            tools=tools,
+            output_format=output_format,
+            system_instruction=system_instruction,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            timeout=timeout,
+        )
+
+    async def create_live_session(
+        self,
+        model: str = "gemini:gemini-2.5-flash",
+        voice: str = "Aoede",
+        video_input: bool = False,
+        timeout: Optional[float] = None,
+    ) -> LiveSessionInfo:
+        """Requests room and participant credentials for a LiveKit WebRTC session asynchronously."""
+        return await self.livekit.create_session(
+            model=model,
+            voice=voice,
+            video_input=video_input,
+            timeout=timeout,
+        )
+
+    async def list_models(self, timeout: Optional[float] = None) -> ModelList:
+        """Lists available AI models asynchronously."""
+        return await self.models.list(timeout=timeout)
+
+
+# Aliases for brand and convenience consistency
+OmniAIClient = OmniaiClient
+AsyncOmniAIClient = AsyncOmniaiClient
+OmniClient = OmniaiClient
+AsyncOmniClient = AsyncOmniaiClient
+
+__all__ = [
+    "OmniaiClient",
+    "AsyncOmniaiClient",
+    "OmniAIClient",
+    "AsyncOmniAIClient",
+    "OmniClient",
+    "AsyncOmniClient",
+]

omniai/exceptions.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class OmniaiError(Exception):
+    """Base exception for all errors raised by the OmniAI Python SDK."""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        return self.message
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} message={self.message!r}>"
+
+
+class OmniaiAuthError(OmniaiError):
+    """Raised when authentication or authorization fails (HTTP 401 / 403)."""
+    pass
+
+
+class OmniaiPaymentRequiredError(OmniaiError):
+    """Raised when API credit balance is exhausted or payment is required (HTTP 402)."""
+    pass
+
+
+class OmniaiNotFoundError(OmniaiError):
+    """Raised when a requested resource, model, or task is not found (HTTP 404)."""
+    pass
+
+
+class OmniaiRateLimitError(OmniaiError):
+    """Raised when request rate limits or concurrency quotas are exceeded (HTTP 429)."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[float] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, details)
+        self.retry_after = retry_after
+
+
+class OmniaiTimeoutError(OmniaiError):
+    """Raised when a network request, streaming chunk, or task polling times out."""
+    pass
+
+
+class OmniaiConnectionError(OmniaiError):
+    """Raised when network connectivity fails (DNS resolution, connection refused, broken pipe)."""
+    pass
+
+
+class OmniaiExecutionError(OmniaiError):
+    """Raised when the OmniAI gateway or upstream LLM provider encounters an execution error (HTTP 5xx / provider failure)."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 500,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, details)
+        self.status_code = status_code
+
+
+class OmniaiValidationError(OmniaiError):
+    """Raised when structured outputs or response_model validation fails against expected schema."""
+
+    def __init__(
+        self,
+        message: str,
+        raw_output: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, details)
+        self.raw_output = raw_output
+
+
+class OmniaiUnsupportedProviderError(OmniaiError):
+    """
+    Raised when an unsupported provider is requested.
+    The OmniAI SDK strictly supports: 'openai', 'gemini', 'anthropic', and 'vllm'.
+    """
+    pass
+
+
+# Standard OpenAI-style & OmniAI naming aliases
+OmniaiAPIError = OmniaiExecutionError
+OmniaiAuthenticationError = OmniaiAuthError
+OmniaiPermissionDeniedError = OmniaiAuthError
+OmniaiBadRequestError = OmniaiValidationError
+
+# Aliases with OmniAI / Omni casing
+OmniAIError = OmniaiError
+OmniAIAuthError = OmniaiAuthError
+OmniAIAuthenticationError = OmniaiAuthError
+OmniAIAPIError = OmniaiAPIError
+OmniAIRateLimitError = OmniaiRateLimitError
+OmniAITimeoutError = OmniaiTimeoutError
+OmniAIConnectionError = OmniaiConnectionError
+OmniAIValidationError = OmniaiValidationError
+
+OmniError = OmniaiError
+OmniAuthError = OmniaiAuthError
+OmniExecutionError = OmniaiExecutionError
+OmniTimeoutError = OmniaiTimeoutError
+OmniRateLimitError = OmniaiRateLimitError

omniai/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 compliance

omniai/resources/__init__.py

@@ -0,0 +1,26 @@
+"""Resource modules for the OmniAI Python SDK."""
+
+from omniai.resources.chat import (
+    ChatResource,
+    AsyncChatResource,
+    CompletionsResource,
+    AsyncCompletionsResource,
+)
+from omniai.resources.models import ModelsResource, AsyncModelsResource
+from omniai.resources.tasks import TasksResource, AsyncTasksResource
+from omniai.resources.livekit import LiveKitResource, AsyncLiveKitResource
+from omniai.resources.router import RouterEngine
+
+__all__ = [
+    "ChatResource",
+    "AsyncChatResource",
+    "CompletionsResource",
+    "AsyncCompletionsResource",
+    "ModelsResource",
+    "AsyncModelsResource",
+    "TasksResource",
+    "AsyncTasksResource",
+    "LiveKitResource",
+    "AsyncLiveKitResource",
+    "RouterEngine",
+]