universal-mcp-applications 0.1.13__py3-none-any.whl → 0.1.14__py3-none-any.whl

universal_mcp/applications/openai/app.py

@@ -61,8 +61,8 @@ class OpenaiApp(APIApplication):
         # Add other common parameters as needed, or rely on
     ) -> dict[str, Any] | str:
         """
-        Creates a model response for the given chat conversation.
-
+        Generates a model response for a chat conversation. It supports both standard and streaming modes; if streaming, it internally aggregates response chunks into a single complete object, simplifying stream handling. Returns the completion data as a dictionary on success or an error string on failure.
+        
         Args:
             messages: A list of messages comprising the conversation so far.
             model: ID of the model to use. Defaults to "gpt-4o".
@@ -79,12 +79,12 @@ class OpenaiApp(APIApplication):
             presence_penalty: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far.
             stop: Up to 4 sequences where the API will stop generating further tokens.
             user: A unique identifier representing your end-user.
-
+        
         Returns:
             A dictionary containing the chat completion response on success,
             or a string containing an error message on failure.
             If stream=True, usage data in the response will be None.
-
+        
         Tags:
             chat, llm, important
         """
@@ -163,17 +163,17 @@ class OpenaiApp(APIApplication):
         self, file: OpenAiFileTypes, purpose: OpenAiFilePurpose
     ) -> dict[str, Any] | str:
         """
-        Upload a file that can be used across various OpenAI API endpoints.
-
+        Uploads a file to the user's OpenAI account for use across various endpoints like 'assistants'. It accepts a file path or object and a purpose string, returning a dictionary with the created file object's details upon success.
+        
         Args:
             file: The File object (not file name) or path to be uploaded.
                   Can be bytes, a PathLike object, or a file-like object.
             purpose: The intended purpose of the uploaded file (e.g., 'fine-tune', 'assistants').
-
+        
         Returns:
             A dictionary containing the file object details on success,
             or a string containing an error message on failure.
-
+        
         Tags:
             files, upload, storage
         """
@@ -194,18 +194,18 @@ class OpenaiApp(APIApplication):
         order: Literal["asc", "desc"] | None = None,
     ) -> dict[str, Any] | str:
         """
-        Lists the files that have been uploaded to your OpenAI account.
-
+        Retrieves a paginated list of files uploaded to the OpenAI account. Allows filtering by purpose and controlling the output with limit, `after` cursor, and sort order parameters to efficiently navigate through the file collection.
+        
         Args:
             purpose: Only return files with the given purpose.
             limit: A limit on the number of objects to be returned.
             after: A cursor for use in pagination.
             order: Sort order by the `created_at` timestamp.
-
+        
         Returns:
             A dictionary representing a page of file objects on success,
             or a string containing an error message on failure.
-
+        
         Tags:
             files, list, storage
         """
@@ -228,17 +228,17 @@ class OpenaiApp(APIApplication):
         except Exception as e:
             return f"Error listing files: {type(e).__name__} - {e}"
 
-    async def retrieve_file(self, file_id: str) -> dict[str, Any] | str:
+    async def retrieve_file_metadata(self, file_id: str) -> dict[str, Any] | str:
         """
-        Retrieves information about a specific file.
-
+        Retrieves the metadata (e.g., purpose, creation date) for a specific file from the OpenAI account using its ID. Unlike `retrieve_file_content`, this function does not download the file's contents. It returns a dictionary with file details on success or an error string on failure.
+        
         Args:
             file_id: The ID of the file to retrieve.
-
+        
         Returns:
             A dictionary containing the file object details on success,
             or a string containing an error message on failure.
-
+        
         Tags:
             files, retrieve, storage
         """
@@ -255,15 +255,15 @@ class OpenaiApp(APIApplication):
 
     async def delete_file(self, file_id: str) -> dict[str, Any] | str:
         """
-        Deletes a file.
-
+        Permanently deletes a file from the user's OpenAI account using its unique file ID. This action is irreversible. It returns a dictionary confirming the deletion on success or an error message string on failure. This is the 'delete' operation in the file management lifecycle.
+        
         Args:
             file_id: The ID of the file to delete.
-
+        
         Returns:
             A dictionary containing the deletion status on success,
             or a string containing an error message on failure.
-
+        
         Tags:
             files, delete, storage
         """
@@ -278,16 +278,15 @@ class OpenaiApp(APIApplication):
 
     async def retrieve_file_content(self, file_id: str) -> dict[str, Any] | str:
         """
-        Retrieves the content of the specified file.
-        Returns text content directly, or base64 encoded content in a dictionary for binary files.
-
+        Retrieves a file's content from OpenAI using its ID. It returns plain text for common text formats (e.g., JSON, CSV). For binary or undecodable files, it returns a dictionary with base64-encoded data, differentiating it from `retrieve_file` which only fetches metadata.
+        
         Args:
             file_id: The ID of the file whose content to retrieve.
-
+        
         Returns:
             The file content as a string if text, a dictionary with base64 encoded
             content if binary, or an error message string on failure.
-
+        
         Tags:
             files, content, download
         """
@@ -332,7 +331,7 @@ class OpenaiApp(APIApplication):
             )
 
     # --- Images Methods ---
-    async def generate_image(
+    async def create_image(
         self,
         prompt: str,
         model: str
@@ -347,8 +346,8 @@ class OpenaiApp(APIApplication):
         user: str | None = None,
     ) -> dict[str, Any] | str:
         """
-        Creates an image given a prompt.
-
+        Generates new images from a textual prompt using OpenAI's DALL-E models. It allows customization of parameters like image size, quality, style, and response format (URL or base64 JSON). Unlike other image functions in this class, it creates images entirely from scratch based on text.
+        
         Args:
             prompt: A text description of the desired image(s).
             model: The model to use for image generation. Defaults to "dall-e-3".
@@ -365,11 +364,11 @@ class OpenaiApp(APIApplication):
                   For "dall-e-3": "1024x1024", "1792x1024", or "1024x1792".
             style: The style of the generated images ("vivid" or "natural"). Only for "dall-e-3".
             user: A unique identifier representing your end-user.
-
+        
         Returns:
             A dictionary containing the image generation response on success,
             or a string containing an error message on failure.
-
+        
         Tags:
             images, generate, dalle, important
         """
@@ -416,8 +415,8 @@ class OpenaiApp(APIApplication):
         user: str | None = None,
     ) -> dict[str, Any] | str:
         """
-        Creates an edited or extended image given an original image and a prompt.
-
+        Modifies a source image using the DALL-E 2 model based on a text prompt. An optional mask can be supplied to specify the exact area for editing. This function is distinct from generating images from scratch (`generate_image`) or creating simple variations (`create_image_variation`).
+        
         Args:
             image: The image to edit. Must be a valid PNG file, less than 4MB, and square.
             prompt: A text description of the desired image(s).
@@ -428,11 +427,11 @@ class OpenaiApp(APIApplication):
             response_format: The format of the returned images ("url" or "b64_json"). Defaults to "url".
             size: The size of the generated images. Must be one of "256x256", "512x512", or "1024x1024".
             user: A unique identifier representing your end-user.
-
+        
         Returns:
             A dictionary containing the image edit response on success,
             or a string containing an error message on failure.
-
+        
         Tags:
             images, edit, dalle
         """
@@ -469,8 +468,8 @@ class OpenaiApp(APIApplication):
         user: str | None = None,
     ) -> dict[str, Any] | str:
         """
-        Creates a variation of a given image.
-
+        Generates one or more variations of a provided image using the OpenAI API, specifically the DALL-E 2 model. It allows customization of the number, size, and response format of the resulting images. Returns a dictionary with image data on success or an error string on failure.
+        
         Args:
             image: The image to use as the basis for the variation(s). Must be a valid PNG file.
             model: The model to use. Defaults to "dall-e-2", which is currently the only
@@ -479,11 +478,11 @@ class OpenaiApp(APIApplication):
             response_format: The format of the returned images ("url" or "b64_json"). Defaults to "url".
             size: The size of the generated images. Must be one of "256x256", "512x512", or "1024x1024".
             user: A unique identifier representing your end-user.
-
+        
         Returns:
             A dictionary containing the image variation response on success,
             or a string containing an error message on failure.
-
+        
         Tags:
             images, variation, dalle
         """
@@ -508,7 +507,7 @@ class OpenaiApp(APIApplication):
         except Exception as e:
             return f"Error creating image variation with model {effective_model}: {type(e).__name__} - {e}"
 
-    async def create_transcription(
+    async def transcribe_audio(
         self,
         file: OpenAiFileTypes,
         model: str | OpenAiAudioModel = "gpt-4o-transcribe",
@@ -522,8 +521,8 @@ class OpenaiApp(APIApplication):
         stream: bool = False,
     ) -> dict[str, Any] | str:
         """
-        Transcribes audio into the input language.
-
+        Transcribes an audio file into text in its original language using models like Whisper or GPT-4o. It supports multiple response formats and internally aggregates streaming data into a final object. This differs from `create_translation`, which translates audio specifically into English text.
+        
         Args:
             file: The audio file object (not file name) to transcribe.
             model: ID of the model to use (e.g., "whisper-1", "gpt-4o-transcribe").
@@ -539,12 +538,12 @@ class OpenaiApp(APIApplication):
                      Only works with response_format="json" and gpt-4o models.
             stream: If True, streams the response. The method will aggregate the stream
                     into a final response object. Streaming is not supported for "whisper-1".
-
+        
         Returns:
             A dictionary containing the transcription or a string, depending on `response_format`.
             If `stream` is True, an aggregated response dictionary.
             Returns an error message string on failure.
-
+        
         Tags:
             audio, transcription, speech-to-text, important
         """
@@ -615,19 +614,19 @@ class OpenaiApp(APIApplication):
         temperature: float | None = None,
     ) -> dict[str, Any] | str:
         """
-        Translates audio into English text.
-
+        Translates audio from any supported language into English text using OpenAI's API. Unlike `create_transcription`, which converts audio to text in its original language, this function's output is always English. It supports various response formats like JSON, text, or SRT for the translated content.
+        
         Args:
             file: The audio file object (not file name) to translate.
             model: ID of the model to use (currently, only "whisper-1" is supported).
             prompt: Optional text to guide the model's style (should be in English).
             response_format: The format of the translated text.
             temperature: Sampling temperature between 0 and 1.
-
+        
         Returns:
             A dictionary containing the translation or a string, depending on `response_format`.
             Returns an error message string on failure.
-
+        
         Tags:
             audio, translation, speech-to-text
         """
@@ -681,8 +680,8 @@ class OpenaiApp(APIApplication):
         instructions: str | None = None,  # For gpt-4o-mini-tts or newer models
     ) -> dict[str, Any] | str:
         """
-        Generates audio from the input text.
-
+        Generates audio from input text using a specified TTS model and voice. This text-to-speech function allows customizing audio format and speed. On success, it returns a dictionary containing the base64-encoded audio content and its corresponding MIME type, or an error string on failure.
+        
         Args:
             input_text: The text to generate audio for (max 4096 characters).
             model: The TTS model to use (e.g., "tts-1", "tts-1-hd", "gpt-4o-mini-tts").
@@ -690,12 +689,12 @@ class OpenaiApp(APIApplication):
             response_format: The format of the audio ("mp3", "opus", "aac", "flac", "wav", "pcm"). Defaults to "mp3".
             speed: Speed of the generated audio (0.25 to 4.0). Defaults to 1.0.
             instructions: Control voice with additional instructions (not for tts-1/tts-1-hd).
-
-
+        
+        
         Returns:
             A dictionary containing the base64 encoded audio content and content type,
             or an error message string on failure.
-
+        
         Tags:
             audio, speech, text-to-speech, tts, important
         """
@@ -746,13 +745,13 @@ class OpenaiApp(APIApplication):
             self.create_chat_completion,
             self.upload_file,
             self.list_files,
-            self.retrieve_file,
+            self.retrieve_file_metadata,
             self.delete_file,
             self.retrieve_file_content,
-            self.generate_image,
+            self.create_image,
             self.create_image_edit,
             self.create_image_variation,
-            self.create_transcription,
+            self.transcribe_audio,
             self.create_translation,
             self.create_speech,
         ]

universal_mcp/applications/outlook/app.py

@@ -10,7 +10,7 @@ class OutlookApp(APIApplication):
         super().__init__(name="outlook", integration=integration, **kwargs)
         self.base_url = "https://graph.microsoft.com/v1.0"
 
-    def users_message_reply(
+    def reply_to_message(
         self,
         message_id: str,
         user_id: str | None = None,
@@ -18,20 +18,20 @@ class OutlookApp(APIApplication):
         message: dict[str, Any] | None = None,
     ) -> Any:
         """
-        Replies to a specific message for a user using the POST method, accepting JSON content in the request body and returning status codes indicating success or error.
-
+        Replies to a specific email message identified by its ID. The reply can contain a simple comment or a full message object with attachments. If no user ID is provided, it defaults to the current user, distinguishing it from `user_send_mail` which sends a new email.
+        
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
             message_id (string): message-id
             comment (string): A comment to include in the reply. Example: 'Thank you for your email. Here is my reply.'.
             message (object): A message object to specify additional properties for the reply, such as attachments. Example: {'subject': 'RE: Project Update', 'body': {'contentType': 'Text', 'content': 'Thank you for the update. Looking forward to the next steps.'}, 'toRecipients': [{'emailAddress': {'address': 'alice@contoso.com'}}], 'attachments': [{'@odata.type': '#microsoft.graph.fileAttachment', 'name': 'agenda.pdf', 'contentType': 'application/pdf', 'contentBytes': 'SGVsbG8gV29ybGQh'}]}.
-
+        
         Returns:
             Any: Success
-
+        
         Raises:
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             users.message, important
         """
@@ -63,26 +63,26 @@ class OutlookApp(APIApplication):
         )
         return self._handle_response(response)
 
-    def user_send_mail(
+    def send_mail(
         self,
         message: dict[str, Any],
         user_id: str | None = None,
         saveToSentItems: bool | None = None,
     ) -> Any:
         """
-        Sends an email on behalf of the specified user, accepting the email details as JSON in the request body and returning a 204 No Content response on success.
-
+        Sends a new email on behalf of a user, using a provided dictionary for content like recipients and subject. Unlike `users_message_reply`, which replies to an existing message, this function is used to compose and send an entirely new email from scratch.
+        
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
             message (object): message Example: {'subject': 'Meet for lunch?', 'body': {'contentType': 'Text', 'content': 'The new cafeteria is open.'}, 'toRecipients': [{'emailAddress': {'address': 'frannis@contoso.com'}}], 'ccRecipients': [{'emailAddress': {'address': 'danas@contoso.com'}}], 'bccRecipients': [{'emailAddress': {'address': 'bccuser@contoso.com'}}], 'attachments': [{'@odata.type': '#microsoft.graph.fileAttachment', 'name': 'attachment.txt', 'contentType': 'text/plain', 'contentBytes': 'SGVsbG8gV29ybGQh'}]}.
             saveToSentItems (boolean): saveToSentItems Example: 'False'.
-
+        
         Returns:
             Any: Success
-
+        
         Raises:
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             users.user.Actions, important
         """
@@ -112,7 +112,7 @@ class OutlookApp(APIApplication):
         )
         return self._handle_response(response)
 
-    def user_get_mail_folder(
+    def get_mail_folder(
         self,
         mailFolder_id: str,
         user_id: str | None = None,
@@ -121,21 +121,21 @@ class OutlookApp(APIApplication):
         expand: list[str] | None = None,
     ) -> Any:
         """
-        Retrieves a specific mail folder for a specified user using optional query parameters to include hidden folders or select/expand properties.
-
+        Retrieves a specific mail folder by its ID for a given user. Allows customization of the response by optionally including hidden folders, selecting specific properties to return, or expanding related entities. It specifically targets folder metadata, not the messages within.
+        
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
             mailFolder_id (string): mailFolder-id
             includeHiddenFolders (string): Include Hidden Folders
             select (array): Select properties to be returned
             expand (array): Expand related entities
-
+        
         Returns:
             Any: Retrieved navigation property
-
+        
         Raises:
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             users.mailFolder, important
         """
@@ -162,7 +162,7 @@ class OutlookApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def user_list_message(
+    def list_user_messages(
         self,
         user_id: str | None = None,
         select: list[str] = ["bodyPreview"],
@@ -176,8 +176,8 @@ class OutlookApp(APIApplication):
         expand: list[str] | None = None,
     ) -> dict[str, Any]:
         """
-        Retrieves a list of messages for a user, allowing optional filtering and sorting of results based on parameters such as includeHiddenMessages, search, filter, top, skip, orderby, select, and expand.
-
+        Retrieves a list of messages from a user's mailbox. This function supports powerful querying using optional parameters for filtering, searching, sorting, and pagination, unlike `user_get_message`, which fetches a single email by its ID.
+        
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
             select (list): Select properties to be returned. Defaults to ['bodyPreview'].
@@ -196,13 +196,13 @@ class OutlookApp(APIApplication):
             count (boolean): Include count of items
             orderby (array): Order items by property values
             expand (array): Expand related entities
-
+        
         Returns:
             dict[str, Any]: Retrieved collection
-
+        
         Raises:
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             users.message, important
         """
@@ -241,7 +241,7 @@ class OutlookApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def user_get_message(
+    def get_user_message(
         self,
         message_id: str,
         user_id: str | None = None,
@@ -250,21 +250,21 @@ class OutlookApp(APIApplication):
         expand: list[str] | None = None,
     ) -> Any:
         """
-        Retrieves a specific message for a user, optionally including hidden messages, selecting specific fields, or expanding related data.
-
+        Retrieves a specific message by its ID for a user, with options to select fields or expand related data. This function fetches a single item, in contrast to `user_list_message` which retrieves a collection of messages.
+        
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
             message_id (string): message-id
             includeHiddenMessages (string): Include Hidden Messages
             select (array): Select properties to be returned
             expand (array): Expand related entities
-
+        
         Returns:
             Any: Retrieved navigation property
-
+        
         Raises:
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             users.message, important
         """
@@ -293,18 +293,18 @@ class OutlookApp(APIApplication):
 
     def user_delete_message(self, message_id: str, user_id: str | None = None) -> Any:
         """
-        Deletes a specific message for a given user using the DELETE method and optional If-Match header for conditional requests.
-
+        Deletes a specific Outlook message for a user, identified by its unique `message_id`. If `user_id` is not provided, it automatically targets the currently authenticated user's mailbox. It makes a DELETE request to the corresponding Microsoft Graph API endpoint to permanently remove the message.
+        
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
             message_id (string): message-id
-
+        
         Returns:
             Any: Success
-
+        
         Raises:
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             users.message, important
         """
@@ -323,7 +323,7 @@ class OutlookApp(APIApplication):
         response = self._delete(url, params=query_params)
         return self._handle_response(response)
 
-    def user_message_list_attachment(
+    def list_message_attachments(
         self,
         message_id: str,
         user_id: str | None = None,
@@ -337,8 +337,8 @@ class OutlookApp(APIApplication):
         expand: list[str] | None = None,
     ) -> dict[str, Any]:
         """
-        Retrieves attachments associated with a specified user's message, supporting filtering, pagination, and field selection via query parameters.
-
+        Retrieves attachments for a specific email message, identified by its ID. Supports advanced querying for filtering, sorting, and pagination, allowing users to select specific fields to return in the result set.
+        
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
             message_id (string): message-id
@@ -350,13 +350,13 @@ class OutlookApp(APIApplication):
             orderby (array): Order items by property values
             select (array): Select properties to be returned
             expand (array): Expand related entities
-
+        
         Returns:
             dict[str, Any]: Retrieved collection
-
+        
         Raises:
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             users.message, important
         """
@@ -388,19 +388,19 @@ class OutlookApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def get_user_id(
+    def get_current_user_profile(
         self,
     ) -> dict[str, Any]:
         """
-        Retrieves the current user.
-
-
+        Fetches the `userPrincipalName` for the currently authenticated user from the `/me` endpoint. It is a helper function used internally by other methods to automatically obtain the user's ID for API calls when one is not explicitly provided.
+        
+        
         Returns:
             dict[str, Any]: Current user information
-
+        
         Raises:
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             me, important
         """
@@ -411,9 +411,9 @@ class OutlookApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def get_from_url(self, url: str) -> dict[str, Any]:
+    def get_next_page(self, url: str) -> dict[str, Any]:
         """
-        Makes a GET request to a full @odata.nextLink or @odata.deltaLink URL.
+        Executes a GET request using a full URL, typically a pagination link (`@odata.nextLink`) from a previous API response. It validates the URL, extracts the relative path and query parameters, and fetches the corresponding data, simplifying navigation through paginated API results.
         """
         if not url:
             raise ValueError("Missing required parameter 'url'.")
@@ -430,13 +430,13 @@ class OutlookApp(APIApplication):
 
     def list_tools(self):
         return [
-            self.users_message_reply,
-            self.user_send_mail,
-            self.user_get_mail_folder,
-            self.user_list_message,
-            self.user_get_message,
+            self.reply_to_message,
+            self.send_mail,
+            self.get_mail_folder,
+            self.list_user_messages,
+            self.get_user_message,
             self.user_delete_message,
-            self.user_message_list_attachment,
-            self.get_user_id,
-            self.get_from_url,
+            self.list_message_attachments,
+            self.get_current_user_profile,
+            self.get_next_page,
         ]