livellm 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

livellm/livellm.py

@@ -1,7 +1,9 @@
 """LiveLLM Client - Python client for the LiveLLM Proxy and Realtime APIs."""
+import asyncio
 import httpx
 import json
-from typing import List, Optional, AsyncIterator, Union
+import warnings
+from typing import List, Optional, AsyncIterator, Union, overload
 from .models.common import Settings, SuccessResponse
 from .models.agent.agent import AgentRequest, AgentResponse
 from .models.audio.speak import SpeakRequest
@@ -119,15 +121,16 @@ class LivellmClient:
             error_response = error_response.decode("utf-8")
             raise Exception(f"Failed to post to {endpoint}: {error_response}")
         if expect_stream:
-            async def stream_response() -> AsyncIterator[Union[dict, bytes]]:
+            async def json_stream_response() -> AsyncIterator[dict]:
                 async for chunk in response.aiter_lines():
-                    if expect_json:
-                        chunk = chunk.strip()
-                        if not chunk:
-                            continue
-                        yield json.loads(chunk)
-                    else:
-                        yield chunk
+                    chunk = chunk.strip()
+                    if not chunk:
+                        continue
+                    yield json.loads(chunk)
+            async def bytes_stream_response() -> AsyncIterator[bytes]:
+                async for chunk in response.aiter_bytes():
+                    yield chunk
+            stream_response = json_stream_response if expect_json else bytes_stream_response
             return stream_response()
         else:
             if expect_json:
@@ -164,6 +167,7 @@ class LivellmClient:
         Should be called when you're done using the client.
         """
         for config in self.settings:
+            config: Settings = config
             await self.delete_config(config.uid)
         await self.client.aclose()
     
@@ -175,43 +179,473 @@ class LivellmClient:
         """Async context manager exit."""
         await self.cleanup()
     
+    def __del__(self):
+        """
+        Destructor to clean up resources when the client is garbage collected.
+        This will close the HTTP client and attempt to delete configs if cleanup wasn't called.
+        Note: It's recommended to use the async context manager or call cleanup() explicitly.
+        """
+        # Warn user if cleanup wasn't called
+        if self.settings:
+            warnings.warn(
+                "LivellmClient is being garbage collected without explicit cleanup. "
+                "Provider configs may not be deleted from the server. "
+                "Consider using 'async with' or calling 'await client.cleanup()' explicitly.",
+                ResourceWarning,
+                stacklevel=2
+            )
+        
+        # Close the httpx client synchronously
+        # httpx.AsyncClient stores a sync Transport that needs cleanup
+        try:
+            with httpx.Client(base_url=self.base_url) as client:
+                for config in self.settings:
+                    config: Settings = config
+                    client.delete("providers/config/{config.uid}", headers=self.headers)
+        except Exception:
+            # Silently fail - we're in a destructor
+            pass
 
+    @overload
+    async def agent_run(
+        self,
+        request: Union[AgentRequest, AgentFallbackRequest],
+    ) -> AgentResponse:
+        ...
+    
+    @overload
+    async def agent_run(
+        self,
+        *,
+        provider_uid: str,
+        model: str,
+        messages: list,
+        tools: Optional[list] = None,
+        **kwargs
+    ) -> AgentResponse:
+        ...
+    
     async def agent_run(
         self,
-        request: Union[AgentRequest, AgentFallbackRequest]
+        request: Optional[Union[AgentRequest, AgentFallbackRequest]] = None,
+        *,
+        provider_uid: Optional[str] = None,
+        model: Optional[str] = None,
+        messages: Optional[list] = None,
+        tools: Optional[list] = None,
+        **kwargs
     ) -> AgentResponse:
-        result = await self.post(request.model_dump(), "agent/run", expect_json=True)
+        """
+        Run an agent request.
+        
+        Can be called in two ways:
+        
+        1. With a request object:
+           await client.agent_run(AgentRequest(...))
+           await client.agent_run(AgentFallbackRequest(...))
+           
+        2. With individual parameters (keyword arguments):
+           await client.agent_run(
+               provider_uid="...",
+               model="gpt-4",
+               messages=[TextMessage(...)],
+               tools=[]
+           )
+        
+        Args:
+            request: An AgentRequest or AgentFallbackRequest object
+            provider_uid: The provider UID string
+            model: The model to use
+            messages: List of messages
+            tools: Optional list of tools
+            gen_config: Optional generation configuration
+            
+        Returns:
+            AgentResponse with the agent's output
+        """
+        # Check if first argument is a request object
+        if request is not None:
+            if not isinstance(request, (AgentRequest, AgentFallbackRequest)):
+                raise TypeError(
+                    f"First positional argument must be AgentRequest or AgentFallbackRequest, got {type(request)}"
+                )
+            result = await self.post(request.model_dump(), "agent/run", expect_json=True)
+            return AgentResponse(**result)
+        
+        # Otherwise, use keyword arguments
+        if provider_uid is None or model is None or messages is None:
+            raise ValueError(
+                "provider_uid, model, and messages are required. "
+                "Alternatively, pass an AgentRequest object as the first positional argument."
+            )
+        
+        agent_request = AgentRequest(
+            provider_uid=provider_uid,
+            model=model,
+            messages=messages,
+            tools=tools or [],
+            gen_config=kwargs or None
+        )
+        result = await self.post(agent_request.model_dump(), "agent/run", expect_json=True)
         return AgentResponse(**result)
     
+    @overload
+    def agent_run_stream(
+        self,
+        request: Union[AgentRequest, AgentFallbackRequest],
+    ) -> AsyncIterator[AgentResponse]:
+        ...
+    
+    @overload
+    def agent_run_stream(
+        self,
+        *,
+        provider_uid: str,
+        model: str,
+        messages: list,
+        tools: Optional[list] = None,
+        **kwargs
+    ) -> AsyncIterator[AgentResponse]:
+        ...
+    
     async def agent_run_stream(
         self,
-        request: Union[AgentRequest, AgentFallbackRequest]
+        request: Optional[Union[AgentRequest, AgentFallbackRequest]] = None,
+        *,
+        provider_uid: Optional[str] = None,
+        model: Optional[str] = None,
+        messages: Optional[list] = None,
+        tools: Optional[list] = None,
+        **kwargs
     ) -> AsyncIterator[AgentResponse]:
-        stream = await self.post(request.model_dump(), "agent/run_stream", expect_stream=True, expect_json=True)
-        async for chunk in stream:
-            yield AgentResponse(**chunk)
+        """
+        Run an agent request with streaming response.
+        
+        Can be called in two ways:
+        
+        1. With a request object:
+           async for chunk in client.agent_run_stream(AgentRequest(...)):
+               ...
+           async for chunk in client.agent_run_stream(AgentFallbackRequest(...)):
+               ...
+           
+        2. With individual parameters (keyword arguments):
+           async for chunk in client.agent_run_stream(
+               provider_uid="...",
+               model="gpt-4",
+               messages=[TextMessage(...)],
+               tools=[]
+           ):
+               ...
+        
+        Args:
+            request: An AgentRequest or AgentFallbackRequest object
+            provider_uid: The provider UID string
+            model: The model to use
+            messages: List of messages
+            tools: Optional list of tools
+            gen_config: Optional generation configuration
+            
+        Returns:
+            AsyncIterator of AgentResponse chunks
+        """
+        # Check if first argument is a request object
+        if request is not None:
+            if not isinstance(request, (AgentRequest, AgentFallbackRequest)):
+                raise TypeError(
+                    f"First positional argument must be AgentRequest or AgentFallbackRequest, got {type(request)}"
+                )
+            stream = await self.post(request.model_dump(), "agent/run_stream", expect_stream=True, expect_json=True)
+            async for chunk in stream:
+                yield AgentResponse(**chunk)
+        else:
+            # Otherwise, use keyword arguments
+            if provider_uid is None or model is None or messages is None:
+                raise ValueError(
+                    "provider_uid, model, and messages are required. "
+                    "Alternatively, pass an AgentRequest object as the first positional argument."
+                )
+            
+            agent_request = AgentRequest(
+                provider_uid=provider_uid,
+                model=model,
+                messages=messages,
+                tools=tools or [],
+                gen_config=kwargs or None
+            )
+            stream = await self.post(agent_request.model_dump(), "agent/run_stream", expect_stream=True, expect_json=True)
+            async for chunk in stream:
+                yield AgentResponse(**chunk)
+    
+    @overload
+    async def speak(
+        self,
+        request: Union[SpeakRequest, AudioFallbackRequest],
+    ) -> bytes:
+        ...
+    
+    @overload
+    async def speak(
+        self,
+        *,
+        provider_uid: str,
+        model: str,
+        text: str,
+        voice: str,
+        mime_type: str,
+        sample_rate: int,
+        chunk_size: int = 20,
+        **kwargs
+    ) -> bytes:
+        ...
     
     async def speak(
         self,
-        request: Union[SpeakRequest, AudioFallbackRequest]
+        request: Optional[Union[SpeakRequest, AudioFallbackRequest]] = None,
+        *,
+        provider_uid: Optional[str] = None,
+        model: Optional[str] = None,
+        text: Optional[str] = None,
+        voice: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        sample_rate: Optional[int] = None,
+        chunk_size: int = 20,
+        **kwargs
     ) -> bytes:
-        return await self.post(request.model_dump(), "audio/speak", expect_json=False)
+        """
+        Generate speech from text.
+        
+        Can be called in two ways:
+        
+        1. With a request object:
+           await client.speak(SpeakRequest(...))
+           await client.speak(AudioFallbackRequest(...))
+           
+        2. With individual parameters (keyword arguments):
+           await client.speak(
+               provider_uid="...",
+               model="tts-1",
+               text="Hello, world!",
+               voice="alloy",
+               mime_type="audio/pcm",
+               sample_rate=24000
+           )
+        
+        Args:
+            request: A SpeakRequest or AudioFallbackRequest object
+            provider_uid: The provider UID string
+            model: The model to use for TTS
+            text: The text to convert to speech
+            voice: The voice to use
+            mime_type: The MIME type of the output audio
+            sample_rate: The sample rate of the output audio
+            chunk_size: Chunk size in milliseconds (default: 20ms)
+            gen_config: Optional generation configuration
+            
+        Returns:
+            Audio data as bytes
+        """
+        # Check if first argument is a request object
+        if request is not None:
+            if not isinstance(request, (SpeakRequest, AudioFallbackRequest)):
+                raise TypeError(
+                    f"First positional argument must be SpeakRequest or AudioFallbackRequest, got {type(request)}"
+                )
+            return await self.post(request.model_dump(), "audio/speak", expect_json=False)
+        
+        # Otherwise, use keyword arguments
+        if provider_uid is None or model is None or text is None or voice is None or mime_type is None or sample_rate is None:
+            raise ValueError(
+                "provider_uid, model, text, voice, mime_type, and sample_rate are required. "
+                "Alternatively, pass a SpeakRequest object as the first positional argument."
+            )
+        
+        speak_request = SpeakRequest(
+            provider_uid=provider_uid,
+            model=model,
+            text=text,
+            voice=voice,
+            mime_type=mime_type,
+            sample_rate=sample_rate,
+            chunk_size=chunk_size,
+            gen_config=kwargs or None
+        )
+        return await self.post(speak_request.model_dump(), "audio/speak", expect_json=False)
+    
+    @overload
+    def speak_stream(
+        self,
+        request: Union[SpeakRequest, AudioFallbackRequest],
+    ) -> AsyncIterator[bytes]:
+        ...
+    
+    @overload
+    def speak_stream(
+        self,
+        *,
+        provider_uid: str,
+        model: str,
+        text: str,
+        voice: str,
+        mime_type: str,
+        sample_rate: int,
+        chunk_size: int = 20,
+        **kwargs
+    ) -> AsyncIterator[bytes]:
+        ...
     
     async def speak_stream(
         self,
-        request: Union[SpeakRequest, AudioFallbackRequest]
+        request: Optional[Union[SpeakRequest, AudioFallbackRequest]] = None,
+        *,
+        provider_uid: Optional[str] = None,
+        model: Optional[str] = None,
+        text: Optional[str] = None,
+        voice: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        sample_rate: Optional[int] = None,
+        chunk_size: int = 20,
+        **kwargs
     ) -> AsyncIterator[bytes]:
-        return await self.post(request.model_dump(), "audio/speak_stream", expect_stream=True, expect_json=False)
+        """
+        Generate speech from text with streaming response.
+        
+        Can be called in two ways:
+        
+        1. With a request object:
+           async for chunk in client.speak_stream(SpeakRequest(...)):
+               ...
+           async for chunk in client.speak_stream(AudioFallbackRequest(...)):
+               ...
+           
+        2. With individual parameters (keyword arguments):
+           async for chunk in client.speak_stream(
+               provider_uid="...",
+               model="tts-1",
+               text="Hello, world!",
+               voice="alloy",
+               mime_type="audio/pcm",
+               sample_rate=24000
+           ):
+               ...
+        
+        Args:
+            request: A SpeakRequest or AudioFallbackRequest object
+            provider_uid: The provider UID string
+            model: The model to use for TTS
+            text: The text to convert to speech
+            voice: The voice to use
+            mime_type: The MIME type of the output audio
+            sample_rate: The sample rate of the output audio
+            chunk_size: Chunk size in milliseconds (default: 20ms)
+            gen_config: Optional generation configuration
+            
+        Returns:
+            AsyncIterator of audio data chunks as bytes
+        """
+        # Check if first argument is a request object
+        if request is not None:
+            if not isinstance(request, (SpeakRequest, AudioFallbackRequest)):
+                raise TypeError(
+                    f"First positional argument must be SpeakRequest or AudioFallbackRequest, got {type(request)}"
+                )
+            speak_stream = await self.post(request.model_dump(), "audio/speak_stream", expect_stream=True, expect_json=False)
+            async for chunk in speak_stream:
+                yield chunk
+        else:
+            # Otherwise, use keyword arguments
+            if provider_uid is None or model is None or text is None or voice is None or mime_type is None or sample_rate is None:
+                raise ValueError(
+                    "provider_uid, model, text, voice, mime_type, and sample_rate are required. "
+                    "Alternatively, pass a SpeakRequest object as the first positional argument."
+                )
+            
+            speak_request = SpeakRequest(
+                provider_uid=provider_uid,
+                model=model,
+                text=text,
+                voice=voice,
+                mime_type=mime_type,
+                sample_rate=sample_rate,
+                chunk_size=chunk_size,
+                gen_config=kwargs or None
+            )
+            speak_stream = await self.post(speak_request.model_dump(), "audio/speak_stream", expect_stream=True, expect_json=False)
+            async for chunk in speak_stream:
+                yield chunk
     
-
+    @overload
+    async def transcribe(
+        self,
+        request: Union[TranscribeRequest, TranscribeFallbackRequest],
+    ) -> TranscribeResponse:
+        ...
+    
+    @overload
     async def transcribe(
         self,
+        *,
         provider_uid: str,
         file: File,
         model: str,
         language: Optional[str] = None,
-        gen_config: Optional[dict] = None
+        **kwargs
     ) -> TranscribeResponse:
+        ...
+        
+    async def transcribe(
+        self,
+        request: Optional[Union[TranscribeRequest, TranscribeFallbackRequest]] = None,
+        *,
+        provider_uid: Optional[str] = None,
+        file: Optional[File] = None,
+        model: Optional[str] = None,
+        language: Optional[str] = None,
+        **kwargs
+    ) -> TranscribeResponse:
+        """
+        Transcribe audio to text.
+        
+        Can be called in two ways:
+        
+        1. With a request object:
+           await client.transcribe(TranscribeRequest(...))
+           
+        2. With individual parameters (keyword arguments):
+           await client.transcribe(
+               provider_uid="...",
+               file=("filename", audio_bytes, "audio/wav"),
+               model="whisper-1"
+           )
+        
+        Args:
+            request: A TranscribeRequest or TranscribeFallbackRequest object
+            provider_uid: The provider UID string
+            file: The audio file as a tuple (filename, content, content_type)
+            model: The model to use for transcription
+            language: Optional language code
+            gen_config: Optional generation configuration
+            
+        Returns:
+            TranscribeResponse with transcription text and detected language
+        """
+        # Check if first argument is a request object
+        if request is not None:
+            if not isinstance(request, (TranscribeRequest, TranscribeFallbackRequest)):
+                raise TypeError(
+                    f"First positional argument must be TranscribeRequest or TranscribeFallbackRequest, got {type(request)}"
+                )
+            # JSON-based request
+            result = await self.post(request.model_dump(), "audio/transcribe_json", expect_json=True)
+            return TranscribeResponse(**result)
+        
+        # Otherwise, use keyword arguments with multipart form-data request
+        if provider_uid is None or file is None or model is None:
+            raise ValueError(
+                "provider_uid, file, and model are required. "
+                "Alternatively, pass a TranscribeRequest object as the first positional argument."
+            )
+        
         files = {
             "file": file
         }
@@ -219,17 +653,10 @@ class LivellmClient:
             "provider_uid": provider_uid,
             "model": model,
             "language": language,
-            "gen_config": json.dumps(gen_config) if gen_config else None
+            "gen_config": json.dumps(kwargs) if kwargs else None
         }
         result = await self.post_multipart(files, data, "audio/transcribe")
         return TranscribeResponse(**result)
-    
-    async def transcribe_json(
-        self,
-        request: Union[TranscribeRequest, TranscribeFallbackRequest]
-    ) -> TranscribeResponse:
-        result = await self.post(request.model_dump(), "audio/transcribe_json", expect_json=True)
-        return TranscribeResponse(**result)
          
 
         

livellm/models/agent/agent.py

@@ -1,6 +1,6 @@
 # models for full run: AgentRequest, AgentResponse
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 from typing import Optional, List, Union
 from .chat import TextMessage, BinaryMessage
 from .tools import WebSearchInput, MCPStreamableServerInput
@@ -9,11 +9,10 @@ from ..common import BaseRequest
 
 class AgentRequest(BaseRequest):
     model: str = Field(..., description="The model to use")
-    messages: List[Union[TextMessage, BinaryMessage]]
-    tools: List[Union[WebSearchInput, MCPStreamableServerInput]]
+    messages: List[Union[TextMessage, BinaryMessage]] = Field(..., description="The messages to use")
+    tools: List[Union[WebSearchInput, MCPStreamableServerInput]] = Field(default_factory=list, description="The tools to use")
     gen_config: Optional[dict] = Field(default=None, description="The configuration for the generation")
 
-
 class AgentResponseUsage(BaseModel):
     input_tokens: int = Field(..., description="The number of input tokens used")
     output_tokens: int = Field(..., description="The number of output tokens used")

livellm/models/agent/chat.py

@@ -1,18 +1,17 @@
 # models for chat messages
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, model_validator, field_serializer
 from enum import Enum
-from typing import Optional
+from typing import Optional, Union
 
-class MessageRole(Enum):
+class MessageRole(str, Enum):
     USER = "user"
     MODEL = "model"
     SYSTEM = "system"
 
 
 class Message(BaseModel):
-    role: MessageRole = Field(..., description="The role of the message")
-
-
+    role: Union[MessageRole, str] = Field(..., description="The role of the message")
+    
 class TextMessage(Message):
     content: str = Field(..., description="The content of the message")
 

livellm/models/agent/tools.py

@@ -3,7 +3,7 @@ from pydantic import BaseModel, Field, field_validator
 from typing import Literal
 from enum import Enum
 
-class ToolKind(Enum):
+class ToolKind(str, Enum):
     WEB_SEARCH = "web_search"
     MCP_STREAMABLE_SERVER = "mcp_streamable_server"
 

livellm/models/audio/speak.py

@@ -6,7 +6,7 @@ from ..common import BaseRequest
 SpeakStreamResponse: TypeAlias = Tuple[AsyncIterator[bytes], str, int]
 
 
-class SpeakMimeType(Enum):
+class SpeakMimeType(str, Enum):
     PCM = "audio/pcm"
     WAV = "audio/wav"
     MP3 = "audio/mpeg"

livellm/models/audio/transcribe.py

@@ -30,17 +30,16 @@ class TranscribeRequest(BaseRequest):
         
         # If content is already bytes, return as-is
         if isinstance(content, bytes):
-            return (filename, content, content_type)
+            try:
+                encoded_content = base64.b64encode(content).decode("utf-8") # base64 encode the content
+                return (filename, encoded_content, content_type)
+            except Exception as e:
+                raise ValueError(f"Failed to encode base64 content: {str(e)}")
         
         # If content is a string, assume it's base64 encoded
         elif isinstance(content, str):
-            try:
-                decoded_content = base64.b64decode(content)
-                return (filename, decoded_content, content_type)
-            except Exception as e:
-                raise ValueError(f"Failed to decode base64 content: {str(e)}")
-        else:
-            raise ValueError(f"file content must be either bytes or base64 string, got {type(content)}")
+            # assume it's already base64 encoded
+            return (filename, content, content_type)
 
 
 class TranscribeResponse(BaseModel):

livellm/models/fallback.py

@@ -1,4 +1,4 @@
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 from typing import List
 from .common import BaseRequest
 from .audio.speak import SpeakRequest
@@ -6,7 +6,7 @@ from .audio.transcribe import TranscribeRequest
 from .agent.agent import AgentRequest
 from enum import Enum
 
-class FallbackStrategy(Enum):
+class FallbackStrategy(str, Enum):
     SEQUENTIAL = "sequential"
     PARALLEL = "parallel"
     
@@ -14,7 +14,7 @@ class FallbackRequest(BaseModel):
     requests: List[BaseRequest] = Field(..., description="List of requests to try as fallbacks")
     strategy: FallbackStrategy = Field(FallbackStrategy.SEQUENTIAL, description="The strategy to use for fallback")
     timeout_per_request: int = Field(default=360, description="The timeout to use for each request")
-
+    
 class AgentFallbackRequest(FallbackRequest):
     requests: List[AgentRequest] = Field(..., description="List of agent requests to try as fallbacks")